diff --git a/plugins/claude-design/skills/claude-design-facilitator/references/02-design-md.md b/plugins/claude-design/skills/claude-design-facilitator/references/02-design-md.md new file mode 100644 index 0000000..5ae3830 --- /dev/null +++ b/plugins/claude-design/skills/claude-design-facilitator/references/02-design-md.md @@ -0,0 +1,333 @@ +# DESIGN.md — template and extractor + +**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md +**Status:** Beta (Labs research preview) +**Captured-on date:** 2026-05-16 + +**Evidence grade:** Community-converged — Anthropic publishes the *concept* of a design-system document anchored to a Claude Design project (`https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design`), but does not publish the 9-section canonical structure. The 9-section template comes from community practitioners (`https://github.com/rohitg00/awesome-claude-design`, `https://github.com/VoltAgent/awesome-claude-design`). Use accordingly: the concept is Anthropic-authoritative; the structure is community-converged. + +--- + +## 1. Why DESIGN.md + +A DESIGN.md file uploaded to a Claude Design project anchors design-system identity for every artifact generated in that project. Without an anchor, Claude Design defaults to its convergent middle-ground aesthetic (rounded corners, generous spacing, friendly typography, gentle shadows — the AI-slop pattern documented at `https://claude.com/blog/improving-frontend-design-through-skills`). With an anchor, the model reads the file at generation time and constrains its aesthetic, component, and motion decisions to match. + +Anthropic publishes the concept of design-system anchors in `https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design`. The article describes asset uploads, brand kits, and the principle that artifacts in a Claude Design project inherit the project's design language. What Anthropic does *not* publish is a recommended structure for the design-language file itself. + +The community converged on a 9-section structure — documented across multiple awesome-claude-design repos, Substack posts, and practitioner blogs — that maps cleanly onto how Claude Design reads design context. The sections below are that converged structure. + +--- + +## 2. The 9-section canonical structure + +Each section names a decision Claude Design will otherwise default. The order is the order Claude Design appears to read most reliably (heaviest design-decision sections first). + +### Section 1 — Visual Theme & Atmosphere + +A one-paragraph description of the aesthetic family. Use named visual references the model can anchor to: "industrial-utilitarian like a Bloomberg terminal", "warm-editorial like The New York Times opinion section", "minimal-monochrome like Linear's UI". + +Worked example: + +```markdown +# Visual Theme & Atmosphere + +Industrial-utilitarian. Slate-monochrome palette, square-cut typography, +flat surfaces. Reference: a modern data-tool UI (Linear, Datadog, +Bloomberg) — dense, intentional, no flourish. The product should look +like it was built for engineers by engineers. +``` + +### Section 2 — Color Palette & Roles + +CSS-variable form with explicit hex values and semantic roles. Avoid relying on opacity for state changes — name each state explicitly. + +Worked example: + +```markdown +# Color Palette & Roles + +:root { + --color-bg: #E9ECEC; + --color-surface: #C9D2D4; + --color-muted: #8C9A9E; + --color-fg: #44545B; + --color-ink: #11171B; + + --color-accent: #4A6FA5; + --color-accent-hover: #3D5C8A; + --color-accent-active: #2F4A70; + + --color-error: #B23A48; + --color-warning: #C89B3F; + --color-success: #4F7A4F; +} + +Semantic roles: +- bg — page background +- surface — card / panel background +- muted — secondary text, borders +- fg — primary text +- ink — emphasis / heading text +``` + +### Section 3 — Typography Rules + +Named typeface, modular scale, weight palette, line-height palette. Modular scales the community converged on are 1.250 (minor third) for dense interfaces and 1.333 (perfect fourth) for marketing pages. + +Worked example: + +```markdown +# Typography Rules + +Primary typeface: Söhne (concrete-named, not "modern sans-serif"). +Fallback: Inter Variable. +Display typeface: same as primary (no separate display face). + +Modular scale: 1.250 (minor third). + --text-xs: 0.64rem; + --text-sm: 0.8rem; + --text-base: 1rem; + --text-lg: 1.25rem; + --text-xl: 1.563rem; + --text-2xl: 1.953rem; + +Weight palette: 500 body, 600 emphasized, 700 headings. +Line height: 1.4 body, 1.2 headings. + +If the typeface is not available, substitute Inter Variable — never +default to Inter, Roboto, Arial, or Space Grotesk +(per https://claude.com/blog/improving-frontend-design-through-skills +AI-slop avoid-list). +``` + +### Section 4 — Component Stylings + +Per-component rules for the components Claude Design generates. Cover buttons, inputs, cards, tables, navigation. Specify radius, padding, border treatment, hover/active/disabled state explicitly. + +Worked example: + +```markdown +# Component Stylings + +Buttons: + - radius: 4px (no pill shapes) + - padding: 8px 16px + - primary: bg accent, fg surface + - secondary: border 1px muted, bg transparent + - hover: bg accent-hover + - active: bg accent-active + - disabled: opacity 0.4, no pointer events + +Inputs: + - radius: 4px + - padding: 8px 12px + - border: 1px solid muted + - focus: border accent + 2px outset ring at accent + 20% alpha + +Cards: + - radius: 4px + - padding: 16px + - bg surface + - no shadow — borders define edges if needed + +Tables: + - row height: 32px (dense) + - cell padding: 8px + - alternating row: bg + 4% darken + - hover row: bg + 8% darken +``` + +### Section 5 — Layout Principles + +Grid system, spacing scale, breakpoint widths. Name the grid columns and the gap value. + +Worked example: + +```markdown +# Layout Principles + +Grid: 12-column on screens >= 1024px, 8-column on screens 768-1023px, +4-column on screens < 768px. +Gap: 16px (--space-md). + +Spacing scale: + --space-xs: 4px + --space-sm: 8px + --space-md: 16px + --space-lg: 24px + --space-xl: 32px + --space-2xl: 48px + +Page max-width: 1440px centered. +Container padding: 24px on screens >= 768px, 16px below. +``` + +### Section 6 — Depth & Elevation + +Surface depth rules. Most designs benefit from a clear flat-vs-layered decision rather than a mixed palette. + +Worked example: + +```markdown +# Depth & Elevation + +Flat. No box-shadows by default. Borders define component edges. +Z-stack: + z-0: page surface + z-10: navigation + z-20: dropdown / popover + z-30: modal backdrop + z-40: modal content + z-50: toast / notification + +Modal: bg surface, 1px border ink, no shadow. +Popover: bg surface, 1px border muted, no shadow. +``` + +### Section 7 — Do's and Don'ts + +Explicit constraint list. This is where layer-3 (AI-slop avoid-list) gets project-specific. + +Worked example: + +```markdown +# Do's and Don'ts + +Do: + - Use accent color sparingly (CTA + active state only) + - Use ink for headings, fg for body, muted for secondary + - Use 4px corner radius consistently + - Use 160ms ease-out for all hover transitions + +Don't: + - Use purple gradients on white backgrounds + - Use solid-color hero backgrounds + - Use Inter / Roboto / Arial / Space Grotesk as primary typeface + - Use bouncy spring easing + - Use pulse / breathing animations on idle elements + - Use glassmorphism or neumorphism + - Use shadows except where the depth-and-elevation section explicitly permits +``` + +### Section 8 — Responsive Behavior + +Breakpoint behavior. Anthropic does not publish responsive rules; this is the section where a project encodes its responsive philosophy. + +Worked example: + +```markdown +# Responsive Behavior + +Mobile-first reasoning, but built desktop-first (target audience is +desktop). Below 768px: + - Navigation collapses to single icon-button row + - Tables become card stacks (one card per row) + - 12-column grid becomes 4-column + - Container padding drops from 24px to 16px + - Font sizes scale down by 0.9x + +Touch targets: minimum 44px height (regardless of viewport). +``` + +### Section 9 — Agent Prompt Guide + +A short block telling Claude Design how to use this DESIGN.md. This section is the bridge between the file and the prompt — it names the file by section and reminds the model that the constraints are load-bearing. + +Worked example: + +```markdown +# Agent Prompt Guide + +When generating an artifact in this project, read every section of this +DESIGN.md before producing output. Treat color palette, typography rules, +component stylings, and layout principles as constraints — not +suggestions. If a generation would violate a constraint, stop and ask +which constraint to relax. + +Cite specific section names when justifying design decisions in +explanatory text (e.g., "I chose 4px corners per Section 4 Component +Stylings"). +``` + +--- + +## 3. Brand-to-DESIGN.md extractor prompt + +A copy-paste-ready prompt the operator pastes into `claude.ai` (the chat product) or Claude.com to convert a brand URL, screenshot, or marketing asset into a DESIGN.md. The pattern comes from `https://github.com/rohitg00/awesome-claude-design/blob/main/prompts/brand-to-design-md.md` (adapted with attribution to the awesome-claude-design community template). + +``` +You will produce a DESIGN.md file by analyzing the brand reference +materials I provide. Output structure: 9 sections, in this order, +with the exact heading names: + + 1. Visual Theme & Atmosphere + 2. Color Palette & Roles + 3. Typography Rules + 4. Component Stylings + 5. Layout Principles + 6. Depth & Elevation + 7. Do's and Don'ts + 8. Responsive Behavior + 9. Agent Prompt Guide + +Rules: +- Use CSS-variable form (--color-name: #HEX) for color palette +- Use modular scale form (--text-xs / --text-sm / ...) for typography +- Use named typefaces ONLY — if you cannot identify the typeface from + the brand materials with high confidence, write "unknown — operator + to fill in" rather than guessing. Do not hallucinate a typeface name. +- For each component (button, input, card, table, navigation), name + radius, padding, border treatment, and hover / active / disabled states +- Cite the source brand material at the top (e.g., "Extracted from + brand kit at on 2026-05-17") + +Brand reference materials: +[paste URL, screenshot, or brand kit description here] +``` + +The anti-hallucination clause ("if you cannot identify... write unknown") is load-bearing — the failure mode without it is plausible-but-wrong typography names that the operator does not catch until they brief Claude Design and the output drifts. + +Source for this extractor: community pattern at `https://github.com/rohitg00/awesome-claude-design/blob/main/prompts/brand-to-design-md.md`, adapted. + +--- + +## 4. DESIGN.md failure modes + +Four failure modes the operator should know before adopting DESIGN.md as a workflow primitive. + +### Vision-token cost penalty + +If the DESIGN.md is uploaded as an image (screenshot of a brand page) rather than as text, Claude Design pays a vision-token cost on every generation. Practitioner walkthroughs (Xinran Ma's documented experience in `research/03`) report meaningful quota burn from image-based DESIGN.md anchors. Use text-form DESIGN.md whenever possible. + +### Per-user quota not pooled + +Anthropic does not pool Claude Design quota across team members. A team using a shared DESIGN.md will not share quota burn — each member pays separately. Plan project workflow accordingly (research/04 documents community-observed Pro burn of roughly 25-30 minutes; Max roughly 60-90). + +### Long-session degradation + +DESIGN.md adherence appears to degrade in the back third of a long session. Opus 4.7 quality drops at the 40-50% context mark (`https://anthropic.com/engineering/harness-design-long-running-apps`); DESIGN.md is part of context, so its enforcement weakens accordingly. Session-break heuristics in `references/03-iteration-and-session.md` apply. + +### Post-export drift + +When an artifact is exported (PPTX, PDF, Code-handoff), the DESIGN.md does not travel with it. Downstream editing tools — PowerPoint, Adobe, Code IDEs — apply their own defaults. Validate the rendered output against DESIGN.md after export. + +--- + +## 5. DESIGN.md sanity-check pattern + +A community-converged test for DESIGN.md adherence: generate three artifacts in the same Claude Design project using deliberately different intent presets (designs, slides, one-pagers) and confirm that all three respect the DESIGN.md color palette, typography, and component-styling rules. If one preset drifts more than the others, the DESIGN.md needs sharpening on the section the drifting preset emphasized. + +The community attribution for this pattern comes from a `theadpharm` Substack walkthrough (cited in `research/03`). It is a smoke test, not a guarantee — but it catches the common case where DESIGN.md is too general to constrain the model. + +--- + +## Sources + +- `https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design` — Anthropic's design-system setup concept +- `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` — Anthropic's AI-slop avoid-list and four design dimensions +- `https://claude.com/blog/improving-frontend-design-through-skills` — Anthropic blog on default-avoidance +- `https://anthropic.com/engineering/harness-design-long-running-apps` — context-degradation framing +- `https://github.com/rohitg00/awesome-claude-design` — community awesome-list, brand-to-DESIGN.md extractor source +- `https://github.com/VoltAgent/awesome-claude-design` — community awesome-list, alternate 9-section structure references + +Re-research trigger: Anthropic publishing an official DESIGN.md structure; either community awesome-list reaching consensus on a different section ordering; new failure mode surfaced in practitioner posts.