@tidyfactor/design 1.5.0

package/memory/17-storytelling-industries-ux.md

@@ -0,0 +1,143 @@
+# 17 · Storytelling Archetypes, Industry Registers & UX Philosophies
+
+Operational guide for `tidyfactor-design` establishing visual rules, layout structures, typography pairings, color systems, and execution constraints across **4 Storytelling Archetypes**, **8 Industry Registers**, and **8 UX Design Philosophies**.
+
+---
+
+## 🎬 4 Storytelling Archetypes
+
+### 1. Cinematic Storytelling
+* **Core Philosophy**: The user experiences a luxury TV ad in continuous motion. Scroll drives product transformation, stage reveals, and lighting shifts.
+* **Layout Structure**: Full-bleed hero stage with 3D product float & pointer tilt → Canvas frame-sequence scroll film (600vh stage) → Spec reveal → Lifestyle moments → Pinned video CTA with smoothstep wash overlay.
+* **Typography**: Clean display serif (`El Messiri`, `Cormorant Garamond`) for headlines paired with high-contrast body sans (`Tajawal`, `Inter`). Small off-center captions over video/film.
+* **Visual Tokens**: Deep dark ground (`#0F172A`), gold radial background aura, drifting particle motes, fixed z-stack layers (`#ambient`, `#glow`, `#vignette`, `#grain`, `#progress`).
+* **Best For**: Physical luxury goods, flagship product launches, brand positioning, automotive, high-ticket offers.
+
+---
+
+### 2. Editorial Storytelling
+* **Core Philosophy**: Literary journalism and broadsheet publishing. Focuses on narrative depth, authoritativeness, and structured typography hierarchy.
+* **Layout Structure**: Magazine header masthead → Split-screen hero (image + narrative copy) → Multi-column article grid → Hairline rule dividers → Pull quote blocks → Author colophon footer.
+* **Typography**: Expressive editorial serifs (`Markazi Text`, `Fraunces`, `El Messiri`) for display paired with legible sans or serif body (`IBM Plex Sans Arabic`, `Tajawal`).
+* **Visual Tokens**: Warm cream/ivory grounds (`#FBF8F2`), ink black text (`#14171C`), fine hairline dividers (`1px solid #E2E5E9`), generous line-height (`1.75`).
+* **Best For**: Media publications, founder origin stories, investigative reports, thought leadership, luxury brand manifests.
+
+---
+
+### 3. Documentary Storytelling
+* **Core Philosophy**: Raw, unpolished, evidence-first presentation. Uses timestamped logs, concrete data points, real photography, and objective split-screen progression.
+* **Layout Structure**: Metadata header bar (date, coordinates, telemetry) → Timeline sequence blocks → High-contrast photo evidence cards → Concrete metric grids → Fact verification footer.
+* **Typography**: Monospaced technical typography (`JetBrains Mono`, `Oswald`) paired with neutral body sans (`Inter`, `Tajawal`).
+* **Visual Tokens**: Titanium grays (`#0F172A`, `#1E293B`), signal amber accent (`#F59E0B`), telemetry badge dots (`● VERIFIED`), hairline grid borders (`1px solid #334155`).
+* **Best For**: Sustainability reports, engineering case studies, NGO causes, supply-chain transparency, technical post-mortems.
+
+---
+
+### 4. Interactive Storytelling
+* **Core Philosophy**: Choice-driven exploration where user interaction (clicks, toggles, hover paths) directly reveals content and alters page state.
+* **Layout Structure**: Interactive hero preview → Tabbed exploration stage → Live calculator / filter widget → Before-and-after comparison slider → Interactive FAQ accordion → Action trigger CTA.
+* **Typography**: Friendly modern sans-serifs (`Outfit`, `Tajawal`).
+* **Visual Tokens**: Interactive hover lift (`transform: translateY(-2px)`), active press feedback (`scale-[0.98]`), focus ring glow (`color-mix()`), smooth tab transitions.
+* **Best For**: SaaS product walk-throughs, pricing calculators, interactive product configurators, digital learning modules.
+
+---
+
+## 💼 8 Industry Registers
+
+### 1. Corporate
+* **Visual Register**: Trust, stability, security, institutional authority.
+* **Color Palette**: Trust Navy (`#0F172A`), Deep Sapphire (`#1E40AF`), Neutral Gray (`#F8FAFC`), Slate (`#475569`).
+* **Typography**: Professional sans-serifs (`Outfit`, `Inter`, `Tajawal`).
+* **Layout Rules**: 12-column grid, clean executive stat callouts, structured table matrices, WCAG AA compliance.
+* **Avoid**: Neo-brutalist offset shadows, neon colors, playful illustrations.
+
+---
+
+### 2. SaaS (Software-as-a-Service)
+* **Visual Register**: High efficiency, modern tech, data clarity, conversion-driven.
+* **Color Palette**: Dark Slate (`#0F172A`) or Clean Light (`#FFFFFF`), Electric Indigo (`#4F46E5`), Cyan (`#06B6D4`).
+* **Typography**: Modern geometric sans (`Outfit`, `Tajawal`, `Inter`).
+* **Layout Rules**: Bento box feature grids, interactive app preview mockups, pricing tier comparison cards, integration logo grids.
+* **Avoid**: Heavy skeuomorphic textures, illegible display fonts.
+
+---
+
+### 3. FinTech
+* **Visual Register**: Precision, high security, transparency, wealth growth.
+* **Color Palette**: Deep Emerald (`#065F46`), Mint (`#10B981`), Dark Indigo (`#1E1B4B`), Slate (`#F8FAFC`).
+* **Typography**: Tabular numeric typography (`tabular-nums`), clean sans (`Outfit`, `Tajawal`).
+* **Layout Rules**: Tabular data displays, security badge trust bars, live balance widgets, crisp financial chart surfaces.
+* **Avoid**: Low-contrast text, informal casual microcopy, playful pastel colors.
+
+---
+
+### 4. AI & Emerging Tech
+* **Visual Register**: Innovation, intelligence, futuristic capabilities, fluid power.
+* **Color Palette**: Pitch Black (`#090A0F`), Luminescent Cyan (`#06B6D4`), Neon Purple (`#7C3AED`), Mesh Gradients.
+* **Typography**: Ultra-clean sans (`Outfit`, `Inter`) paired with monospaced prompt accents (`JetBrains Mono`).
+* **Layout Rules**: Aurora mesh gradient backgrounds, interactive prompt bars, glowing input borders, clean dark theme.
+* **Avoid**: Traditional corporate clip-art, heavy paper textures.
+
+---
+
+### 5. Healthcare & Wellness
+* **Visual Register**: Calm, empathy, hygiene, human warmth, accessible clarity.
+* **Color Palette**: Soft Teal (`#0D9488`), Sage Green (`#047857`), Warm Ivory (`#FDFBF7`), Soft Blue (`#0284C7`).
+* **Typography**: Highly legible rounded sans-serifs (`Tajawal`, `Outfit`, `Almarai`).
+* **Layout Rules**: Generous padding, large accessible touch targets (≥44px), calm color transitions, clear patient steps.
+* **Avoid**: Harsh neon contrast, aggressive countdown timers, jarring animation bounces.
+
+---
+
+### 6. Education & EdTech
+* **Visual Register**: Playful engagement, encouragement, progressive growth, clarity.
+* **Color Palette**: Vibrant Primary Triad (Soft Violet `#7C3AED`, Amber `#F59E0B`, Emerald `#10B981`, Sky `#0284C7`).
+* **Typography**: Friendly approachble fonts (`Outfit`, `Tajawal`).
+* **Layout Rules**: Gamified progress meters, rounded cards (`rounded-2xl`), badge rewards, interactive step cards.
+* **Avoid**: Overly dense corporate tables, dark dystopian cyber-themes.
+
+---
+
+### 7. Luxury & Haute Couture
+* **Visual Register**: Exclusivity, craftsmanship, prestige, timeless elegance.
+* **Color Palette**: Espresso Black (`#0B0D10`), Warm Cream (`#FBF8F2`), Muted Gold (`#A97B33`), Ink (`#241812`).
+* **Typography**: Display serifs (`El Messiri`, `Cormorant Garamond`) with delicate light-weight Latin accents.
+* **Layout Rules**: Massive negative space, centered product cutouts, minimal navigation, dark/light theme commitment.
+* **Avoid**: Cheap gradient badges, busy multi-column grids, aggressive sales banners.
+
+---
+
+### 8. E-Commerce & Retail
+* **Visual Register**: Immediate desire, friction-free purchase flow, trust proof.
+* **Color Palette**: High-contrast Primary CTA (`#4F46E5` or `#000000`), Neutral Surface (`#FFFFFF`), Soft Tint (`#F8FAFC`).
+* **Typography**: Clear sans-serifs (`Outfit`, `Tajawal`).
+* **Layout Rules**: Hero product image, price tag display, sticky buy bar on scroll, customer star review badges, variant selectors.
+* **Avoid**: Hiding pricing or buy buttons below multiple screens of filler text.
+
+---
+
+## 🧠 8 UX Design Philosophies
+
+### 1. Minimalism & Flat Design
+Strips away all non-essential visual fluff. Focuses on negative space, crisp typography, and clear focal hierarchy.
+
+### 2. Emotional Design
+Incorporate purposeful micro-interactions and microcopy across 4 whimsy tiers (subtle feedback, task celebrations, discovery Easter eggs, contextual microcopy) to make interfaces delightful.
+
+### 3. Human-Centered Experience (HCD)
+Design for human cognitive limits: progressive disclosure of complex features, clear visual hierarchy, max 3 words on primary CTAs, predictable interaction models.
+
+### 4. Accessibility-First (WCAG 2.1 AA)
+Minimum 4.5:1 contrast for body text, 3:1 for large display text/UI controls. Touch targets minimum 44px on touch viewports. Never suppress focus outlines without a `color-mix()` replacement ring.
+
+### 5. Mobile-First & Responsive Physics
+Design layout containers to collapse fluidly from desktop (`2xl` 1536px) to mobile (`sm` 640px). Place primary actions within natural thumb-reach zones.
+
+### 6. Arabic RTL First (Bidi-Native)
+Design natively for Right-to-Left languages (`dir="rtl"`). Use CSS logical properties (`margin-inline-start`, `padding-inline`, `border-inline-end`). Pair **El Messiri** (headings) + **Tajawal** (body); never Amiri above 24px.
+
+### 7. Dark Mode Native
+Treat dark mode as a first-class citizen using `brand.json` v2 dual-mode tokens (`colors.light` & `colors.dark`). Use tinted dark neutrals (`#0F172A`, `#1E293B`) instead of flat pure black `#000000`.
+
+### 8. Mixed Media Maximalism
+Embrace high visual density, kinetic typography, multi-layered collage imagery, and bold color contrast for youth-focused, creative, or entertainment brands.

package/memory/18-design-decision-engine.md

@@ -0,0 +1,81 @@
+# 18 · Design Decision Engine Rules & Protocols
+
+System operational rules for `tidyfactor-design` that transform visual references into deterministic, repeatable, and non-contradictory design decisions.
+
+---
+
+## 🌳 1. The 9-Step Design Decision Tree Protocol
+
+Before selecting visual schools, tokens, or components, every AI agent execution MUST evaluate choices sequentially through this 9-step decision tree:
+
+```
+Step 1: Project Scope       → Determine surface type (marketing, dashboard, e-commerce, docs, spatial)
+Step 2: Industry Register   → Map domain (Corporate, SaaS, FinTech, AI, Healthcare, Education, Luxury, E-Commerce)
+Step 3: Audience Mode       → Classify user state (Inspire, Evaluate, Act, Learn)
+Step 4: Brand Personality   → Lock 3-5 tone adjectives (e.g. Precise, Confident, Technical, Calm)
+Step 5: Storytelling        → Choose archetype (Cinematic, Editorial, Documentary, Interactive)
+Step 6: UX Philosophy       → Lock core principles (Accessibility-first, Mobile-first, RTL-first, Dark Native)
+Step 7: Visual School       → Select Primary School & max 1 Secondary Influence from confidence/compatibility matrix
+Step 8: Token Generation    → Derive tokens.css & brand.json v2 based on Visual DNA & Color Palettes
+Step 9: Component Behavior  → Apply exact component shape, form, and motion language specifications
+```
+
+---
+
+## 🍲 2. Anti-"Design Soup" Constraint Rule (Mandatory)
+
+> [!CAUTION]
+> **AI Anti-Pattern Failure**: AI generators frequently create "Design Soup" by mixing 4-5 clashing design movements on a single page (e.g., Glassmorphism frosted panels + Neo-Brutalist 4px hard black offset shadows + Neumorphic extruded buttons + Cyberpunk glitch effects).
+
+### Strict Mixing Limits
+Unless explicitly requested by the user, an AI Agent MUST NEVER exceed:
+- **1 Primary Visual School** (e.g., Swiss)
+- **1 Secondary Influence** (e.g., Minimalism — MUST be listed as `Compatible` in the school's matrix)
+- **1 Motion Language** (e.g., Subtle / 150ms / ease-out)
+- **1 Storytelling Style** (e.g., Editorial)
+- **1 UX Philosophy Accent** (e.g., RTL-first + Dark Native)
+
+Any output violating this cap fails audit and triggers an automatic revision pass.
+
+---
+
+## ⚡ 3. Executable Signature Element Rule
+
+Every visual school defines a **Concrete Executable Signature Element**. The AI Agent MUST render this signature element at least 1-2 times on every project page to ensure the interface has distinct visual identity:
+
+| Visual School | Executable Signature Element | Mechanical Implementation |
+|---|---|---|
+| **Swiss** | Asymmetric Grid Lines & Huge Type | Hairline 1px grid borders (`#E2E8F0`), display type `clamp(3rem,8vw,6rem)`, zero shadow |
+| **Flat** | Saturated 2D Color Blocks | Solid 2D fills, `border-radius: 8px`, 0px shadow, high-contrast flat icon badges |
+| **Material** | Floating Elevation Sheet & FAB | Floating action button, `box-shadow: 0 4px 12px rgba(0,0,0,0.15)`, touch ripple feedback |
+| **Minimalism** | Massive Negative Space & Single Focal Point | Section padding `96px`+, max 1 accent color, zero clutter |
+| **Neo-Brutalism** | Hard Offset Box Shadow & Black Border | `box-shadow: 4px 4px 0px #000000`, `border: 2px solid #000000`, sharp/rounded corners |
+| **Bauhaus** | Primary Color Block Geometry | Red/Blue/Yellow color blocking, circular accent containers mixed with sharp grids |
+| **Skeuomorphism** | Dual Inner/Outer Bevel & Tactile Surface | `box-shadow: inset 0 2px 4px rgba(255,255,255,0.6), 0 4px 12px rgba(0,0,0,0.2)` |
+| **Glassmorphism** | Frosted Glass Pill / Card | `backdrop-filter: blur(12px) saturate(180%)`, `background: rgba(255,255,255,0.12)`, `border: 1px solid rgba(255,255,255,0.2)` |
+| **Maximalism** | Layered Collage & Kinetic Marquee | Overlapping sticker badges, infinite text marquee ticker, dense typography contrast |
+| **Industrial** | Monospaced Blueprint Telemetry | Monospace font, crosshair markers, `● LIVE` status indicator dots, titanium grounds |
+| **Bento Box** | Modular Masonry Tiles | `border-radius: 20px`–`24px` compartmentalized cards, 1px subtle border |
+| **Aurora UI** | Luminescent Mesh Gradient Spotlight | Radial glowing mesh gradient (`blur(60px)`) behind hero cutout or primary card |
+| **Neumorphism** | Dual Soft Extrusion Shadow | Light/Dark dual shadow (`box-shadow: 6px 6px 12px #b8b9be, -6px -6px 12px #ffffff`) |
+| **Corporate Memphis** | Soft Pastel Pill Containers | `border-radius: 9999px` soft pill buttons, warm pastel background panels |
+| **Cyberpunk** | Neon Glow Border & Monospace HUD | `box-shadow: 0 0 12px rgba(0,240,255,0.5)`, monospaced telemetry headers, pitch black ground |
+| **Claymorphism** | Soft Clay 3D Extrusion | `border-radius: 24px`+, deep inner light reflection + warm outer shadow |
+| **Isometric** | 30° Parallel Perspective SVG | SVG 30° parallel projection vector diagram or feature illustration |
+| **Kinetic Type** | Interactive Scaling Display Headline | `font-size: clamp(4rem, 12vw, 9rem)` headline, hover stretch effect |
+| **Organic UI** | Asymmetrical Morphing Blob | Fluid asymmetrical blob border (`border-radius: 60% 40% 30% 70% / 60% 30% 70% 40%`) |
+| **Frutiger Aero** | Glossy Glass Overlay & Aero Pill | Linear glossy highlight (`background: linear-gradient(180deg, rgba(255,255,255,0.5) 0%, transparent 50%)`) |
+
+---
+
+## 📊 4. School Evaluation Dimensions Schema
+
+Every movement entry in `memory/16-design-movements-guide.md` is structured using 7 standardized evaluation dimensions:
+
+1. **Confidence Matrix**: Rated `★` to `★★★★★` across 6 surface targets (`production`, `marketing`, `dashboard`, `landing`, `mobile`, `accessibility`).
+2. **Compatibility Matrix**: Explicit lists of `Compatible` secondary schools and `Avoid / Not Recommended` clashing schools.
+3. **Brand Personality**: 4-6 tone keywords governing copy tone, media choices, and hover states.
+4. **Visual DNA Vector**: Rated `★` to `★★★★★` across 8 design dimensions (`Grid`, `Typography`, `Geometry`, `Illustration`, `Motion`, `Texture`, `Photography`, `Depth`).
+5. **Component Behaviour**: Concrete styling for `Buttons`, `Cards`, `Forms`, `Navigation`, and `Search`.
+6. **Motion Language**: Specified `Duration`, `Curve`, `Energy`, `Scroll`, and `Hover` behavior.
+7. **Executable Signature Element**: Exact CSS/HTML code snippet for the school's signature tell.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tidyfactor/design",
+  "version": "1.5.0",
+  "description": "TidyFactor Design track — code-native UI design lifecycle engine (Figma alternative) with Contextual Decision Layer (CDL)",
+  "main": "SKILL.md",
+  "bin": {
+    "tidyfactor-design": "bin/add-skill.js",
+    "add-skill": "bin/add-skill.js",
+    "add-design-skill": "bin/add-skill.js"
+  },
+  "keywords": [
+    "tidyfactor",
+    "design-system",
+    "ui-design",
+    "figma-alternative",
+    "code-native",
+    "prototyping",
+    "arabic-ui",
+    "rtl",
+    "ai-agents",
+    "antigravity",
+    "claude-code",
+    "cursor"
+  ],
+  "author": "TidyFactor <hello@tidyfactor.com> (https://tidyfactor.com)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TidyFactor/Design.git"
+  },
+  "scripts": {
+    "validate": "python tools/validate_skill.py",
+    "build": "node tools/build-skill.js",
+    "release": "python ../tools/release_skill.py ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    ".tidyfactor",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.ar.md",
+    "README.de.md",
+    "README.es.md",
+    "README.fa.md",
+    "README.fr.md",
+    "README.md",
+    "README.pt.md",
+    "README.zh.md",
+    "SKILL-REGISTRY.md",
+    "SKILL.md",
+    "VISION.md",
+    "assets",
+    "bin",
+    "brand.json",
+    "memory",
+    "references",
+    "scripts",
+    "templates",
+    "tools"
+  ]
+}

package/references/commands/_template.md

@@ -0,0 +1,27 @@
+# Command: `<name>` — <Short Title>
+
+## Purpose
+One or two sentences: what this command extracts/organizes, and why it's
+its own command rather than folded into another one.
+
+## When to run it
+- Signal from the audit that suggests this command applies.
+- User phrasing that should trigger it (besides the bare command word).
+
+## What it does
+Numbered steps — concrete actions, not vague principles.
+
+## Output convention
+```
+Example file tree fragment showing where output lands.
+```
+
+## Checklist
+- [ ] Concrete, checkable outcomes for this command specifically.
+
+---
+To register a new command:
+1. Copy this file to `references/commands/<name>.md` and fill it in.
+2. Add a row to the Command Index table in `SKILL.md`.
+3. If it interacts with an existing command (consumes/produces the same
+   files), cross-reference it in both files' "What it does" sections.

package/references/commands/assets.md

@@ -0,0 +1,35 @@
+# Command: `assets` — Asset Processing & Media Optimization Engine
+
+Runtime entry point for generating AI media, removing image backgrounds, and optimizing image payloads.
+
+## 5-Layer AI Photography Prompt Construction Matrix
+
+When generating visual assets with `generate_image` or external AI image engines, construct prompts across 5 technical photography layers:
+
+1. **Subject Layer**: Primary subject, micro-textures, pose, surface materials (e.g. brushed aluminum, matte leather).
+2. **Environment Layer**: Setting, time of day, atmospheric conditions (fog, volumetric haze, studio backdrop).
+3. **Lighting Layer**: Source (softbox, natural light), direction (Rembrandt, split, backlit), color temperature.
+4. **Technical Photography Layer**: Perspective, focal length (85mm f/1.4), depth of field / bokeh (`f/1.8` shallow focus).
+5. **Post-Processing & Film Stock Layer**: Color grading, subtle film grain, Kodak Portra 400 aesthetic.
+
+## Python Asset Tooling
+
+1. **Background Removal**: `python scripts/remove_backgrounds.py <input_path>` (rembg + Pillow transparent PNG cutouts).
+2. **Batch Optimization**: `python scripts/optimize_images.py <assets_dir>` (compress WebP variants).
+3. **Asset Inspection**: `python scripts/inspect_images.py <assets_dir>` (dimension & size budget check).
+
+## Output Convention
+
+```
+my-prototype/
+└── assets/
+    ├── hero-cutout.png      ← BG-removed cutout
+    ├── banner.webp          ← WebP compressed asset
+    └── photo-01.webp        ← 5-Layer AI prompt generated asset
+```
+
+## Checklist
+
+- [ ] AI image prompts structured across all 5 technical photography layers
+- [ ] Product cutouts have clean transparent backgrounds (`rembg`)
+- [ ] Prototype assets optimized to WebP format (< 500KB payload per image)

package/references/commands/audit.md

@@ -0,0 +1,15 @@
+# Command: `audit` — Structural Consistency & Health Report
+
+Runtime entry point for auditing prototype compliance and structural integrity (read-only by default).
+
+## Dispatch steps
+
+1. Load `references/memory/architecture.md` — locked file tree layout and consistency rules.
+2. Load `memory/06-quality-bar.md` — quality bar criteria.
+3. Load `references/workflows/audit-prototype.md` — check sequence and report format.
+4. Execute audit steps per `audit-prototype.md` and produce a read-only health report.
+
+## Checklist
+
+- [ ] Audit is read-only unless explicit fix requested
+- [ ] `references/workflows/audit-prototype.md` validation checklist fully satisfied

package/references/commands/brand.md

@@ -0,0 +1,85 @@
+# Command: `brand` — Brand Identity Scaffolding & Extraction
+
+Runtime entry point for creating, extracting, or evolving `brand.json` v2. Part of the **Foundation** lifecycle phase.
+
+## When to use
+
+- **New project** → scaffold `brand.json` from scratch with user interview
+- **Existing identity** → extract `brand.json` from a live site, PDF guidelines, or logo + reference photos (the `clone-brand` path)
+- **Schema upgrade** → migrate `brand.json` v1 to v2
+
+## Dispatch Steps
+
+1. Load `memory/11-brand-json-v2.md` — full schema reference.
+2. Load `memory/02-design-tokens.md` — token derivation rules.
+3. Determine path: **scaffold** (no existing identity) or **extract** (existing site/PDF/assets).
+4. Execute the appropriate protocol below.
+
+## Path A: Scaffold (new identity)
+
+### Interview (ask these in order)
+1. **Product name + tagline** → `meta.product`, `meta.tagline`
+2. **Logo files** → `identity.logo.*` (SVG preferred; if unavailable, flag as missing — do NOT fabricate)
+3. **Primary color + accent** → seed `colors.light.primary`, `colors.light.accent`
+4. **Light or dark default?** → determines which mode's `background`/`surface`/`text` values are set first
+5. **Voice/tone** → `voice.tone`, `voice.personality` (3 adjectives)
+6. **Foundation** → `foundation` (one of 8 supported options)
+7. **Design school** → `school` (one of the movements in `memory/01-design-schools.md`)
+8. **Locales** → `localization.supportedLocales`, `localization.rtl`
+
+### Auto-derived tokens
+From the primary color + mode choice, auto-generate:
+- `primaryForeground` (contrast-safe white or dark)
+- `secondary` (complementary hue shift)
+- `surface`, `surface2`, `border` (tinted neutrals — NEVER pure black/white)
+- Dark mode mirror tokens (shift lightness, preserve hue)
+- `shadows.focusRing` using `color-mix()` from the primary
+
+## Path B: Extract (existing identity → `brand.json`)
+
+### What to extract, and from where
+
+| Token | Primary source | Fallback |
+|---|---|---|
+| `colors.*` | **Computed styles** of existing site's key surfaces (buttons, header bg, body text) — sample actual rendered hex, NOT guesses from screenshots | Ask user for 2–3 hex values |
+| `typography.families.*` | `<link>`/`@font-face` declarations in HTML/CSS | Route through `memory/12-typography-matrix.md` mood table |
+| `voice.*` | Read 3–5 paragraphs of existing marketing copy; infer register | Ask user for 3 adjectives |
+| `identity.logo.*` | Existing logo file (SVG or high-res PNG with transparency) | Flag as missing — do NOT fabricate |
+| `localization.*` | `<html lang>` / `dir` on existing site | Ask which locales needed |
+
+### What NOT to extract
+- **Layout or page structure** — not a `brand.json` token
+- **Exact copy text** — voice *rules* transfer, literal sentences don't
+- **Font files** — only family *names*, resolved against Google Fonts. Non-Google fonts flagged, NOT silently substituted
+
+### Extract procedure
+1. Confirm source (URL / PDF / assets)
+2. Extract candidate tokens per table above
+3. **Present draft `brand.json` to user before writing** — extraction is inference, not ground truth
+4. Once confirmed, write `brand.json` and validate
+
+## Path C: Migrate (v1 → v2)
+
+Load `memory/11-brand-json-v2.md` migration table and transform:
+- Flat `colors.primary` → `colors.light.primary` + `colors.dark.primary`
+- `typography.headings.arabic` → `typography.families.arabicHeading`
+- Add missing sections: `shadows`, `radius`, `spacing`, `motion`, `breakpoints`, `iconography`, `components`, `localization`, `accessibility`
+
+## Output Convention
+
+After any path, the final `brand.json` must:
+1. Pass JSON validation
+2. Have `$schema: "brand-core-v2"`
+3. Have all 16 tokens in both `colors.light` and `colors.dark`
+4. Have `motion.reducedMotion` policy stated
+5. Have `accessibility.minTouchTarget` ≥ 44px
+
+## Checklist
+
+- [ ] `$schema` is `"brand-core-v2"`
+- [ ] Both color modes have all 16 semantic tokens
+- [ ] No pure `#000000` or `#ffffff` in any surface token
+- [ ] Contrast passes WCAG AA on all text/background pairings
+- [ ] `googleFontsUrl` loads ONLY families referenced in `typography.families`
+- [ ] Logo files exist or are explicitly flagged as missing
+- [ ] Draft was confirmed by user before writing (extract path)

package/references/commands/brief.md

@@ -0,0 +1,107 @@
+# Command: `brief` — Design Context Gate & Fit Test
+
+Runtime entry point for establishing design context before any build begins. Part of the **Discovery** lifecycle phase.
+
+## When to use
+
+- **Always** before `init`, `page`, `dashboard`, or `components` — the brief ensures the design has intention, not defaults.
+- After `study` if a reference was analyzed.
+- Whenever a design request lacks context ("build me a landing page" without audience/tone/purpose).
+
+## The 3-Question Design-Context Gate
+
+### Question 1: Audience
+> Who is the primary audience, and what is their emotional state when they arrive?
+
+**Why it matters**: A B2B decision-maker comparing vendors arrives in *evaluate mode* (needs tables, specs, trust signals). A luxury buyer arrives in *aspire mode* (needs atmosphere, restraint, desire). The same "landing page" requires completely different design DNA.
+
+**Classify into**:
+| Mode | Characteristics | Design implications |
+|---|---|---|
+| **Inspire** | Browse, dream, aspirate | Atmospheric, generous whitespace, cinematic motion, minimal text |
+| **Evaluate** | Compare, decide, justify | Data-forward, specs tables, social proof, clear pricing |
+| **Act** | Purchase, sign up, convert | Friction-free, prominent CTA, trust signals, minimal distraction |
+| **Learn** | Study, explore, understand | Content-rich, good typography, navigation, readable hierarchy |
+
+### Question 2: Use Case / Surface Type
+> What kind of surface is this?
+
+| Surface | Layout suggestions | Foundation fit |
+|---|---|---|
+| Marketing landing page | `film`, `story`, `minimal` (from `memory/13-layout-archetypes.md`) | native, tailwind |
+| Product / e-commerce | `product`, `store` | tailwind, daisyui |
+| Dashboard / app screen | Use `dashboard` command | native, shadcn |
+| Documentation / content | Use `page` command with editorial school | native, pico |
+| Real estate / spatial | `space` | tailwind |
+| Personal brand / portfolio | `creator` | native, pico |
+
+### Question 3: Tone / Design School
+> What emotional register should the design communicate?
+
+Route to `memory/01-design-schools.md` and lock one of:
+- **Minimalist**: Restraint, whitespace, typography-driven
+- **Brutalist**: Raw, exposed, high-contrast, intentionally rough
+- **Neo-skeuomorphic**: Tactile, soft shadows, warm surfaces
+- **Glassmorphic**: Frosted glass, translucency, depth layers
+- **Editorial**: Magazine layout, strong hierarchy, serif typography
+- **Playful**: Rounded, vibrant, animated, friendly
+
+## The 9-Step Design Decision Tree Protocol (`memory/18-design-decision-engine.md`)
+
+Execute decisions sequentially to prevent random or clashing visual choices:
+
+```
+Step 1: Project Scope       → Determine surface type (marketing, dashboard, e-commerce, docs, spatial)
+Step 2: Industry Register   → Map domain (Corporate, SaaS, FinTech, AI, Healthcare, Education, Luxury, E-Commerce)
+Step 3: Audience Mode       → Classify user state (Inspire, Evaluate, Act, Learn)
+Step 4: Brand Personality   → Lock 3-5 tone adjectives (from memory/16-design-movements-guide.md)
+Step 5: Storytelling        → Choose archetype (Cinematic, Editorial, Documentary, Interactive)
+Step 6: UX Philosophy       → Lock core principles (Accessibility-first, Mobile-first, RTL-first, Dark Native)
+Step 7: Visual School       → Select Primary School & max 1 Secondary Influence from compatibility matrix
+Step 8: Token Generation    → Derive tokens.css & brand.json v2 based on Visual DNA & Color Palettes
+Step 9: Component Behavior  → Apply exact component shape, form, motion language, & executable signature
+```
+
+### Mandatory Constraint: Anti-"Design Soup" Rule
+Never combine more than:
+- **1 Primary School**
+- **1 Secondary Influence** (must be listed as `compatible` in the primary school's matrix)
+- **1 Motion Language**
+- **1 Storytelling Style**
+- **1 UX Philosophy Accent**
+
+## Fit Test (3-Question Filter)
+
+After the context gate, run the fit test to confirm the right tool:
+
+1. **One clear subject?** (one product / one brand / one space / one person) → ✅ proceed. Multiple products / catalog → route to `store` layout.
+2. **Transformation arc?** (before→after, raw→finished, outside→inside) → ✅ `film` layout. Static spec → `story` or `editorial` layout.
+3. **User in inspire mode?** → ✅ cinematic/atmospheric. Evaluate/compare mode → data-forward layout.
+
+## Output: Design Brief
+
+```markdown
+## Design Brief
+
+### Context
+- **Audience**: [description] — [inspire/evaluate/act/learn] mode
+- **Surface**: [marketing / product / dashboard / docs / portfolio]
+- **Tone**: [design school] — [2-3 adjective mood words]
+
+### Decisions Locked
+- **Foundation**: [native / tailwind / daisyui / hybrid / shadcn / pico / bootstrap / alpine]
+- **Layout Archetype**: [film / story / space / app / creator / product / store / auto]
+- **Typography Route**: [from memory/12-typography-matrix.md mood table]
+- **Color Direction**: [dark luxury / light gallery / warm / cool / vibrant]
+
+### What to Build
+- [Specific sections and features based on the brief]
+```
+
+## Checklist
+
+- [ ] All 3 context questions answered before building
+- [ ] Audience mode classified (inspire / evaluate / act / learn)
+- [ ] Surface type matched to layout archetype
+- [ ] Design school locked and documented
+- [ ] Foundation chosen and will not change mid-project

package/references/commands/clone.md

@@ -0,0 +1,26 @@
+# Command: `clone` — Reverse-Engineering & Design System Extraction
+
+Runtime entry point for reverse-engineering an external website reference into a clean, code-native prototype design system.
+
+## Computed-Style Extraction Protocol
+
+When reverse-engineering an existing brand reference:
+1. **Computed Styles**: Sample actual rendered hex values from `getComputedStyle()` on key DOM elements (buttons, headers, body text) rather than visual guesses from screenshots.
+2. **Typography Declarations**: Read exact font family names from `<link>` tags and `@font-face` declarations.
+3. **Draft Confirmation**: Always present extracted `brand.json` v2 drafts back to the user for explicit confirmation before writing as final.
+4. **Token Isolation**: Extract design system tokens ONLY — do not carry over source layout structure or literal copy text.
+
+## Dispatch Steps
+
+1. Load `references/memory/architecture.md` — locked file tree layout and consistency rules.
+2. Load `memory/03-narrative-conversion.md` — token derivation rules.
+3. Load `references/workflows/clone-prototype.md` — execution sequence, multi-state diffing, and validation checklist.
+4. Enforce **150-Line Complexity Budget Rule**: split sections exceeding 150-line specs into sub-component tasks.
+5. Execute workflow steps per `clone-prototype.md`.
+
+## Checklist
+
+- [ ] Interaction models (`scroll-driven`, `click-driven`, `hover-driven`) documented before building
+- [ ] Multi-state CSS transition diffs mapped to `tokens.css`
+- [ ] Component specs written to `docs/research/components/`
+- [ ] `references/workflows/clone-prototype.md` validation checklist fully satisfied

package/references/commands/components.md

@@ -0,0 +1,46 @@
+# Command: `components` — The Shared Component Library & 8-State Demo Wrapper
+
+Runtime entry point for authoring shared component classes in `components.css` and generating an 8-state demo preview.
+
+## Purpose
+The mechanism that makes the consistency guarantee real: one place where every reusable visual pattern lives. When building a standalone component, this command authors `components.css` AND generates a temporary 8-state preview wrapper (`<Component>.preview.html`) rendering all interactive states.
+
+## 8-State Component Matrix & Demo Wrapper (`<Component>.preview.html`)
+
+When a component is created or updated, generate `<Component>.preview.html` rendering all **8 interactive states** vertically stacked:
+
+```
+┌──── Component — 8 states ────────────────────────┐
+│ default       [ Component default state   ]    │
+│ hover         [ Component hover state     ]    │  ← .is-hover
+│ focus         [ Component focus state     ]    │  ← .is-focus
+│ active        [ Component active state    ]    │  ← .is-active
+│ disabled      [ Component disabled state  ]    │  ← disabled / aria-disabled
+│ loading       [ Component loading state   ]    │  ← data-state="loading"
+│ error         [ Component error state     ]    │  ← data-state="error"
+│ success       [ Component success state   ]    │  ... data-state="success"
+└────────────────────────────────────────────────┘
+```
+
+## What it does
+
+1. Confirm `cssFoundation` from `brand.json` and read matching foundation file.
+2. Author reusable class in `design-system/components.css` referencing tokens in `tokens.css`.
+3. Support all 8 states in CSS using both pseudo-classes and preview helper classes (`.is-hover`, `.is-focus`, `.is-active`).
+4. Generate `<Component>.preview.html` for single-file visual validation.
+5. Never duplicate an existing component under a new name—extend with a modifier class (`.card--compact`, `.btn--accent`).
+
+## Output Convention
+
+```
+design-system/
+├── components.css              ← Reusable component styling with 8-state support
+└── Button.preview.html         ← 8-state vertical demo preview wrapper
+```
+
+## Checklist
+
+- [ ] All 8 interactive states supported in `components.css`
+- [ ] `<Component>.preview.html` generated showing all 8 states vertically
+- [ ] Every color/font value traces to a token in `tokens.css`
+- [ ] No hardcoded hex or literal values in component CSS