diff --git a/src/workflows/0-project-setup/templates/folder-guides/00-design-system.template.md b/src/workflows/0-project-setup/templates/folder-guides/00-design-system.template.md index a5e41edbc..8bc8e2b45 100644 --- a/src/workflows/0-project-setup/templates/folder-guides/00-design-system.template.md +++ b/src/workflows/0-project-setup/templates/folder-guides/00-design-system.template.md @@ -87,9 +87,77 @@ D-Design-System/ --- +## Spacing Scale + +> **Bring your own or use ours.** If your project already has a design system with a spacing scale (Tailwind, Material, Carbon, your own tokens), use that. Map your token names below so page specs reference them consistently. If you don't have one yet, WDS provides a default 9-token scale to get started. + +### Option A: Use your existing design system + +Replace the table below with your system's spacing tokens. Any naming convention works — numbered (`spacing-4`), t-shirt (`sm`/`md`/`lg`), or your own. The only rule: page specs reference token names, never raw pixel values. + +### Option B: WDS default scale + +Nine tokens, symmetric around `space-md`. Freya will propose pixel values during the first design session. + +| Token | Value | Use | +|-------|-------|-----| +| space-3xs | — | Hairline gaps (icon-to-label, inline elements) | +| space-2xs | — | Minimal spacing (badge padding, tight lists) | +| space-xs | — | Tight spacing (within compact groups) | +| space-sm | — | Small gaps (between related elements) | +| space-md | — | Default element spacing | +| space-lg | — | Comfortable spacing (card padding, form fields) | +| space-xl | — | Section padding | +| space-2xl | — | Section gaps | +| space-3xl | — | Page-level breathing room | + + + +--- + +## Type Scale + +> **Bring your own or use ours.** Same principle as spacing — if your project has a type system, map it here. If not, use the WDS default. + +The type scale controls **visual size** — how big text looks. This is separate from semantic level (H1, H2, p) which controls **document structure**. An H2 in a sidebar might be `text-sm`. A tagline might be a `

` at `text-2xl`. The semantic level is for accessibility and SEO; the type token is for visual hierarchy. + +Headings can have different typefaces, weights, and styles on different pages. A landing page H1 might be a serif display font at `text-3xl` italic. An admin page H1 might be clean sans-serif at `text-lg` medium. Each page spec declares its own typographic treatment — the type scale provides the shared sizing vocabulary. + +### Option A: Use your existing type system + +Replace the table below with your system's type tokens. + +### Option B: WDS default scale + +Nine tokens, symmetric around `text-md` (body text). Freya will propose sizes during the first design session. + +| Token | Value | Use | +|-------|-------|-----| +| text-3xs | — | Fine print, legal text | +| text-2xs | — | Metadata, timestamps | +| text-xs | — | Captions, helper text | +| text-sm | — | Labels, secondary text | +| text-md | — | Body text (the baseline) | +| text-lg | — | Emphasis, lead paragraphs | +| text-xl | — | Subheadings | +| text-2xl | — | Section titles, display text | +| text-3xl | — | Hero headings, page titles | + + + +--- + ## Tokens -_Design tokens will be documented here as they emerge from page specifications._ +_Additional design tokens (colors, shadows, borders) will be documented here as they emerge from page specifications._ --- diff --git a/src/workflows/4-ux-design/data/guides/DESIGN-LOOP-GUIDE.md b/src/workflows/4-ux-design/data/guides/DESIGN-LOOP-GUIDE.md index dd3aeebe6..1dd6610e3 100644 --- a/src/workflows/4-ux-design/data/guides/DESIGN-LOOP-GUIDE.md +++ b/src/workflows/4-ux-design/data/guides/DESIGN-LOOP-GUIDE.md @@ -10,22 +10,23 @@ Design is not a handoff between phases. It's a loop: discuss → visualize → a --- -## The 8-Step Loop +## The 9-Step Loop ``` 1. DISCUSS → Talk about what the page needs to do, who it's for, primary actions 2. SPEC → Write the page specification (content, structure, object IDs) 3. WIREFRAME → Generate Excalidraw wireframe from the spec 4. ITERATE → User reviews wireframe, agent updates — fast loop (seconds) -5. SYNC SPEC → Spec updates to match agreed wireframe -6. IMPLEMENT → Build the page in code -7. REFINE → Browser review via screenshots at real breakpoints -8. TOKENS → Extract recurring patterns into design tokens +5. APPROVE → User exports PNG — the export IS the approval +6. SYNC SPEC → Spec updates to match agreed wireframe +7. IMPLEMENT → Build the page in code +8. REFINE → Browser review via screenshots at real breakpoints +9. TOKENS → Extract recurring patterns into design tokens ``` -Steps 4 and 7 are the iteration loops: +Steps 4 and 8 are the iteration loops: - **Step 4** is fast — Excalidraw JSON manipulation, seconds per change -- **Step 7** is real — actual browser rendering, actual responsive breakpoints +- **Step 8** is real — actual browser rendering, actual responsive breakpoints --- @@ -52,6 +53,19 @@ No other design tool offers this: - Pencil uses encrypted files - AI image generators produce dead images that can't be edited +### Export = approval + +The agent can read and write `.excalidraw` JSON, but it cannot export to PNG — that requires the Excalidraw UI. This limitation is a feature: the manual export becomes an approval gate. + +**The pattern:** +1. Agent creates/edits the `.excalidraw` file (JSON) +2. User reviews in Excalidraw, can tweak things directly +3. When agreed → user exports PNG and saves it alongside the `.excalidraw` file +4. PNG becomes the frozen visual reference in the specification +5. `.excalidraw` file stays as the editable source for future revisions + +The PNG serves as both a backup and a confirmation. If the user hasn't exported the image, the wireframe isn't approved yet. + ### The spec is the contract The wireframe helps reach agreement. The spec captures what was agreed. The implementation follows the spec. This prevents "I thought we said..." drift. @@ -66,11 +80,23 @@ Because the spec has object IDs, responsive breakpoints, and real content, the a Real fonts, real images, real responsive breakpoints. Screenshots at 375px, 768px, 1280px show exactly what users will see. This is where micro-adjustments happen — spacing, font sizes, proportions. -### Tokens emerge from usage +### Spacing discipline — named scale, never arbitrary values -Don't design a heading scale and spacing system before building the page. Build the page, notice you're making the same kinds of adjustments ("make this heading bigger," "more space here"), and extract the patterns into tokens. The design system grows from real needs. +Agents don't have a trained eye for spacing. Without constraints, they'll use arbitrary values — 17px here, 23px there. The fix: a named spacing scale defined per project. -**Don't design tokens upfront.** Build pages first. Extract patterns when they recur across 3+ pages. +**The scale lives in** `D-Design-System/00-design-system.md` → Spacing Scale. If the project already has a design system (Tailwind, Material, Carbon, custom tokens), use that. If not, WDS provides a default 9-token scale from `space-3xs` to `space-3xl`, symmetric around `space-md`. The user defines what pixel values they represent. + +**First design session:** Freya checks if the project has an existing spacing system. If yes, map those tokens into the design system file. If no, Freya proposes values for the default scale and the user confirms. From that point on, every spec uses token names. + +``` +space-3xs space-2xs space-xs space-sm space-md space-lg space-xl space-2xl space-3xl +``` + +**The rules:** +- Specs always use token names, never raw pixel values +- Every section in a page spec declares its padding and element gap using tokens +- If a spacing value isn't in the scale, it doesn't belong in the spec +- The scale can be adjusted as the project matures — specs stay valid because they reference names, not numbers --- @@ -78,11 +104,11 @@ Don't design a heading scale and spacing system before building the page. Build | Tool | Role | When | |------|------|------| -| **Excalidraw** | Wireframes and layout iteration | Steps 3-4 | -| **Puppeteer** | Browser screenshots for visual review | Step 7 | +| **Excalidraw** | Wireframes and layout iteration | Steps 3-5 | +| **Puppeteer** | Browser screenshots for visual review | Step 8 | | **Nano Banana** | Image asset generation (photos, illustrations) | Asset creation only | -| **Design tokens** | Heading scale, spacing scale, component tokens | Step 8 | -| **Page specs** | Source of truth for structure and content | Steps 2, 5 | +| **Design tokens** | Heading scale, spacing scale, component tokens | Step 9 | +| **Page specs** | Source of truth for structure, content, and spacing | Steps 2, 6 | ### Tool boundaries @@ -108,11 +134,11 @@ When the wireframe and spec disagree, the spec must be updated before implementa ## Communication During Refinement -When making spacing or sizing changes during browser review (step 7), state the change in concrete terms: +When making spacing or sizing changes during browser review (step 8), state the change in concrete terms: > "Changed hero top padding from 48px to 64px" -Once design tokens exist (step 8), use token names: +Once design tokens exist (step 9), use token names: > "Changed hero top padding from **space-2xl** (48px) to **space-3xl** (64px)" @@ -122,7 +148,7 @@ This builds shared vocabulary. Over time, the user learns to say "change from sp ## When to Use This Loop -**Full loop (all 8 steps):** New pages where layout isn't obvious. Pages with complex information hierarchy. First page of a new scenario. +**Full loop (all 9 steps):** New pages where layout isn't obvious. Pages with complex information hierarchy. First page of a new scenario. **Partial loop (skip wireframe):** Pages that follow an established pattern. Second instance of a template page (e.g., vehicle type pages after the first one is done). Simple content pages. diff --git a/src/workflows/4-ux-design/steps-c/step-01-exploration.md b/src/workflows/4-ux-design/steps-c/step-01-exploration.md index fdaba8576..1db754828 100644 --- a/src/workflows/4-ux-design/steps-c/step-01-exploration.md +++ b/src/workflows/4-ux-design/steps-c/step-01-exploration.md @@ -155,7 +155,24 @@ When the discussion feels complete, summarize: Wireframe must be CLEAN — no annotations, no labels outside the page area. Design decisions belong in the page specification, not on the sketch. Present wireframe for review. The user can open the same .excalidraw file in VS Code and edit visually — both agent and user can modify the same artifact. ITERATE: When user gives feedback, update the wireframe. This loop is fast — JSON manipulation, seconds per change. Repeat until agreed. -SYNC SPEC: When wireframe is agreed, update the page specification to match. The spec is the source of truth — never implement from wireframe directly. + +**Approval gate — user exports PNG:** + +When the wireframe is agreed, ask the user to save a PNG snapshot: + + +**Wireframe agreed!** + +Before we move on — please export a PNG from Excalidraw and save it as: +`Sketches/{page-slug}-wireframe.png` + +This becomes the approved visual reference in the specification. The `.excalidraw` file stays as the editable source if we need to revisit later. + +Let me know when you've saved the image. + + +Wait for user confirmation that the PNG is saved. +SYNC SPEC: Update the page specification to match the agreed wireframe. Add a reference to the PNG in the spec's visual reference section. The spec is the source of truth — never implement from wireframe directly. Update design log: append row with status `wireframed` to `{output_folder}/_progress/00-progress.md` (see section 9) See `{designLoopGuide}` for the full design loop reference. diff --git a/src/workflows/4-ux-design/templates/page-specification.template.md b/src/workflows/4-ux-design/templates/page-specification.template.md index fc186e3ec..44cc54672 100644 --- a/src/workflows/4-ux-design/templates/page-specification.template.md +++ b/src/workflows/4-ux-design/templates/page-specification.template.md @@ -82,6 +82,49 @@ --- +## Spacing + + + +**Scale:** [Spacing Scale](../../D-Design-System/00-design-system.md#spacing-scale) + +| Property | Token | +|----------|-------| +| Page padding (horizontal) | {e.g., space-md mobile / space-lg desktop} | +| Section gap | {e.g., space-xl} | +| Element gap (default within sections) | {e.g., space-md} | +| Component gap (within groups) | {e.g., space-sm} | + +--- + +## Typography + + + +**Scale:** [Type Scale](../../D-Design-System/00-design-system.md#type-scale) + +| Element | Semantic | Size | Weight | Typeface | +|---------|----------|------|--------|----------| +| {Page title} | H1 | {e.g., text-2xl} | {e.g., bold} | {e.g., display / default} | +| {Section heading} | H2 | {e.g., text-xl} | {e.g., semibold} | {default} | +| {Body text} | p | text-md | normal | {default} | +| {Caption/helper} | p | {e.g., text-xs} | normal | {default} | + +--- + ## Page Sections ### Section: {Section Name} @@ -92,6 +135,8 @@ |----------|-------| | Purpose | {What this section does} | | Component | [{Design System Component}]({path}) | +| Padding | {e.g., space-lg space-md} | +| Element gap | {e.g., space-md — or "default" if same as page-level} | ---