feat(claude-design): add 02-design-md template + brand-to-DESIGN.md extractor
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
ce715ef087
commit
72336f811b
1 changed files with 333 additions and 0 deletions
|
|
@ -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 <URL> 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue