Version. 0.1
Date. 2026-04-28
Author. Marvin Percival (DUNIN7), prepared via Claude.
Target. /Users/dunin7/loomworks (substrate, Step 0 amendments) and /Users/dunin7/loomworks-ui (frontend, Steps 1–4). DUNIN7-M4 (MacMini).
Priority. Standard.
Confidential. Internal.
Companion to. Phase 23 scoping note v0.1, Phase 21 CR v0.2 (Shaping Room original build), methodology v0.19.
Status. First draft. Six scoping decisions (S1–S6). Design target validated with the Operator via high-fidelity mockup.
Phase 23 redesigns the Shaping room from flat sections to a status-first card layout. The current layout — one full-width section per DeclaredShapeType with heading, description, and either Shaping cards or a "Create Shaping" button — is verbose, hard to scan, and scales poorly. The redesign replaces it with compact expandable cards that let the Operator scan all shape types at a glance and drill into detail on demand.
Step 0 renames the five Loomworks DeclaredShapeTypes to plain-language names and rewrites their descriptions. The frontend work replaces the flat-section layout with the card layout, adds a "What is shaping?" expandable room explanation, and adds "What is this?" links on empty cards. All existing Shaping CRUD operations and Shape production are preserved — only their visual placement changes.
Layer 1 — Methodology document v0.19. Shaping takes a confirmed Manifestation and forms it for a specific consumer. The room's job is to make the Operator's relationship with Shapings clear: what does this engagement produce, for whom, and what is the current state.
Design validation. A high-fidelity mockup was reviewed and approved by the Operator in the scoping session. The mockup is the design target. This CR specifies the mockup's composition in terms the executing agent can build from.
phase-22-rendering-room-ui (operational commits). 1138 tests, 2 skips.phase-22-rendering-room-ui (UUID cleanup commit). Lint + tsc + build + test clean. Thirteen surfaces. 72 component tests, 1 E2E test.CC confirms before Step 1 (after Step 0):
npm run test passes.
Archive this CR to docs/phase-crs/phase-23-cr-shaping-room-redesign-v0_1.md in the substrate repo at Step 0.
Amend the five DeclaredShapeTypes in the Loomworks engagement. Five declared_shape_type_amended events. No schema changes, no migrations.
| Current name | New name | |---|---| | Phase execution context | Phase preparation | | Project state | Project overview | | Methodology narrative | Methodology | | Discovery trajectory | Discovery | | Commons education | Education |
For each DeclaredShapeType, update:
shape_type_name — new name as listed.consumer_declaration — rewritten in plain language. No abbreviations, no toolchain vocabulary. The consumer_declaration describes who receives the shaped material, not which tools produce it.selection_criterion — rewritten to lead with what material is selected from Memory.shaping_instructions — updated to match the new names and descriptions.Consumer declarations (new text):
| Shape type | Consumer declaration | |---|---| | Phase preparation | The person preparing the next build phase and the person executing it. | | Project overview | Anyone orienting to the project or reviewing its overall state. | | Methodology | Anyone needing to understand what the engagement builds and why. | | Discovery | Anyone reviewing how a decision was reached or an idea developed. | | Education | Every person in the system. |
CC writes the amendment script following the pattern established by scripts/amend_loomworks_dst_drt_abbreviations.py. Idempotent.
Archive this CR to docs/phase-crs/phase-23-cr-shaping-room-redesign-v0_1.md.
Commit (substrate repo): Phase 23 step 0: CR archival and DeclaredShapeType rename.
The current Shaping room layout:
Replaced by:
Cards are stacked vertically with {spacing.s-4} (1rem) gap. No grouping level. The order follows the DeclaredShapeTypes as they appear in the engagement.
The room page background remains env-shaping (#E6D4C5). Cards sit on {colors.bleached} (#FFFCF5) — raised above the room's atmospheric ground per the brand's paper hierarchy.
Each DeclaredShapeType is a card ({components.card}) in the collapsed state by default.
Layout: two-column. Left column (flex: 1) carries the content. Right column (flex-shrink: 0, right-aligned) carries the status.
Left column content:
{typography.h3} (IBM Plex Serif, 1.5rem, weight 500).{typography.display-italic} (IBM Plex Serif italic, 1.2rem, weight 400) with {colors.ink-faint}. One or two lines. The description comes from the DeclaredShapeType's amended consumer_declaration or a dedicated description field — CC determines which field best serves.{typography.caption} with {colors.brass}. Format: "Produces change requests, scoping notes, handoffs, implementation notes" where the render type names are in {colors.type-metal} (not bold weight — just darker color against the brass). The produces list is derived by querying DeclaredRenderTypes whose source_shape_type_ref points at this DeclaredShapeType.Right column content:
{typography.label} (IBM Plex Mono, uppercase, 0.18em tracking). Active Shapings: {colors.state-attest} dot + "N ACTIVE". No Shapings: {colors.rule} dot + "NO SHAPINGS".{typography.mono} with {colors.brass}. "N shapes" when active Shapings exist. Absent when no Shapings.
Interaction: the entire card is clickable. Cursor pointer. On hover, border transitions from {colors.rule} to {colors.brass} at duration-fast with ease-out.
On click: the card expands (§7) or collapses back. Multiple cards can be expanded simultaneously.
When expanded, the card gains:
{colors.type-metal} (darker than hover, indicating active/selected).{colors.rule-soft} horizontal divider with {spacing.s-5} vertical margin.The collapsed content (name, description, produces, status) remains visible at the top.
Each active Shaping is a row inside the expanded card.
Row background: {colors.cartridge} (#F2EDE0). This is one step down from the card's bleached ground — per the brand's paper hierarchy (bleached card → cartridge rows within). {rounded.sm} (3px) radius. Padding: {spacing.s-4} (1rem) horizontal, {spacing.s-3} (0.75rem) vertical.
Row layout — two visual rows within each Shaping row:
First row: Shaping identity.
{typography.body-em} (Inter, 1rem, weight 500).{typography.caption} with {colors.ink-faint}: "v[N] · [Executor display_name] · [N] shapes produced". Separated by {colors.brass} middle dots.Second row: action buttons. Full-width row below the metadata. Buttons at standard component size — not miniaturized. See §9 for the contextual color rules.
Shapes toggle: below the action buttons, a text toggle: "Show shapes · [N] ▾" in {typography.caption} with {colors.ink-faint}. Clicking reveals the Shape list (same content as Phase 21 §12 — newest-first, Manifestation version, Shaping version, timestamp, confirmation status). Collapsed by default.
Retired Shapings: if any retired Shapings exist for this DeclaredShapeType, a "Show retired · [N]" collapsible toggle appears below the active Shaping rows. Same pattern as Phase 21 §13 but within the expanded card.
Gap between Shaping rows: {spacing.s-3} (0.75rem).
Shaping action buttons appear inside rows on {colors.cartridge} (#F2EDE0) background. The standard button tokens are designed for {colors.bleached} ground. On cartridge, secondary and ghost buttons lose contrast. This section specifies contextual adjustments.
Primary button ({components.button-primary}): no change needed. Press-ink background on cartridge ground has strong contrast.
Secondary button on cartridge ground: border changes from {colors.rule} (#E0DACC) to {colors.type-metal} (#4A4843). The rule border is nearly invisible on cartridge; type-metal provides the contrast the Operator needs to see the button as an action. Hover state: {colors.vellum} background + {colors.press-ink} border (unchanged from token).
Ghost button on cartridge ground: text changes from {colors.press-ink} to {colors.type-metal} (#4A4843) at rest. This keeps the ghost button visible as an action but lighter than the secondary button. Hover state: {colors.vellum} background (unchanged from token).
Implementation. CC can implement this as a CSS modifier class (e.g., .on-cartridge applied to the button group within Shaping rows) or as a variant prop on the button components. The mechanism is CC's choice; the requirement is that buttons on cartridge ground are clearly visible as actions.
Cards with no Shapings show the empty state below the card's collapsed content:
Layout: a row with text on the left and the "Create shaping" button on the right.
{typography.body} with {colors.ink-faint}. Below that, the "What is this?" link (§12).{components.button-primary}.The empty state replaces the expanded content area — there are no Shaping rows to show, so the card's lower area is the empty state. The card is not clickable in the empty state (nothing to expand). The "Create shaping" button opens the existing Create Shaping modal (Phase 21 §7) with the DeclaredShapeType pre-selected.
Below the room heading, above the card stack:
"What is shaping?" in {typography.display-italic} (IBM Plex Serif italic) with {colors.ink-faint}. A small caret (▶ collapsed, ▼ expanded) precedes the text.
Collapsed state (default): one line. The caret and text.
Expanded state: the full explanation appears below. For Phase 23, this is static text derived from assertion #14 in Memory. The text renders in {typography.body} with {colors.type-metal}, with examples in the same style.
The static text (derived from assertion #14):
> Shaping is the moment where the engagement's accumulated knowledge gets organized for someone specific. > > Everything the engagement knows lives in Memory. The Manifestation organizes Memory at a point in time. But neither of those is directed at any particular reader — they are the whole body of knowledge, organized but not shaped for anyone. > > Shaping takes that organized knowledge and asks: what does this specific reader need, and how should it be arranged for them? > > The same Memory, the same Manifestation, produces different Shapings for different readers. The knowledge does not change — what changes is what gets selected, what gets emphasized, and what gets left out.
The full assertion #14 text is longer (includes Loomworks-specific and cross-domain examples). Phase 23 uses the first four paragraphs — enough to orient without overwhelming. A future phase replaces static text with a live read from Memory.
Animation: expand/collapse at duration-normal (250ms) with ease-in-out. Respects prefers-reduced-motion.
Empty-state cards (§10) show a "What is this?" link below the empty-state text.
"What is this? ▸" in {typography.caption} with {colors.brass}. On hover, color transitions to {colors.type-metal}.
Clicking expands an explanation of the shape type below the link. For Phase 23, the explanation is the DeclaredShapeType's selection_criterion field rendered in {typography.body} with {colors.ink-faint}. A future phase reads from a dedicated explains assertion per shape type.
The toggle collapses the explanation on second click.
Update existing Shaping room component tests (Phase 21 contributed 17 ShapingCard tests) to reflect the new layout:
CC writes or updates tests to cover the new components. Existing modal tests (Create Shaping, Amend Rules, Change Executor) should still pass — the modals are unchanged.
Auto-mode posture: Step 0 auto. Steps 1–2 auto, Checkpoint A. Steps 3–4 auto, Checkpoint B (final).
Step 0 — CR archival, DeclaredShapeType rename.
docs/phase-crs/phase-23-cr-shaping-room-redesign-v0_1.md.
Commit (substrate repo): Phase 23 step 0: CR archival and DeclaredShapeType rename.
Step 1 — Card layout, collapsed state, produces line.
Replace the flat-section layout with the card stack. Implement collapsed card state (§6) with name, description, produces line, status badge. The produces line queries DeclaredRenderTypes for each shape type. Remove the old section-based components.
Verification: lint + tsc + build clean. Room renders with five cards in collapsed state.
Commit (frontend repo): Phase 23 step 1: card layout and collapsed state.
Step 2 — Expanded state, Shaping rows, action buttons, empty state.
Implement expanded card state (§7). Shaping rows (§8) with action button contextual color rules (§9). Empty-state cards (§10) with "Create shaping" button. Shapes toggle within Shaping rows. Retired Shapings collapsible within expanded cards.
Verification: lint + tsc + build + test clean. Operator can expand cards, see Shapings, take actions.
Commit (frontend repo): Phase 23 step 2: expanded state, shaping rows, empty state.
Checkpoint A — Card layout functional. All CRUD operations work. Action buttons visible on cartridge ground. Operator confirms before explanation toggles and tests.
Step 3 — Room explanation toggle, "What is this?" toggle, component tests.
Implement "What is shaping?" toggle (§11). Implement "What is this?" on empty cards (§12). Write/update component tests (§13).
Verification: lint + tsc + build + test clean.
Commit (frontend repo): Phase 23 step 3: explanation toggles and component tests.
Step 4 — Implementation notes and tagging.
Create docs/phase-impl-notes/phase-23-implementation-notes-v0_1.md.
Commit (substrate repo): Phase 23 step 4: implementation notes.
Checkpoint B — Final. Both repos green. Tag both repos as phase-23-shaping-room-redesign.
Phase 23 is accepted when:
On acceptance: tag both repos as phase-23-shaping-room-redesign. Write implementation notes.
explains relationship pattern. Future phase.
> Read the Change Request document at the path I supply below. This is
> CR-2026-037 v0.1, the Phase 23 Change Request. You are the executing
> agent named in the CR.
>
> CR path: ~/Downloads/phase-23-cr-shaping-room-redesign-v0_1.md
>
> Phase 23 redesigns the Shaping room from flat sections to a
> status-first card layout. Design validated by Operator via mockup.
>
> Key design requirements:
> - Each DeclaredShapeType is a compact card, not a page section.
> - Cards expand on click to show Shaping rows within.
> - Action buttons sit on their own row at standard size (not
> miniaturized). See §9 for contextual color rules on cartridge
> ground: secondary buttons get type-metal border, ghost buttons
> get type-metal text.
> - Empty cards show "Create shaping" button inline.
> - "What is shaping?" expandable toggle below room heading.
> - "What is this?" expandable link on empty cards.
>
> Code baseline: substrate at HEAD on main beyond phase-22 tag.
> Frontend at HEAD on main beyond phase-22 tag. Substrate: 1138 tests,
> 2 skips. Frontend: lint + tsc + build + test clean, 72 component
> tests, 1 E2E.
>
> Run Step 0 per §4: archive CR, rename five DeclaredShapeTypes,
> substrate tests green.
>
> Steps 1–2 auto, Checkpoint A halts for smoke-test.
> Steps 3–4 auto, Checkpoint B halts for tagging.
>
> Brand enforcement: env-shaping (#E6D4C5) on outer frame. Bleached
> (#FFFCF5) card backgrounds. Cartridge (#F2EDE0) Shaping rows.
> No pure white. IBM Plex Serif for card names and room heading.
> Inter for body. IBM Plex Mono for labels and status badges.
> Audit before tagging.
>
> Implementation notes at Step 4:
> docs/phase-impl-notes/phase-23-implementation-notes-v0_1.md
DUNIN7 — Done In Seven LLC — Miami, Florida Phase 23: Shaping Room Redesign — CR v0.1 — 2026-04-28