mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-12 06:06:37 +03:00
Align DESIGN.md format with official Google Stitch spec
The format at https://stitch.withgoogle.com/docs/design-md/format/ defines exactly six sections in a fixed order: Overview, Colors, Typography, Elevation, Components, Do's and Don'ts. Our previous format used non-compliant names (Visual Theme & Atmosphere, Color Palette & Roles, Typography Rules, Component Stylings), a non-existent "Layout Principles" section, and had no Do's and Don'ts. Changes to reference/document.md: - Fixed section list to match the spec character-for-character - Added mandatory "Creative North Star" pattern at top of Overview - Added Named Rules pattern (e.g. "The No-Line Rule") — stickier than bullet lists for AI consumers, mirrors Stitch's own generator output - Added explicit Do's and Don'ts section with concrete, forceful guardrails - Elevation is now its own section (was buried in Components) - Layout/motion/responsive content folds into Overview + Components rather than inventing new top-level sections - Guidance on forceful voice ("prohibited"/"forbidden"/"never") matching PRODUCT.md's expert-decisive tone - Pitfalls section warns against renaming sections or adding new ones Changes to our DESIGN.md: - Rewrote to use spec-compliant section headers with evocative subtitles (e.g. "## 2. Colors: The Warm-Paper Palette") - Opened with "Creative North Star: The Editorial Sanctuary" - Added 11 Named Rules across sections (The One Voice Rule, The Paper- Not-White Rule, The OKLCH-Only Rule, The Italic-Is-Voice Rule, The 1.6 Leading Rule, The Fluid-Headlines-Only Rule, The Flat-By- Default Rule, The Low-Alpha Rule, The Tinted-Shadow-Only-For-Accent Rule, plus the existing implicit ones) - Full Do's and Don'ts section with 10 Dos and 15 Don'ts, many of which translate PRODUCT.md anti-references into concrete prohibitions - Elevation section documents shadow vocabulary separately from Components - Layout/spacing/motion content relocated to a sub-section under Components Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
866973fdcf
commit
1ebe204b1b
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and call the AskUserQuestion tool to clarify. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and call the AskUserQuestion tool to clarify. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. STOP and call the AskUserQuestion tool to clarify. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and call the `question` tool to clarify. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and call the `question` tool to clarify. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. STOP and call the `question` tool to clarify. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
@@ -9,7 +20,7 @@ DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. ask the user directly to clarify what you cannot infer. for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
@@ -0,0 +1,184 @@
|
||||
# Design System: Impeccable
|
||||
|
||||
## 1. Overview: The Editorial Sanctuary
|
||||
|
||||
**Creative North Star: "The Editorial Sanctuary"**
|
||||
|
||||
The Impeccable site reads more like a printed design publication than a SaaS landing page. Committed typography, generous breathing room, and a single decisive accent that cuts through warm paper. The interface feels **considered, unhurried, and expert** — the work of someone who has made the calls a thousand times and has zero interest in chasing the current AI-tool aesthetic.
|
||||
|
||||
The aesthetic philosophy is **restraint in service of craft**. Every element earns its place. Nothing is decorative without function. The palette is dominated by warm paper tones with one vibrant voice. The typography pairs a stately italic serif with a clean neutral sans. Motion is reserved for moments that actually communicate state. The site is the demo — it must pass the same anti-pattern audit it asks its users to run on their own work.
|
||||
|
||||
This system explicitly rejects the AI-tool visual vocabulary that surrounds the product: dark mode with purple gradients, neon accents, glassmorphism, glowing cyan-on-black, SaaS hero-metric layouts, and identical-card feature grids. When in doubt, do less than a marketing site would, more than a portfolio would.
|
||||
|
||||
**Key Characteristics:**
|
||||
- Warm off-white paper tones with an almost-imperceptible magenta tint for subliminal palette cohesion.
|
||||
- A single decisive magenta accent used on no more than 10% of any screen. Its rarity is the point.
|
||||
- Italic serif for display type; clean neutral sans for body at 1.6+ line-height.
|
||||
- Sharp, uppercase, letter-tracked primary CTAs — no rounded-rectangle-with-drop-shadow defaults.
|
||||
- Flat surfaces at rest. Shadows appear only as a response to state (hover, elevation, focus).
|
||||
- Asymmetric magazine-scale spacing; intentionally skips the 4px step.
|
||||
|
||||
## 2. Colors: The Warm-Paper Palette
|
||||
|
||||
A two-chord palette: warm paper neutrals carrying a near-invisible magenta tint, plus one decisive accent in the same hue family. No secondary or tertiary accents in the core system — the restraint is doctrinal.
|
||||
|
||||
### Primary
|
||||
- **Editorial Magenta** (oklch(60% 0.25 350)): The one vibrant voice. Primary CTAs, active navigation states, live-state indicators, rare editorial emphasis. Never used as a gradient, never as a background wash, never as text fill. Rarity is the design choice.
|
||||
|
||||
### Neutral
|
||||
- **Warm Ash Cream** (oklch(96% 0.005 350)): Primary page background. Near-white with a near-imperceptible magenta tint that creates subconscious cohesion with Editorial Magenta. Used on `body` and standard surfaces.
|
||||
- **Crisp Paper White** (oklch(98% 0 0)): Pure background. Used for inverted text moments (white-on-dark CTAs) and surfaces needing maximum contrast. Almost never the page background — too cold alone.
|
||||
- **Deep Graphite** (oklch(10% 0 0)): Primary text for body copy and headlines. Softer than pure black, reads as confident-but-not-aggressive on warm paper. Background of the primary CTA.
|
||||
- **Soft Charcoal** (oklch(25% 0 0)): Secondary text — taglines, hook paragraphs, supporting copy. Clearly subordinate to Deep Graphite without being washed out.
|
||||
- **Mid Ash** (oklch(55% 0 0)): Tertiary text — micro-labels, captions, meta lines, "works with" labels. At small sizes reads as intentionally recessed metadata.
|
||||
- **Paper Mist** (oklch(92% 0 0)): Hairline borders, section dividers, the barely-visible structural seams.
|
||||
|
||||
### Accent Alpha Variants
|
||||
- **Editorial Magenta Deep** (oklch(52% 0.25 350)): Hover/active state for Editorial Magenta. Small darkening, confirms interaction without shouting.
|
||||
- **Magenta Whisper** (oklch(60% 0.25 350 / 0.15)): Glow backdrop under accent elements on hover (diffuse shadows only), subtle selection highlights.
|
||||
- **Magenta Veil** (oklch(60% 0.25 350 / 0.25)): Slightly stronger translucent tint for focus rings and emphasis shells.
|
||||
|
||||
### Command Category Tints (fenced — do not extend)
|
||||
A separate six-tint vocabulary used exclusively to color-code the periodic-table visualization of impeccable's 23 commands. These tints predate the OKLCH system and live in one component. **Do not extend this vocabulary elsewhere.**
|
||||
|
||||
- **Create** (bg `#fdf2f8` / border `#ec4899` / text `#be185d`)
|
||||
- **Evaluate** (bg `#fdf4ff` / border `#d946ef` / text `#a21caf`)
|
||||
- **Refine** (bg `#eff6ff` / border `#3b82f6` / text `#1d4ed8`)
|
||||
- **Simplify** (bg `#fffbeb` / border `#f59e0b` / text `#b45309`)
|
||||
- **Harden** (bg `#f0fdf4` / border `#22c55e` / text `#15803d`)
|
||||
- **System** (bg `#f5f5f4` / border `#78716c` / text `#44403c`)
|
||||
|
||||
### Named Rules
|
||||
|
||||
**The One Voice Rule.** Editorial Magenta is the only vibrant color in the system. No supporting accent is added, ever, no matter how much a layout "wants" a second color. If a second emphasis point is needed, use scale or weight, never a second hue.
|
||||
|
||||
**The Paper-Not-White Rule.** The page background is Warm Ash Cream, never Crisp Paper White. Pure white is reserved for specific inverted surfaces. Warmth is load-bearing — without it, the site reads as generic and the decisive magenta reads as abrasive rather than decisive.
|
||||
|
||||
**The OKLCH-Only Rule.** All new colors must be declared in OKLCH. Legacy hex values exist only in the fenced Command Category Tints. Do not introduce new hex-declared colors into the system.
|
||||
|
||||
## 3. Typography: The Italic-and-Ink Voice
|
||||
|
||||
**Display Font:** Cormorant Garamond (with Georgia fallback)
|
||||
**Body Font:** Instrument Sans (with system-ui fallback)
|
||||
**Label/Mono Font:** Space Grotesk (used as a geometric mono, not for code blocks)
|
||||
|
||||
**Character:** The display face is a refined transitional serif used in its **italic** cut — stately without being stuffy, drawing on long-form editorial headline traditions. The body face is a clean neutral sans with subtle geometric warmth, chosen to set long paragraphs without visual overhead. The "mono" is a contemporary grotesque reserved for small labels and metadata where a machine-adjacent feel reinforces the command-line product story.
|
||||
|
||||
### Hierarchy
|
||||
|
||||
- **Display** (display family, weight 300, italic, clamp(2.5rem, 7vw, 4.5rem), line-height 1): Hero title only. The light weight + italic cursive reads as an author signature rather than a marketing headline.
|
||||
- **Headline** (display family, weight 400, clamp(1.75rem, 4vw, 2.5rem), line-height 1.2): Section headings. Larger editorial moments.
|
||||
- **Title** (display family, weight 400, italic, clamp(1.125rem, 2.5vw, 1.75rem), line-height 1.3): Hero tagline / section leads. A quieter second display voice.
|
||||
- **Body** (body family, weight 400, 1rem, line-height 1.6): Paragraph copy. Capped at 65–75ch for readability.
|
||||
- **Body Lead** (body family, weight 400, 1rem–1.0625rem, line-height 1.6–1.65): The one or two "lead" paragraphs on each page. Slightly relaxed leading.
|
||||
- **Supporting** (body family, weight 400, 0.875rem, line-height 1.6): Captions, footnotes, supporting context.
|
||||
- **Label** (body family, weight 500, 0.9rem, `text-transform: uppercase`, `letter-spacing: 0.05em`): CTA labels. Short, declarative.
|
||||
- **Micro-Label** (body family, weight 500, 0.625–0.6875rem, `text-transform: uppercase`, `letter-spacing: 0.1em`): "Works with", "What's Included", "v3.0 Changelog".
|
||||
- **Monospace Meta** (mono family, weight 400–500, 0.6875–0.8125rem): Command names in inline prose, periodic-table tile labels.
|
||||
|
||||
### Named Rules
|
||||
|
||||
**The Italic-Is-Voice Rule.** Italic is used as a voice choice for display type, not as emphasis within body copy. Body emphasis is carried by weight or by swapping to the mono family (see `<em>` in command menus). Treating italic as emphasis inside paragraphs dilutes the display voice.
|
||||
|
||||
**The 1.6 Leading Rule.** Body line-height is 1.6 everywhere. Not 1.5, not 1.7, not "relaxed". This is the load-bearing readability decision — when the site reads as calm and editorial, it's 1.6 doing the work.
|
||||
|
||||
**The Fluid-Headlines-Only Rule.** Headings use `clamp()` fluid sizing. Body copy uses fixed `rem` values. Fluid body sizes look clever and feel wrong — they make line-lengths wander off spec.
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
Flat by default. Depth is conveyed through **state response**, not structural shadow. Surfaces rest on a single tonal layer (Warm Ash Cream); shadows appear only when an element is hovered, deliberately lifted, or requires ambient separation from a busy area.
|
||||
|
||||
### Shadow Vocabulary
|
||||
|
||||
- **Soft Hover Lift** (`0 4px 24px -4px rgba(0,0,0,0.12), 0 1px 3px rgba(0,0,0,0.06)`): The default hover response on cards and interactive surfaces. Diffuse, offset downward.
|
||||
- **Lifted Card** (`0 20px 40px rgba(0,0,0,0.08)`): Deliberately elevated content (featured cards, install blocks). Low alpha — never reads as dark.
|
||||
- **Accent Glow** (`0 20px 60px var(--color-accent-dim)`): Magenta-tinted ambient shadow under the one or two moments that should feel magnetic. Used sparingly — this is the "rare ingredient" of the shadow vocabulary.
|
||||
- **Tooltip / Popover** (`0 0 20px rgba(0,0,0,0.15)` or `0 2px 8px rgba(0,0,0,0.1)`): Tight shadow for small floating UI.
|
||||
|
||||
### Named Rules
|
||||
|
||||
**The Flat-By-Default Rule.** Surfaces are flat at rest. If you find yourself adding a shadow to a non-interactive, non-elevated element, stop — you're reaching for Material Design muscle memory. Use a hairline Paper Mist border instead, or no articulation at all.
|
||||
|
||||
**The Low-Alpha Rule.** Every shadow in the system uses ≤0.15 alpha on its strongest blur. Higher alphas read as 2014 Material Design drop shadows — an immediate tell that the design wasn't considered.
|
||||
|
||||
**The Tinted-Shadow-Only-For-Accent Rule.** Neutral shadows (black alpha) for structure. Colored (magenta-dim) shadows only for the deliberate accent-glow moments. Never tint shadows for decorative effect.
|
||||
|
||||
## 5. Components
|
||||
|
||||
### Buttons
|
||||
|
||||
- **Shape:** Flat and squared by default (`border-radius: 0`). Sharp corners are an explicit editorial choice — the site rejects the rounded-rectangle-with-drop-shadow default that marks most AI-adjacent marketing pages.
|
||||
- **Primary (hero-cta-combined):** Deep Graphite background, Crisp Paper White text. Padding 16px / 48px (`--spacing-sm` / `--spacing-xl`). Uppercase, `letter-spacing: 0.05em`, weight 500. No border, no shadow at rest.
|
||||
- **Hover:** `transform: translateY(-2px)` and background shifts to Editorial Magenta. Transition 200ms linear ease. A small confident step up, never a bounce.
|
||||
- **Focus:** Browser-default focus ring combined with the hover treatment. Visible keyboard focus is required.
|
||||
- **Secondary:** Inline text link in body copy, weight 500, hover shifts to Editorial Magenta. **No boxed secondary button exists in the system** — the site avoids the "stack of equal-weight CTAs" pattern entirely.
|
||||
- **Chip (picker overlay):** Radius 3–5px, small padding, mono-family label. Used in the live-mode action selector.
|
||||
|
||||
### Cards & Containers
|
||||
|
||||
- **Corner Style:** Controlled vocabulary — 4px (chips / inline callouts), 8px (standard cards and card-CTAs), 12px (feature cards, install blocks), 16px (large content frames). No single "rounded-lg" default. Radius is picked per component weight.
|
||||
- **Background:** Warm Ash Cream or Crisp Paper White depending on layering. Deeper nested surfaces may lift to Paper Mist as a near-imperceptible tone shift.
|
||||
- **Shadow:** Flat at rest — see Elevation for the shadow vocabulary that applies on hover/lift.
|
||||
- **Border:** Hairline 1px in Paper Mist when a surface needs articulation without shadow.
|
||||
- **Internal Padding:** 16–32px for typical cards; large editorial frames 48px+. Padding matches visual weight, not applied uniformly.
|
||||
|
||||
### Inputs / Fields
|
||||
|
||||
The site is primarily editorial, so inputs are minimal:
|
||||
|
||||
- **Email / text field:** Radius 4–6px, hairline Paper Mist border, transparent background. Focus state shifts border to Editorial Magenta with a Magenta Whisper backdrop glow.
|
||||
- **Combobox / select (filter controls):** Same stroke vocabulary, smaller padding, chevron glyph in Mid Ash.
|
||||
- **No custom checkbox/radio styling** beyond what the live-mode command picker needs.
|
||||
|
||||
### Navigation
|
||||
|
||||
- **Site Header:** 62px compact bar, left-aligned brand lockup (monochrome mark + wordmark), right-aligned link cluster.
|
||||
- **Typography:** Body family, weight 500, 0.9–1rem. Normal case — the header is readable prose, not a set of signals.
|
||||
- **Default State:** Deep Graphite on Warm Ash Cream.
|
||||
- **Hover / Active:** Smooth color transition to Editorial Magenta, 200ms. No underline bar at rest; if an active indicator is needed, a thin accent-colored underline appears.
|
||||
- **Mobile:** Collapses to an icon-triggered drawer when horizontal space is insufficient.
|
||||
|
||||
### Periodic Table of Commands (signature component)
|
||||
|
||||
A distinctive custom element worth documenting: the 23 commands are laid out as a periodic-table grid of 56×64px tiles, each with a category tint background, category-colored border, atomic number in the top-left (mono family, 7px), a symbol in the center (display family, weight 500, 20px), and a command label in mono below. Hover lifts the tile 2px with a category-colored shadow. Tiles are the one place where the Category Tint vocabulary (see Colors) is used on a colored surface rather than as a text accent.
|
||||
|
||||
### Layout & Spacing (fold from spec-absent Layout section)
|
||||
|
||||
- **Max width:** Content blocks cap at 900px (`--width-content`); page-level containers at 1400px (`--width-max`). Prose further constrained to 65–75ch.
|
||||
- **Spacing scale:** 8 / 16 / 24 / 32 / 48 / 80 / 120px (`--spacing-xs` through `--spacing-3xl`). The 4px step is deliberately omitted — this is an editorial scale, not an app-UI scale.
|
||||
- **Rhythm:** 80–120px between top-level sections, 24–48px between content groups within a section, 6–16px inside tight clusters.
|
||||
- **Grid:** No traditional column grid. Hero layouts are asymmetric two-column splits. Feature sections use `repeat(auto-fit, minmax(280px, 1fr))` rather than breakpoint-driven columns.
|
||||
- **Motion:** 150ms for color/opacity, 300–400ms for transforms, 600–1200ms for orchestrated entrances. All use `--ease-out` (`cubic-bezier(0.16, 1, 0.3, 1)`) or `--ease-out-quint`. `prefers-reduced-motion` collapses every non-essential transition.
|
||||
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
### Do:
|
||||
|
||||
- **Do** treat Warm Ash Cream (not Crisp Paper White) as the default page background. Warmth is load-bearing — see The Paper-Not-White Rule.
|
||||
- **Do** use Editorial Magenta on ≤10% of any given screen. Scarcity is what makes it read as decisive rather than noisy — see The One Voice Rule.
|
||||
- **Do** set all new colors in OKLCH. Hex is for the fenced Command Category Tints only.
|
||||
- **Do** use italic display type as a voice, not as emphasis inside paragraphs. Body emphasis is carried by weight.
|
||||
- **Do** use `clamp()` fluid sizing for headings; use fixed `rem` for body — see The Fluid-Headlines-Only Rule.
|
||||
- **Do** keep the primary CTA sharp and squared. `border-radius: 0`, uppercase, letter-tracked. This is the editorial signature.
|
||||
- **Do** use `--ease-out` (`cubic-bezier(0.16, 1, 0.3, 1)`) or `--ease-out-quint` on transitions. Expo-out only.
|
||||
- **Do** leave surfaces flat at rest. Reach for shadows only on hover or for deliberate elevation — see The Flat-By-Default Rule.
|
||||
- **Do** respect `prefers-reduced-motion` on every animation.
|
||||
- **Do** cap body line length at 65–75ch via `max-width`.
|
||||
|
||||
### Don't:
|
||||
|
||||
- **Don't** use pure black (#000) or pure white (#fff). Always the tinted neutrals (Deep Graphite / Warm Ash Cream / Crisp Paper White).
|
||||
- **Don't** use `border-left` or `border-right` greater than 1px as a colored stripe on cards, list items, callouts, or alerts. Ever. This is the single most recognizable AI-dashboard tell.
|
||||
- **Don't** use `background-clip: text` with a gradient. Gradient text is banned across the site. If you want emphasis, use weight or size, never gradient fill.
|
||||
- **Don't** default to dark mode. The site is light mode because editorial reading is a light-mode activity. Dark mode with glowing accents is the AI-tool aesthetic Impeccable exists to replace.
|
||||
- **Don't** use glassmorphism (blurred translucent cards, glass borders, glow backgrounds as decoration). It is on PRODUCT.md's explicit anti-reference list.
|
||||
- **Don't** add a second accent color. If a layout "needs" a second emphasis point, use scale or weight, not hue.
|
||||
- **Don't** use rounded rectangles with generic drop shadows. That's the "could be any AI output" fingerprint.
|
||||
- **Don't** use bounce or elastic easing. Real objects decelerate smoothly — expo-out is the signature.
|
||||
- **Don't** animate layout properties (`width`, `height`, `padding`, `margin`). Use `transform` and `opacity` only.
|
||||
- **Don't** nest cards inside cards. Flatten the hierarchy.
|
||||
- **Don't** use identical card grids (same-sized cards with icon + heading + text, repeated endlessly).
|
||||
- **Don't** use the hero-metric layout template (big number + small label + supporting stats + gradient accent). SaaS cliché.
|
||||
- **Don't** extend the Command Category Tints vocabulary. Those hex tints are scoped to the periodic-table viz.
|
||||
- **Don't** hedge in UI copy. "Maybe consider" and "could be helpful" are banned in-product — match PRODUCT.md's expert-decisive voice.
|
||||
- **Don't** introduce a new spacing token outside the 8/16/24/32/48/80/120 scale. If you need a specific pixel gap, use a literal value rather than polluting the token scale.
|
||||
@@ -1,15 +1,26 @@
|
||||
Generate a DESIGN.md file in the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
Generate a `DESIGN.md` file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand.
|
||||
|
||||
DESIGN.md follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): a single markdown file at the project root with five fixed sections describing colors, typography, components, layout, and overall atmosphere. Keep section headers exactly as specified so the file stays compatible with other DESIGN.md-aware tools.
|
||||
DESIGN.md follows the [official Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/): exactly six sections in a fixed order. Sections may be omitted when not relevant, but **do not reorder them and do not rename them**. Section headers must match the spec character-for-character so the file stays parseable by other DESIGN.md-aware tools (Stitch itself, awesome-design-md, skill-rest, etc.).
|
||||
|
||||
## The six sections (exact order)
|
||||
|
||||
1. `## Overview`
|
||||
2. `## Colors`
|
||||
3. `## Typography`
|
||||
4. `## Elevation`
|
||||
5. `## Components`
|
||||
6. `## Do's and Don'ts`
|
||||
|
||||
Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs.
|
||||
|
||||
## When to run
|
||||
|
||||
- The user just ran `{{command_prefix}}impeccable teach` and needs the visual side documented.
|
||||
- The user just ran `/impeccable teach` and needs the visual side documented.
|
||||
- The skill noticed no `DESIGN.md` exists and nudged the user to create one.
|
||||
- An existing `DESIGN.md` is stale (the design has drifted).
|
||||
- Before a large redesign, to capture the current state as a reference.
|
||||
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and {{ask_instruction}} whether to refresh it, overwrite it, or merge into it.
|
||||
If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and {{ask_instruction}} whether to refresh, overwrite, or merge.
|
||||
|
||||
## Process (approach C: auto-extract, then confirm descriptive language)
|
||||
|
||||
@@ -19,7 +30,7 @@ Search the codebase in priority order:
|
||||
|
||||
1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in.
|
||||
2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow.
|
||||
3. **CSS-in-JS theme files** — if the project uses styled-components, emotion, vanilla-extract, stitches, etc., look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent.
|
||||
4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format.
|
||||
5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles.
|
||||
6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments.
|
||||
@@ -29,93 +40,143 @@ Search the codebase in priority order:
|
||||
|
||||
Build a structured draft from the discovered tokens. For each token class:
|
||||
|
||||
- **Colors**: Group by hue family. Convert hex → OKLCH to infer lightness/chroma. Identify background vs. text vs. accent by usage patterns in CSS (`background`, `color`, `border`, `fill`). Flag any that are only used once (possibly one-off, not system tokens).
|
||||
- **Typography**: Extract font families and their declared stacks. Extract the scale (all `font-size` values used in CSS custom props + component styles). Extract weights actually used. Detect the scale ratio (1.125, 1.2, 1.25, 1.333, 1.5, golden).
|
||||
- **Spacing**: Extract the scale, detect the base unit (4px, 8px, other).
|
||||
- **Radii & shadows**: List the values used.
|
||||
- **Components**: For each common component (button, card, input, nav, dialog), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them.
|
||||
- **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio.
|
||||
- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly.
|
||||
- **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding.
|
||||
- **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section.
|
||||
|
||||
### Step 3: Ask the user for qualitative language
|
||||
|
||||
The following sections require creative input that cannot be auto-extracted reliably. {{ask_instruction}} for each (group them into one interaction if possible):
|
||||
The following require creative input that cannot be auto-extracted. Group them into one `AskUserQuestion` interaction:
|
||||
|
||||
- **Visual Theme & Atmosphere**: mood adjectives (airy/dense, minimal/maximalist, editorial/utilitarian, warm/clinical), aesthetic philosophy in 2-3 sentences, key characteristics as a bullet list.
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per color based on the hue/saturation, let the user pick.
|
||||
- **Typographic character**: describe the font pairing ("Modern geometric sans-serif with humanist warmth" > "Manrope 500"). Describe letter-spacing strategy.
|
||||
- **Spacing philosophy**: 1-2 sentences on whitespace strategy ("generous breathing room that prioritizes photography").
|
||||
- **Component philosophy**: brief description of the feel of buttons, cards, inputs ("refined and understated" vs. "tactile and confident").
|
||||
- **Creative North Star**: a single named metaphor for the whole system ("The Editorial Sanctuary", "The Golden State Curator", "The Lab Notebook"). Offer 2-3 options that honor PRODUCT.md's brand personality.
|
||||
- **Overview voice**: mood adjectives, aesthetic philosophy in 2-3 sentences, anti-references (what the system should not feel like).
|
||||
- **Color character** (for auto-extracted colors): descriptive names ("Deep Muted Teal-Navy", not "blue-800"). Suggest 2-3 options per key color based on hue/saturation.
|
||||
- **Elevation philosophy**: flat/layered/lifted. If shadows exist, is their role ambient or structural?
|
||||
- **Component philosophy**: the feel of buttons, cards, inputs in one phrase ("tactile and confident" vs. "refined and restrained").
|
||||
|
||||
If the user has a `PRODUCT.md` that covers brand personality, quote a line from it so they see their own strategic language carry over.
|
||||
Quote a line from PRODUCT.md when possible so the user sees their own strategic language carry forward.
|
||||
|
||||
### Step 4: Write DESIGN.md
|
||||
|
||||
Use this exact structure (section headers must match the Google spec character-for-character):
|
||||
Use this exact structure. Headers must match character-for-character. Optional evocative subtitles (e.g. `## 2. Colors: The Coastal Palette`) are allowed.
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [optional — only if a Stitch project ID exists]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
## 1. Overview
|
||||
|
||||
[2-3 paragraph description using evocative adjectives. Start with the overall sanctuary/laboratory/workshop/stage analogy if one fits. End with a short **Key Characteristics:** bullet list.]
|
||||
**Creative North Star: "[Named metaphor in quotes]"**
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
[2-3 paragraph holistic description: personality, density, aesthetic philosophy. Start from the North Star and work outward. State what this system explicitly rejects (pulled from PRODUCT.md's anti-references). End with a short **Key Characteristics:** bullet list.]
|
||||
|
||||
### [Semantic group name: Primary Foundation, Accent & Interactive, Typography & Text Hierarchy, Functional States, etc.]
|
||||
- **[Descriptive Name]** (#HEX) – [Functional role. Where/why it's used.]
|
||||
## 2. Colors
|
||||
|
||||
## 3. Typography Rules
|
||||
[Describe the palette character in one sentence.]
|
||||
|
||||
**Primary Font Family:** [Name]
|
||||
**Character:** [1-sentence personality description.]
|
||||
### Primary
|
||||
- **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.]
|
||||
|
||||
### Hierarchy & Weights
|
||||
- **[Role (e.g. Display Headlines H1)]:** [Weight] weight ([num]), [letter-spacing], [size]. [Purpose.]
|
||||
### Secondary (optional — omit if the project has only one accent)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
### Spacing Principles
|
||||
[Short list of rules about leading, letter-spacing, vertical rhythm.]
|
||||
### Tertiary (optional)
|
||||
- **[Descriptive Name]** (#HEX): [Role.]
|
||||
|
||||
## 4. Component Stylings
|
||||
### Neutral
|
||||
- **[Descriptive Name]** (#HEX): [Text / background / border / divider role.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional, powerful)
|
||||
**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."]
|
||||
|
||||
## 3. Typography
|
||||
|
||||
**Display Font:** [Family] (with [fallback])
|
||||
**Body Font:** [Family] (with [fallback])
|
||||
**Label/Mono Font:** [Family, if distinct]
|
||||
|
||||
**Character:** [1-2 sentence personality description of the pairing.]
|
||||
|
||||
### Hierarchy
|
||||
- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.]
|
||||
- **Headline** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Title** ([weight], [size], [line-height]): [Purpose.]
|
||||
- **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.]
|
||||
- **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [Purpose.]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [Short doctrine about type use.]
|
||||
|
||||
## 4. Elevation
|
||||
|
||||
[One paragraph: does this system use shadows, tonal layering, or a hybrid? If "no shadows", say so explicitly and describe how depth is conveyed instead.]
|
||||
|
||||
### Shadow Vocabulary (if applicable)
|
||||
- **[Role name]** (`box-shadow: [exact value]`): [When to use it.]
|
||||
- [...]
|
||||
|
||||
### Named Rules (optional)
|
||||
**The [Rule Name] Rule.** [e.g. "The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus)."]
|
||||
|
||||
## 5. Components
|
||||
|
||||
For each component, lead with a short character line, then specify shape, color assignment, states, and any distinctive behavior.
|
||||
|
||||
### Buttons
|
||||
- **Shape:** [radius description with px value in parens]
|
||||
- **Primary CTA:** [color assignment + padding]
|
||||
- **Hover State:** [transition description]
|
||||
- **Focus State:** [accessibility treatment]
|
||||
- **Secondary CTA (if applicable):** [description]
|
||||
- **Shape:** [radius described, exact value in parens]
|
||||
- **Primary:** [color assignment + padding, in semantic + exact terms]
|
||||
- **Hover / Focus:** [transitions, treatments]
|
||||
- **Secondary / Ghost / Tertiary (if applicable):** [brief description]
|
||||
|
||||
### Cards & Containers
|
||||
- **Corner Style:** [description]
|
||||
### Chips (if used)
|
||||
- **Style:** [background, text color, border treatment]
|
||||
- **State:** [selected / unselected, filter / action variants]
|
||||
|
||||
### Cards / Containers
|
||||
- **Corner Style:** [radius]
|
||||
- **Background:** [colors used]
|
||||
- **Shadow Strategy:** [flat / soft / heavy]
|
||||
- **Shadow Strategy:** [reference Elevation section]
|
||||
- **Border:** [if any]
|
||||
- **Internal Padding:** [scale]
|
||||
- **Image Treatment:** [if relevant]
|
||||
|
||||
### Inputs / Fields
|
||||
- **Style:** [stroke, background, radius]
|
||||
- **Focus:** [treatment — glow, border shift, etc.]
|
||||
- **Error / Disabled:** [if applicable]
|
||||
|
||||
### Navigation
|
||||
- [Style, typography, default/hover/active states, mobile treatment]
|
||||
- **Style, typography, default/hover/active states, mobile treatment.**
|
||||
|
||||
### Inputs/Forms
|
||||
- [Stroke style, background, focus treatment]
|
||||
### [Signature Component] (optional — if the project has a distinctive custom component worth documenting)
|
||||
[Description.]
|
||||
|
||||
## 5. Layout Principles
|
||||
## 6. Do's and Don'ts
|
||||
|
||||
[Paragraph or short list describing whitespace strategy, margin scale, grid system, responsive breakpoints. Include px/rem values in parens.]
|
||||
Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md.
|
||||
|
||||
### Do:
|
||||
- **Do** [specific prescription with exact values / named rule].
|
||||
- **Do** [...]
|
||||
|
||||
### Don't:
|
||||
- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"].
|
||||
- **Don't** [...]
|
||||
- **Don't** [...]
|
||||
```
|
||||
|
||||
### Step 5: Write & confirm
|
||||
|
||||
1. Write the file to `PROJECT_ROOT/DESIGN.md` (uppercase, at root).
|
||||
2. Show the user the full DESIGN.md you wrote, briefly highlighting the non-obvious creative choices (descriptive color names, atmosphere language).
|
||||
3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?"
|
||||
|
||||
## Style guidelines
|
||||
|
||||
- **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior).
|
||||
- **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description.
|
||||
- **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is.
|
||||
- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description.
|
||||
- **Group colors semantically**: Foundation (backgrounds), Accent (interactive), Typography (text hierarchy), States (success/warning/error), not hex-sorted.
|
||||
- **Reference the user's domain**: if the project is a DEX, say "trading-focused"; if it's a CMS, say "editorial". Domain-aware language helps agents pick sensible defaults.
|
||||
- **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section.
|
||||
- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone.
|
||||
- **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle.
|
||||
- **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase.
|
||||
- **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
@@ -124,3 +185,5 @@ Use this exact structure (section headers must match the Google spec character-f
|
||||
- Don't invent components that don't exist. If the project only has buttons and cards, only document those.
|
||||
- Don't overwrite an existing DESIGN.md without asking.
|
||||
- Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual.
|
||||
- Don't add a "Layout Principles" or "Motion" or "Responsive Behavior" top-level section. The spec has six, not nine. Fold that content where it belongs.
|
||||
- Don't rename sections even slightly. "Colors" not "Color Palette & Roles". "Typography" not "Typography Rules". Tooling parsing depends on exact headers.
|
||||
|
||||
Reference in New Issue
Block a user