wordle/.claude/skills/wds-0-project-setup/templates/folder-guides/00-design-system.template.md

Design System: {{project_name}}

Components, tokens, and patterns that grow from actual usage — not upfront planning.

Created: {{date}} Phase: 7 — Design System (optional) Agent: Freya (Designer)

---

What Belongs Here

The Design System captures reusable patterns that emerge during UX Design (Phase 4). It is not designed upfront — it crystallizes from real page specifications.

What goes here:

• Design Tokens — Colors, spacing, typography, shadows
• Components — Buttons, inputs, cards, navigation elements
• Patterns — Layouts, form structures, content blocks
• Visual Design — Mood boards, design concepts, color and typography explorations
• Assets — Logos, icons, images, graphics

What does NOT go here:

• Page-specific content (that lives in C-UX-Scenarios/)
• Business logic or API specs (that's BMM territory)
• Aspirational components nobody uses yet

When to skip this phase:

• Using shadcn/ui or Material UI → the library IS your design system
• Simple sites with Tailwind → tokens in tailwind.config are enough

Learn more:

• WDS Course Module 12: Functional Components — Patterns Emerge
• WDS Course Module 13: Design System

---

Folder Structure

D-Design-System/
├── 00-design-system.md          ← This file (hub + guide)
├── 01-Visual-Design/            [Early design exploration]
│   ├── mood-boards/             [Visual inspiration, style exploration]
│   ├── design-concepts/         [NanoBanana outputs, design explorations]
│   ├── color-exploration/       [Color palette experiments]
│   └── typography-tests/        [Font pairing and hierarchy tests]
├── 02-Assets/                   [Final production assets]
│   ├── logos/                   [Brand logos and variations]
│   ├── icons/                   [Icon sets]
│   ├── images/                  [Photography, illustrations]
│   └── graphics/                [Custom graphics and elements]
└── components/                  [Emerges during Phase 4]
    ├── interactive/             [Buttons, toggles, tabs]
    ├── form/                    [Inputs, selects, checkboxes]
    ├── layout/                  [Containers, grids, sections]
    ├── content/                 [Cards, lists, media blocks]
    ├── feedback/                [Alerts, toasts, progress]
    └── navigation/              [Menus, breadcrumbs, links]

01-Visual-Design/ is used early — before or during scenarios — for exploring visual direction. Mood boards, color palettes, typography tests, and AI-generated design concepts live here.

02-Assets/ holds final, production-ready assets. Logos, icons, images, and graphics that are referenced from page specifications.

components/ grows organically during Phase 4 as patterns emerge across page specifications.

---

For Agents

Workflow: skill:wds-7-design-system Agent trigger: DS (Freya) Router: ./resources/wds-7-design-system/design-system-router.md Templates: ./resources/wds-7-design-system/templates/ Guide: ./resources/agent-guides/freya/design-system.md

Before creating any component:

1. Check if it already exists in the chosen component library
2. Look at actual usage in C-UX-Scenarios/ page specs — extract, don't invent
3. Load the component template from the workflow templates folder

File naming: Number all documents with a two-digit prefix: 01-design-tokens.md, 02-button.md, etc. Update the sections below as each file is created.

Harm: Designing an abstract component library before any pages exist. Components without real usage are decoration. They waste time and create maintenance burden for patterns nobody needs.

Help: Extracting patterns from real page specs. When three pages use similar card layouts, that's a component. The design system documents what emerged, making future pages faster and more consistent.

---

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 (the baseline). Freya will propose pixel values during the first design session.

space-md is to spacing what text-md is to typography — the default you reach for first. It's the gap between paragraphs, between form fields, between list items. Everything else is relative to it: space-sm is tighter, space-lg is more generous.

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 (the baseline)
space-lg	—	Comfortable spacing (card padding, form fields)
space-xl	—	Section padding
space-2xl	—	Section gaps
space-3xl	—	Page-level breathing room

Optical adjustments

Sometimes the math is right but the eye says it's wrong. A circular image leaves white corners, a light element on a light background looks more spaced than it is. When this happens, use token math — not raw pixels:

space-lg - space-3xs    → "standard spacing, pulled in by a hairline"
space-xl + space-2xs    → "section padding, nudged out slightly"

In page specs, always annotate why:

| Padding top | space-lg - space-3xs (optical: circular image adds perceived whitespace) |

Rules:

• Adjustments always use token math: base ± correction
• Always annotate the reason — future readers need to know this wasn't a mistake
• If adjusting by more than one step, the base token is probably wrong — reconsider

In CSS: calc(var(--space-lg) - var(--space-3xs))

---

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 <p> 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

Additional design tokens (colors, shadows, borders) will be documented here as they emerge from page specifications.

---

Patterns

Spacing objects are first-class — they have IDs in page specs (e.g., hem-v-space-xl) and live here organized by value. Each spacing value accumulates the situations where it's used. The list grows from real design decisions.

Patterns will be documented here as spacing objects recur across pages.

---

Components

Components will be documented here as patterns emerge across scenarios.

---

Created using Whiteport Design Studio (WDS) methodology