ui-ux-master 1.2.1 → 1.5.0

package/references/color-scale-system.md

@@ -0,0 +1,347 @@
+# Color Scale System
+
+Load this file when building a design system that requires full architectural color scales. Every production-grade design system needs 11-step shade ramps (50–950), not just 5–7 semantic tokens.
+
+Use these scales as the foundation for your token system. Then map semantic roles (primary, surface, text, border, accent, semantic states) onto the appropriate shade steps.
+
+---
+
+## How to Use
+
+1. Choose a hue for your brand primary color.
+2. Use the scale template below to generate the 11 steps (50–950) in OKLch.
+3. Map semantic roles to specific steps using the role-to-step mapping table.
+4. For secondary, neutral, and semantic colors (success/warning/error/info), use the provided base scales.
+5. Export as CSS custom properties using the naming convention `--[color-name]-[step]`.
+
+---
+
+## Scale Generation Formula (OKLch)
+
+For any hue `H`, the 11-step scale uses lightness and chroma progressions:
+
+| Step | Lightness | Chroma multiplier | Usage |
+|------|-----------|-------------------|-------|
+| 50 | 97% | 0.15× base chroma | Tinted backgrounds, hover states |
+| 100 | 93% | 0.25× | Soft backgrounds, tags |
+| 200 | 85% | 0.40× | Borders, dividers |
+| 300 | 74% | 0.60× | Disabled states, placeholder |
+| 400 | 62% | 0.80× | Muted text, icons |
+| 500 | 52% | 1.00× **base** | Primary brand color |
+| 600 | 44% | 0.95× | Hover on primary |
+| 700 | 36% | 0.90× | Active/pressed states |
+| 800 | 27% | 0.80× | Dark headings on light |
+| 900 | 18% | 0.65× | Near-black brand tint |
+| 950 | 12% | 0.50× | Deepest shade, dark mode bg |
+
+**Example for Indigo (H=264, base chroma=0.20):**
+
+```css
+:root {
+  --indigo-50:  oklch(97% 0.030 264);
+  --indigo-100: oklch(93% 0.050 264);
+  --indigo-200: oklch(85% 0.080 264);
+  --indigo-300: oklch(74% 0.120 264);
+  --indigo-400: oklch(62% 0.160 264);
+  --indigo-500: oklch(52% 0.200 264);  /* brand primary */
+  --indigo-600: oklch(44% 0.190 264);
+  --indigo-700: oklch(36% 0.180 264);
+  --indigo-800: oklch(27% 0.160 264);
+  --indigo-900: oklch(18% 0.130 264);
+  --indigo-950: oklch(12% 0.100 264);
+}
+```
+
+---
+
+## Semantic Role → Step Mapping
+
+Once you have your scales, map semantic tokens to steps:
+
+| Semantic Token | Light Mode Step | Dark Mode Step | Notes |
+|---|---|---|---|
+| `--color-bg` | Neutral 50 | Neutral 950 | Page background |
+| `--color-surface` | Neutral 100 | Neutral 900 | Card/panel background |
+| `--color-surface-2` | Neutral 200 | Neutral 800 | Nested surface |
+| `--color-border` | Neutral 300 | Neutral 700 | Dividers, input border |
+| `--color-border-strong` | Neutral 400 | Neutral 600 | Emphasis borders |
+| `--color-text-muted` | Neutral 400 | Neutral 500 | Placeholder, disabled |
+| `--color-text-secondary` | Neutral 600 | Neutral 400 | Meta, captions |
+| `--color-text-primary` | Neutral 900 | Neutral 50 | Body copy |
+| `--color-accent` | Primary 500 | Primary 400 | CTAs, links, active |
+| `--color-accent-hover` | Primary 600 | Primary 300 | Hover on accent |
+| `--color-accent-active` | Primary 700 | Primary 200 | Pressed state |
+| `--color-accent-soft` | Primary 100 | Primary 900 | Tinted backgrounds |
+| `--color-accent-text` | Primary 700 | Primary 200 | Text on tinted bg |
+
+---
+
+## Base Neutral Scale (Gray)
+
+Use as the backbone for backgrounds, text, and borders.
+
+```css
+:root {
+  /* Neutral — cool gray, H=264, chroma=0.005 */
+  --neutral-50:  oklch(99% 0.002 264);   /* #FAFAFA */
+  --neutral-100: oklch(96% 0.003 264);   /* #F4F4F6 */
+  --neutral-200: oklch(92% 0.004 264);   /* #EBEBEE */
+  --neutral-300: oklch(85% 0.006 264);   /* #D8D8DE */
+  --neutral-400: oklch(72% 0.008 264);   /* #ABABB8 */
+  --neutral-500: oklch(58% 0.009 264);   /* #818190 */
+  --neutral-600: oklch(46% 0.009 264);   /* #5E5E6E */
+  --neutral-700: oklch(34% 0.008 264);   /* #434352 */
+  --neutral-800: oklch(24% 0.007 264);   /* #2C2C38 */
+  --neutral-900: oklch(15% 0.006 264);   /* #1A1A24 */
+  --neutral-950: oklch(9%  0.005 264);   /* #0E0E14 */
+}
+```
+
+**Warm neutral variant** (use for editorial/warm brand):
+```css
+:root {
+  /* Warm Neutral — H=72, chroma=0.010 */
+  --warm-50:  oklch(98% 0.008 72);
+  --warm-100: oklch(95% 0.012 72);
+  --warm-200: oklch(90% 0.016 72);
+  --warm-300: oklch(82% 0.018 72);
+  --warm-400: oklch(70% 0.016 72);
+  --warm-500: oklch(56% 0.014 72);
+  --warm-600: oklch(44% 0.012 72);
+  --warm-700: oklch(33% 0.010 72);
+  --warm-800: oklch(24% 0.008 72);
+  --warm-900: oklch(16% 0.007 72);
+  --warm-950: oklch(10% 0.005 72);
+}
+```
+
+---
+
+## Brand Color Scales by Hue Family
+
+### Blue / Indigo (Trust, Technology, Finance)
+```css
+:root {
+  --blue-50:  oklch(97% 0.020 230);
+  --blue-100: oklch(93% 0.040 230);
+  --blue-200: oklch(85% 0.070 230);
+  --blue-300: oklch(74% 0.110 230);
+  --blue-400: oklch(62% 0.150 230);
+  --blue-500: oklch(52% 0.180 230);   /* #0072CE calm blue */
+  --blue-600: oklch(44% 0.170 230);
+  --blue-700: oklch(36% 0.160 230);
+  --blue-800: oklch(27% 0.140 230);
+  --blue-900: oklch(18% 0.110 230);
+  --blue-950: oklch(11% 0.080 230);
+
+  --indigo-50:  oklch(97% 0.025 264);
+  --indigo-100: oklch(93% 0.050 264);
+  --indigo-200: oklch(85% 0.080 264);
+  --indigo-300: oklch(74% 0.120 264);
+  --indigo-400: oklch(62% 0.160 264);
+  --indigo-500: oklch(52% 0.200 264);   /* #4361EE */
+  --indigo-600: oklch(44% 0.190 264);
+  --indigo-700: oklch(36% 0.180 264);
+  --indigo-800: oklch(27% 0.160 264);
+  --indigo-900: oklch(18% 0.130 264);
+  --indigo-950: oklch(11% 0.095 264);
+}
+```
+
+### Green (Health, Finance-positive, Nature, Success)
+```css
+:root {
+  --green-50:  oklch(97% 0.025 142);
+  --green-100: oklch(93% 0.050 142);
+  --green-200: oklch(85% 0.085 142);
+  --green-300: oklch(74% 0.120 142);
+  --green-400: oklch(62% 0.150 142);
+  --green-500: oklch(52% 0.160 142);   /* #1A7F5A */
+  --green-600: oklch(44% 0.150 142);
+  --green-700: oklch(36% 0.140 142);
+  --green-800: oklch(27% 0.120 142);
+  --green-900: oklch(18% 0.095 142);
+  --green-950: oklch(11% 0.070 142);
+}
+```
+
+### Red (Energy, Alert, Food, Bold brands)
+```css
+:root {
+  --red-50:  oklch(97% 0.025 25);
+  --red-100: oklch(93% 0.050 25);
+  --red-200: oklch(85% 0.090 25);
+  --red-300: oklch(74% 0.130 25);
+  --red-400: oklch(62% 0.180 25);
+  --red-500: oklch(52% 0.220 25);   /* #C0392B */
+  --red-600: oklch(44% 0.210 25);
+  --red-700: oklch(36% 0.195 25);
+  --red-800: oklch(27% 0.170 25);
+  --red-900: oklch(18% 0.135 25);
+  --red-950: oklch(11% 0.100 25);
+}
+```
+
+### Amber / Gold (Warning, Luxury, Premium, Energy)
+```css
+:root {
+  --amber-50:  oklch(98% 0.030 72);
+  --amber-100: oklch(94% 0.060 72);
+  --amber-200: oklch(88% 0.100 72);
+  --amber-300: oklch(80% 0.140 72);
+  --amber-400: oklch(74% 0.170 72);
+  --amber-500: oklch(72% 0.180 72);   /* #D4A017 */
+  --amber-600: oklch(62% 0.170 72);
+  --amber-700: oklch(50% 0.160 72);
+  --amber-800: oklch(38% 0.140 72);
+  --amber-900: oklch(26% 0.110 72);
+  --amber-950: oklch(16% 0.080 72);
+}
+```
+
+### Purple / Violet (Creative, Premium SaaS, Innovation)
+```css
+:root {
+  --purple-50:  oklch(97% 0.025 300);
+  --purple-100: oklch(93% 0.050 300);
+  --purple-200: oklch(85% 0.085 300);
+  --purple-300: oklch(74% 0.120 300);
+  --purple-400: oklch(62% 0.170 300);
+  --purple-500: oklch(52% 0.220 300);
+  --purple-600: oklch(44% 0.210 300);
+  --purple-700: oklch(36% 0.195 300);
+  --purple-800: oklch(27% 0.170 300);
+  --purple-900: oklch(18% 0.130 300);
+  --purple-950: oklch(11% 0.095 300);
+}
+```
+
+### Teal / Cyan (Healthcare, Tech, Trust-plus-energy)
+```css
+:root {
+  --teal-50:  oklch(97% 0.025 180);
+  --teal-100: oklch(93% 0.050 180);
+  --teal-200: oklch(85% 0.085 180);
+  --teal-300: oklch(74% 0.125 180);
+  --teal-400: oklch(64% 0.165 180);
+  --teal-500: oklch(55% 0.185 180);
+  --teal-600: oklch(46% 0.175 180);
+  --teal-700: oklch(37% 0.160 180);
+  --teal-800: oklch(28% 0.140 180);
+  --teal-900: oklch(19% 0.110 180);
+  --teal-950: oklch(12% 0.080 180);
+}
+```
+
+---
+
+## Semantic State Scales (Fixed — used for success/warning/error/info)
+
+These are standardized across all projects:
+
+```css
+:root {
+  /* Success — green family */
+  --success-50:  oklch(97% 0.025 142);
+  --success-100: oklch(92% 0.050 142);
+  --success-500: oklch(52% 0.160 142);
+  --success-700: oklch(36% 0.140 142);
+  --success-900: oklch(18% 0.095 142);
+
+  /* Warning — amber family */
+  --warning-50:  oklch(98% 0.030 72);
+  --warning-100: oklch(94% 0.060 72);
+  --warning-500: oklch(72% 0.180 72);
+  --warning-700: oklch(50% 0.160 72);
+  --warning-900: oklch(26% 0.110 72);
+
+  /* Error — red family */
+  --error-50:  oklch(97% 0.025 25);
+  --error-100: oklch(93% 0.050 25);
+  --error-500: oklch(52% 0.220 25);
+  --error-700: oklch(36% 0.195 25);
+  --error-900: oklch(18% 0.135 25);
+
+  /* Info — blue family */
+  --info-50:  oklch(97% 0.020 230);
+  --info-100: oklch(93% 0.040 230);
+  --info-500: oklch(52% 0.180 230);
+  --info-700: oklch(36% 0.160 230);
+  --info-900: oklch(18% 0.110 230);
+}
+```
+
+---
+
+## Dark Mode Scale Mapping
+
+In dark mode, the scale direction inverts for surfaces and text but stays consistent for interactive elements:
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root {
+    /* Surfaces — use high-step (dark) values */
+    --color-bg:       var(--neutral-950);
+    --color-surface:  var(--neutral-900);
+    --color-surface-2: var(--neutral-800);
+    --color-border:   var(--neutral-700);
+    --color-border-strong: var(--neutral-600);
+
+    /* Text — use low-step (light) values */
+    --color-text-primary:   var(--neutral-50);
+    --color-text-secondary: var(--neutral-400);
+    --color-text-muted:     var(--neutral-500);
+
+    /* Accent — shift one step lighter for dark bg legibility */
+    --color-accent:       var(--[brand]-400);
+    --color-accent-hover: var(--[brand]-300);
+    --color-accent-soft:  var(--[brand]-900);
+
+    /* Semantic states — lighter variants for dark bg */
+    --color-success: var(--success-400);
+    --color-warning: var(--warning-400);
+    --color-error:   var(--error-400);
+    --color-info:    var(--info-400);
+  }
+}
+```
+
+---
+
+## Typography Scale (px + rem)
+
+Always output both px and rem values. Base: 16px = 1rem.
+
+| Token | px | rem | Line-height | Weight | Use |
+|---|---|---|---|---|---|
+| `--text-xs` | 11px | 0.6875rem | 1.4 | 400 | Labels, captions |
+| `--text-sm` | 13px | 0.8125rem | 1.5 | 400 | Secondary body |
+| `--text-base` | 15px | 0.9375rem | 1.6 | 400 | Primary body |
+| `--text-md` | 16px | 1rem | 1.6 | 400 | Alternate body |
+| `--text-lg` | 18px | 1.125rem | 1.5 | 500 | Lead / intro |
+| `--text-xl` | 20px | 1.25rem | 1.4 | 500–600 | Section label |
+| `--text-2xl` | 24px | 1.5rem | 1.3 | 600 | Card headline |
+| `--text-3xl` | 30px | 1.875rem | 1.25 | 600–700 | H3 |
+| `--text-4xl` | 36px | 2.25rem | 1.2 | 700 | H2 |
+| `--text-5xl` | 48px | 3rem | 1.15 | 700 | H1 |
+| `--text-6xl` | 60px | 3.75rem | 1.1 | 700–800 | Display |
+| `--text-7xl` | 72px | 4.5rem | 1.05 | 800 | Hero headline |
+
+---
+
+## Pre-Delivery Color Checklist
+
+Before any design system output, verify:
+
+```
+COLOR SCALE CHECKLIST
+[ ] All 11 steps (50–950) defined for primary brand color
+[ ] Neutral scale complete (50–950)
+[ ] Semantic roles mapped to specific scale steps
+[ ] Dark mode overrides specified
+[ ] Text on --color-bg: contrast ≥ 4.5:1 (body), ≥ 3:1 (large/UI)
+[ ] Text on --color-accent: contrast ≥ 4.5:1
+[ ] Text on --color-success/warning/error backgrounds: contrast verified
+[ ] Both px and rem values in typography scale
+[ ] Google Fonts import URL included if using web fonts
+```

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).