Design System mode — tokens → components → pages three-layer workflow. Generate a complete token set (palette/type/spacing/motion/elevation/radius), confirm it, then all downstream outputs are visually consistent. Triggers on: ds, design system, tokens, create token set, define palette, define to...
---
name: variant-design-system
description: "Design System mode — tokens → components → pages three-layer workflow. Generate a complete token set (palette/type/spacing/motion/elevation/radius), confirm it, then all downstream outputs are visually consistent. Triggers on: ds, design system, tokens, create token set, define palette, define tokens, set up tokens, ds confirm, compose"
---
> Before generating code, load `skills/shared/code-output.md`, `references/project-context.md`, and `references/quality-baseline.md`.
For product-critical work, also read `references/design-declaration.md` and `references/product-integrity-gate.md`. A confirmed design system locks the declaration's product constraints as well as visual tokens.
## Design System Mode
The canonical workflow for production-quality work. Define once, generate consistently.
```
ds → confirm → component [name] → compose [page]
↑ ↑ ↑
Token foundation Atomic pieces Assembled layouts
```
### Triggers
| User says | Action |
|---|---|
| `ds` / "create a design system" / "define tokens" / "set up tokens" | Generate design system → preview → confirm |
| `ds confirm` | Lock the current design system and any product-critical Design Declaration for future outputs |
| `ds edit [section]` | Edit one section of the design system (palette / type / spacing / motion) without regenerating all |
| `ds show` | Print current design system token summary in terminal |
| `component [name]` (after DS confirmed) | Generate component using locked DS tokens, all 8 states |
| `compose [page name]` | Assemble confirmed components into a page, 3 layout variations |
| `compose [page] using A B C` | Compose page from specific named components |
### Step 1 — Generate Design System (`ds`)
**Before generating**, infer these dimensions from the brief and repository. Ask at most two material unanswered questions across the entire request; no mandatory intake:
1. **Brand personality** — 2–3 adjectives that describe the feel (e.g. "precise, warm, understated")
2. **Color direction** — existing brand color, or a reference (hex / site URL / mood word)
3. **Typeface preference** — existing fonts, or a direction ("editorial serif", "clean geometric sans", "monospace-forward")
If user says "surprise me" or has no preferences, infer from their codebase (README, existing CSS, component names) or pick a strongly opinionated direction and state it.
**Generate `variant-output/design-system.css`** — a complete, self-documenting token file:
```css
/* ═══════════════════════════════════════════════════
DESIGN SYSTEM — [Project Name]
Generated by variant-design · [date]
Confirm with: ds confirm
Edit with: ds edit [palette | type | spacing | motion | elevation | radius]
═══════════════════════════════════════════════════ */
/* ── Primitives ─────────────────────────────────── */
:root {
/* Color primitives — OKLCH */
--p-brand-50: oklch(97% 0.02 [H]);
--p-brand-100: oklch(93% 0.04 [H]);
--p-brand-200: oklch(86% 0.08 [H]);
--p-brand-300: oklch(76% 0.13 [H]);
--p-brand-400: oklch(66% 0.18 [H]);
--p-brand-500: oklch(56% 0.20 [H]); /* primary */
--p-brand-600: oklch(46% 0.18 [H]);
--p-brand-700: oklch(36% 0.15 [H]);
--p-brand-800: oklch(26% 0.10 [H]);
--p-brand-900: oklch(16% 0.06 [H]);
--p-neutral-50: oklch(98% 0.005 [H]);
--p-neutral-100: oklch(95% 0.008 [H]);
--p-neutral-200: oklch(90% 0.010 [H]);
--p-neutral-300: oklch(82% 0.012 [H]);
--p-neutral-400: oklch(68% 0.010 [H]);
--p-neutral-500: oklch(55% 0.008 [H]);
--p-neutral-600: oklch(42% 0.008 [H]);
--p-neutral-700: oklch(30% 0.006 [H]);
--p-neutral-800: oklch(20% 0.005 [H]);
--p-neutral-900: oklch(12% 0.004 [H]);
--p-success: oklch(55% 0.18 145);
--p-warning: oklch(60% 0.18 80);
--p-error: oklch(55% 0.22 25);
--p-info: oklch(55% 0.18 250);
}
/* ── Semantic tokens ─────────────────────────────── */
:root {
/* Surfaces */
--color-bg: var(--p-neutral-50);
--color-surface: #ffffff;
--color-surface-2: var(--p-neutral-100);
--color-surface-3: var(--p-neutral-200);
/* Borders */
--color-border: var(--p-neutral-200);
--color-border-strong: var(--p-neutral-300);
/* Text */
--color-text-primary: var(--p-neutral-900);
--color-text-secondary: var(--p-neutral-600);
--color-text-tertiary: var(--p-neutral-400);
--color-text-on-accent: #ffffff;
/* Brand */
--color-accent: var(--p-brand-500);
--color-accent-hover: var(--p-brand-600);
--color-accent-subtle: var(--p-brand-50);
--color-accent-border: var(--p-brand-200);
/* Semantic */
--color-success: var(--p-success);
--color-success-subtle: oklch(97% 0.03 145);
--color-warning: var(--p-warning);
--color-warning-subtle: oklch(98% 0.03 80);
--color-error: var(--p-error);
--color-error-subtle: oklch(97% 0.03 25);
}
/* ── Typography ─────────────────────────────────── */
:root {
--font-display: '[Display Font]', serif; /* or sans-serif */
--font-body: '[Body Font]', sans-serif;
--font-mono: 'IBM Plex Mono', monospace;
/* Scale — ratio [ratio] */
--text-xs: clamp(0.69rem, 0.65rem + 0.2vw, 0.75rem);
--text-sm: clamp(0.8rem, 0.77rem + 0.2vw, 0.875rem);
--text-base: clamp(0.95rem, 0.9rem + 0.25vw, 1.0625rem);
--text-lg: clamp(1.1rem, 1rem + 0.5vw, 1.25rem);
--text-xl: clamp(1.3rem, 1.1rem + 1vw, 1.75rem);
--text-2xl: clamp(1.6rem, 1.2rem + 2vw, 2.5rem);
--text-3xl: clamp(2rem, 1.4rem + 3vw, 3.5rem);
--text-4xl: clamp(2.5rem, 1.6rem + 5vw, 5.5rem);
/* Weights */
--font-weight-normal: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;
--font-weight-bold: 700;
/* Line heights */
--leading-tight: 1.2;
--leading-snug: 1.35;
--leading-normal: 1.5;
--leading-relaxed: 1.7;
/* Tracking */
--tracking-tight: -0.04em;
--tracking-snug: -0.02em;
--tracking-normal: 0;
--tracking-wide: 0.04em;
--tracking-caps: 0.08em;
}
/* ── Spacing ─────────────────────────────────────── */
:root {
/* 4pt base grid */
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 20px;
--space-6: 24px;
--space-8: 32px;
--space-10: 40px;
--space-12: 48px;
--space-16: 64px;
--space-20: 80px;
--space-24: 96px;
/* Layout */
--container-sm: 640px;
--container-md: 768px;
--container-lg: 1024px;
--container-xl: 1280px;
--container-2xl: 1440px;
}
/* ── Radius ──────────────────────────────────────── */
:root {
--radius-xs: 2px;
--radius-sm: 4px;
--radius-md: 6px;
--radius-lg: 10px;
--radius-xl: 16px;
--radius-2xl: 24px;
--radius-full: 9999px;
}
/* ── Elevation (shadow) ──────────────────────────── */
:root {
--shadow-xs: 0 1px 2px rgba(0,0,0,0.05);
--shadow-sm: 0 1px 4px rgba(0,0,0,0.07), 0 0 0 1px rgba(0,0,0,0.04);
--shadow-md: 0 4px 12px rgba(0,0,0,0.08), 0 0 0 1px rgba(0,0,0,0.04);
--shadow-lg: 0 8px 24px rgba(0,0,0,0.10), 0 0 0 1px rgba(0,0,0,0.04);
--shadow-xl: 0 16px 48px rgba(0,0,0,0.12), 0 0 0 1px rgba(0,0,0,0.05);
/* Focus ring */
--ring-width: 2px;
--ring-offset: 2px;
--ring-color: var(--color-accent);
}
/* ── Motion ──────────────────────────────────────── */
:root {
/* Durations */
--duration-instant: 80ms;
--duration-fast: 150ms;
--duration-normal: 250ms;
--duration-slow: 400ms;
--duration-slower: 600ms;
/* Easings */
--ease-out: cubic-bezier(0.0, 0.0, 0.2, 1);
--ease-in: cubic-bezier(0.4, 0.0, 1, 1);
--ease-in-out: cubic-bezier(0.4, 0.0, 0.2, 1);
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
--ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
/* Common transitions */
--transition-fast: all var(--duration-fast) var(--ease-out);
--transition-normal: all var(--duration-normal) var(--ease-out);
--transition-colors: color var(--duration-fast) var(--ease-out),
background-color var(--duration-fast) var(--ease-out),
border-color var(--duration-fast) var(--ease-out);
}
/* ── Z-index ─────────────────────────────────────── */
:root {
--z-base: 0;
--z-raised: 10;
--z-dropdown: 100;
--z-sticky: 200;
--z-overlay: 300;
--z-modal: 400;
--z-toast: 500;
}
```
**Also generate `variant-output/design-system-preview.html`** — a visual token preview showing:
- Color palette swatches (brand scale + neutrals + semantic)
- Typography specimens at each size step with sample text
- Spacing scale as a visual bar chart
- Shadow/elevation showcase
- Motion demo (hover cards to see transition, animated duration reference)
- Border radius examples
Open the preview immediately in browser.
### Step 2 — Confirm Design System (`ds confirm`)
When the user approves (says `ds confirm`, "looks good", "confirm this", "ship it"):
1. Write the confirmed status to `.variant-context.json`:
```json
{
"designSystem": {
"confirmed": true,
"file": "variant-output/design-system.css",
"palette": "[palette name]",
"fonts": ["[Display]", "[Body]"],
"confirmedAt": "[ISO date]"
}
}
```
2. Print confirmation:
```
✦ Design system confirmed — locked as visual foundation
File: variant-output/design-system.css
Palette: [name] · [hue]° OKLCH
Type: [Display font] + [Body font]
Next steps:
component [name] → build atomic components on this foundation
compose [page] → assemble components into page layouts
ds edit palette → refine colors before building
```
3. From this point forward, **all Generate, Component, and Compose outputs** must `<link rel="stylesheet" href="design-system.css">` (or inline the tokens) — no aesthetic invention allowed outside the locked token system.
4. For product-critical work, compile the confirmed declaration into `variant-output/design-contract.md` and run the Product Integrity Gate separately from the visual quality gate.
### Step 3 — Build Components (`component [name]`)
When design system is confirmed, Component Mode runs on a tighter brief:
- All colors from `design-system.css` semantic tokens — **no new colors**
- All spacing from `design-system.css` spacing scale — **no new values**
- Typography from `design-system.css` type tokens
- Add to component registry in `.variant-context.json`:
```json
{
"components": {
"button": "variant-output/component-button.html",
"card": "variant-output/component-card.html",
"form": "variant-output/component-form.html"
}
}
```
Terminal output:
```
✦ Component: Button System [DS: confirmed · Amber Warm · DM Sans]
Tokens used: --color-accent, --color-surface, --space-2/3/4, --radius-md
New tokens added: none
variant-output/component-button.html ← opened in browser
Registry: button · (no other components yet)
Next: component card · component form · compose [page] using button
```
### Step 4 — Compose Pages (`compose [page name]`)
Assembles registered components into page layouts. **3 structural variations** — layout and composition differ; visual language does not.
**Process:**
1. Read `.variant-context.json` to get component registry
2. Read `design-system.css` for tokens
3. For each variation, invent a different **structural arrangement**:
- Variation A: canonical / expected layout for this page type
- Variation B: unconventional hierarchy (e.g. sidebar-dominant, reversed stack)
- Variation C: density variant (compact/information-dense vs. spacious/editorial)
4. All three use identical tokens and components — the only differences are grid, order, proportion, and density
5. Write `variant-output/compose-[page]-A.html`, `-B.html`, `-C.html`
**What changes across compose variations:**
| Dimension | Can vary | Cannot vary |
|---|---|---|
| Grid structure | ✓ | |
| Section order / hierarchy | ✓ | |
| Column count / proportion | ✓ | |
| Density (padding, gap) | ✓ — within spacing scale | |
| Which components are prominent | ✓ | |
| Colors | | ✗ — all from DS |
| Typography | | ✗ — all from DS |
| Component visual design | | ✗ — use as-built |
| New spacing values | | ✗ — DS scale only |
Terminal output:
```
✦ Compose: Dashboard page [DS confirmed · 3 components registered]
Components used: button · card · data-table
Layout variations:
A — Standard: left sidebar + main content grid
B — Topbar: horizontal nav + full-width zones
C — Focused: single column, task-driven, no sidebar
Files:
variant-output/compose-dashboard-A.html ← opened in browser
variant-output/compose-dashboard-B.html
variant-output/compose-dashboard-C.html
Next: pick A/B/C · compose [another page] · tokens A
```
### DS Quick Triggers
| User types | Action |
|---|---|
| `ds` | Start design system generation workflow |
| `ds confirm` | Lock design system — constrains all future outputs |
| `ds show` | Print current DS summary (palette, fonts, status) |
| `ds edit palette` | Regenerate color section only, keep everything else |
| `ds edit type` | Regenerate typography section only |
| `ds edit spacing` | Regenerate spacing/radius section only |
| `ds edit motion` | Regenerate motion/animation section only |
| `ds preview` | Re-open design-system-preview.html in browser |
| `ds reset` | Remove DS lock, allow aesthetic invention again |
| `compose [page]` | Assemble page from registered components |
| `compose [page] using A B C` | Compose using only specified components |
| `registry` | Print component registry (which components are built) |
### When DS is NOT Confirmed
Standard Generate mode — full aesthetic invention per the normal workflow. Each variation picks its own palette, fonts, and direction.
### When DS IS Confirmed
Visual language is locked. The freedom space narrows to:
- Layout composition (grid, order, proportion)
- Content hierarchy (what's prominent, what's secondary)
- Interaction specifics (animation choreography within motion tokens)
- Copywriting and content strategy
Print a one-line reminder on every generation:
```
✦ DS locked: Amber Warm · DM Sans + Newsreader · variations differ in layout only
```
---
name: variant-design-system
description: "Design System mode — tokens → components → pages three-layer workflow. Generate a complete token set (palette/type/spacing/motion/elevation/radius), confirm it, then all downstream outputs are visually consistent. Triggers on: ds, design system, tokens, create token set, define palette, define tokens, set up tokens, ds confirm, compose"
---
> Before generating code, load `skills/shared/code-output.md`, `references/project-context.md`, and `references/quality-baseline.md`.
For product-critical work, also read `references/design-declaration.md` and `references/product-integrity-gate.md`. A confirmed design system locks the declaration's product constraints as well as visual tokens.
## Design System Mode
The canonical workflow for production-quality work. Define once, generate consistently.
```
ds → confirm → component [name] → compose [page]
↑ ↑ ↑
Token foundation Atomic pieces Assembled layouts
```
### Triggers
| User says | Action |
|---|---|
| `ds` / "create a design system" / "define tokens" / "set up tokens" | Generate design system → preview → confirm |
| `ds confirm` | Lock the current design system and any product-critical Design Declaration for future outputs |
| `ds edit [section]` | Edit one section of the design system (palette / type / spacing / motion) without regenerating all |
| `ds show` | Print current design system token summary in terminal |
| `component [name]` (after DS confirmed) | Generate component using locked DS tokens, all 8 states |
| `compose [page name]` | Assemble confirmed components into a page, 3 layout variations |
| `compose [page] using A B C` | Compose page from specific named components |
### Step 1 — Generate Design System (`ds`)
**Before generating**, infer these dimensions from the brief and repository. Ask at most two material unanswered questions across the entire request; no mandatory intake:
1. **Brand personality** — 2–3 adjectives that describe the feel (e.g. "precise, warm, understated")
2. **Color direction** — existing brand color, or a reference (hex / site URL / mood word)
3. **Typeface preference** — existing fonts, or a direction ("editorial serif", "clean geometric sans", "monospace-forward")
If user says "surprise me" or has no preferences, infer from their codebase (README, existing CSS, component names) or pick a strongly opinionated direction and state it.
**Generate `variant-output/design-system.css`** — a complete, self-documenting token file:
```css
/* ═══════════════════════════════════════════════════
DESIGN SYSTEM — [Project Name]
Generated by variant-design · [date]
Confirm with: ds confirm
Edit with: ds edit [palette | type | spacing | motion | elevation | radius]
═══════════════════════════════════════════════════ */
/* ── Primitives ─────────────────────────────────── */
:root {
/* Color primitives — OKLCH */
--p-brand-50: oklch(97% 0.02 [H]);
--p-brand-100: oklch(93% 0.04 [H]);
--p-brand-200: oklch(86% 0.08 [H]);
--p-brand-300: oklch(76% 0.13 [H]);
--p-brand-400: oklch(66% 0.18 [H]);
--p-brand-500: oklch(56% 0.20 [H]); /* primary */
--p-brand-600: oklch(46% 0.18 [H]);
--p-brand-700: oklch(36% 0.15 [H]);
--p-brand-800: oklch(26% 0.10 [H]);
--p-brand-900: oklch(16% 0.06 [H]);
--p-neutral-50: oklch(98% 0.005 [H]);
--p-neutral-100: oklch(95% 0.008 [H]);
--p-neutral-200: oklch(90% 0.010 [H]);
--p-neutral-300: oklch(82% 0.012 [H]);
--p-neutral-400: oklch(68% 0.010 [H]);
--p-neutral-500: oklch(55% 0.008 [H]);
--p-neutral-600: oklch(42% 0.008 [H]);
--p-neutral-700: oklch(30% 0.006 [H]);
--p-neutral-800: oklch(20% 0.005 [H]);
--p-neutral-900: oklch(12% 0.004 [H]);
--p-success: oklch(55% 0.18 145);
--p-warning: oklch(60% 0.18 80);
--p-error: oklch(55% 0.22 25);
--p-info: oklch(55% 0.18 250);
}
/* ── Semantic tokens ─────────────────────────────── */
:root {
/* Surfaces */
--color-bg: var(--p-neutral-50);
--color-surface: #ffffff;
--color-surface-2: var(--p-neutral-100);
--color-surface-3: var(--p-neutral-200);
/* Borders */
--color-border: var(--p-neutral-200);
--color-border-strong: var(--p-neutral-300);
/* Text */
--color-text-primary: var(--p-neutral-900);
--color-text-secondary: var(--p-neutral-600);
--color-text-tertiary: var(--p-neutral-400);
--color-text-on-accent: #ffffff;
/* Brand */
--color-accent: var(--p-brand-500);
--color-accent-hover: var(--p-brand-600);
--color-accent-subtle: var(--p-brand-50);
--color-accent-border: var(--p-brand-200);
/* Semantic */
--color-success: var(--p-success);
--color-success-subtle: oklch(97% 0.03 145);
--color-warning: var(--p-warning);
--color-warning-subtle: oklch(98% 0.03 80);
--color-error: var(--p-error);
--color-error-subtle: oklch(97% 0.03 25);
}
/* ── Typography ─────────────────────────────────── */
:root {
--font-display: '[Display Font]', serif; /* or sans-serif */
--font-body: '[Body Font]', sans-serif;
--font-mono: 'IBM Plex Mono', monospace;
/* Scale — ratio [ratio] */
--text-xs: clamp(0.69rem, 0.65rem + 0.2vw, 0.75rem);
--text-sm: clamp(0.8rem, 0.77rem + 0.2vw, 0.875rem);
--text-base: clamp(0.95rem, 0.9rem + 0.25vw, 1.0625rem);
--text-lg: clamp(1.1rem, 1rem + 0.5vw, 1.25rem);
--text-xl: clamp(1.3rem, 1.1rem + 1vw, 1.75rem);
--text-2xl: clamp(1.6rem, 1.2rem + 2vw, 2.5rem);
--text-3xl: clamp(2rem, 1.4rem + 3vw, 3.5rem);
--text-4xl: clamp(2.5rem, 1.6rem + 5vw, 5.5rem);
/* Weights */
--font-weight-normal: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;
--font-weight-bold: 700;
/* Line heights */
--leading-tight: 1.2;
--leading-snug: 1.35;
--leading-normal: 1.5;
--leading-relaxed: 1.7;
/* Tracking */
--tracking-tight: -0.04em;
--tracking-snug: -0.02em;
--tracking-normal: 0;
--tracking-wide: 0.04em;
--tracking-caps: 0.08em;
}
/* ── Spacing ─────────────────────────────────────── */
:root {
/* 4pt base grid */
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 20px;
--space-6: 24px;
--space-8: 32px;
--space-10: 40px;
--space-12: 48px;
--space-16: 64px;
--space-20: 80px;
--space-24: 96px;
/* Layout */
--container-sm: 640px;
--container-md: 768px;
--container-lg: 1024px;
--container-xl: 1280px;
--container-2xl: 1440px;
}
/* ── Radius ──────────────────────────────────────── */
:root {
--radius-xs: 2px;
--radius-sm: 4px;
--radius-md: 6px;
--radius-lg: 10px;
--radius-xl: 16px;
--radius-2xl: 24px;
--radius-full: 9999px;
}
/* ── Elevation (shadow) ──────────────────────────── */
:root {
--shadow-xs: 0 1px 2px rgba(0,0,0,0.05);
--shadow-sm: 0 1px 4px rgba(0,0,0,0.07), 0 0 0 1px rgba(0,0,0,0.04);
--shadow-md: 0 4px 12px rgba(0,0,0,0.08), 0 0 0 1px rgba(0,0,0,0.04);
--shadow-lg: 0 8px 24px rgba(0,0,0,0.10), 0 0 0 1px rgba(0,0,0,0.04);
--shadow-xl: 0 16px 48px rgba(0,0,0,0.12), 0 0 0 1px rgba(0,0,0,0.05);
/* Focus ring */
--ring-width: 2px;
--ring-offset: 2px;
--ring-color: var(--color-accent);
}
/* ── Motion ──────────────────────────────────────── */
:root {
/* Durations */
--duration-instant: 80ms;
--duration-fast: 150ms;
--duration-normal: 250ms;
--duration-slow: 400ms;
--duration-slower: 600ms;
/* Easings */
--ease-out: cubic-bezier(0.0, 0.0, 0.2, 1);
--ease-in: cubic-bezier(0.4, 0.0, 1, 1);
--ease-in-out: cubic-bezier(0.4, 0.0, 0.2, 1);
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
--ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
/* Common transitions */
--transition-fast: all var(--duration-fast) var(--ease-out);
--transition-normal: all var(--duration-normal) var(--ease-out);
--transition-colors: color var(--duration-fast) var(--ease-out),
background-color var(--duration-fast) var(--ease-out),
border-color var(--duration-fast) var(--ease-out);
}
/* ── Z-index ─────────────────────────────────────── */
:root {
--z-base: 0;
--z-raised: 10;
--z-dropdown: 100;
--z-sticky: 200;
--z-overlay: 300;
--z-modal: 400;
--z-toast: 500;
}
```
**Also generate `variant-output/design-system-preview.html`** — a visual token preview showing:
- Color palette swatches (brand scale + neutrals + semantic)
- Typography specimens at each size step with sample text
- Spacing scale as a visual bar chart
- Shadow/elevation showcase
- Motion demo (hover cards to see transition, animated duration reference)
- Border radius examples
Open the preview immediately in browser.
### Step 2 — Confirm Design System (`ds confirm`)
When the user approves (says `ds confirm`, "looks good", "confirm this", "ship it"):
1. Write the confirmed status to `.variant-context.json`:
```json
{
"designSystem": {
"confirmed": true,
"file": "variant-output/design-system.css",
"palette": "[palette name]",
"fonts": ["[Display]", "[Body]"],
"confirmedAt": "[ISO date]"
}
}
```
2. Print confirmation:
```
✦ Design system confirmed — locked as visual foundation
File: variant-output/design-system.css
Palette: [name] · [hue]° OKLCH
Type: [Display font] + [Body font]
Next steps:
component [name] → build atomic components on this foundation
compose [page] → assemble components into page layouts
ds edit palette → refine colors before building
```
3. From this point forward, **all Generate, Component, and Compose outputs** must `<link rel="stylesheet" href="design-system.css">` (or inline the tokens) — no aesthetic invention allowed outside the locked token system.
4. For product-critical work, compile the confirmed declaration into `variant-output/design-contract.md` and run the Product Integrity Gate separately from the visual quality gate.
### Step 3 — Build Components (`component [name]`)
When design system is confirmed, Component Mode runs on a tighter brief:
- All colors from `design-system.css` semantic tokens — **no new colors**
- All spacing from `design-system.css` spacing scale — **no new values**
- Typography from `design-system.css` type tokens
- Add to component registry in `.variant-context.json`:
```json
{
"components": {
"button": "variant-output/component-button.html",
"card": "variant-output/component-card.html",
"form": "variant-output/component-form.html"
}
}
```
Terminal output:
```
✦ Component: Button System [DS: confirmed · Amber Warm · DM Sans]
Tokens used: --color-accent, --color-surface, --space-2/3/4, --radius-md
New tokens added: none
variant-output/component-button.html ← opened in browser
Registry: button · (no other components yet)
Next: component card · component form · compose [page] using button
```
### Step 4 — Compose Pages (`compose [page name]`)
Assembles registered components into page layouts. **3 structural variations** — layout and composition differ; visual language does not.
**Process:**
1. Read `.variant-context.json` to get component registry
2. Read `design-system.css` for tokens
3. For each variation, invent a different **structural arrangement**:
- Variation A: canonical / expected layout for this page type
- Variation B: unconventional hierarchy (e.g. sidebar-dominant, reversed stack)
- Variation C: density variant (compact/information-dense vs. spacious/editorial)
4. All three use identical tokens and components — the only differences are grid, order, proportion, and density
5. Write `variant-output/compose-[page]-A.html`, `-B.html`, `-C.html`
**What changes across compose variations:**
| Dimension | Can vary | Cannot vary |
|---|---|---|
| Grid structure | ✓ | |
| Section order / hierarchy | ✓ | |
| Column count / proportion | ✓ | |
| Density (padding, gap) | ✓ — within spacing scale | |
| Which components are prominent | ✓ | |
| Colors | | ✗ — all from DS |
| Typography | | ✗ — all from DS |
| Component visual design | | ✗ — use as-built |
| New spacing values | | ✗ — DS scale only |
Terminal output:
```
✦ Compose: Dashboard page [DS confirmed · 3 components registered]
Components used: button · card · data-table
Layout variations:
A — Standard: left sidebar + main content grid
B — Topbar: horizontal nav + full-width zones
C — Focused: single column, task-driven, no sidebar
Files:
variant-output/compose-dashboard-A.html ← opened in browser
variant-output/compose-dashboard-B.html
variant-output/compose-dashboard-C.html
Next: pick A/B/C · compose [another page] · tokens A
```
### DS Quick Triggers
| User types | Action |
|---|---|
| `ds` | Start design system generation workflow |
| `ds confirm` | Lock design system — constrains all future outputs |
| `ds show` | Print current DS summary (palette, fonts, status) |
| `ds edit palette` | Regenerate color section only, keep everything else |
| `ds edit type` | Regenerate typography section only |
| `ds edit spacing` | Regenerate spacing/radius section only |
| `ds edit motion` | Regenerate motion/animation section only |
| `ds preview` | Re-open design-system-preview.html in browser |
| `ds reset` | Remove DS lock, allow aesthetic invention again |
| `compose [page]` | Assemble page from registered components |
| `compose [page] using A B C` | Compose using only specified components |
| `registry` | Print component registry (which components are built) |
### When DS is NOT Confirmed
Standard Generate mode — full aesthetic invention per the normal workflow. Each variation picks its own palette, fonts, and direction.
### When DS IS Confirmed
Visual language is locked. The freedom space narrows to:
- Layout composition (grid, order, proportion)
- Content hierarchy (what's prominent, what's secondary)
- Interaction specifics (animation choreography within motion tokens)
- Copywriting and content strategy
Print a one-line reminder on every generation:
```
✦ DS locked: Amber Warm · DM Sans + Newsreader · variations differ in layout only
```
Imported from the listed AgentSkill.sh category. Complete supplied package files and notices are retained. Required external tools and credentials are not installed. No bundled code was executed during import. Individual agent task behavior has not been tested.