Design Knowledge Base — for design-builder

You are the knowledge base behind the design-builder plugin. Commands in commands/ (/setup, /start, /design_page, /design_screen, /build, /improve, /review) activate you to resolve facts, apply filters, and enforce rules. The portable design-builder skill also activates these same workflows in Codex. Read host compatibility first; use actual host tools and preserve the user's scope.

The two failure modes this skill exists to prevent — read first.

Discovery proportional to the task

Use setup discovery for a new, undecided design direction. Reuse a supplied brief, existing tokens and choices already accepted in this chat. For scoped reviews and fixes, proceed with the available project context. If the user delegates choices, state your assumptions and continue; ask only for consequential missing information.

Failure mode 2 — describing variants in prose instead of rendering

When a command asks for "2-3 candidates" (/setup's direction proposal, /design_page's and /design_screen's reference picker), your default is to write paragraphs of prose: "A. Editorial — light, warm. B. Forest-block — dark, confident…" Don't.

For /setup direction candidates: each candidate gets the verbose block format defined in commands/setup.md Phase 3. The HTML preview in Phase 4 is mandatory (unless explicitly skipped) — never offer "I can render previews if you want", they are required.

For /design_page and /design_screen page references: each reference gets the card format defined in commands/design_page.md Phase 3.

If you find yourself drafting a generic A/B/C narrative — stop. Use the structured per-candidate format and (for /setup) render the HTML preview.

Architecture — three layers

┌──────────────────────────────────────────────────────────────────┐
│  COMMANDS    (commands/setup,start,design_page,design_screen,build,improve,review.md)  │
│  Entry points the user invokes. Thin scenarios.                   │
└────────────────────────────┬─────────────────────────────────────┘
                             │ activate this skill, which:
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│  Layer 2: DESIGN FILTERS  (gating — what we will not emit)        │
│  Direction · Dials · Aesthetics · Anti-Patterns ·                 │
│  Distinctiveness Gate · Output Rules                              │
│  ALL SIX always run before emit. Silent skip = AI slop.           │
└────────────────────────────┬─────────────────────────────────────┘
                             │ candidate facts come from ↓
┌──────────────────────────────────────────────────────────────────┐
│  Layer 1: KNOWLEDGE BASE  (informing — where facts come from)     │
│  Project tokens · designlib MCP (incl. inspiration_pages) ·       │
│  local CSV · iOS HIG · free generation                            │
│  Resolved via get_design_reference(type, filters)                 │
└──────────────────────────────────────────────────────────────────┘

THE RULE: every command emits design output by (1) resolving facts through Layer 1 in the fixed source order, (2) gating output through all six Layer 2 filters, in that order. Silently skipping Layer 2 is the single most common way this skill produces "AI slop" — do not do it.

Architecture detail + extension points: references/architecture.md.

Agent delegation

The shared audit lives in references/audit-workflow.md; run it inline when delegation is unavailable or disallowed. Claude also has one native adapter in agents/:

/setup, /design_page, /design_screen, /build, /improve run inline through this skill — no delegation. The earlier v1.2 plugin shipped six agents (design-system-architect, design-critic, motion-auditor, polish-fixer, brand-agent); they were removed because Claude doesn't reliably auto-delegate, and the rules had to live inline anyway. Only the auditor survives.

Layer 1: Knowledge Base — where facts come from

get_design_reference(type, filters) describes resolver pseudocode, not an executable tool. Apply that source-selection process with available host tools. See references/layer1-resolvers.md for the full contract, the MCP_TOOL_MAP, and the resolution-order pseudocode.

Source order (strict)

1. Project tokens — design/tokens.css, design/design-system.md, design/style-guide.md, design/content-library.md, tailwind.config.*, *.xcassets. Read when a command wants "use what the user has". 1.5. Spec files (only for /build) — design/pages/<name>.md, design/screens/<name>.md. /build's primary Layer 1 source: the spec already committed to the references during /design_page / /design_screen, including chosen anchor inspiration_page IDs and per-section anchors. /build does NOT re-resolve references; it honors what the spec captured. (For /design_page, /design_screen, /setup, /improve, /review — sources 1, 2, 3, 4, 5 apply as before, no spec source.)
2. designlib MCP — primary source for most types. New in v2.0: inspiration_pages (whole-page references with palette / typography / sections / generation_prompt) via list/get_inspiration_pages, plus animations (whole React component recipes — hero / background / text-effect / loader / overlay, verbatim TSX in prompt_text) via list/get_animations. Existing: palettes, styles, font_pairs, icons, landing_patterns, chart_types, domains. Filters are SINGULAR (one mood, one signature, one keyword, one category); to combine values, call multiple times and dedupe.
3. Local CSV — scripts/search.py over data/. UX guidelines, tech-stack specifics, react-performance, ui-reasoning, app-interface, anti-patterns. (Charts, landing_patterns, icons → designlib MCP, no longer local.)
4. iOS HIG references — references/ios/. Apple-specific rules. Use when filters specify platform='ios'.
5. Free generation — last resort. Mark source='free' on the result.

If designlib MCP is NOT connected and a user starts a design system from scratch, tell them once:

"designlib MCP is not connected. It gives authoritative palettes/fonts/inspiration_pages for web + iOS. Check the plugin MCP connection in your host. Proceeding with local CSV fallback."

Motion sub-source (KB-EXTENSION)

When the resolved type is animation or the spec includes an animation: block, the designlib MCP gives what to do (the recipe / inspiration); the motion sister skill at ../motion/SKILL.md gives how to implement it (library choice, registration patterns, easing, performance, accessibility). Always consult both — the MCP picks the candidate, the motion skill writes correct code.

The motion skill also owns video mode (HyperFrames) when the user asks for an MP4 / WebM / short-video deliverable rather than UI motion.

Live web reference capture (visual augmenter, KB-EXTENSION)

Not a Layer 1 source on its own — a visual augmenter for sources that already return a record with a url field (today: inspiration_pages.url; future: any whole-page reference). The canonical fact still comes from designlib MCP; playwright-cli (../playwright-cli/SKILL.md) just adds rendered pixels so commands can reason about composition, not only metadata.

Used by /improve --restructure (caches inspiration_page captures to design/.cache/inspiration/<page_id>.png) and /review (captures user-supplied URLs to design/screenshots/<slug>.<viewport>.png for the auditor). Skip silently if playwright-cli is unavailable — never block a rebuild on it.

Schema map for inspiration_pages

references/inspiration_pages.md — vocab, filter triad, field semantics, known issues. Load whenever a command resolves type='page'. Key facts: inspiration_pages are web-only; list_inspiration_pages returns a SUBSET of fields (deep-fetch via get_inspiration_page(page_id=...) for palette/typography/sections/generation_prompt).

Platform router

Primary platforms: web · ios · cross.

Inference: SwiftUI/UIKit code present → ios; tailwind.config / package.json with React/Next → web; both → ask the user.

iOS output: xcassets, SwiftUI Color extensions, Dynamic Type, .sensoryFeedback, Liquid Glass on iOS 26. Web output: CSS custom properties + Tailwind/shadcn.

iOS deep references: references/ios/ — 18 files. Load on demand.

Context gathering

Required minimum: target audience, top 3 use cases, brand personality (3 concrete words), platform.

Where to find: design/.cache/interview.json (written by /setup), or by reading the project's brief/PRD.

For new branding, do not invent audience or product facts. For bounded review/fix work, code and the user's request can supply enough context; mark unavailable visual or brand evidence as unassessed.

Reference index

Token sources

Platform-agnostic

Web

iOS

Figma (when MCP available)

Brand & assets

Data & scripts

Templates

Layer 2: Design Filters — what we will not emit

Every command-emitted output MUST pass through all six filters before emit. If a filter rejects, either re-resolve Layer 1 with tighter constraints, or ask the user to relax the filter explicitly. Do not bypass silently.

Distinctiveness Gate

The Anti-Pattern filter catches technical AI-slop (3-column rows, gradient text, side-stripe). It does not catch outputs that are technically clean and creatively forgettable.

The Distinctiveness Gate asks the model — privately, before showing the user — 8 questions: one-line takeaway, 30-second-without-context test, risk inventory, named reference, brief-shaped element, cross-variant differentiation, load-bearing element, and layout posture (only when VARIANCE ≥ 7). Adjective answers fail; concrete answers pass.

• HARD mode on /setup direction candidates: failures regenerate silently.
• HARD-with-1-retry on /design_page and /design_screen page output: first failure regenerates once with a changed input; second failure emits SOFT with a Risks taken & gaps block.
• SOFT mode on /improve (default mechanical mode): annotate, don't regenerate user code.
• Evaluator mode inside /review: the auditor applies it to as-built surfaces.

Full spec: references/distinctiveness-gate.md.

Design Direction

Commit to a BOLD direction. Purpose / tone / differentiation. Bold maximalism and refined minimalism both work — the key is intentionality. For /design_page, /design_screen, and /build, the direction is read from design/design-system.md (set by /setup); commands must respect it, not override.

Design Dials

Three tunable parameters: DESIGN_VARIANCE (1-10, default 8), MOTION_INTENSITY (1-10, default 6), VISUAL_DENSITY (1-10, default 4). User sets in chat or via /setup (persisted to design/.cache/interview.json). Detail: references/design-dials.md.

Output Rules

A partial output is a broken output.

Banned: // ..., // rest of code, // TODO, /* ... */, bare ..., "for brevity", "the rest follows the same pattern", "I can provide more details", skeletons when full implementation requested.

When approaching token limit: write at full quality to a clean breakpoint, then:

[PAUSED — X of Y complete. Send "continue" to resume from: next section]

Frontend Aesthetics — core rules

Web detail in references/web/, iOS detail in references/ios/. Top-level summary follows; drill in when working.

Typography

Pair distinctive display + refined body. Web: references/web/typography.md. iOS Dynamic Type: references/ios/layout.md.

Color

Cohesive palette; dominant + sharp accents. Web: references/web/color-and-contrast.md. iOS: references/ios/color.md. LILA BAN detail in BAN 3.

Layout & Space

Web: references/web/spatial-design.md. iOS: references/ios/layout.md.

Motion

High-impact moments > scattered micro-interactions. Web: references/web/motion-design.md + references/web/motion/. iOS: references/ios/motion.md.

For implementation (which library, how to register, easing/performance/accessibility) and for short-video output (HyperFrames pipeline), use the sister skill: ../motion/SKILL.md.

Interaction

Web: references/web/interaction-design.md. iOS: references/ios/gestures.md, modals.md, controls.md.

Responsive (web)

references/web/responsive-design.md.

Haptics (iOS)

references/ios/haptics.md.

UX Writing

Web: references/ux-writing.md. iOS: references/ios/ui-writing.md.

Anti-Patterns (The AI Slop Test)

If you showed this interface to someone and said "AI made this," would they believe immediately? If yes, that's the problem.

Absolute Bans

• BAN 1: Side-stripe borders — border-left:/border-right: > 1px on cards/list items/callouts/alerts.
• BAN 2: Gradient text — background-clip: text with gradient background.
• BAN 3: AI color palette — cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds.
• BAN 4: 3-column card layouts — generic "3 equal cards horizontally" feature rows. Use 2-column zig-zag, asymmetric grid, or horizontal scroll.

Technical rules

• Animate only transform / opacity (GPU-accelerated) on web.
• iOS: .animation() scoped to value; Reduce Motion = substitute (not remove).
• No h-screen — use min-h-[100dvh].
• No window.addEventListener('scroll') — use IntersectionObserver / Framer Motion hooks.
• No z-50 / z-10 spam — z-index only for systemic layers.
• Check package.json / Swift Package deps before importing any 3rd-party library.

Motion-specific anti-patterns

Full P0–P3 list at ../motion/references/anti-patterns.md. When a candidate output includes motion, walk that list as part of the Anti-Patterns filter pass — P0 (accessibility breakers) and P1 (AI-slop tells) are constraints on emitted code.

Implementation Principles

Match implementation complexity to aesthetic vision. Maximalist → elaborate animations/effects. Minimalist → restraint, precision, spacing.

Interpret creatively. Make unexpected choices. NEVER converge on common choices across generations.