@tidyfactor/design 1.5.0

package/references/commands/dashboard.md

@@ -0,0 +1,45 @@
+# Command: `dashboard` — Add an App/Dashboard Screen
+
+## Purpose
+Dashboards are structurally different from marketing pages (persistent
+navigation shell, data-density, empty/loading/error states are core to the
+experience, not edge cases) — kept as its own command so those differences
+get deliberate handling instead of the marketing-page template stretched to
+fit.
+
+## When to run it
+- Any app-shell screen: overview/analytics, a data table view, a settings
+  screen, a detail/record view, an onboarding step.
+- User phrasing: "design a dashboard screen", "add the settings page to
+  the app", `dashboard`.
+
+## What it does
+1. Confirm (or establish, on the first `dashboard` run) the **persistent
+   shell**: sidebar or topbar navigation, defined once as a component,
+   reused identically across every dashboard screen — never rebuilt per
+   screen.
+2. Compose the screen's content area from `components.css`/foundation
+   library data surfaces: stat cards, data tables, charts-as-static-visual
+   (a prototype doesn't need live data binding, but the visual should read
+   as real data, not a placeholder grid), filters, forms.
+3. **Build the full state set as part of this command, not as an
+   afterthought**: populated, empty (with a clear next action), loading
+   (skeleton, not a spinner-only blank), and error — a dashboard prototype
+   that only shows the happy path isn't credible to a client review.
+4. Keep density and information hierarchy deliberate — a dashboard's job is
+   scanning, not persuading; resist marketing-page hero treatment here.
+5. Same drift rule as `page`: any missing pattern gets routed through
+   `components`, never improvised in place.
+
+## Output convention
+```
+pages/dashboard-<screen-name>.html
+  <nav class="app-shell__sidebar">...</nav>   ← identical markup across every dashboard screen
+```
+
+## Checklist
+- [ ] Shell (nav) markup identical across all dashboard screens in the
+      project
+- [ ] Empty, loading, and error states built alongside the populated state
+- [ ] Data surfaces read as real data, not obvious placeholder content
+- [ ] No page-level CSS/JS — same rule as `page`

package/references/commands/deploy.md

@@ -0,0 +1,45 @@
+# Command: `deploy` — Preview, Present, Export
+
+## Purpose
+Always the last command: verify the prototype actually behaves correctly
+and package it for a client presentation or a developer handoff, with zero
+build step required either way.
+
+## When to run it
+- Always last in a full sequence, after `audit` passes.
+- User phrasing: "get this ready to present", "export the prototype",
+  `deploy`.
+
+## What it does
+1. **Serve locally**: `python -m http.server 8123` or `npx serve` — open in
+   a **visible** browser tab (backgrounded tabs pause
+   `requestAnimationFrame`, which affects `motion`'s entrance/scroll
+   effects and can produce false verification results).
+2. **Present mode**: confirm `proto-nav.js`'s toolbar works — page jump,
+   flow start, state toggles — this is the client-facing "click through it
+   yourself" experience.
+3. **Confirm portability**: the whole `pages/` + `design-system/` folder
+   runs correctly opened via plain static file serving — no server
+   process, no build step, matches the zero-dependency promise of every
+   TidyFactor track's *output*, whatever the CSS foundation needed at
+   design time.
+4. **Handoff note (optional, never assumed)**: if the user wants this
+   handed to `tidyfactor-html`/`tidyfactor-php-*` for production, that's a
+   separate, explicit request — `deploy` doesn't restructure anything
+   toward another skill's conventions unasked.
+5. Final `audit` pass — nothing ships to a client review with open
+   structural violations.
+
+## Output convention
+```
+project/
+  design-system/   ← shipped as-is, still the only source of styling
+  pages/
+  proto-nav.js       (strip before any production handoff — it's a dev tool)
+```
+
+## Checklist
+- [ ] Verified in a visible browser tab
+- [ ] `proto-nav.js` present-mode toolbar functions correctly
+- [ ] Runs from plain static file serving, no build step
+- [ ] Final `audit` clean (or open findings explicitly accepted by the user)

package/references/commands/flow.md

@@ -0,0 +1,44 @@
+# Command: `flow` — Click-Through Prototype Navigation
+
+## Purpose
+Turns a folder of independent pages into a navigable prototype a client can
+click through unassisted — the feature that makes this a genuine Figma
+"present mode" alternative rather than a pile of static mockups.
+
+## When to run it
+- Enough pages exist to connect into a coherent path (a few pages minimum
+  — running this on a single page has nothing to connect).
+- User phrasing: "link these pages together", "make this clickable",
+  "prototype the flow from signup to dashboard", `flow`.
+
+## What it does
+1. Map the intended user journeys from the brief (e.g. landing → pricing →
+   signup → dashboard-overview) — real navigation intent, not just "link
+   everything to everything".
+2. Wire real `<a href="...">` links between pages for the primary
+   journeys — this must work with plain static hosting/file:// browsing,
+   not just the dev server.
+3. Add the shared, dev-only **prototype toolbar** (`proto-nav.js`): a small
+   floating control (page jump list, "back to flow start", state toggles
+   for pages that expose empty/loading/error states) — visibly styled as a
+   tool, not part of the design itself, and easy to strip out before any
+   production handoff.
+4. Where a linked page doesn't exist yet, either build it (route to `page`/
+   `dashboard`) or mark it clearly as a stub end-point — never a silent
+   dead link.
+5. For state toggles (e.g. viewing a dashboard's empty vs. populated state
+   without needing separate pages): drive them via a URL query param or the
+   toolbar, documented in that page's markup comment.
+
+## Output convention
+```
+proto-nav.js            ← shared floating toolbar, all pages include it
+pages/*.html               ← real <a href> links for primary journeys
+```
+
+## Checklist
+- [ ] Primary journeys from the brief are actually clickable end-to-end
+- [ ] No silent dead links — every reference either resolves or is a
+      marked stub
+- [ ] Prototype toolbar is visually distinct from the design itself
+- [ ] Works via plain static file browsing, not only the dev server

package/references/commands/handoff.md

@@ -0,0 +1,53 @@
+# Command: `handoff` — Developer Handoff Spec Generation
+
+Runtime entry point for generating clean, developer-ready design system specifications, token maps, component state matrices, and implementation guidelines. Part of the **Delivery & Handoff** lifecycle phase.
+
+## When to use
+
+- After prototype approval, when handing off to engineering/developers
+- When documenting design system tokens for production implementation
+- When building a component library documentation site
+
+## Handoff Package Specification
+
+The `handoff` command extracts and formats technical documentation into `docs/handoff/`:
+
+```
+docs/handoff/
+├── 01-token-map.md          ← Exact CSS variables, HSL values, typography scale, spacing grid
+├── 02-component-matrix.md   ← Full inventory of components with all 8 interactive states
+├── 03-layout-specs.md       ← Spacing rules, grid containers, breakpoint behaviors
+└── 04-motion-handbook.md    ← Easings, timing curves, reduced motion fallbacks
+```
+
+## Generated Outputs
+
+### 1. Token Map (`01-token-map.md`)
+Export clean tables tracing `brand.json` v2 tokens to CSS variable implementations:
+- Color swatches with hex, HSL, and light/dark role mappings
+- Font family declarations, weights, line-height ratios, letter-spacing
+- Spacing scale values in `rem` and `px`
+- Elevation levels & shadow specs (including `color-mix()` focus rings)
+
+### 2. Component Matrix (`02-component-matrix.md`)
+For each shared component in `design-system/components.css`:
+- HTML markup snippet
+- Interactive state inventory: Default, Hover, Active, Focus-Visible, Disabled, Loading, Error, Success
+- Accessibility requirements (ARIA roles, minimum 44px touch targets)
+
+### 3. Layout & Grid Specs (`03-layout-specs.md`)
+- Container max-widths (`sm`, `md`, `lg`, `xl`, `2xl`)
+- Section padding discipline
+- RTL mirroring guidelines for bidirectional UI
+
+### 4. Motion Handbook (`04-motion-handbook.md`)
+- Cubic-bezier curves and duration values
+- Reduced-motion fallback rules (`prefers-reduced-motion: reduce`)
+
+## Checklist
+
+- [ ] Complete token mapping table generated
+- [ ] All components documented with interactive states
+- [ ] ARIA roles & WCAG AA contrast notes included
+- [ ] Motion timing curves & reduced motion policy exported
+- [ ] Handoff documentation written to `docs/handoff/`

package/references/commands/i18n.md

@@ -0,0 +1,64 @@
+# Command: `i18n` — Arabic/RTL & Bilingual Sites
+
+## Purpose
+Arabic support is a first-class capability of this skill, not a translation
+pass bolted on at the end — this command carries conventions drawn directly
+from prior production work, not generic RTL guidance. Run this as a real
+step in every project, even English-only ones, so the decision is explicit.
+
+## When to run it
+- Always, once, as part of Phase 3 — even to explicitly confirm an
+  English-only project isn't accidentally missing a locale decision.
+- User phrasing: "make this bilingual", "add the Arabic version", "flip to
+  RTL", `i18n`.
+
+## What it does
+1. Set `localization.defaultLocale` / `localization.rtlLocales` in
+   `brand.json`; set `html[lang]`/`html[dir]` per page accordingly.
+2. **Typography (non-negotiable)**: Arabic headings = El Messiri, Arabic
+   body = Tajawal, defined as `typography.families.arabicHeading` /
+   `arabicBody` tokens. **Never Amiri** for display/UI text — it reads as
+   calligraphic/traditional, not modern-clean, and has consistently been
+   wrong for this kind of work.
+3. **Bilingual sites**: pick and document one pattern per project, don't
+   mix:
+   - **Separate localized pages** (`pages/home.html` +
+     `pages/home.ar.html`) — simplest, works with the `page` command
+     unchanged, best when Arabic and English content genuinely differ in
+     length/structure.
+   - **Single page, dual-tree toggle** (both language trees present, one
+     hidden via `[hidden]`/`dir`-scoped CSS, `proto-nav.js` toggle switches
+     them) — best for a fast side-by-side client review of both locales.
+4. **Mirroring vs. not**: layout mirrors in RTL (nav, breadcrumbs, form
+   label alignment, icon-direction for "next/back" arrows) — but numerals,
+   embedded Latin brand names, and code/data stay LTR inside the RTL flow
+   (`unicode-bidi: isolate` where needed). Don't blanket-mirror everything.
+   Logo/wordmark and any Latin brand name stays unmirrored and identical
+   across locales — brand identity doesn't flip.
+5. Re-run the `components` states matrix mentally for RTL: hover/focus
+   rings, dropdown open-direction, and modal close-button position all need
+   to make sense mirrored, not just the text direction.
+6. If `voice.doNotUse` (brand voice rules) has a localized Arabic block,
+   apply it — don't machine-translate the English voice guide.
+
+## Output convention
+```
+design-system/tokens.css
+  --font-heading-ar: 'El Messiri', serif;
+  --font-body-ar: 'Tajawal', sans-serif;
+design-system/brand.json
+  "localization": { "defaultLocale": "ar", "rtlLocales": ["ar"] }
+pages/
+  home.html       (or home.en.html / home.ar.html, per chosen pattern)
+```
+
+## Checklist
+- [ ] `html[lang]`/`html[dir]` correct on every page, not left at a
+      template default
+- [ ] Arabic type is El Messiri/Tajawal — confirmed never Amiri
+- [ ] One bilingual pattern chosen and applied consistently, not mixed
+      across pages
+- [ ] Layout mirrors appropriately; numerals/Latin brand names stay LTR
+      where correct
+- [ ] Interactive states (dropdowns, modals) re-checked for sensible RTL
+      behavior, not just text direction

package/references/commands/init.md

@@ -0,0 +1,30 @@
+# Command: `init` — Foundation + First Page, One Pass
+
+Runtime entry point for starting a brand-new interactive prototype from scratch.
+
+## Dispatch steps
+
+1. Load `references/memory/architecture.md` — locked file tree layout and consistency rules.
+2. Load `references/memory/foundations.md` — CSS foundation selection rules.
+3. Load `references/workflows/init-prototype.md` — execution sequence and validation checklist.
+4. Execute workflow steps per `init-prototype.md`.
+
+## Output convention
+
+```
+project/
+  design-system/
+    tokens.css
+    base.css
+    components.css
+    brand.json
+    motion.js
+    interactions.js
+  pages/
+    home.html
+```
+
+## Checklist
+
+- [ ] Mode and CSS foundation both confirmed and recorded
+- [ ] `references/workflows/init-prototype.md` validation checklist fully satisfied

package/references/commands/layout.md

@@ -0,0 +1,81 @@
+# Command: `layout` — Surface Layout Archetypes
+
+Runtime entry point for selecting and applying specialized surface layout blueprints. Part of the **Architecture** lifecycle phase.
+
+## When to use
+
+- During `init` to select the page's macrostructure
+- When adding a new page type that doesn't fit standard `page` or `dashboard`
+- When the user describes a surface type (e.g., "real estate showcase", "app launch page", "product showcase")
+
+## Dispatch Steps
+
+1. Load `memory/13-layout-archetypes.md` — full archetype specifications.
+2. Run the fit test (from `brief`) to narrow the archetype choice.
+3. Load `references/memory/architecture.md` — locked file tree rules.
+4. Scaffold the page with the selected archetype's section rhythm.
+
+## Layout Archetype Catalog
+
+| Archetype | Codename | Best For | Hero Type | Section Rhythm |
+|---|---|---|---|---|
+| **Film** | `fullbleed` | Physical goods, brand stories, rebrands, fashion, artisan | Product cutout + aura + motes | Hero → Film (600vh canvas) → Product reveal → Lifestyle → CTA |
+| **Story** | `editorial` | Specs-heavy products, founders, events, conferences | Split-screen: image + copy | Hero → Film (420vh) → Feature grid → Origin story → CTA |
+| **Space** | `spatial` | Real estate, architecture, travel, hospitality, venues | Wide establishing shot, no cutout | Hero → Film walkthrough (500vh) → Space details → Location → CTA |
+| **App** | `interface` | SaaS, apps, digital platforms | Device mockup (phone/laptop frame) | Hero → Film (420vh UI flow) → Feature highlights → Social proof → CTA |
+| **Creator** | `minimal` | Personal brands, creators, digital products, books | Centered cutout, clean background | Hero → Statement → About → Portfolio grid → CTA |
+| **Product** | `product` | Single product high-conversion e-commerce | Hero product + price + WhatsApp CTA | Hero → Optional film (480vh) → Specs → Social proof → Buy CTA |
+| **Store** | `store` | Multi-product catalog store | Store banner + WhatsApp CTA | Banner → Category filter → Product grid → Footer CTA |
+| **Auto** | `auto` | Automotive & performance magazine showpiece | Hero car + tachometer gauge preloader | Hero → 3D slider stage → HUD spec tooltips → Gallery → CTA |
+
+## Fit Test (Quick Decision Tree)
+
+```
+1. One product or many?
+   → Many → "store" archetype
+   → One → continue
+
+2. Physical product or digital?
+   → Digital (SaaS/app) → "app" archetype
+   → Physical → continue
+
+3. Is it a space/place?
+   → Yes → "space" archetype
+   → No → continue
+
+4. Person or brand?
+   → Person → "creator" archetype
+   → Brand → continue
+
+5. High-ticket or conversion-focused?
+   → Yes → "product" archetype
+   → No → continue
+
+6. Strong transformation story?
+   → Yes → "film" archetype
+   → No → "story" archetype
+```
+
+## Archetype Application
+
+When an archetype is selected:
+
+1. **Scaffold sections** — create the HTML skeleton with semantic section markers matching the archetype's rhythm
+2. **Set ambient palette direction** — configure the `#ambient` background-color tween targets per section
+3. **Configure hero type** — select the hero component variant matching the archetype (cutout vs. full-bleed vs. split-screen vs. device mockup)
+4. **Lock nav + footer** — route to `memory/14-nav-footer-catalog.md` for genre-appropriate nav (N1–N9) and footer (Ft1–Ft8) selection
+
+## Customization
+
+Archetypes are **starting points, not straitjackets**. The user can:
+- **Add/remove sections** from the archetype rhythm
+- **Swap hero type** (e.g., use a split-screen hero on a `film` archetype)
+- **Mix elements** from multiple archetypes (document the deviation in the design brief)
+
+## Checklist
+
+- [ ] Archetype selected via fit test, not defaulted
+- [ ] Section rhythm follows archetype spec
+- [ ] Hero type matches archetype (or deviation is documented)
+- [ ] Nav and footer selected from catalogs (not AI-default)
+- [ ] Ambient palette direction set per section

package/references/commands/motion.md

@@ -0,0 +1,62 @@
+# Command: `motion` — Shared Animation, Choreography & Micro-Delight
+
+Runtime entry point for configuring global motion tokens, scroll-reveals, and micro-delight interactions in `motion.js` and `interactions.js`.
+
+## 4-Tier Whimsy & Micro-Interaction Taxonomy
+
+Incorporate purposeful micro-interactions across 4 operational tiers to give prototypes distinct brand character without sacrificing usability or accessibility:
+
+1. **Tier 1: Subtle Whimsy (Default UI Feedback)**
+   - Micro-lifts on hover (`transform: translateY(-2px)`), smooth button scale on click, subtle focus ring glows.
+   - Defined in `tokens.css` and `components.css`.
+2. **Tier 2: Interactive Whimsy (Task Celebrations)**
+   - Sparkle animation on form validation, smooth checkmark draw on task completion, progress step rewards.
+   - Defined in `interactions.js`.
+3. **Tier 3: Discovery Whimsy (Exploration Rewards)**
+   - Subtle Easter eggs, custom keyboard shortcuts (`⌘+K`, `?` modal), hidden theme toggles.
+4. **Tier 4: Contextual Whimsy (Charming Microcopy & States)**
+   - Playful empty states with micro-illustrations, empathetic 404 error states, animated loading dot pulses.
+
+## Advanced Motion Recipes & Fixed Z-Stack Layers
+
+### Fixed Z-Stack Background Layers
+Implement 5 persistent background layers behind page content for ambient depth:
+- `#ambient` — Fullscreen background color, GSAP-tweened per section (`onEnter`/`onEnterBack`).
+- `#glow` — Soft radial lighting; opacity animates based on active section.
+- `#vignette` — Subtle edge darkening to direct visual focus toward center.
+- `#grain` — SVG fractal noise data-URI film grain overlay with low opacity.
+- `#progress` — Thin accent scroll-progress bar fixed at top of viewport.
+
+### Ambient Section Background Color Tweening
+```javascript
+ScrollTrigger.create({
+  trigger: section,
+  onEnter: () => gsap.to('#ambient', { backgroundColor: section.dataset.ambient, duration: 1.1 }),
+  onEnterBack: () => gsap.to('#ambient', { backgroundColor: section.dataset.ambient, duration: 1.1 })
+});
+```
+
+### Canvas Scroll-Film Engine
+For smooth video-like scroll reveals without H.264 playback stutter, draw pre-rendered frame sequences (`assets/seq/f000.jpg`) directly onto a fixed `<canvas>` element mapped to scroll progress.
+
+## Global Motion Rules
+
+1. **Token Discipline**: Every duration (`--duration-fast`, `--duration-base`) and easing curve (`--ease-out-quint`) must reference a CSS variable in `tokens.css`.
+2. **Accessibility & Reduced Motion**: `prefers-reduced-motion: reduce` must automatically disable keyframe translates and scale bounces across all pages, falling back to simple opacity fades.
+3. **Single Shared Script**: All interaction choreography lives inside `design-system/motion.js` and `design-system/interactions.js` — zero per-page JS scripts allowed.
+
+## Output Convention
+
+```
+design-system/
+├── motion.js          ← Shared entrance reveals & scroll choreography
+├── interactions.js    ← Tier 1-4 micro-delight & component interactions
+└── tokens.css         ← Motion easings & duration tokens
+```
+
+## Checklist
+
+- [ ] Micro-interactions implemented across Tier 1-4 Whimsy taxonomy
+- [ ] Every motion duration/easing traces to a token in `tokens.css`
+- [ ] `prefers-reduced-motion` compliance enforced globally across all tiers
+- [ ] No per-page motion scripts exist in `pages/`

package/references/commands/nav-footer.md

@@ -0,0 +1,54 @@
+# Command: `nav-footer` — Navigation & Footer Archetype Catalogs
+
+Runtime entry point for selecting, customizing, and auditing Navigation (N1–N9) and Footer (Ft1–Ft8) components. Part of the **Architecture** lifecycle phase.
+
+## When to use
+
+- During `init` or `layout` when scaffolding page macrostructure
+- When replacing a generic AI nav or footer with a genre-authentic archetype
+- When auditing a page for anti-AI navigation/footer tells
+
+## Navigation Catalog (N1–N9)
+
+| ID | Name | Structure | Best For |
+|---|---|---|---|
+| **N1** | Floating Pill | Glassmorphic floating island (`max-w-fit mx-auto`), rounded-full | SaaS, modern minimal, mobile-first |
+| **N2** | Newspaper Masthead | Centered title block top, rule divider, category links row below | Editorial, literary, publishing |
+| **N3** | Brutal Slab | Stark thick bottom border (`border-b-4`), uppercase mono text | Industrial, dev tools, brutalist |
+| **N4** | Terminal / CLI | Dark background, prompt symbol (`>`), monospace links | Developer tools, CLI apps, tech |
+| **N5** | Edge-Aligned Minimal | Wordmark hard-left, navigation hard-right, no center links | Portfolio, creator, luxury |
+| **N6** | Split Brand | Emblem center, links distributed evenly left & right | Fashion, luxury, artisan physical goods |
+| **N7** | Double-Decker Utility | Top utility bar (announcement/currency/lang), main header below | E-commerce, multi-locale, enterprise |
+| **N8** | Vertical Rail | Fixed side navigation bar (collapsed/expanded on hover) | Dashboards, complex web apps |
+| **N9** | Fullscreen Overlay | Minimal trigger icon, click expands to full-screen menu modal | High-fashion, artistic showcases |
+
+## Anti-AI Navigation Tell (Auto-Reject Rule #11)
+> **The AI Nav**: Wordmark left, 4-5 links center, primary CTA right, 1px bottom border.
+> 
+> *Rule*: If N1–N9 is not explicitly declared, the nav must use an opinionated layout variance (e.g. N1 floating pill or N5 edge-aligned), never the default AI Nav template.
+
+## Footer Catalog (Ft1–Ft8)
+
+| ID | Name | Structure | Best For |
+|---|---|---|---|
+| **Ft1** | Mast-Headed | Giant brand display wordmark at top, multi-column grid below | Flagship brands, luxury, editorial |
+| **Ft2** | Minimal Inline | Single horizontal line: Wordmark · Links · Copyright | Minimalist, single-page, creator |
+| **Ft3** | Colophon / Credits | Technical metadata, font credits, server region, timestamp | Developer tools, design engineering |
+| **Ft4** | Big Statement | Huge opinionated quote/tagline block, minimal links below | Personal brand, agency, manifesto |
+| **Ft5** | Letter Close | Signed founder letter / closing note + CTA + copyright | Founder-led, indie hacker, newsletter |
+| **Ft6** | Newsletter-First | Large email input form taking top 50% of footer | Content, publishing, e-commerce |
+| **Ft7** | Marquee Scroll | Infinite scrolling text marquee above standard links | Fashion, agencies, events |
+| **Ft8** | Sitemap Grid | Structured multi-section directory grid + locale switcher | Enterprise, SaaS, docs |
+
+## Anti-AI Footer Tell (Auto-Reject Rule #12)
+> **The AI Footer**: 4 equal columns (Product, Company, Resources, Legal) + social row + copyright line.
+> 
+> *Rule*: Reject 4-column equal grids without asymmetric visual hierarchy or distinctive hero elements (e.g. Ft1 giant wordmark or Ft5 letter close).
+
+## Checklist
+
+- [ ] Nav selected from N1–N9 catalog (or explicitly customized)
+- [ ] Footer selected from Ft1–Ft8 catalog
+- [ ] No generic 4-link center AI nav used
+- [ ] No generic 4-column equal AI footer used
+- [ ] RTL mirroring rules respected (`localization.mirrorOnRtl` in `brand.json`)

package/references/commands/page.md

@@ -0,0 +1,45 @@
+# Command: `page` — Add a Marketing/Content Page
+
+## Purpose
+The recurring loop this whole skill exists to support: add another page to
+the prototype without any risk of visual drift, however large the site
+grows. This is the command most likely to run dozens of times on one
+project — its discipline matters more than any other command's.
+
+## When to run it
+- Any time a new website page (not a dashboard/app screen — see
+  `dashboard` for that) is needed: landing, pricing, about, feature,
+  listing, detail, contact, 404...
+- User phrasing: "add a pricing page", "build the about page", `page`.
+
+## What it does
+1. Confirm `design-system/tokens.css` and `components.css` (or the
+   foundation's theme) are current — never build against a stale set.
+2. Apply the `references/foundations/<choice>.md` narrative-quality
+   principles: the hero is a thesis for *this* page's job, structure
+   encodes real information (no decorative numbering unless it's a real
+   sequence), copy is real content for this page, not lorem ipsum.
+3. Compose the page **only** from existing `components.css` classes /
+   daisyUI components / Tailwind utilities per the locked foundation.
+4. **Hit a design need with no existing match?** Stop. Route it through
+   `components` first. Never write it inline "just this once" — that's
+   exactly the drift this architecture prevents.
+5. Add the page to `flow`'s navigation map if a prototype nav flow already
+   exists (don't leave new pages orphaned/unreachable).
+6. Verify: view source for any `<style>` tag or inline `style="..."`
+   attribute, and for any `<script>` beyond the shared includes — both are
+   automatic fails.
+
+## Output convention
+```
+pages/<page-name>.html    ← markup only, references design-system/* in <head>
+```
+
+## Checklist
+- [ ] Zero inline `<style>`, zero `style="..."` attributes
+- [ ] Zero page-specific `<script>` logic (shared includes only)
+- [ ] Every component used exists in `components.css`/foundation library —
+      none invented ad hoc
+- [ ] Hero/opening treats the page's specific job as a thesis, not a
+      generic template
+- [ ] Reachable from the prototype's `flow` navigation, if one exists

package/references/commands/palette.md

@@ -0,0 +1,35 @@
+# Command: `palette` — Brand Color Extraction & WCAG Contrast Check
+
+## Purpose
+Extract dominant brand colors, background tones, accent highlights, and WCAG 2.1 AA contrast compliance scores from reference images, logos, or hero screenshots using the built-in Python tool `scripts/extract_palette.py`. Automatically updates `brand.json` and appends CSS custom properties to `design-system/tokens.css`.
+
+## When to run it
+- User phrased: "extract color palette", "extract colors from logo", "check contrast ratio", "palette", `/palette`.
+- During `init` or `clone` when converting a reference logo or screenshot into a design token system.
+
+## What it does
+1. **Color Quantization & Extraction**:
+   - Runs `python scripts/extract_palette.py <image_path> --json brand.json --css design-system/tokens.css`.
+   - Quantizes the image palette to identify dominant Primary, Secondary, and Accent brand colors.
+2. **WCAG 2.1 AA Contrast Analysis**:
+   - Computes relative luminance and contrast ratios between text/primary colors against dark (`#0F172A`) and light (`#F8FAFC`) background surfaces.
+   - Ensures text meets minimum 4.5:1 ratio (WCAG AA compliant).
+3. **Token Synchronization**:
+   - Updates `brand.json` colors object.
+   - Appends CSS variables (`--color-primary`, `--color-secondary`, `--color-accent`) to `design-system/tokens.css`.
+
+## Usage Examples
+```bash
+# Extract palette from logo and update brand.json
+python scripts/extract_palette.py assets/logo.png --json brand.json
+
+# Append extracted tokens to tokens.css
+python scripts/extract_palette.py reference.png --css design-system/tokens.css
+```
+
+## Checklist
+- [ ] Image path is valid and readable by Pillow
+- [ ] Primary, secondary, and accent colors extracted cleanly
+- [ ] WCAG contrast ratio verified (≥ 4.5:1 for body text)
+- [ ] `brand.json` updated with new color tokens
+- [ ] `design-system/tokens.css` updated with matching CSS variables

package/references/commands/perf.md

@@ -0,0 +1,57 @@
+# Command: `perf` — Asset Performance Budgets & Optimization Check
+
+Runtime entry point for checking asset performance budgets, script preconnects, and load optimization. Part of the **Quality & Audit** lifecycle phase.
+
+## When to use
+
+- Before running `deploy` or finalizing any prototype
+- During `audit` to verify asset weight compliance
+- When performance or slow page load is flagged
+
+## Asset Performance Budgets (Mechanical Checklist)
+
+Report as a **table with actual numbers vs budget limit**, not generic pass/fail prose:
+
+| Asset Class | Budget Limit | Rationale |
+|---|---|---|
+| **Total Frame Sequence** (`assets/seq/*.jpg`) | ≤ 6.0 MB total (~90–120 frames) | Frame sequence payload on scroll-driven canvas |
+| **Single JPG Frame** | ≤ 60 KB at 1280px wide (q≈80) | Prevents un-scaled frame extraction issues |
+| **Hero Cutout PNG** | ≤ 400 KB (max width 1200px) | Transparent PNGs compress poorly; resize before optimization |
+| **Brand Logo PNG / SVG** | ≤ 40 KB (max width 240px) | Header/footer brand emblem |
+| **Google Fonts Payload** | ≤ 3 families, ≤ 4 weights total | Excess font families delay First Text Paint |
+| **Total CSS Payload** | ≤ 150 KB (gzipped/uncompressed) | Zero per-page CSS constraint enforces shared tokens |
+
+## Execution Protocol
+
+1. **Sum directory sizes**:
+   - Check `assets/` and `design-system/` file sizes.
+2. **Check Font `<link>` references**:
+   - Verify `<link rel="preconnect" href="https://fonts.googleapis.com">` exists.
+   - Verify `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>` exists.
+   - Ensure loaded font families match only those referenced in `brand.json`.
+3. **Verify LCP Optimization**:
+   - Confirm hero image does **NOT** have `loading="lazy"` (violates AI Anti-Pattern Rule #16).
+   - Below-the-fold images MUST use `loading="lazy"`.
+4. **Clean Script Tags**:
+   - Check for dead/duplicate script tags.
+
+## Report Output Format
+
+```
+Asset Class          Actual Weight    Budget Limit    Status
+------------------------------------------------------------
+Hero Cutout PNG      340 KB           400 KB          ✅ PASS
+Brand Logo SVG       12 KB            40 KB           ✅ PASS
+Google Fonts         2 families       3 families      ✅ PASS
+Total CSS            48 KB            150 KB          ✅ PASS
+LCP Image Eager      Yes              Yes             ✅ PASS
+Font Preconnects     Present          Present         ✅ PASS
+```
+
+## Checklist
+
+- [ ] All numeric budgets checked and reported in data table
+- [ ] Preconnect tags present for font and CDN domains
+- [ ] No `loading="lazy"` on LCP hero image
+- [ ] Lazy loading enabled for below-the-fold assets
+- [ ] Font families strictly capped at ≤ 3 families / 4 weights

package/references/commands/retrofit.md

@@ -0,0 +1,15 @@
+# Command: `retrofit` — Improve Mode Prototype Unification
+
+Runtime entry point for unifying a drifted prototype under one design system.
+
+## Dispatch steps
+
+1. Load `references/memory/architecture.md` — locked file tree layout and consistency rules.
+2. Load `memory/07-consistency-contract.md` — zero-drift contract rules.
+3. Load `references/workflows/retrofit-prototype.md` — execution sequence and validation checklist.
+4. Execute workflow steps per `retrofit-prototype.md`.
+
+## Checklist
+
+- [ ] All per-page CSS and inline styles purged
+- [ ] `references/workflows/retrofit-prototype.md` validation checklist fully satisfied