Based on Google Stitch DESIGN.md methodology and 58 world-class brand design systems (Apple, Tesla, Stripe, Vercel, Linear, Airbnb, Spotify, Notion, etc.), this skill provides a complete framework for AI agents to generate production-grade UI with distinctive aesthetic quality. Covers design analysis, DESIGN.md creation, and pixel-perfect implementation across all frontend platforms.
インストール
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
Based on Google Stitch DESIGN.md methodology and 58 world-class brand design systems (Apple, Tesla, Stripe, Vercel, Linear, Airbnb, Spotify, Notion, etc.), this skill provides a complete framework for AI agents to generate production-grade UI with distinctive aesthetic quality. Covers design analysis, DESIGN.md creation, and pixel-perfect implementation across all frontend platforms.
Design-driven tech stack advisory — recommending component libraries that best EXPRESS a design intent
Consistency enforcement — the 5 C-rules preventing color/icon/font/illustration drift
A2UI protocol — for agent-driven declarative UI
This skill IS NOT (defers to other skills):
NOT a frontend implementation skill → defer to frontend-patterns for React/Vue/Angular patterns, state management, component architecture, performance optimization
NOT a project scaffolding skill → defer to web-development for build config, SDK integration, static hosting, deployment
NOT a coding standards skill → defer to coding-standards for naming conventions, file organization, type safety, error handling
NOT a deployment skill → defer to deployment-patterns for Docker, CI/CD, cloud config
NOT a mini program structure skill → defer to miniprogram-development for project structure, WeChat DevTools, wx.cloud
NOT a security skill → defer to security-review for OWASP, injection prevention, auth security
NOT an accessibility implementation skill → defer to frontend-patterns for WCAG implementation code; this skill only defines contrast/touch-target SPECIFICATIONS in DESIGN.md
Relationship with ui-design skill:
The ui-design skill and this skill are complementary, not competing:
Concern
ui-design owns
designdna owns
When to trigger
User asks to create NEW page/component/interface
User asks about design SYSTEM, tokens, DESIGN.md, audit, brand matching
Aesthetic direction
Chooses aesthetic direction (e.g. "brutalist", "editorial")
Provides reference archetypes from 58 real brands
Color selection
Creative color choices for a specific page
Semantic color ORGANIZATION (4-tier text, surface hierarchy, accent rules)
Typography
Font SELECTION for a specific aesthetic feel
Typography SYSTEM (hierarchy table, weight roles, letter-spacing formula)
Output
Beautiful individual pages/components
Reusable design system documents (DESIGN.md)
Collaboration rules:
If ui-design is active and this skill is also triggered → ui-design leads creative decisions, this skill provides the SYSTEM STRUCTURE to organize them
If a DESIGN.md already exists in the project → BOTH skills must follow it; neither may override it without user approval
If ui-design picks fonts/colors → this skill organizes them into semantic tokens, hierarchy tables, and CSS variables
If this skill recommends an archetype → ui-design may refine the aesthetic within that archetype's guardrails
Tech Stack Advisory — Design Perspective Only
This skill recommends tech stacks from a design expression perspective:
"Which component library best EXPRESSES this design archetype?"
"Which icon set best MATCHES this visual language?"
API integration patterns → backend-patterns / api-design
When this skill's tech stack suggestion conflicts with another skill:
→ The OTHER skill wins on implementation details.
→ This skill wins on VISUAL/DESIGN rationale only.
→ Example: This skill says "use Lucide icons for this design archetype". frontend-patterns says "use dynamic imports for tree-shaking". Both apply — choose Lucide (design), import dynamically (implementation).
Distilled from 58 world-class brand design systems following Google Stitch's DESIGN.md methodology.
Source: DesignDNA-Skills | Design data: awesome-design-md
Library Sub-Skills
For library-specific implementation guidance (Taro, NutUI Vue, NutUI React, NutUI UniApp, NutUI Icons, NutUI Templates, NutUI Biz, Taro UI), load the matching skill from designdna/skills/.
These sub-skills teach an AI agent the how (installation, component usage, theme tokens, BANNED patterns, pre-flight) for each library. Combine with the brand DNAs in design-md/ for full "what + how" coverage.
Compatibility guardrails:
Treat each runtime as having one primary UI library unless you are explicitly comparing alternatives.
Some install-stack presets are reference bundles, not "use all of these in one app" instructions.
For WeChat MiniProgram native UI, vant-weapp and tdesign-miniprogram are alternatives.
For Flutter, flutter-material and tdesign-flutter are alternatives unless you have a very deliberate mixed-language design system.
For generated visual assets, load gpt-image-2 only when the task needs custom generation or editing; curated real assets still come first when realism/provenance matters.
Use these lessons as process patterns, not vendored content. Huashu Design's public repository has a personal-use license; do not copy its assets, scripts, demos, BGM, references, or prompt text into commercial or organizational workflows without authorization. The distilled DesignDNA interpretation lives in OPEN-SOURCE-LEARNINGS.md.
Fact-first rule
If a task names a modern product, company, library, version, public figure, event, release, or current design system, verify current facts before making design or implementation claims. This applies especially to package versions, peer dependencies, product launch assets, official logos, product screenshots, and brand guidelines.
Core asset protocol
For named brand/product work, recognizable assets outrank abstract vibe. Prioritize:
Logo
Product render/photo for physical products
UI screenshots for digital products
Color values
Fonts
Mood keywords
Freeze collected assets into brand-spec.md or equivalent notes with source URLs, capture date, local paths, resolution, and usage role. Do not substitute generic SVG silhouettes, fake screenshots, or generated lookalikes when official assets are needed.
Image-first rule
For visual-risk website, campaign, hero, landing-page, or redesign work, use an image-first loop when generation is available and helpful:
Generate or collect clear references.
Analyze layout, type, spacing, color, imagery, and component rhythm.
Convert findings into DESIGN.md tokens and component rules.
Implement from the extracted system.
Prefer one clear section/detail reference over a compressed multi-section board. Do not crop an old generated board as the main source for a new section; generate a fresh section-specific reference if detail fidelity matters.
Pre-flight Checklist (MANDATORY)
Before emitting any UI code, self-audit with this checklist. Print each item as [x] (passed) or [ ] (failed) in your output reasoning.
This is a bias-correction checklist inspired by taste-skill. LLMs have strong statistical priors toward generic patterns — these rules fight the mean.
Facts & Assets
Current facts verified when the task names a modern product/company/library/version
Existing DESIGN.md, brand guidelines, screenshots, UI kit, or codebase checked before inventing visuals
For brand-specific work: logo/product/UI assets prioritized before colors/fonts
Important non-logo hero assets pass the 5-10-2-8 gate or are explicitly marked as placeholders
Generated images have prompt/provenance notes and are not presented as official assets
Typography
No Inter unless the brand DNA specifies it
≤ 2 font families used on the page
≤ 4 font weights used total
No all-caps headings > 16px
Font families match the brand DNA exactly
Color
No pure #000000 (use warm near-black from brand DNA)
No pure #FFFFFF surfaces without a brand-specific off-white alternative
No default AI purple #8B5CF6 family unless brand specifies purple
No rainbow blue→purple→pink gradient
Accent color explicitly from brand DNA palette
Layout
Hero is NOT the generic "centered headline + subhead + 2 buttons" template
No 3-column icon-card feature grid
No "Trusted by" fake-logo bar
At least one section breaks the symmetric 12-column grid
The resulting PROJECT-DESIGN.md is committed to the user's repo and becomes the durable design contract. When the design evolves, they edit this file — everyone (humans and AI) reads from it.
What is DESIGN.md?
DESIGN.md is a concept from Google Stitch — a plain-text design system document that AI agents read to generate consistent, high-quality UI. Markdown is the format LLMs read best; no Figma exports, no JSON schemas, no special tooling required.
File
Who reads it
What it defines
AGENTS.md
Coding agents
How to build the project
DESIGN.md
Design agents
How the project should look and feel
Part 1: The 9-Section DESIGN.md Standard
Every DESIGN.md MUST follow this exact 9-section architecture. This consistency enables AI agents to parse and implement any design system predictably.
Section 1: Visual Theme & Atmosphere
Purpose: Establish the emotional and philosophical foundation of the design.
Requirements:
150-300 words of narrative prose, NOT bullet points
Describe the emotional quality (warm, clinical, cinematic, editorial, etc.)
Framer: "Nightclub for web designers" — cinematic dark canvas, extreme letter-spacing compression
Section 2: Color Palette & Roles
Purpose: Define every color with its semantic purpose.
Organization (NEVER use a flat list — always group by semantic purpose):
### Primary & Brand
- **Brand Color** (`#hexcode`): CSS variable name, semantic purpose and usage
### Secondary & Accent
- Variant 1: description
- Variant 2: description
### Text Scale (3-5 tiers)
- Primary text: color + when to use
- Secondary text: color + when to use
- Tertiary text: color + when to use
- Quaternary/Disabled: color + when to use
### Surface & Background (2-6 variants)
- Base background
- Elevated surface
- Overlay surface
### Interactive States
- Default, Hover, Focus, Active, Disabled
### Borders & Dividers
- Primary border, subtle border, focus ring
### Semantic
- Error, Success, Warning, Info
### Shadows
- Shadow colors with opacity values
Key patterns from top brands:
Always include hex code + semantic name + use case in every color entry
Warm neutrals outperform cold grays: Airbnb uses #222222 (warm near-black), Claude uses #5e5d59 (olive gray), Notion uses rgba(0,0,0,0.95) — NOT pure #000000
Brand accent restraint: Tesla uses ONE accent color (#3E6AE1). Spotify reserves green ONLY for play/active. Coinbase uses blue only for primary CTAs
Dark mode colors: Linear uses semi-transparent whites for borders (rgba(255,255,255,0.05-0.08)). Raycast uses double-ring containment technique
Section 3: Typography Rules
Purpose: Define the complete type system.
Required structure:
Font Families — Primary, secondary, monospace with fallback stacks
Hierarchy Table (Markdown table format):
Role
Font
Size
Weight
Line Height
Letter Spacing
Notes
Display Hero
...
...px
...
...
...px
...
Section Heading
...
...
...
...
...
...
Body
...
...
...
...
...
...
Typography Principles — Weight philosophy, spacing rules, OpenType features
Key patterns from top brands:
Weight Systems (no brand uses more than 4 weights):
2-weight systems: Tesla (400/500), Claude (400/500) — hierarchy through serif/sans split or size alone
3-weight systems: Vercel (400/500/600), Stripe (300/400/500) — strict role assignment per weight
Micro-weight systems: Linear (300/400/510/590), Figma (320-540 variable) — precision through interpolation
Letter-Spacing Rules:
Negative at large sizes: Universal rule. Vercel: -2.4px at 64px. Framer: -5.5px at 110px. Notion: -2.125px at 64px
Zero or positive at body: Most systems use 0px at 14-16px body text
Positive at small sizes: Raycast uses +0.2px to +0.4px for airy readability in dark UIs
Formula: letter-spacing = -(fontSize * 0.03 to 0.05) for headlines; 0 for body; +(0.01 to 0.02) for captions
OpenType Features (frequently required):
Stripe: "ss01" stylistic set required on ALL text
Linear: "cv01", "ss03" on Inter — character variant + stylistic set
Figma: kern enabled globally
Raycast: "calt", "kern", "liga", "ss03" on Inter
Notion: NotionInter with custom rendering
Section 4: Component Stylings
Purpose: Define visual specifications for all major UI elements.
Required components (minimum):
Buttons — Primary, Secondary, Ghost/Text variants with all states
Cards & Containers — Standard, Elevated, Featured variants
Input Fields — Text input, Select, Textarea with focus states
Navigation — Header, sidebar, tabs, breadcrumbs
Images & Media — Aspect ratios, border radius, overlay treatment
Distinctive Components — Brand-specific unique elements
Format for each component:
### Component Name
**Variant Name (Context)**
- Background: color value
- Text/Color: value
- Padding: value (often asymmetric)
- Radius: value
- Border/Shadow: CSS value
- Hover: state change description
- Focus: state change description
- Use: explicit use case
Key patterns from top brands:
Button Philosophies:
Vercel: Shadow-as-border technique (ring shadow instead of border property)
### Do
- Use [specific pattern] because [reason]
- Always [required behavior]
### Don't
- Don't use [anti-pattern] because [consequence]
- Never [forbidden behavior]
Minimum 10 rules total (5 Do + 5 Don't).
Common patterns across all brands:
DO maintain weight restraint (max 3-4 weights)
DO use brand accent color sparingly (one purpose, not decoration)
DO include OpenType features when specified
DO use warm neutrals over cold grays (unless brand dictates otherwise)
DON'T use pure black (#000000) for text on light backgrounds
DON'T skip letter-spacing adjustments at different sizes
DON'T use light/thin weights on dark backgrounds (readability)
DON'T apply brand colors decoratively (reserve for semantic purposes)
DON'T use uniform shadow opacity across all elevation levels
Section 8: Responsive Behavior
Purpose: Define how the design adapts across screen sizes.
Required subsections:
Breakpoints — Table with name, pixel width, key layout changes
Touch Targets — Minimum tap sizes (typically 44x44px minimum)
Collapsing Strategy — How multi-column layouts simplify
Image Behavior — How media scales and crops
Section 9: Agent Prompt Guide
Purpose: Enable AI agents to generate brand-matching designs immediately.
Required subsections:
Quick Color Reference — 5-15 most-used colors with hex codes and roles
Example Component Prompts — 3-5 full natural-language component descriptions with ALL specifications (hex codes, sizes, weights, radii, shadows)
"Create a dark card: #181818 background, 8px radius. Title at 16px weight 700, white text. Subtitle at 14px weight 400, #b3b3b3. Shadow rgba(0,0,0,0.3) 0px 8px 8px on hover."
Part 2: Design Analysis Framework
When analyzing a website to create a DESIGN.md or when generating new UI, follow this systematic approach:
Step 1: Identify the Design Archetype
Classify the design into one of these proven archetypes (from 58 brand analysis):
Thin/light fonts on dark backgrounds — Below weight 400 on dark surfaces
Quality Signals (present in ALL top brands)
Negative letter-spacing on headlines (every single one of 58 brands)
Multi-layer shadow systems (or deliberate zero-shadow philosophy)
Semantic color organization (never a flat color list)
Typography hierarchy with 8+ distinct roles
Explicit Do's and Don'ts preventing drift
Warm neutrals (even "cool" brands avoid pure gray)
8px spacing base unit (universal)
Consistent border-radius scale (8 named variants)
Brand accent used for ONE primary purpose
Component states fully specified (hover, focus, active, disabled)
Part 5: Quick Reference Card
When starting any UI design task:
Check for existing DESIGN.md in the project root
If exists: Read it completely, follow it exactly
If not exists: Ask the user which brand aesthetic to follow, or identify the closest archetype
Generate DESIGN.md first before writing any UI code (unless user has existing pages to patch)
The 10 Universal Design Rules (from 58 brands):
Use 8px as base spacing unit
Limit to 2-4 font weights maximum
Scale letter-spacing inversely with font size
Organize colors by semantic purpose
Use multi-layer shadows (or deliberately zero)
Reserve brand accent for ONE semantic purpose
Use warm near-black for text, never pure #000000
Define 8 border-radius variants from sharp to pill
Every component needs 4 states: default, hover, focus, disabled
Write Do's and Don'ts to prevent design drift
Part 6: Existing Project UI Audit & Optimization
When the user wants to optimize or upgrade the UI of an existing project, follow this systematic workflow.
Workflow Overview
Existing Project
├─ Step 1: Extract current design DNA (read code + screenshots)
├─ Step 2: Audit against 10 Universal Rules (identify violations)
├─ Step 3: Generate improvement DESIGN.md (target state)
├─ Step 4: Prioritized refactoring plan (high-impact first)
└─ Step 5: Incremental implementation (one system at a time)
Step 1: Extract Current Design DNA
Read the project's existing CSS/styles and identify the current state:
What to extract:
1. Colors currently in use:
- grep/search for hex codes (#xxx, #xxxxxx), rgb(), rgba(), hsl()
- List all unique colors, group by apparent purpose
- Check: are they organized by semantic purpose? or random?
2. Typography currently in use:
- font-family declarations (how many fonts?)
- font-weight values (how many weights? which ones?)
- font-size values (how many distinct sizes?)
- letter-spacing values (are they scaling with size?)
- line-height values (are they compressing at larger sizes?)
3. Spacing patterns:
- padding/margin values (are they on 8px grid?)
- gap values
- Any evidence of a spacing scale?
4. Shadow system:
- box-shadow declarations (single-layer or multi-layer?)
- shadow colors (warm, cool, or pure black?)
- how many distinct shadow levels?
5. Border radius:
- border-radius values (how many unique values?)
- are they systematic or random?
6. Component patterns:
- Button variants and their states
- Card patterns
- Input styles
- Navigation treatment
Commands to run (adjust for the project's tech stack):
# Find all color values
grep -rn '#[0-9a-fA-F]\{3,8\}' src/ --include="*.css" --include="*.scss" --include="*.tsx" --include="*.vue"# Find all font-weight values
grep -rn 'font-weight' src/ --include="*.css" --include="*.scss"# Find all box-shadow values
grep -rn 'box-shadow' src/ --include="*.css" --include="*.scss"# Find all border-radius values
grep -rn 'border-radius' src/ --include="*.css" --include="*.scss"# Find all font-size values
grep -rn 'font-size' src/ --include="*.css" --include="*.scss"
Step 2: Audit Against 10 Universal Rules
Score each rule as PASS / PARTIAL / FAIL:
#
Rule
Check
Common Violations
1
8px base spacing
Are padding/margin/gap on 8px grid?
Random values like 13px, 17px, 25px
2
Max 4 font weights
Count distinct font-weight values
5+ weights scattered without purpose
3
Letter-spacing scales
Negative at display, zero at body?
Uniform 0px or uniform -1px everywhere
4
Semantic color organization
Colors grouped by purpose in variables?
Flat list, or colors defined inline
5
Multi-layer shadows
2+ shadow layers per elevation?
Single 0 2px 4px rgba(0,0,0,0.1) everywhere
6
Brand accent restraint
Brand color used for ONE purpose?
Brand color on borders, backgrounds, dividers
7
Warm near-black text
Text color is warm, not #000?
Pure #000000 on white backgrounds
8
Border-radius scale
Systematic radius variants?
Random values or same radius everywhere
9
4 component states
hover/focus/disabled defined?
Missing focus states, no disabled styles
10
Do's/Don'ts exist
Any design guardrails documented?
No documentation, inconsistent patterns
Step 3: Generate Improvement DESIGN.md
Based on the audit, generate a DESIGN.md that:
Preserves what's already working well (don't break what's good)
Fixes rule violations with specific improvements
Elevates the design toward the closest world-class archetype
When the user has generated prototypes with Google Stitch (or any tool that produces HTML/images), follow this workflow to extract the design system and build the complete project.
1. Read ALL HTML files the user provides
2. Extract inline styles and <style> blocks
3. Identify linked stylesheets
4. List all unique CSS property values:
- colors (hex, rgb, rgba, hsl)
- font-family, font-size, font-weight, letter-spacing, line-height
- padding, margin, gap (spacing values)
- border-radius values
- box-shadow values
- background (gradients, images)
- border values
5. Identify component patterns (buttons, cards, inputs, nav)
6. Note layout approach (flexbox, grid, float)
For image files (screenshots, mockups):
1. View the image to understand overall aesthetic direction
2. Note the dominant colors, typography style, spacing density
3. Identify the layout grid and spatial rhythm
4. Identify components visible in the mockup
5. Assess the emotional quality (warm, clinical, cinematic, etc.)
Step 2: Extract Design Tokens
Create a structured extraction from the prototype:
## Extracted Tokens from Prototype### Colors Found
| Hex/Value | Where Used | Suggested Role |
|-----------|-----------|----------------|
| #______ | hero background | bg-primary |
| #______ | heading text | text-primary |
| #______ | CTA button | brand-accent |
| ... | ... | ... |
### Typography Found
| Element | Font | Size | Weight | Line Height | Letter Spacing |
|---------|------|------|--------|-------------|----------------|
| h1 | ... | ...px | ... | ... | ... |
| body | ... | ...px | ... | ... | ... |
| ... | ... | ... | ... | ... | ... |
### Spacing Values Found
[list all padding/margin/gap values]
### Shadow Values Found
[list all box-shadow declarations]
### Border Radius Found
[list all border-radius values]
### Components Identified
[list buttons, cards, inputs, nav patterns found]
Step 3: Identify Design Archetype
Compare the extracted tokens against the 10 archetypes:
Matching heuristics:
Dark background + ring shadows + monospace → Dark Instrument (Linear/Raycast)
White background + strict black/white + geometric type → Precision Monochrome (Vercel)
Section 9: Agent Prompt Guide — write prompts using actual extracted values
Gap-filling rules:
If prototype has 5 colors → expand to 15+ using archetype's pattern
If prototype has 3 type sizes → expand to 10+ role hierarchy
If prototype has no shadows → add the archetype's shadow system
If prototype has no focus states → add from archetype
If spacing is not on 8px grid → snap to nearest 8px multiple
If only light mode → create dark mode palette following archetype
Step 5: Build Component Library
Extract reusable components from the prototype:
1. Identify ALL unique components in the prototype HTML
2. For each component, create a reusable version:
- Use DESIGN.md tokens (CSS variables, not hardcoded values)
- Add ALL 4 states (default, hover, focus, disabled)
- Make responsive (test at mobile/tablet/desktop)
- Add proper semantic HTML + accessibility attributes
3. Component hierarchy (build in this order):
Level 1 — Atoms: Button, Input, Badge, Avatar, Icon
Level 2 — Molecules: Card, Form Group, Nav Item, List Item
Level 3 — Organisms: Navigation, Hero, Feature Section, Footer
Level 4 — Templates: Full page layouts
Step 6: Implement Full Pages
With the DESIGN.md + component library ready:
1. Create page layouts matching prototype structure
2. Use components from the library (never inline styles)
3. Populate with real content (not Lorem ipsum for final)
4. Check every element against DESIGN.md specifications
5. Verify: colors ✓, type ✓, spacing ✓, shadows ✓, radius ✓, states ✓
Step 7: Production Polish
Final quality gate:
□ All colors use CSS variables from DESIGN.md
□ Typography follows the hierarchy table exactly
□ All spacing on 8px grid
□ All shadows match the elevation system
□ All interactive elements have 4 states
□ Responsive at all breakpoints (320px → 1920px)
□ Touch targets ≥ 44px on mobile
□ Contrast ratios meet WCAG AA (4.5:1 body, 3:1 large)
□ Focus rings visible for keyboard navigation
□ No pure #000000 text on light backgrounds
□ Brand accent used for ONE purpose only
□ Design matches prototype intent (screenshot comparison)
Part 8: Practical Usage Scenarios
Scenario A: "Optimize my existing project's UI"
What to say to AI:
"Read my project's CSS/styles and run a UI audit against the DesignDNA rules. Show me what violations exist and create a phased improvement plan."
What happens:
AI reads your styles (CSS/SCSS/Tailwind config/styled-components)
Scores against 10 Universal Rules
Identifies closest archetype
Generates improvement DESIGN.md
Provides Phase 1-5 refactoring plan
Implements changes incrementally
Scenario B: "I have Stitch prototypes, build the full project"
What to say to AI:
"I have HTML prototypes from Google Stitch in [directory]. Extract the design tokens, generate a complete DESIGN.md, then build the full project using [React/Vue/etc.]."
What happens:
AI reads your prototype HTML files (and views any images)
Extracts all design tokens (colors, type, spacing, shadows)
Identifies the closest design archetype
Generates complete DESIGN.md (filling gaps from archetype)
Builds component library using extracted tokens
Implements full pages matching prototype layout
Adds responsive behavior + production polish
Scenario C: "Make my UI look like [brand]"
What to say to AI:
"Redesign my project's UI to match the [Stripe/Linear/Notion/etc.] aesthetic. Use the awesome-design-md reference for [brand]."
What happens:
AI reads the reference brand's DESIGN.md from awesome-design-md collection
Audits your current UI against that brand's design system
Generates a project-specific DESIGN.md adapting the brand's patterns
Implements the redesign following the phased plan
Scenario D: "Generate a DESIGN.md for my project"
What to say to AI:
"Analyze my project and generate a DESIGN.md. My project is a [type] and I want the aesthetic to feel [description]."
What happens:
AI identifies the closest archetype
Reads your existing code for any design patterns already in place
Generates a complete 9-section DESIGN.md
Provides example component prompts tuned to your project
Scenario E: "Review my UI quality"
What to say to AI:
"Review my project's UI against production design standards. Score it and tell me what to fix first."
What happens:
AI extracts current design DNA from your code
Scores each of the 10 Universal Rules
Compares against world-class brand patterns
Provides prioritized fix list with specific CSS changes
Archetype Quick Selector:
If the project is...
Use archetype
Reference brands
Developer tool / CLI
Dark Instrument
Linear, Raycast, Warp
SaaS / Productivity
Precision Monochrome
Vercel, HashiCorp
Consumer / Marketplace
Warm Editorial
Airbnb, Notion
Fintech / Data
Enterprise Trust + Gradient
Stripe, Coinbase
AI / ML product
Warm Editorial or Dark Cinematic
Claude, xAI
Creative tool
Vibrant Gradient
Figma, Framer
Media / Content
Content Stage
Spotify, Pinterest
Automotive / Luxury
Premium Automotive
Tesla, BMW, Ferrari
E-commerce
Friendly Warm
Zapier, Lovable
Backend / Infra
Developer Native
Supabase, Resend
Part 9: Design Resource Integration & Consistency Enforcement
Core Problem: LLMs often produce inconsistent colors, missing icons, and ugly placeholder graphics because they lack concrete resource anchoring. This section solves that by binding every design decision to a specific, accessible resource.
See RESOURCES.md for the complete resource catalog.
The 5 Consistency Killers (and How to Fix Them)
#
Problem
Root Cause
Solution
1
Colors drift across pages
Colors defined inline, not as tokens
ALL colors MUST be CSS variables or theme tokens. NEVER use inline hex values in components.
2
Icons inconsistent
Mixing icon sets, or using emoji/text as icons
Choose ONE icon library per project. Install via npm for offline reliability.
3
Illustrations missing or ugly
LLM generates placeholder text instead of real assets
Specify exact illustration source + search term in DESIGN.md. Use SVG illustrations from unDraw/Storyset.
4
Typography breaks on different OS
Using system fonts without fallbacks
Always specify font via Fontsource (npm install) + proper fallback stack.
5
Components look different across pages
Not using a component library consistently
Choose ONE component library. Import from it. Never hand-code what the library provides.
Consistency Enforcement Rules (MANDATORY)
Rule C1 — One Icon Library Per Project
BEFORE writing any UI code, declare the icon library:
"This project uses [Lucide/Heroicons/Tabler/etc.]"
Then ALWAYS import from that library. NEVER:
❌ Mix Lucide icons with Heroicons
❌ Use emoji as icons (🔍 ← never this)
❌ Use Unicode symbols as icons (→ ← never this in UI)
❌ Use text characters as icons ("X" for close ← never this)
Install offline:
npm i lucide-react # React
npm i @heroicons/react # React + Tailwind
npm i @tabler/icons-react # React (largest set)
npm i lucide-vue-next # Vue
npm i @iconify/react # Universal (200k+ icons)
LOCAL FALLBACK (no npm needed):
DesignDNA includes 750 pre-downloaded SVG icons in assets/icons/:
- assets/icons/lucide/ → 436 icons, 20 categories
- assets/icons/material/ → 314 icons, 16 categories
- assets/ICON-INDEX.md → searchable catalog with quick lookup table
Copy SVGs directly into your project:
cp designdna/assets/icons/lucide/actions/search.svg src/assets/icons/
cp -r designdna/assets/icons/lucide/navigation/ src/assets/icons/
Rule C2 — One Color Source of Truth
ALL colors MUST flow from ONE source:
Option A: DESIGN.md → CSS custom properties → components
Option B: Component library theme (Tailwind config / Ant Design theme / etc.)
NEVER:
❌ Use inline color values: style={{ color: '#3b82f6' }}
❌ Use unnamed colors in CSS: color: #666;
❌ Approximate colors: "use a blue similar to..."
ALWAYS:
✅ color: var(--text-secondary);
✅ className="text-gray-600" (Tailwind)
✅ Use theme tokens from chosen component library
Rule C3 — Font Installation via npm (Offline-First)
NEVER rely on Google Fonts CDN in production code.
ALWAYS install via Fontsource for offline reliability:
npm i @fontsource-variable/inter
npm i @fontsource-variable/jetbrains-mono
npm i @fontsource/plus-jakarta-sans
Then import in your entry file:
import '@fontsource-variable/inter';
Fallback stacks MUST include system fonts:
font-family: 'Inter Variable', 'Inter', -apple-system,
BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',
'Hiragino Sans GB', 'Microsoft YaHei', sans-serif;
For EVERY section that needs an illustration or image, specify:
1. Source: which resource to use (Pexels, Huaban, GPT Image 2, unDraw, Storyset, etc.)
2. Search terms: exact keywords to find the right asset
3. Format: SVG for illustrations, WebP/JPEG/PNG for images
4. Fallback: CSS gradient or pattern if image fails to load
Example in DESIGN.md:
"Empty state illustration: unDraw 'no_data' in brand primary color #3b82f6"
"Hero image: Pexels search 'minimal workspace laptop' → WebP 1920x1080"
"Localized campaign asset: Huaban search '科技 蓝色 UI 背景' → JPG/PNG, verify asset license"
"Generated product hero: GPT Image 2 prompt in skills/gpt-image-2 → WebP 1536x1024, no embedded body text"
"User avatars: UI Faces API or DiceBear generative avatars"
For programmatic avatar generation (no network needed):
npm i @dicebear/core @dicebear/collection
Rule C5 — Component Library Discipline
Choose ONE primary component library at project start.
NEVER hand-build what the library already provides.
NEVER mix component libraries on the same page.
If the library lacks a specific component:
1. Check if a headless version exists (Radix, Headless UI)
2. Build it using the library's design tokens
3. Style it consistently with the library's patterns
Offline Resource Checklist
For production reliability, install these locally at project initialization:
# Icons (choose ONE)
npm i lucide-react # or lucide-vue-next# Fonts (choose as needed)
npm i @fontsource-variable/inter
npm i @fontsource-variable/jetbrains-mono
# Animation
npm i framer-motion # React
npm i @vueuse/motion # Vue# Illustrations (for generative avatars/placeholders)
npm i @dicebear/core @dicebear/collection
# Component library (choose ONE, see Tech Stack Matrix below)
npm i @radix-ui/themes # or ant-design, etc.
Part 10: Design-Driven Tech Stack Catalog & Recommendation
📦 Fresh catalog (2026-05 audit): The authoritative, regularly-updated inventory of 70+ component libraries lives in designdna/components/ with health indicators (🟢 active / 🟡 maintenance / 🔴 deprecated), GitHub stars, last-commit dates, and migration paths:
Load these files first when the user asks for a tech-stack recommendation — they supersede any stale data in the tables below. The tables here are narrative guidance; the components/ folder is the source of truth.
2026 audit — platform guidance:
For new iOS projects prefer SwiftUI + Apple HIG. material-components-ios is archived but still usable for existing projects (migrate on your cadence).
For new Flutter projects use the SDK-bundled package:flutter/material. The standalone material-components-flutter has been consolidated into the SDK.
material-web (Lit) is in maintenance mode — safe for existing projects, evaluate alternatives (MUI / Shoelace) for greenfield.
For new React + Microsoft work use @fluentui/react-components v9, not the v8 Fabric branch.
For WeChat MiniProgram native use Vant Weapp or TDesign MiniProgram. Older iView Weapp / Wuss Weapp / TouchWX have been dormant 5-8 years.
For multi-MP vendor use Taro + NutUI. Remax stopped in 2022.
Bootstrap v4 is security-only — v5.3 is the current version.
Chakra v2 is still widely deployed; v3 (Panda CSS) is the modern path.
Scope: This section recommends tech stacks from a design expression perspective — "which library best expresses this design intent?" For framework architecture, state management, build tools, and implementation patterns, defer to frontend-patterns, web-development, and coding-standards skills.
User Choice Protocol:
When the user has NOT specified a tech stack → present the top 2-3 options with design-focused reasons, then ask "Which would you prefer?"
When the user HAS already chosen a stack → respect their choice, NEVER suggest switching. Adapt all design resource selections to match.
When the user's choice differs from recommendation → acknowledge, adapt, proceed. Design advice remains valid regardless of framework.
When another skill (e.g. frontend-patterns) recommends a different framework for engineering reasons → BOTH recommendations are valid. Present both perspectives, let user decide.
10.1 Web UI Frameworks — Complete Catalog
React Ecosystem
Framework
Meta-Framework
Component Library Options
Best For
React
—
Radix, shadcn/ui, Ant Design v6, Ant Design X, TDesign React, Mantine, Chakra, MUI
Interactive SPAs, complex state
Next.js
React SSR/SSG/RSC
shadcn/ui (recommended), Ant Design v6, TDesign React, Mantine
Full-stack web apps, SEO-critical
Remix
React SSR
shadcn/ui, Mantine, Chakra
Data-heavy apps, nested routing
Gatsby
React SSG
MUI, Chakra, Theme UI
Content sites, blogs, marketing
React Component Libraries — Full List:
Library
GitHub
Styling
Strength
Stars
shadcn/ui
shadcn-ui/ui
Tailwind
Copy-paste, full control, best DX
80k+
Radix UI Primitives
radix-ui/primitives
Unstyled
Accessibility-first headless
16k+
Radix Themes
radix-ui/themes
Built-in
Pre-styled Radix
5k+
Ant Design
ant-design/ant-design
CSS variables / token API
Enterprise CN, data-dense
97k+
Ant Design X
ant-design/x
antd tokens
React AI chat / copilot UI
3k+
MUI (Material UI)
mui/material-ui
Emotion/Styled
Material Design, largest component set
95k+
Mantine
mantinedev/mantine
CSS Modules
100+ hooks, batteries-included
27k+
Chakra UI
chakra-ui/chakra-ui
Emotion
Accessible, great theming API
38k+
NextUI
nextui-org/nextui
Tailwind
Modern, beautiful defaults
22k+
Headless UI
tailwindlabs/headlessui
Tailwind
Official Tailwind unstyled
26k+
React Aria
adobe/react-spectrum
Any
Adobe's accessibility primitives
13k+
Arco Design
arco-design/arco-design
Less
ByteDance enterprise
4k+
Semi Design
DouyinFE/semi-design
SCSS
ByteDance modern enterprise
8k+
Geist UI
geist-org/geist-ui
CSS-in-JS
Vercel-style minimalist
4k+
Park UI
park-ui/park-ui
Tailwind
Ark UI + Park styling
2k+
DaisyUI
saadeghi/daisyui
Tailwind
Tailwind component classes
34k+
Flowbite React
themesberg/flowbite-react
Tailwind
Tailwind pre-built
2k+
Vue Ecosystem
Framework
Meta-Framework
Component Library Options
Best For
Vue 3
—
TDesign, Element Plus, Naive UI, Vuetify, PrimeVue
Note: This recommendation is from a DESIGN perspective — "which stack best expresses the target aesthetic?"
If frontend-patterns or web-development skills are also active, their engineering perspective may differ. Present both and let the user decide.
When the user asks to build something, follow this decision flow:
Step 1: Ask "What platform?" (if not obvious from context)
├─ Web app → Step 2a
├─ Mobile app → Step 2b
├─ Mini program → Step 2c
├─ Desktop app → Step 2d
├─ Cross-platform → Step 2e
└─ Special → Step 2f
Step 2a (Web): Ask "What type of web app?"
├─ SaaS / Tool → Next.js + shadcn/ui + Tailwind + Lucide
├─ Admin / Dashboard → Next.js + Ant Design (or TDesign for CN)
├─ Landing page → Astro or Next.js + Tailwind + Framer Motion
├─ Blog / Documentation → Astro + Tailwind (or VitePress for Vue)
├─ E-commerce → Next.js + shadcn/ui + Commerce SDK
├─ Real-time / Chat → Next.js + shadcn/ui + WebSocket
├─ Data visualization → Next.js + Tremor or Recharts + Tailwind
├─ Chinese enterprise → Vue 3 + Element Plus or TDesign
└─ Portfolio / Creative → Astro or Next.js + Tailwind + GSAP
Step 2b (Mobile): Ask "Which platforms?"
├─ iOS + Android → Expo (React Native) + Paper or Tamagui
├─ iOS only → SwiftUI (native)
├─ Android only → Jetpack Compose (native)
├─ High-fidelity UI → Flutter + Material 3
└─ HarmonyOS → ArkUI (ArkTS)
Step 2c (Mini Program): Ask "Which platform?"
├─ WeChat only → Native + TDesign Mini or Vant Weapp
├─ Multi-platform → UniApp + uView or Taro + NutUI
├─ Alipay → Native + Ant Design Mini
└─ ByteDance → Native + Arco Design Mini
Step 2d (Desktop): Ask "Main language?"
├─ TypeScript/JS → Tauri + React/Vue + shadcn/ui + Tailwind
├─ Go → Wails + Vue + Naive UI
├─ Rust → Tauri native or Tauri + web frontend
├─ C#/.NET → WPF or MAUI
├─ Kotlin → Compose Desktop
├─ Swift → SwiftUI macOS
└─ C++/Python → Qt or GTK
Step 2e (Cross-platform): Ask "Which surfaces?"
├─ Web + Mobile → Next.js (web) + Expo (mobile) + shared Tailwind tokens
├─ Mobile + Desktop → Flutter (all) or Compose Multiplatform
├─ Web + Mobile + Mini → UniApp (Vue) or Taro (React)
└─ All platforms → Flutter or separate best-of-breed per platform
Step 2f (Special):
├─ Chrome extension → Plasmo + React + Tailwind
├─ VS Code extension → @vscode/webview-ui-toolkit
├─ CLI tool → Ink (React for CLI)
├─ Email template → React Email + Resend
└─ 3D / Game → Three.js + React Three Fiber
10.8 User Choice Override Protocol
When the user has already chosen a stack that differs from our recommendation:
User says: "I want to use [X]"
AI response pattern:
1. Acknowledge: "Great, I'll build this with [X]."
2. (Optional brief note ONLY if there's a significant trade-off):
"Quick note: [X] works well for this. [Y] is also popular for this type of project
due to [reason], but [X] is a solid choice. Let's proceed with [X]."
3. Adapt ALL selections to match:
- Icon set → pick the best match for [X]
- CSS approach → pick what's native to [X]
- Animation → pick compatible library
- Fonts → same (universal)
4. Proceed without further questioning.
Adaptation table — when user picks a specific framework, automatically pair:
User Chooses
Auto-Pair Icons
Auto-Pair CSS
Auto-Pair Animation
React + any
Lucide React
Tailwind CSS
Framer Motion
Next.js
Lucide React
Tailwind CSS
Framer Motion
Vue + any
Iconify Vue
UnoCSS or Tailwind
@vueuse/motion
Nuxt
Iconify Vue
UnoCSS or Tailwind
@vueuse/motion
Angular
Angular Material Icons
SCSS
Angular Animations
Svelte / SvelteKit
Lucide Svelte
Tailwind CSS
Svelte transitions
Solid.js
Lucide (generic SVG)
Tailwind CSS
Solid Transition Group
Flutter
Material Icons
Flutter ThemeData
Flutter built-in
React Native / Expo
Expo Vector Icons
StyleSheet / NativeWind
Reanimated
UniApp
uni-icons
UniApp built-in
uni.animation
Taro
@tarojs/icons
Taro CSS
Taro animation API
Electron + React
Lucide React
Tailwind CSS
Framer Motion
Tauri + Vue
Iconify Vue
UnoCSS
@vueuse/motion
Wails + Vue
Iconify Vue
UnoCSS
@vueuse/motion
HTMX
Lucide (SVG)
Tailwind CSS
CSS transitions
Astro
Astro Icon
Tailwind CSS
View Transitions
10.9 Project Bootstrap Quick Commands
React / Next.js (Most Common):
npx create-next-app@latest my-app --typescript --tailwind --eslint --app
cd my-app && npx shadcn@latest init
npm i lucide-react @fontsource-variable/inter framer-motion
Vue / Nuxt:
npx nuxi@latest init my-app
cd my-app && npm i naive-ui @iconify/vue @vueuse/motion
npm i @fontsource-variable/inter unocss -D
Angular:
ng new my-app --style=scss --routing
cd my-app && ng add @angular/material
npm i @fontsource-variable/inter
Svelte / SvelteKit:
npx sv create my-app
cd my-app && npx shadcn-svelte@latest init
npm i lucide-svelte @fontsource-variable/inter
Astro:
npm create astro@latest my-app -- --template minimal
cd my-app && npx astro add tailwind
npm i astro-icon @fontsource-variable/inter
Expo (React Native):
npx create-expo-app my-app --template blank-typescript
cd my-app && npm i react-native-paper react-native-safe-area-context
npx expo install react-native-reanimated
Flutter:
flutter create my_app --platforms=android,ios
cd my_app
# Material 3 is built-in, enable in ThemeData
Tauri (Desktop):
npm create tauri-app@latest my-app -- --template react-ts
cd my-app && npx shadcn@latest init
npm i lucide-react @fontsource-variable/inter framer-motion
WeChat Mini Program + TDesign:
# In mini program project root:
npm i tdesign-miniprogram
# Build npm in WeChat DevTools → Tools → Build npm
UniApp:
npx degit dcloudio/uni-preset-vue#vite-ts my-app
cd my-app && npm i uview-plus
Chrome Extension:
npm create plasmo@latest my-ext -- --with-tailwindcss
cd my-ext && npm i lucide-react @fontsource-variable/inter
Part 11: Integrated Design-to-Development Workflow
This is the complete workflow that combines design resources, DESIGN.md, and tech stack into a seamless pipeline.
Phase 0: Project Initialization
1. Identify project type and platform
2. Select tech stack from Part 10 matrix
3. Choose design archetype from Part 2
4. Initialize project with Quick Commands from Part 10
5. Install offline resources (icons, fonts, animation)
Phase 1: Design System Setup
1. Generate DESIGN.md (9-section format from Part 1)
2. In Section 2 (Colors):
- Derive from archetype palette OR use Realtime Colors to preview
- Define ALL as CSS variables or Tailwind theme
3. In Section 3 (Typography):
- Install chosen fonts via Fontsource (offline)
- Define hierarchy table with exact values
4. In Section 4 (Components):
- Map to chosen component library's components
- Document which library component implements each design element
5. Create theme configuration file matching DESIGN.md to library
Phase 2: Asset Preparation
0. Inspiration research: extract principles, never clone assets
- Sources: Dribbble, Awwwards, Page Flows, Muzli, ZCOOL, Alibaba UED
- Extract: grid, density, image treatment, component rhythm, motion intent
- Convert the useful parts into DESIGN.md tokens/rules before implementation
1. Core asset protocol for named brands/products
- Verify current product/company facts before collecting assets
- Ask/search/download/verify/freeze assets into brand-spec.md or equivalent notes
- Priority: logo → product render/photo → UI screenshot → colors → fonts → mood words
- For important non-logo visuals, use the 5-10-2-8 gate:
5 source/search passes → 10 candidates → keep 2 → each should score 8/10+
- Score by resolution, provenance, brand fit, composition consistency, narrative usefulness
