Design Engineering

Design Engineering

Premium design engineering for agentic workflows. Produce distinctive, high-end interfaces — not generic AI output — using DESIGN.md as the portable design contract across three complementary tools.

DESIGN.md (contract) ─────────────────────────────────────────────────
    │                         │                        │
    ▼                         ▼                        ▼
  Stitch                   Pencil                    Figma
  (explore)              (design in IDE)         (refine + handoff)
    │                         │                        │
    └─────────────────────────┴────────────────────────┘
                              │
                              ▼
                    Production Code
                 (validated via screenshots)

Quick Start

1. Create or Load DESIGN.md

Every project needs a DESIGN.md at its root. Generate one from an existing project:

# From existing code (read globals.css, extract tokens)
# Agent analyzes CSS → generates DESIGN.md in Stitch spec format

# From a reference website (via Stitch)
# Use stitch-design skill → extract_design_context → synthesize DESIGN.md

# From a Figma file
# Use Figma MCP → get_variable_defs + get_design_context → synthesize DESIGN.md

2. Design Pipeline

3. Validate Design Quality

After every major design step, run the Premium Design Checklist:

• [ ] No generic AI aesthetic (purple gradients on white, stock photos, identical cards)
• [ ] Consistent atmospheric hue across all neutral surfaces (never pure gray)
• [ ] Maximum 2-3 saturated brand colors + semantic states
• [ ] Custom typography (not Inter/Roboto/Arial defaults)
• [ ] Glass/material metaphor with deliberate restraint (3-5 glass surfaces per viewport)
• [ ] Tiered animation timing (150ms hover → 250ms transition → 500ms morph → 1500ms ambient)
• [ ] WCAG 2.2 AA: 4.5:1 text contrast, visible focus indicators, 24x24px touch targets
• [ ] Reduced motion: prefers-reduced-motion disables all animation
• [ ] Mobile-first: 16px min font on inputs, responsive breakpoints tested

The DESIGN.md Specification

DESIGN.md is a portable, agent-friendly markdown file following Google Stitch's five-section format. It captures a project's visual identity in terms readable by both humans and AI agents.

Required Sections

Writing Rules

• Evocative names: "Resonant AI Blue" not "blue"; "Abyssal Indigo" not "dark background"
• Precise values in parens: oklch(0.55 0.25 260) / #0066ff after every descriptive name
• Functional purpose: Every color/component explains what it's used for
• Physical descriptions: "Pill-shaped" not rounded-full; "Whisper-soft shadows" not shadow-sm
• Never raw CSS class names: Translate all technical values into design language

How Agents Use DESIGN.md

1. Read DESIGN.md at the start of every design or frontend task 2. Apply tokens — use the exact color values, font stacks, spacing units, and animation timings 3. Follow component patterns — buttons, cards, inputs should match the described styling 4. Validate against it — every generated component should pass a visual audit against the spec 5. Update it — when the design system evolves, keep DESIGN.md current

Multi-Tool Pipeline

Pencil MCP (Design in IDE)

Agent-native vector design on an infinite canvas. .pen files are JSON, live in Git, and are read/written via MCP tools.

Core workflow: 1. get_editor_state() — understand current context 2. get_guidelines("web-app") — load design rules for your project type 3. get_style_guide_tags → get_style_guide(tags) — choose aesthetic direction 4. set_variables(...) — set design tokens from DESIGN.md 5. find_empty_space_on_canvas(...) — locate placement for new frames 6. batch_design(operations) — create/modify design (max 25 ops per call) 7. get_screenshot(nodeId) — validate visually after every major step 8. snapshot_layout() — verify computed positions, detect clipping/overflow

Design-to-code: Agent reads .pen tree via batch_get, extracts layout/styling, generates React + Tailwind components referencing DESIGN.md tokens.

Key rules:

• Always take screenshots after major design steps
• Keep batch_design to max 25 operations per call
• Use realistic content, never "Lorem ipsum"
• Name layers semantically ("UserAvatarImage" not "Rectangle 12")
• Desktop-first at 1440px unless mobile-first specified
• Mark reusable patterns with reusable: true

Figma MCP (Refine + Handoff)

Industry-standard design tool with official MCP server for agent integration.

Setup:

# Official Figma MCP (hosted, OAuth)
claude mcp add --transport http figma https://mcp.figma.com/mcp

# Framelink (community, most popular, 90% payload compression)
claude mcp add figma-framelink -- npx figma-developer-mcp --figma-api-key=YOUR_KEY

Core workflow: 1. get_design_context(url) — extract layout/styling for a frame (React + Tailwind default) 2. get_variable_defs(url) — read design tokens (colors, spacing, typography) 3. get_code_connect_map(url) — map Figma components → codebase components 4. get_screenshot(url) — visual snapshot for fidelity validation 5. create_design_system_rules(url) — generate agent-readable rules file

Design tokens pipeline:

Figma Variables → REST API / plugin → DTCG JSON → Style Dictionary → CSS / iOS / Android

Google Stitch (Vibe Exploration)

AI-native design platform for rapid UI exploration from natural language.

Setup:

# Install skills (already done globally)
npx skills add google-labs-code/stitch-skills --yes --global

# MCP server
npx @_davideast/stitch-mcp init
# or set STITCH_API_KEY and configure manually

Core workflow: 1. Describe a goal, feeling, or inspiration — not a wireframe 2. Stitch generates multiple high-fidelity UI directions 3. Extract design DNA via extract_design_context 4. Synthesize into DESIGN.md via the design-md skill 5. Export to Figma (with Auto Layout) or download HTML/CSS

DESIGN.md generation pipeline (5 stages): Retrieval → Extraction → Translation → Synthesis → Alignment

Premium Design Principles

What Makes Design Look Premium

1. Deliberate restraint — every element earns its place; nothing is there by default 2. Material metaphor — surfaces feel like glass, paper, stone, or metal — not flat rectangles 3. Atmospheric hue — never pure gray; always a subtle color tint in neutrals (e.g., 275-hue blue-purple) 4. Micro-detail precision — kerning, line spacing ratios, shadow angles, border opacities all consciously chosen 5. Custom typography — distinctive font pairing that immediately separates from generic defaults 6. Interaction choreography — tiered animation timing creates rhythm and hierarchy 7. Light simulation — top-edge gradient highlights on glass surfaces simulate physical light 8. Dominant + accent — one strong brand color with sharp accents, never evenly distributed

What Makes Design Look Generic AI (Avoid These)

Color System Principles

• Define all colors in OKLCH (perceptually uniform lightness)
• Provide hex fallbacks via @supports not (color: oklch())
• Enhance brand colors on P3 displays via @media (color-gamut: p3)
• Limit saturated colors to 2-3 brand + 4 semantic (success, warning, error, info)
• Maintain a consistent hue undertone across all neutral surfaces

Typography Principles

• Pair a confident display face (headings) with a precise body face
• Establish explicit weight hierarchy: Display (SemiBold), Body (Regular), UI Labels (Medium)
• Set text-rendering: optimizeLegibility, antialiased smoothing
• Use text-wrap: balance for headlines
• Minimum 16px font on mobile inputs to prevent iOS Safari zoom

Accessibility Enforcement (WCAG 2.2 AA)

These are non-negotiable in every design:

Color Contrast

• Normal text: 4.5:1 minimum contrast ratio
• Large text (18pt+ or 14pt+ bold): 3:1 minimum
• UI components and graphics: 3:1 minimum

Focus Indicators

• Visible focus on all interactive elements (2px solid outline, 2px offset)
• 3:1 contrast between focused and unfocused states
• Never trap or hide focus

Keyboard & Navigation

• All functionality available via keyboard
• Logical tab order
• Skip navigation links on content-heavy pages

Touch Targets

• Minimum 24x24 CSS pixels (WCAG 2.2 AA)
• Recommended 44x44px (Apple HIG) / 48x48dp (Material)

Motion

• Comprehensive prefers-reduced-motion support
• Collapse all animation to 0.01ms duration
• Disable hover transforms in reduced motion mode

Semantic HTML

• aria-invalid for error identification
• required / aria-required for required fields
• ARIA live regions for status messages

Visual Validation Workflow

After Every Major Design Step:

1. Screenshot — use Pencil get_screenshot or browser screenshot tools 2. Layout inspection — use Pencil snapshot_layout(problemsOnly: true) to detect clipping/overflow 3. Token audit — use search_all_unique_properties to find raw hex values that should be tokenized 4. Contrast check — verify all text/background combinations meet WCAG ratios 5. Responsive test — validate at 375px (mobile), 768px (tablet), 1440px (desktop) 6. Dark/light mode — verify both themes maintain contrast and readability

Design Token Audit

search_all_unique_properties → find leaked raw values
replace_all_matching_properties → tokenize to variable references
get_variables → verify all tokens are defined

Animation System

Timing Tiers

Rules

• Every animation must serve navigation, feedback, or attention — no decorative-only motion
• Use CSS transitions for standard elements; Motion library for React orchestration
• Never animate width, height, top, left — use transform and opacity only
• Use will-change sparingly and remove after animation completes
• Stagger entrance animations by 50-100ms per element for cascading reveals

Design Token Architecture

Three-layer token structure (Martin Fowler's framework):

Token Flow

DESIGN.md (specification)
    ↓
globals.css (CSS custom properties)
    ↓
@theme inline (Tailwind v4 mapping)
    ↓
Component code (utility classes + cva variants)

Cross-Tool Sync

Resources

references/

• design-md-spec.md — Full DESIGN.md specification with examples and writing rules
• pencil-mcp-reference.md — Complete Pencil MCP tool reference, batch_design syntax, .pen format
• figma-mcp-reference.md — Figma MCP ecosystem (official + community), Code Connect, Variables API
• stitch-integration.md — Stitch MCP server, SDK, skills, vibe design methodology
• premium-design-principles.md — Anti-generic patterns, material metaphors, atmospheric coherence
• accessibility-enforcement.md — WCAG 2.2 AA checklist, automated enforcement strategies
• visual-validation.md — Screenshot workflows, layout inspection, token auditing, responsive testing

Accessibility Enforcement (WCAG 2.2 AA)

These requirements are non-negotiable in every design generated by an agent. Accessibility is built into generation, not added as an afterthought.

Color Contrast

Minimum Ratios (WCAG 2.2 AA)

Verification

When using OKLCH colors, calculate contrast ratio between text and background:

• oklch(0.98 0 0) (white text) on oklch(0.17 0.03 275) (surface) → passes 4.5:1
• oklch(0.50 0.02 275) (muted text) on oklch(0.12 0.02 275) (deep bg) → check carefully
• Automated tools: axe-core, Lighthouse, WebAIM contrast checker

Glass Surface Considerations

Glass surfaces with backdrop-blur can create unpredictable contrast depending on background content. Mitigate with:

• Sufficient background opacity (≥ 60% for text-bearing surfaces)
• Adding a solid fallback behind text areas
• Testing contrast with both best-case and worst-case background content

Focus Indicators

Requirements

:focus-visible {
  outline: 2px solid var(--ag-border-focus);  /* AI Blue */
  outline-offset: 2px;
  border-radius: var(--ag-radius-sm);
}

• Always visible on keyboard navigation
• 2px minimum outline thickness
• 3:1 contrast between focused and unfocused state
• 2px offset so outline doesn't overlap content
• Never hidden by other content or z-index

Interactive Element Coverage

Every one of these MUST have visible focus:

• Buttons (all variants: primary, secondary, ghost, icon)
• Links (inline and navigation)
• Inputs (text, select, checkbox, radio, switch, slider)
• Cards (if clickable)
• Tabs
• Menu items
• Modal close buttons
• Custom controls

Keyboard Navigation

Requirements

• All functionality available via keyboard (no mouse-only interactions)
• Logical tab order following visual layout (top-to-bottom, left-to-right)
• No keyboard traps (user can always Tab/Shift+Tab out)
• Skip navigation link at page top for content-heavy pages
• Escape key closes modals, dropdowns, popovers
• Arrow keys navigate within component groups (tabs, menus, radio groups)

Tab Order

<!-- Correct: follows visual order -->
<nav>...</nav>           <!-- Tab 1-5: nav links -->
<main>
  <input />              <!-- Tab 6: search -->
  <div class="card">     <!-- Tab 7: card link -->
  </div>
</main>
<footer>...</footer>     <!-- Tab 8-10: footer links -->

• Never use tabindex > 0 (disrupts natural order)
• Use tabindex="0" for custom interactive elements
• Use tabindex="-1" for programmatic focus (modals, skip targets)

Touch Targets

Minimum Sizes

Implementation

• Buttons: minimum h-9 (36px) with adequate padding
• Icon buttons: minimum 36px × 36px clickable area
• Links in text: adequate line-height for touch (1.5+)
• Close buttons: minimum 24 × 24 with padding extending the touch area
• Checkboxes/radio: minimum 24 × 24 including label as click target

Motion and Animation

prefers-reduced-motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
  /* Disable transform-based hover effects */
  .glass-card:hover, .glass-button:hover {
    transform: none;
  }
}

Requirements:

• ALL animations collapse to near-instant
• ALL hover transforms disabled
• Glow effects, pulsing, shimmer — all disabled
• Auto-playing carousels/slideshows must stop
• Page functionality must remain complete without animation

Auto-Playing Content

• Auto-playing video/audio must be pausable
• Auto-scrolling content must be stoppable
• Blinking/flashing content: never more than 3 flashes per second

Semantic HTML & ARIA

Required Attributes

Component Patterns

High Contrast and Color Independence

• Never convey information through color alone (add icons, text, patterns)
• Support forced-colors: active (Windows High Contrast)
• Provide hex fallbacks for OKLCH via @supports not (color: oklch())
• Test with color blindness simulators (protanopia, deuteranopia, tritanopia)

Text and Content

• Minimum 16px body text (14px absolute minimum for secondary text)
• Minimum 16px for mobile inputs (prevents iOS Safari zoom)
• Line height ≥ 1.5 for body text
• Text must be resizable to 200% without loss of content
• text-wrap: balance for headlines to prevent orphans
• Selection color must maintain sufficient contrast

Agent Enforcement Strategy

When generating UI code, agents MUST:

1. Include focus-visible styles on all interactive elements 2. Add ARIA attributes to all custom components 3. Set minimum touch target sizes on buttons and links 4. Include prefers-reduced-motion media query 5. Calculate and verify contrast ratios for all text/background combinations 6. Use semantic HTML elements (<button>, <nav>, <main>) not <div> substitutes 7. Add alt text to all meaningful images 8. Test tab order matches visual order 9. Include skip navigation on content-heavy pages 10. Provide hex fallbacks for OKLCH colors

DESIGN.md Specification

The DESIGN.md format was introduced by Google for Stitch as an agent-friendly markdown file that captures a project's design system in a format readable by both humans and AI agents.

Role in the File Ecosystem

Required Structure

# Design System: [Project Title]
**Project ID:** [Insert Project ID Here]

## 1. Visual Theme & Atmosphere
(Evocative mood descriptors, density, aesthetic philosophy, key characteristics)

## 2. Color Palette & Roles
(Each color: Descriptive Name + value + functional role)

## 3. Typography Rules
(Font families, weight/size hierarchy, rendering, spacing)

## 4. Component Stylings
* **Buttons:** shape, color, behavior, states
* **Cards/Containers:** corners, background, shadow, padding
* **Navigation:** layout, typography, states, mobile
* **Inputs/Forms:** stroke, background, focus, placeholder

## 5. Layout Principles
(Spacing system, grid, whitespace, responsive, animation)

## 6. Design System Notes for Stitch Generation (optional)
(Prompt templates, color reference format, iteration guidance)

Writing Rules

DO

• Use evocative, designer-friendly language: "Ocean-deep Cerulean (#0077B6)" not "blue"
• Always explain what each element is used for (functional purpose)
• Include exact values in parentheses after natural language descriptions
• Translate CSS values into physical descriptions:
• rounded-full → "Pill-shaped"
• rounded-lg → "Generously rounded corners"
• rounded-none → "Sharp, squared-off edges"
• shadow-sm → "Whisper-soft diffused shadow"
• shadow-xl → "Heavy, high-contrast drop shadow"
• Maintain consistent terminology throughout

DON'T

• Use generic terms like "blue" or "rounded" without qualification
• Use unexplained CSS class names ("rounded-xl" without "generously rounded corners")
• Rely solely on descriptive names without precise values, or vice versa
• Omit functional explanations for design components
• Use vague atmospheric descriptions without specificity

Color Entry Format

Every color entry must have three components:

- **Descriptive Name** (`color-value` / `hex-fallback`) — Functional role explaining where and when this color is used

Example:

- **Resonant AI Blue** (`oklch(0.55 0.25 260)` / `#0066ff`) — Primary brand color. Used exclusively for primary CTAs, active navigation links, focus rings, and interactive element accents

Color Organization

Group colors by functional role:

1. Primary Foundation — Background surfaces, depth layers 2. Accent & Interactive — Brand colors, CTAs, interactive states 3. Typography & Text Hierarchy — Primary, secondary, muted, disabled text 4. Functional States — Success, warning, error, info 5. Borders — Subtle, default, strong, focus 6. Charts & Data Visualization — 5-color sequential palette

Typography Entry Format

| Role | Font | Weight | Line Height | Notes |
|------|------|--------|-------------|-------|
| Display Headlines | [Name] | [Weight] | [Value] | [Context] |

Include:

• Font families with full fallback chains
• Weight names AND numeric values
• Line height for each tier
• Letter-spacing where non-default

Component Entry Format

For each component type:

1. Shape — corner radius in descriptive terms + exact value 2. Surface — background treatment (solid, glass, gradient) with opacity/blur values 3. Border — style, color, width 4. Default state — complete visual description 5. Hover state — what changes and by how much 6. Focus state — focus ring specification 7. Disabled state — opacity, pointer-events 8. Transition — duration + easing

Generation Pipeline

When creating DESIGN.md from an existing project, follow five stages:

1. Retrieval — Read the project's CSS (globals.css, theme files) and component code 2. Extraction — Identify design tokens: colors, typography, spacing, borders, shadows, radii, animations 3. Translation — Convert every CSS/Tailwind value into natural design language with values in parens 4. Synthesis — Organize into the five-section format with consistent terminology 5. Alignment — Verify all sections are complete, no raw CSS leaked, all values have descriptive names

Portability

DESIGN.md is portable because:

• Written in plain Markdown — no tool-specific syntax
• Any agent (Claude Code, Cursor, Gemini CLI, Codex) can read and apply it
• Can be generated from Stitch projects, Figma files, existing code, or hand-written
• Bridges visual design tools and code-generation agents
• Version-controllable alongside code in Git

Figma MCP Reference

Figma is the industry-standard design tool with multiple MCP server options for agent integration.

MCP Server Options

Official Figma MCP (Recommended)

Hosted by Figma — no local installation required.

# Claude Code setup
claude mcp add --transport http figma https://mcp.figma.com/mcp

# Or via plugin
claude plugin install figma@claude-plugins-official

Auth: OAuth via browser (no personal access token needed) Rate limits: Dev/Full seats on paid plans get Tier 1 API limits; free/view seats get 6 calls/month

Tools (13):

Framelink (Community, Most Popular)

13,800+ stars. Compresses Figma API response by ~90% for better LLM accuracy.

claude mcp add figma-framelink -- npx figma-developer-mcp --figma-api-key=YOUR_KEY

Tool: get_figma_data(url) — takes a Figma URL, returns compressed design context

TalkToFigma (Bidirectional Read/Write)

6,500+ stars. Requires Figma Desktop plugin + WebSocket relay.

40+ tools including: create shapes/frames/text, set fill/stroke, manage auto-layout, clone nodes, export images, bulk text replacement.

Figma Console MCP

1,100+ stars. 63+ tools with full read+write, variable management, component instantiation, visual debugging.

Code Connect

Bridges Figma components to codebase components. The key differentiator for production-quality agent output.

Supported frameworks: React, React Native, HTML (Angular, Vue), SwiftUI, Jetpack Compose, Storybook

Workflow: 1. get_code_connect_suggestions — auto-detect Figma → code component mappings 2. Review and confirm suggestions 3. get_code_connect_map — agent uses real components instead of generating from scratch

Requires: Organization or Enterprise plan with Full Design or Dev Mode seat

Design Tokens Pipeline

Figma Variables API

• GET local/published variables, POST to create/update/delete
• Supports color, number, string, boolean types
• Multiple modes (light/dark themes)
• Enterprise plan required for API access

Export Flow

Figma Variables
    → REST API / lukasoppermann plugin
    → DTCG JSON format ($value, $type, $description)
    → Style Dictionary transform
    → CSS custom properties / SASS / iOS / Android

DTCG Token Types

• Primitive: color, dimension, fontFamily, fontWeight, duration, cubicBezier, number
• Composite: shadow, border, gradient, typography, transition, strokeStyle
• References: {group.token} syntax for aliases

Agent Workflow with Figma

Design-to-Code (Read)

1. Receive Figma frame URL from designer 2. get_design_context(url) → structured layout/styling data 3. get_code_connect_map(url) → map to existing codebase components 4. get_variable_defs(url) → extract design tokens 5. Generate production code using DESIGN.md tokens + Figma structure + mapped components

Code-to-Design (Write)

1. Build feature in code, render locally 2. generate_figma_design(url) → capture rendered UI as editable Figma layers 3. Designer reviews and refines in Figma 4. Agent picks up changes for next iteration

Design System Rules

1. create_design_system_rules(url) → generate rules file 2. Save to .cursor/rules/ or project root 3. Agent references rules during all code generation

Best Practices

1. Work one frame at a time — paste individual frame URLs, not entire pages 2. Use Code Connect first — map components before generating code 3. Specify your framework — "Generate in React + Tailwind" not just "generate code" 4. Keep screenshots enabled — visual validation alongside structured data 5. Export tokens, don't hardcode — use the Variables API → Style Dictionary pipeline 6. Link dev resources — connect Figma nodes to GitHub PRs, Jira tickets, Storybook

Pencil MCP Reference

Pencil is an AI-native vector design tool that runs in your IDE (VS Code, Cursor) or as a standalone desktop app. Design files (.pen) are JSON, live in Git, and are read/written via a local MCP server.

Architecture

Claude Code ← MCP Client → MCP Server (Pencil, local) → Design Canvas (WebGL)

No cloud dependency. The MCP server starts automatically when Pencil is open and auto-configures in .claude.json.

MCP Tools (14 total)

Context & Discovery

Design Operations

Validation

batch_design Operation Syntax

Max 25 operations per call. Sequential execution; rollback on error.

Insert

foo=I("parentId", { type: "frame", layout: "vertical", width: 390, height: 844, fill: "#1a1a2e" })

• Always needs a parent ("document" for top-level)
• Never specify id — auto-generated
• Returns binding for reference in later operations

Copy

bar=C("nodeId", "parent", { positionDirection: "right", positionPadding: 100 })

• Copies a node. If reusable, creates a connected ref instance
• Use descendants map to override child properties (do NOT use separate U() on descendants)

Replace

baz=R("instanceId/childId", { type: "text", content: "New content" })

• Replaces a node entirely. Ideal for swapping parts of component instances

Update

U("nodeId", { content: "Updated text", fill: "#0066ff" })
U(foo+"/childId", { fontSize: 24 })

• Modifies existing properties. Cannot change id, type, or ref
• Use slash-separated paths for nested component instances

Delete

D("nodeId")

Move

M("nodeId", "newParent", 2)

• Moves to new parent at specified index

Generate Image

G("nodeId", "ai", "modern glass office with blue ambient lighting")
G("nodeId", "stock", "coffee shop interior")

• Applies image fill to frame/rectangle. Two modes: "ai" (generated) or "stock" (Unsplash)
• There is NO image node type — images are fills on frames/rectangles

.pen Node Types

Layout System

Flexbox-like layout on frames:

Sizing Behaviors

• Fixed pixel value: width: 390
• Fit content: width: "fit_content"
• Fill container: width: "fill_container" (optionally with min: "fill_container(500)")

get_guidelines Topics

Variables and Themes

Variables are reusable design tokens. Types: color (hex), number, string, boolean.

• Reference with dollar-prefix: "$color.background"
• Theme support: variables can have different values per theme (light/dark)
• set_variables to create from DESIGN.md tokens
• get_variables to extract for CSS generation

Best Practices

1. Start with `get_editor_state()` — always know your context 2. Load guidelines before designing (get_guidelines for your project type) 3. Set variables first — import DESIGN.md tokens via set_variables 4. Screenshot after every major step — visual validation prevents drift 5. Max 25 ops per batch_design — split large designs by logical sections 6. Realistic content — never use "Lorem ipsum" or placeholder text 7. Semantic layer names — "UserAvatarImage" not "Rectangle 12" 8. Desktop-first at 1440px — unless mobile-first is specified 9. Mark reusable patterns — reusable: true for component library building 10. Structure first, content second — build frame hierarchy before adding text and images

Premium Design Principles

Guidelines for producing distinctive, high-end UI designs that are immediately distinguishable from generic AI-generated output.

The Premium Design Checklist

Every design must pass these checks before it ships:

Atmospheric Coherence

• [ ] Consistent hue undertone across ALL neutral surfaces (never pure gray)
• [ ] Shared material metaphor throughout (glass, paper, stone — pick one)
• [ ] Unified shadow direction and depth scale
• [ ] Color palette follows dominant + accent hierarchy (not evenly distributed)

Material Quality

• [ ] Surfaces feel like something physical (glass, metal, fabric, wood)
• [ ] Maximum 3-5 glass/blur surfaces per viewport (glass is earned, not default)
• [ ] Each glass surface uses the composable 4-layer system: backdrop blur + highlight + shadow + tint
• [ ] Light simulation via top-edge gradient highlights

Typography Distinction

• [ ] Custom font pairing (NOT Inter, Roboto, Arial, system-ui defaults)
• [ ] Explicit weight hierarchy visible in the design (display vs body vs label)
• [ ] Appropriate letter-spacing for each tier (tighter for display, normal for body, wide for badges)
• [ ] text-rendering: optimizeLegibility and antialiased smoothing

Color Precision

• [ ] All colors defined in perceptually uniform color space (OKLCH preferred)
• [ ] Maximum 2-3 saturated brand colors + 4 semantic states
• [ ] Wide-gamut P3 enhancement for brand colors where supported
• [ ] Hex fallbacks via @supports not (color: oklch())
• [ ] Descriptive names for every color (not "blue-500")

Interaction Choreography

• [ ] Tiered animation timing creates rhythm (not everything at 200ms)
• [ ] Hover effects are subtle and purposeful (lift, glow, border shift)
• [ ] Entry animations use staggered reveals (50-100ms per element)
• [ ] Ambient effects reserved for loading/attention states
• [ ] prefers-reduced-motion collapses ALL animation

Detail Precision

• [ ] Shadow opacities are intentional (0.30-0.55 dark mode, 0.05-0.18 light mode)
• [ ] Border opacities vary by purpose (subtle 0.40, default 0.50, strong 0.60)
• [ ] Radius scale is consistent and purposeful (sm/md/lg/xl/full)
• [ ] Scrollbar styling maintains the design aesthetic

Anti-Patterns: What Makes Design Look Generic AI

Material Metaphor System

Choose ONE primary material and use it consistently:

Glass (Arcan Glass)

• Translucent backgrounds via color-mix(in oklab, surface opacity%, transparent)
• backdrop-filter: blur() saturate() for frosted effect
• Top-edge gradient highlight for light simulation
• Three tiers: subtle (40%/8px), medium (60%/16px), heavy (80%/24px)

Paper/Editorial

• Flat surfaces with subtle shadows
• High contrast between surface layers
• Heavy reliance on typography hierarchy for depth
• Minimal decoration, maximum content density

Metal/Industrial

• Hard edges, sharp corners
• High-contrast borders
• Monochromatic with single accent
• Heavy shadows, minimal blur

Organic/Natural

• Generous border radius
• Warm color temperature
• Soft shadows with color tinting
• Flowing transitions, breathing animations

Color Theory for Agents

The 60-30-10 Rule

• 60% dominant color (backgrounds, surfaces) — should be your darkest/lightest neutral
• 30% secondary color (cards, containers, elevated surfaces) — slightly lighter/darker neutral
• 10% accent color (CTAs, links, highlights) — your saturated brand color(s)

Perceptual Uniformity (OKLCH)

OKLCH ensures that colors with the same lightness value LOOK equally light, regardless of hue. This prevents the common problem where "red at 50% lightness looks darker than yellow at 50% lightness."

oklch(L C H)
  L = Lightness (0 = black, 1 = white) — perceptually uniform
  C = Chroma (0 = gray, ~0.4 = maximum saturation)
  H = Hue (0-360 degrees)

Wide-Gamut Enhancement

/* Standard sRGB */
--brand-blue: oklch(0.55 0.25 260);

/* Enhanced for P3 displays */
@media (color-gamut: p3) {
  --brand-blue: oklch(0.55 0.28 260); /* higher chroma */
}

Typography Hierarchy

The Professional Stack

Font Pairing Rules

• Contrast: Heading and body fonts should be visually distinct
• Complement: They should share similar x-height and proportions
• Character: The heading font carries personality; the body font carries readability
• Consistency: Same body font for all non-heading text (labels, buttons, inputs, meta)

Animation Design Language

Purpose Categories

The One-Effect Rule

Each surface gets ONE primary effect:

• A card either glows OR lifts OR scales — not all three
• A button either shifts color OR grows — not both
• A nav either blurs OR slides — not both

Exception: composable glass layers (blur + highlight + shadow + tint) are designed as a single cohesive system, not independent effects.

Responsive Design Strategy

Breakpoint Philosophy

• Mobile-first CSS with min-width queries
• But desktop-first design — start with the full layout, then simplify for mobile
• Design at: 375px (mobile), 768px (tablet), 1440px (desktop)

Responsive Decisions

• Navigation: inline → hamburger below 768px
• Grid: 3-column → 2-column → 1-column
• Typography: scale down 15-20% on mobile
• Spacing: reduce by one step on mobile (section margins, card padding)
• Glass: reduce blur intensity on mobile for performance
• Animation: simpler on mobile, respect prefers-reduced-motion

Google Stitch Integration

Google Stitch is a free AI-native UI design platform for rapid "vibe design" — describe a goal, feeling, or inspiration, and generate high-fidelity interfaces.

Setup

Skills (Agent Knowledge)

# Install all 7 skills globally
npx skills add google-labs-code/stitch-skills --yes --global

# Or individual skills
npx skills add google-labs-code/stitch-skills --skill stitch-design --global
npx skills add google-labs-code/stitch-skills --skill design-md --global
npx skills add google-labs-code/stitch-skills --skill stitch-loop --global
npx skills add google-labs-code/stitch-skills --skill enhance-prompt --global
npx skills add google-labs-code/stitch-skills --skill react-components --global

MCP Server

# Interactive setup wizard
npx @_davideast/stitch-mcp init

# Or manual configuration (.claude/mcp.json)
{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["@_davideast/stitch-mcp", "proxy"],
      "env": {
        "STITCH_API_KEY": "your-api-key-here"
      }
    }
  }
}

SDK (Programmatic Access)

npm install @google/stitch-sdk

import { stitch } from "@google/stitch-sdk";

const project = stitch.project("your-project-id");
const screen = await project.generate("A login page with dark glass theme");
const html = await screen.getHtml();
const image = await screen.getImage();

// Edit existing screen
await screen.edit("Make the button larger and add a glow effect");

// Generate variants
const variants = await screen.variants("Try different color schemes", {
  variantCount: 3,
  creativeRange: "EXPLORE", // REFINE | EXPLORE | REIMAGINE
  aspects: ["COLOR_SCHEME", "LAYOUT"]
});

API Key

1. Go to https://stitch.withgoogle.com 2. Click profile icon → Stitch Settings → API Keys 3. Click "Create Key" — copy immediately (shown once) 4. Set: export STITCH_API_KEY="your-key" (add to .zshrc)

Available Skills

MCP Server Tools

Vibe Design Methodology

Instead of wireframes, start with one of these:

• A goal: "increase conversion on our pricing page"
• A feeling: "calm and minimal, like a meditation app"
• An inspiration: "premium and minimalist, like Stripe's website"
• A persona: "playful and colorful, targeted at Gen Z"

Stitch generates multiple high-fidelity directions — not sketches.

Generation Models

DESIGN.md Generation Pipeline

Using the design-md skill:

1. Retrieval — Fetch project screens and HTML via Stitch MCP 2. Extraction — Identify tokens: colors, typography, spacing, components 3. Translation — Convert CSS/Tailwind values into natural design language 4. Synthesis — Generate DESIGN.md in five-section semantic format 5. Alignment — Verify compliance with Stitch prompting principles

Integration with DESIGN.md

Applying DESIGN.md to Stitch Generation

When generating with Stitch, include DESIGN.md context in prompts:

"Design a dashboard with the Arcan Glass aesthetic — dark translucent surfaces with

275-hue blue-purple undertone, AI Blue (#0066ff) primary accents, glass-morphism cards

with backdrop blur, CalSans headings over Geist body text."

Extracting DESIGN.md from Stitch

1. Design screens in Stitch using vibe design 2. Run design-md skill to analyze screens 3. Agent extracts tokens and synthesizes DESIGN.md 4. DESIGN.md travels to Pencil/Figma/code as the portable contract

Export Options

• HTML/CSS — Clean, production-ready code
• Figma — Editable layers with proper Auto Layout
• Screenshot — High-resolution PNG for reference

Free Tier Limits

• 350 standard generations/month
• 50 experimental generations/month
• Full MCP server access
• No credit card required

Visual Validation Workflow

Screenshot-driven visual validation ensures agent-generated designs maintain quality, consistency, and correctness at every stage.

Core Principle

Generate → Screenshot → Evaluate → Iterate

Never proceed to the next design step without validating the current one visually.

Validation Stages

Stage 1: Structure Validation

After creating the frame hierarchy and layout:

1. `snapshot_layout()` (Pencil) — verify computed layout rectangles

• Check: no overlapping elements
• Check: no elements clipped by parent bounds
• Check: spacing between elements matches design tokens
• Use problemsOnly: true for quick audit

2. `get_screenshot(nodeId)` (Pencil) — visual confirmation

• Check: layout structure matches intent
• Check: proper alignment and visual hierarchy

Stage 2: Content Validation

After adding text, images, and component content:

1. Screenshot — verify content renders correctly

• Check: text is readable and properly sized
• Check: images have correct aspect ratio and fill
• Check: component hierarchy is clear

2. Token audit — verify design system compliance

   search_all_unique_properties(parentIds, ["fillColor", "textColor", "fontSize", "fontFamily"])

• Check: no raw hex values that should be variable references
• Check: font families match DESIGN.md specification
• Check: font sizes follow the hierarchy

Stage 3: Styling Validation

After applying colors, effects, and glass treatments:

1. Screenshot — verify visual quality

• Check: glass effects render correctly (blur, transparency, highlight)
• Check: color palette matches DESIGN.md
• Check: shadow depth creates proper elevation hierarchy
• Check: borders are consistent weight and opacity

2. Contrast check — verify accessibility

• Check: all text/background combinations meet 4.5:1 (normal) or 3:1 (large)
• Check: UI components meet 3:1 against backgrounds

Stage 4: Interaction State Validation

After defining hover, focus, active, and disabled states:

1. Screenshot each state — verify all states are distinct

• Check: hover state is noticeably different from default
• Check: focus indicator is clearly visible (2px outline, 2px offset)
• Check: disabled state shows reduced opacity

Stage 5: Responsive Validation

Test at standard breakpoints:

Stage 6: Dark/Light Mode Validation

1. Screenshot in both modes — verify theme switching

• Check: all text remains readable in both modes
• Check: glass opacity adjusts correctly (dark: 0.40-0.80, light: 0.60-0.90)
• Check: shadows adjust appropriately (lighter in light mode)
• Check: brand colors remain unchanged across modes

Design Token Audit Workflow

Find Leaked Raw Values

search_all_unique_properties(parentIds, [
  "fillColor",
  "textColor",
  "strokeColor",
  "fontSize",
  "fontFamily",
  "fontWeight",
  "cornerRadius",
  "padding",
  "gap"
])

Review results for:

• Colors not matching DESIGN.md palette → should be tokenized
• Font families not matching spec → should use variable references
• Inconsistent spacing values → should use base unit multiples
• Inconsistent corner radius → should match design token scale

Tokenize Raw Values

replace_all_matching_properties(parentIds, {
  fillColor: { from: "#0066ff", to: "$color.aiBlue" },
  textColor: { from: "#ffffff", to: "$color.textPrimary" },
  fontSize: { from: 14, to: "$size.bodySmall" }
})

Verify Token Coverage

get_variables()

Ensure all used values have corresponding variable definitions.

Cross-Tool Validation

Code → Visual Comparison

When implementing designs in code:

1. Render the component in browser 2. Screenshot the rendered output 3. Compare side-by-side with Pencil/Figma screenshot 4. Verify: colors match, spacing matches, typography matches, effects match

Figma → Code Fidelity

When implementing from Figma designs:

1. get_design_context(figmaUrl) — extract structured layout 2. get_screenshot(figmaUrl) — capture design reference 3. Implement in code 4. Screenshot the implementation 5. Compare and iterate until pixel-accurate

Automated Checks

Layout Inspection Flags

When using snapshot_layout(), flag these problems:

Color Audit Flags

Typography Audit Flags

Validation Frequency