ui-ux-master 1.2.0 → 1.5.0

package/references/competitive-landscape.md

@@ -10,6 +10,11 @@ This reference summarizes the open-source/UI-agent landscape checked while impro
 - `@assistant-ui/react`: production-grade React components for AI chat interfaces.
 - `@figma/code-connect`: strong design-to-code component mapping for Figma and codebases.
 - Mature design systems such as GOV.UK Frontend, Salesforce Lightning, Material, Carbon, Atlassian, and Fluent: strong component guidance and production CSS/component foundations.
+- `ui-ux-pro-max-skill` (nextlevelbuilder): 161 industry-specific design system generation rules, 67 UI styles, 57 font pairings, 161 color palettes, 25 chart types, 15 tech stacks, BM25-ranked reasoning engine. Multi-domain parallel search (product → style → palette → typography → pattern). MASTER.md + page-override hierarchy for design system persistence. Pre-delivery checklist on every output. Key innovations adopted into UI/UX Master v1.5.0: full industry reasoning engine, MASTER+overrides pattern, pre-delivery checklist format, chart type guide.
+- `saifyxpro/ui-ux-design-pro-skill` (2026 Edition): 107 UI styles (incl. Liquid Glass, Data Brutalism, Spatial UI, Aurora, Cyberpunk), 127 palettes, 107 font pairings, 11-step (50–950) architectural color scales with semantic roles, 150+ UX guidelines, 16 tech stacks, Orama search engine (sub-50ms), code-level AI audit detecting hallucinated Tailwind utilities, low-contrast pseudo-transparency, h-screen layout shifts. Key innovations adopted into UI/UX Master v1.5.0: 11-step OKLch scale system, UI styles catalog, code-level AI audit error codes (AI001–AI030), tech stack guidelines.
+- `ux-ui-agent-skills` (plugin87): solid 3-tier DTCG token architecture (primitive → semantic → component), dark mode swap approach, scored design review output across 6 dimensions.
+- `claude-code-ui-agents` (mustafakendiguzel): curated prompt library for component development, UX research, animation, and accessibility across multiple categories.
+- `open-design` (nexu-io): Full-stack app (daemon + Next.js + Electron), 132 skills, 150 design systems, 16 CLI adapters. Key innovations adopted into UI/UX Master v1.4.0: discovery question form, brand extraction protocol, 5-dimensional self-critique, anti-slop blacklist, 5 OKLch visual directions, 9-section DESIGN.md schema, P0/P1/P2 quality gates, honest placeholder protocol.
 
 ## Where Narrow Skills Often Outperform Generic UI Prompts
 
@@ -18,6 +23,8 @@ This reference summarizes the open-source/UI-agent landscape checked while impro
 - They focus on one concrete task, such as token extraction or component mapping.
 - Some have npm packaging and tests.
 - Some integrate with a specific agent's native command system.
+- `ui-ux-pro-max-skill` matches industry → style → color → font in one automated step with BM25 ranking, very fast for first-time project setup.
+- `saifyxpro/ui-ux-design-pro-skill` has a native CLI (Bun + Orama) with sub-50ms search, live code audit, and icon search — functionality that requires running a process, not just a Markdown skill.
 
 ## Gaps UI/UX Master Must Beat
 
@@ -30,18 +37,37 @@ UI/UX Master is designed to lead by combining the best parts:
 5. Standards alignment across WCAG, WAI-ARIA, NN/g-style heuristics, GOV.UK service patterns, Material, Apple HIG, Microsoft, ISO HCD concepts, and Baymard-style ecommerce practice.
 6. Advanced risk coverage: privacy, ethics, dark patterns, high-risk domains, AI transparency, localization, and platform conventions.
 7. Release engineering: npm package, CLI installer, tests, validator, and deployment zip.
+8. Brand-method depth: 10 dedicated skill files with full design specs (layout, typography, spacing, motion, component specs, accessibility, anti-patterns, QA) — more depth per method than any competitor.
+9. Color psychology and branding skill with industry-specific palette prescriptions, sentiment-to-color mapping, WCAG contrast verification, and dark mode adaptation rules.
+10. Discovery-first workflow: 6-question form before any visual output, brand extraction protocol (never guesses colors), 5 OKLch visual directions for brandless projects, junior-designer warm-up pass.
+11. Quality-gated output: 5-dimensional self-critique, P0/P1/P2 hard gates, anti-AI-slop blacklist, honest placeholder protocol.
+12. Portable 9-section design system schema (DESIGN.md-compatible): single source of truth for every `.ui-ux-memory.md`.
+13. **v1.5.0:** UI styles catalog (20+ named styles) — matches `saifyxpro`'s 107-style scope at the Markdown-skill layer with complete token overrides, required effects, forbidden patterns, and decision tree.
+14. **v1.5.0:** 11-step (50–950) OKLch architectural color scales — matches and extends `saifyxpro`'s scale system with full semantic role mapping and dark mode overrides.
+15. **v1.5.0:** Industry reasoning engine (15+ categories) — matches `ui-ux-pro-max-skill`'s 161-rule reasoning engine for instant Design System Block output per product type.
+16. **v1.5.0:** 16-framework tech stack guidelines — matches and extends `saifyxpro`'s 16-stack coverage with component patterns, rules, and common AI mistakes for React, Next.js, Vue, Nuxt, Angular, Svelte, Astro, Remix, SolidJS, React Native, Flutter, SwiftUI, shadcn/ui, Jetpack Compose, Laravel, HTML+Tailwind.
+17. **v1.5.0:** 12 landing page conversion patterns + 25-type chart guide — matches `ui-ux-pro-max-skill`'s 24-pattern + chart coverage.
+18. **v1.5.0:** Code-level AI audit error codes AI001–AI030 — matches `saifyxpro`'s live audit capability at the Markdown-skill layer (no CLI runtime required).
+19. **v1.5.0:** MASTER.md + page-override hierarchy — matches `ui-ux-pro-max-skill`'s design system persistence pattern.
 
 ## Remaining Honest Limitations
 
+- No sandboxed live preview or daemon: UI/UX Master is a prompt-layer skill only; `open-design` ships a full Next.js + Electron app with iframe preview, export, and SQLite persistence. If a live rendering environment is needed, pair with open-design or use a separate preview tool.
+- No built-in media generation: `open-design` integrates gpt-image-2 and Seedance video generation. UI/UX Master focuses on design specs and code-handoff, not media rendering.
 - It does not replace specialized code libraries such as assistant-ui React components or GOV.UK Frontend CSS.
-- It does not extract live design tokens from websites by itself; pair it with token-extraction tools if needed.
 - It does not integrate directly with Figma APIs; pair it with Figma Code Connect or MCP/Figma tooling if needed.
 - It cannot replace real user research, accessibility expert review, or legal/domain review in high-risk contexts.
+- No native CLI runtime: `saifyxpro` has Bun+Orama sub-50ms search, live code audit, and icon search via a real process. UI/UX Master delivers equivalent guidance as Markdown references (no install of Bun/Node required), but cannot achieve sub-50ms database lookups.
+- Fewer named styles at launch: `saifyxpro` ships 107 styles; we launch v1.5.0 with 20+ documented in depth. Volume can grow iteratively.
+- Fewer industry categories at launch: `ui-ux-pro-max-skill` has 161 product categories; we cover 15+ in depth with full Design System Blocks. Depth per category exceeds theirs; breadth can grow.
+- `open-design` has live rendering, export to PDF/PPTX/MP4, and a 132-skill catalog; UI/UX Master is a lighter-weight prompt-layer skill that works without a local daemon or Electron app.
 
 ## Strategy to Stay Ahead
 
-- Keep `/ui-ux-master` simple and opt-in.
-- Keep references standards-aligned and updated.
-- Add focused subcommands only when they preserve simplicity.
-- Validate every release with Python, Node tests, npm pack dry-run, zip extraction validation, and independent review.
-- Prefer concrete outputs: memory, specs, states, QA, acceptance criteria, and handoff.
+- Keep `/ui-ux-master` simple, opt-in, and daemon-free — one npm install, works in every agent.
+- Re-audit major competitors (`saifyxpro`, `ui-ux-pro-max-skill`, `open-design`) on every major release; close gaps in the Markdown skill layer.
+- Grow UI styles catalog and industry rules iteratively — depth per entry beats volume.
+- Discovery-first + quality-gated output as non-negotiable defaults.
+- Tech stack guidelines are a durable differentiator — keep them updated as frameworks evolve.
+- Validate every release with Python, Node tests, npm pack dry-run, and independent review.
+- Maintain DESIGN.md-compatible schema — interoperability with open-design's ecosystem is a feature, not a bug.

package/references/design-discovery-protocol.md

@@ -0,0 +1,171 @@
+# Design Discovery Protocol
+
+Load this file at the start of every fresh design task. The protocol has two phases: **intake** (question form) and **brand extraction**. Complete both before writing any CSS, tokens, or visual specs.
+
+The single biggest cause of wasted design cycles is starting visuals before locking down surface, audience, tone, and brand context. This protocol eliminates that problem.
+
+---
+
+## Phase 1 — Discovery Question Form
+
+**Rule: Turn 1 of any new design task is this form only.** Do not produce wireframes, code, tokens, or visual descriptions in the same turn as the form. Show the form. Wait. Let the user answer. Then proceed.
+
+If the user provides a very detailed brief, the form may be shortened to only the unanswered dimensions — but never skipped entirely. A detailed brief still leaves visual tone, scale, and constraints open.
+
+### Form Template
+
+Present this as a structured set of questions. Group them clearly. Give the user sensible defaults they can accept quickly.
+
+```
+Before I start designing, I need to lock down a few things (takes ~60 seconds):
+
+1. SURFACE
+   What are we designing?
+   [ ] Web page / landing page
+   [ ] Web app / SaaS dashboard
+   [ ] Mobile app (iOS / Android)
+   [ ] Email / newsletter
+   [ ] Slide deck / presentation
+   [ ] Component / design system piece
+   [ ] Other: ___
+
+2. AUDIENCE
+   Who is the primary user?
+   [ ] General consumer (any age, any tech level)
+   [ ] Professional / knowledge worker
+   [ ] Developer / technical user
+   [ ] Enterprise buyer / decision-maker
+   [ ] Children / family
+   [ ] Other: ___
+
+3. TONE
+   What should it feel like?
+   [ ] Premium / luxury — quiet, restrained, confident
+   [ ] Energetic / bold — high-contrast, expressive, dynamic
+   [ ] Calm / trustworthy — soft, clear, clinical
+   [ ] Playful / friendly — rounded, warm, approachable
+   [ ] Technical / precise — data-dense, monospace, diagram-forward
+   [ ] Minimal / editorial — lots of whitespace, typographic
+   [ ] Other: ___
+
+4. BRAND CONTEXT
+   Do you have brand assets?
+   [ ] Yes — I'll share a URL, screenshot, or hex codes
+   [ ] Partial — I have a logo but no full system
+   [ ] No brand yet — suggest directions
+   [ ] Existing codebase — inspect it first
+
+5. SCALE AND FIDELITY
+   What do you need as output?
+   [ ] Quick concept / wireframe (fast, grey-block placeholder OK)
+   [ ] Mid-fidelity mockup (layout + real colors, placeholder content OK)
+   [ ] High-fidelity spec (production-ready, real copy, all states)
+   [ ] Full design system (tokens, components, usage rules)
+
+6. CONSTRAINTS
+   Any hard requirements?
+   (Examples: accessibility WCAG AA, RTL support, dark mode required,
+    specific tech stack, existing component library, performance budget)
+   Free text: ___
+```
+
+### Form Rules
+
+- Do not interpret or guess any dimension the user has not answered.
+- If the user answers "Other" on any dimension, ask one follow-up question before proceeding.
+- If the user accepts all defaults, treat unchecked items as: Web page, General consumer, Minimal/editorial, No brand, Mid-fidelity, No constraints.
+- Once all six dimensions are answered, confirm back in one sentence: "Got it — [surface] for [audience], [tone] feel, [brand status], [fidelity] output. Starting now."
+- Then proceed to Phase 2 or directly to design if brand is already known.
+
+---
+
+## Phase 2 — Brand Extraction Protocol
+
+Run this phase when the user provides a brand URL, screenshot, or partial assets. Do **not** guess brand colors from memory. Do not assume a brand's palette from the company name alone.
+
+### 5-Step Extraction
+
+**Step 1 — Locate assets.**
+- If URL given: navigate to the homepage or provided page.
+- If screenshot given: examine it directly.
+- If logo file given: examine the file.
+- Note: primary hero color, CTA button color, background color, heading font, body font, any distinctive icon or illustration style.
+
+**Step 2 — Extract hex values precisely.**
+- For URLs: look for CSS variables (`--color-primary`, `--brand`, etc.), inline styles, or Tailwind config.
+- For screenshots: identify the dominant colors, CTA button, and background. Use exact observed values — never approximate.
+- For logos: extract the exact brand color(s) from the SVG or image.
+- Never hallucinate hex values. If you cannot extract precisely, state: "I could not extract exact values — I'll use the closest approximation and mark it for user verification."
+
+**Step 3 — Identify typography.**
+- Font family used for headings and body.
+- Approximate weight (light/regular/medium/bold).
+- Approximate size ratio between heading and body.
+- If not determinable from assets, note: "Font not identified — will use a matching system font."
+
+**Step 4 — Write a brand-spec summary.**
+
+After extraction, produce this brief before any visual work:
+
+```
+BRAND SPEC: [Brand Name]
+Primary color: #[hex] — [description, e.g. "deep navy, used for nav and CTA"]
+Secondary color: #[hex] — [description]
+Accent / CTA: #[hex] — [description]
+Background: #[hex]
+Text: #[hex]
+Heading font: [name or "not identified"]
+Body font: [name or "not identified"]
+Tone cues: [2-3 adjectives from brand observation, e.g. "minimal, technical, dark-surface"]
+Anti-patterns observed: [anything the brand explicitly avoids — e.g. "no drop shadows", "no rounded corners"]
+Confidence: [HIGH / MEDIUM / LOW — based on quality of source assets]
+```
+
+**Step 5 — Vocalise before designing.**
+State the brand spec out loud in one sentence before starting:
+> "I'm designing in [Brand Name]'s system: [primary color] primary, [font] type, [tone] feel. Proceeding."
+
+This confirms to the user that extraction was correct before any visual work begins.
+
+### When Brand Assets Are Absent
+
+If the user selects "No brand yet" in the question form, do not improvise. Instead:
+
+1. State: "No brand provided. I'll offer 5 visual directions — pick one or describe your preference."
+2. Load `references/visual-directions.md` and present the 5 direction summaries.
+3. Wait for the user to select or describe a preference.
+4. Bind the selected direction's tokens as the design baseline.
+5. Note in the output: "Visual direction: [name]. All tokens are provisional — update when brand is confirmed."
+
+---
+
+## Phase 3 — Junior Designer Warm-Up (for high-fidelity requests)
+
+When the user requests high-fidelity or full-spec output, add one lightweight step between the question form and the final design:
+
+1. **Show a wireframe sketch first.** Grey blocks for images, placeholder text ("Headline here", "Body copy"), real layout structure, no color, no typography polish.
+2. **Confirm direction** in one line: "This is the layout I'm planning — does this structure work before I apply brand and polish?"
+3. Wait for confirmation or redirect.
+4. Only then produce the final design.
+
+This step costs one extra turn but eliminates the risk of fully polishing a layout the user doesn't want.
+
+**Skip the warm-up when:**
+- The user explicitly says "skip wireframe" or "go straight to final."
+- The task is a minor edit or component update (not a full page/screen).
+- The user has provided a reference screenshot or detailed layout description.
+
+---
+
+## Discovery Checklist
+
+Before proceeding to any visual output, confirm:
+
+- [ ] Surface identified (web / app / mobile / email / deck / component).
+- [ ] Audience identified (consumer / professional / developer / enterprise / children).
+- [ ] Tone identified (premium / energetic / calm / playful / technical / minimal).
+- [ ] Brand status known (full assets / partial / none / inspect codebase).
+- [ ] Fidelity level agreed (concept / mid / high / design-system).
+- [ ] Constraints noted (a11y, RTL, dark mode, tech stack, performance).
+- [ ] Brand spec written (if assets provided) OR visual direction selected (if no brand).
+- [ ] Warm-up wireframe shown (for high-fidelity requests only).

package/references/design-system-schema.md

@@ -0,0 +1,407 @@
+# Design System Schema
+
+This file defines the portable 9-section design system format used by UI/UX Master. Every project should have a `.ui-ux-memory.md` at its root that follows this schema. Every design output reads from this schema — when it's populated, no design decision needs to be re-established.
+
+Use this as the template for creating or updating a project's design system record.
+
+---
+
+## How to Use
+
+When starting work on a project:
+
+1. Look for `.ui-ux-memory.md` at the project root.
+2. If it exists: read all 9 sections before designing. Follow the schema as the source of truth.
+3. If it doesn't exist: create it using this template. Fill in what is known. Mark unknown sections with `[not yet defined]`.
+4. After each design session: update the schema with any new durable decisions (new component pattern, new color token, new spacing rule).
+5. The schema is **living documentation** — it grows with the project.
+
+---
+
+## The 9-Section Schema
+
+---
+
+### Section 1 — Color
+
+```markdown
+## Color
+
+### Palette
+| Role | Token | Hex | OKLch | Usage |
+|------|-------|-----|-------|-------|
+| Background | --color-bg | #FAFAFA | oklch(99% 0.002 264) | Page background |
+| Surface | --color-surface | #F4F4F6 | oklch(97% 0.003 264) | Card, panel backgrounds |
+| Surface raised | --color-surface-2 | #EDEDF0 | oklch(94% 0.004 264) | Hover states, nested surfaces |
+| Border | --color-border | #DDDDE3 | oklch(88% 0.005 264) | Dividers, input borders |
+| Text primary | --color-text-primary | #1A1A22 | oklch(15% 0.010 264) | Body copy, headings |
+| Text secondary | --color-text-secondary | #666677 | oklch(45% 0.010 264) | Meta, captions, labels |
+| Text muted | --color-text-muted | #999AAA | oklch(65% 0.008 264) | Placeholders, disabled |
+| Accent / Brand | --color-accent | #4361EE | oklch(52% 0.18 264) | CTAs, links, active states |
+| Accent hover | --color-accent-hover | #3451DE | oklch(45% 0.18 264) | Hover on accent |
+| Success | --color-success | #1A7F5A | oklch(52% 0.16 142) | Positive states |
+| Warning | --color-warning | #D4A017 | oklch(72% 0.18 72) | Caution states |
+| Error | --color-error | #C0392B | oklch(52% 0.22 25) | Error states |
+| Info | --color-info | #0072CE | oklch(52% 0.18 230) | Informational states |
+
+### Dark Mode
+[yes / no — if yes, include dark-mode token overrides]
+
+### Color Rules
+- Primary brand color: [token] — used for CTAs, active navigation, key links only.
+- Maximum accent colors active simultaneously: [number].
+- Gradient: [allowed / not allowed — if allowed, describe usage].
+- Background: [light / dark / both].
+```
+
+---
+
+### Section 2 — Typography
+
+```markdown
+## Typography
+
+### Fonts
+| Role | Family | Fallback | Weights loaded |
+|------|--------|----------|----------------|
+| Display / heading | [name] | [fallback] | [400, 600, 700] |
+| Body | [name] | system-ui, sans-serif | [400, 500] |
+| Mono / code | [name] | monospace | [400] |
+
+### Scale
+| Token | Size | Line-height | Weight | Tracking | Use |
+|-------|------|-------------|--------|----------|-----|
+| --text-xs | 11px | 1.4 | 400 | normal | Captions, labels |
+| --text-sm | 13px | 1.5 | 400 | normal | Secondary body |
+| --text-base | 15px | 1.6 | 400 | normal | Primary body |
+| --text-lg | 17px | 1.6 | 400-500 | normal | Lead text |
+| --text-xl | 20px | 1.4 | 500-600 | -0.01em | Section headings |
+| --text-2xl | 24px | 1.3 | 600 | -0.02em | Page subheadings |
+| --text-3xl | 32px | 1.2 | 600-700 | -0.02em | H2 |
+| --text-4xl | 40-56px | 1.1 | 700 | -0.03em | H1, hero |
+
+### Typography Rules
+- Heading font pairing with body: [describe].
+- Max heading size at desktop: [size].
+- Max heading size at mobile: [size].
+- Line-length (prose): max [60-72]ch.
+- Minimum body font size: [14px].
+```
+
+---
+
+### Section 3 — Spacing
+
+```markdown
+## Spacing
+
+### System
+Base unit: [4px / 8px]
+
+| Token | Value | Use |
+|-------|-------|-----|
+| --space-1 | 4px | Micro gaps, icon padding |
+| --space-2 | 8px | Tight stacks, inline gaps |
+| --space-3 | 12px | Dense component padding |
+| --space-4 | 16px | Standard component padding |
+| --space-6 | 24px | Card padding, section inner |
+| --space-8 | 32px | Between components |
+| --space-12 | 48px | Section separation |
+| --space-16 | 64px | Major section gaps |
+| --space-24 | 96px | Hero / CTA section padding |
+
+### Spacing Rules
+- Component padding: [token].
+- Card inner padding: [token].
+- Page horizontal padding (mobile): [token].
+- Page horizontal padding (desktop): [token].
+- Grid gutter: [token].
+- Max content width: [px].
+```
+
+---
+
+### Section 4 — Layout
+
+```markdown
+## Layout
+
+### Grid
+| Breakpoint | Columns | Gutter | Margin |
+|------------|---------|--------|--------|
+| Mobile 375px | 4 | 16px | 16px |
+| Tablet 768px | 8 | 20px | 24px |
+| Desktop 1024px | 12 | 24px | 40px |
+| Wide 1440px+ | 12 | 24px | auto (centered) |
+
+### Container
+- Max content width: [px].
+- Centered: yes.
+- Full-bleed sections: [allowed / not — describe when].
+
+### Responsive Rules
+- Mobile-first: [yes / no].
+- Primary breakpoints: [list].
+- Touch targets minimum: 44×44px.
+- Any mobile-specific patterns: [describe].
+
+### Brand Method
+- Primary design method: [Product Cinema / Utility Command Center / Editorial Brand World / etc.]
+- Reference file: `references/brand-method-[name].md`
+```
+
+---
+
+### Section 5 — Components
+
+```markdown
+## Components
+
+List all established component patterns. For each component, record the key decisions so they are not re-decided.
+
+### Button
+- Primary: background [token], text [token], border-radius [token], padding [token].
+- Secondary: [outlined / ghost / filled-muted].
+- Sizes: [sm / md / lg].
+- Loading state: [spinner inside / text change].
+- Disabled: [opacity / different color].
+- Focus: [ring spec].
+
+### Input / Form
+- Border: [token], focus border: [accent token].
+- Label: above or floating?
+- Error state: [border color + message below].
+- Helper text: [below input, muted color].
+- Required marker: [asterisk / word].
+
+### Card
+- Background: [token].
+- Border: [token] or shadow: [token].
+- Border-radius: [token].
+- Padding: [token].
+- Hover state: [describe].
+
+### Navigation
+- Type: [sticky / scroll-away / sidebar / bottom-nav].
+- Background: [on-scroll behavior].
+- Mobile: [hamburger / bottom-nav / other].
+
+### [Additional components — add as they are established]
+```
+
+---
+
+### Section 6 — Motion
+
+```markdown
+## Motion
+
+### Principles
+- Motion philosophy: [purposeful / minimal / expressive / none].
+- Default easing: [ease-out / ease-in-out / spring].
+- Default duration: [150ms / 200ms / 300ms].
+
+### Token Set
+| Token | Value | Use |
+|-------|-------|-----|
+| --duration-instant | 100ms | Immediate feedback (button tap) |
+| --duration-fast | 150ms | Hover states, small transitions |
+| --duration-normal | 250ms | Panel open/close, dropdown |
+| --duration-slow | 400ms | Page transitions, large reveals |
+| --duration-slower | 600ms | Scroll-triggered animations |
+| --ease-default | cubic-bezier(0.16, 1, 0.3, 1) | Standard ease-out |
+| --ease-spring | cubic-bezier(0.34, 1.56, 0.64, 1) | Playful/springy |
+| --ease-in-out | cubic-bezier(0.4, 0, 0.2, 1) | Symmetric transitions |
+
+### Reduced Motion
+- All animations wrapped in `@media (prefers-reduced-motion: no-preference)`.
+- Reduced motion fallback: [instant transition / static].
+
+### Allowed Animations
+[List what is allowed — e.g., fade-in on scroll, hover lifts, page transitions]
+
+### Forbidden Animations
+[List what is not allowed — e.g., no autoplay videos with sound, no infinite spinning logos]
+```
+
+---
+
+### Section 7 — Voice and Copy
+
+```markdown
+## Voice and Copy
+
+### Brand Voice
+- Tone: [formal / conversational / technical / playful / authoritative].
+- Person: [first person "we" / second person "you" / impersonal].
+- Reading level: [general / professional / expert].
+
+### Copy Rules
+- Headlines: [sentence case / title case / all-caps].
+- CTA copy: [imperative verb first — "Start free trial" not "Free trial"].
+- Error messages: [describe the problem + say what to do — never just "Error"].
+- Empty states: [explain why it's empty + offer an action — never just "No results"].
+- Loading states: [describe what's loading — "Loading your projects…"].
+- Confirmation messages: [specific — "Project saved" not just "Saved"].
+
+### Forbidden Copy Patterns
+- No: "Seamlessly", "Effortlessly", "Powerful yet simple", "All-in-one".
+- No invented metrics without a source.
+- No lorem ipsum in high-fidelity output.
+- No "Click here" as link text.
+
+### Localization
+- Primary language: [language].
+- RTL support: [yes / no].
+- Key markets for i18n: [list if known].
+```
+
+---
+
+### Section 8 — Brand
+
+```markdown
+## Brand
+
+### Identity
+- Brand name: [name].
+- Tagline: [tagline or "not defined"].
+- Brand personality: [3 adjectives].
+- Brand anti-personality: [3 things the brand is NOT].
+
+### Assets
+- Logo: [path or "not yet available"].
+- Favicon: [path or "not yet available"].
+- Icon set: [Lucide / Heroicons / Phosphor / custom].
+- Illustration style: [describe or "none"].
+- Photography style: [describe or "none"].
+
+### Brand Extraction
+- Source: [URL / file / "not extracted"].
+- Extracted on: [date or "not yet"].
+- Confidence: [HIGH / MEDIUM / LOW / "not extracted"].
+- Notes: [any caveats or approximations].
+
+### Visual Direction (if no brand)
+- Active direction: [Neutral Modern / Dark Technical / Warm Editorial / Bold Energetic / Calm Trust / "not selected"].
+- Status: [provisional — update when brand is confirmed / confirmed].
+```
+
+---
+
+### Section 9 — Anti-Patterns
+
+```markdown
+## Anti-Patterns
+
+Record project-specific patterns that have been tried and rejected, in addition to the universal list in `references/output-quality-gates.md`.
+
+### Visual Anti-Patterns
+- [Pattern]: [Why it was rejected for this project].
+- [Add as patterns are identified and rejected].
+
+### Copy Anti-Patterns
+- [Pattern]: [Why].
+
+### UX Anti-Patterns
+- [Pattern]: [Why].
+
+### Technical Anti-Patterns
+- [Pattern]: [Why — e.g. "No inline styles — we use CSS tokens only"].
+
+---
+*Last updated: [date]*
+*Updated by: [agent session or designer name]*
+```
+
+---
+
+## Schema Maintenance Rules
+
+1. **Read before design.** Always read the schema before starting any new screen or component on an existing project.
+2. **Write after design.** After any session that establishes a new durable decision, update the relevant section.
+3. **Tokens must be consistent.** If a new token is added to the schema, it must be consistent with existing tokens. No ad-hoc magic numbers.
+4. **Anti-patterns are permanent.** Once a pattern is added to Section 9, it stays unless explicitly reversed by the user.
+5. **Version the schema.** Update the "Last updated" line at the bottom of Section 9 after every meaningful change.
+6. **The schema is not a spec.** It records decisions, not deliverables. Component specs and screen specs live in `templates/component-spec.md` and `templates/ui-ux-brief.md`.
+
+---
+
+## MASTER + Page Overrides Hierarchy
+
+For multi-page products, use a hierarchical design system file structure. This prevents global tokens from being re-established per page and allows page-specific deviations without polluting the master.
+
+### File Structure
+
+```
+design-system/
+├── MASTER.md          ← Global source of truth (all 9 sections)
+└── pages/
+    ├── landing.md     ← Landing page overrides only
+    ├── dashboard.md   ← Dashboard overrides only
+    ├── checkout.md    ← Checkout overrides only
+    ├── onboarding.md  ← Onboarding overrides only
+    └── [page].md      ← Any page-specific deviations
+```
+
+### MASTER.md
+
+Contains the full 9-section schema. This is the global design system. Every page inherits from it unless overridden.
+
+### pages/[page].md
+
+Contains **only the deviations** from the master. Do not repeat tokens from MASTER.md — only write what is different.
+
+**Example `pages/dashboard.md`:**
+```markdown
+# Dashboard — Design System Overrides
+
+Inherits from: design-system/MASTER.md
+
+## Color Overrides
+- --color-bg: var(--neutral-950)  ← Dark mode for dashboard only
+- --color-surface: var(--neutral-900)
+- --color-text-primary: var(--neutral-50)
+
+## Layout Overrides
+- Grid: sidebar (240px fixed) + main content (fluid)
+- No hero section
+- Compact spacing: --space-4 for most gaps (vs. --space-6 in master)
+
+## Component Overrides
+- Nav: Left sidebar (not top nav from master)
+- Cards: Dense data variant — --space-4 inner padding (vs. --space-6)
+```
+
+### Retrieval Protocol
+
+When building any page, always follow this lookup order:
+
+```
+1. Check if design-system/pages/[current-page].md exists.
+2. If YES → Read the page file. Its rules override the master for this page.
+3. Read design-system/MASTER.md for everything NOT overridden in the page file.
+4. Combined rules = the complete design system for this page.
+```
+
+**Context-aware prompt pattern:**
+```
+I am building the [Page Name] page.
+Please read design-system/MASTER.md for the global design system.
+Also check if design-system/pages/[page-name].md exists.
+If it exists, apply its rules as overrides on top of the master.
+If not, use MASTER.md exclusively.
+```
+
+### When to Create a Page Override
+
+Create a page override file when:
+- The page uses a significantly different layout (sidebar nav, full-bleed, etc.)
+- The page has a different color scheme (dark dashboard on a light-mode product)
+- The page needs denser or more spacious spacing than the master
+- The page has unique component variants not used elsewhere
+
+Do **not** create a page override for:
+- Minor copy differences
+- Individual component states
+- One-off color tweaks that should be global tokens anyway