@tidyfactor/design 1.5.0 → 1.7.0

package/references/memory/08-arabic-bilingual.md

@@ -1,54 +1,42 @@
-# Arabic & Bilingual Design — Reference for `i18n`
+# Arabic & Bilingual Design — Reference for `i18n` & RTL Engineering
+<!-- last-verified: 2026-09-01 -->
 
-Conventions carried consistently across Alwkala's production work and the
-rest of the TidyFactor ecosystem (`tidyfactor-html`, `tidyfactor-cinematic`)
-— not generic RTL advice.
+Conventions carried consistently across Alwkala's production work and the rest of the TidyFactor ecosystem (`tidyfactor-design`, `tidyfactor-styler`, `tidyfactor-html`, `tidyfactor-cinematic`) — not generic RTL advice.
 
-## Typography
-- Headings: **El Messiri** — modern, geometric-leaning, reads as
-  contemporary rather than traditional/calligraphic.
-- Body: **Tajawal** — high legibility at small sizes, wide weight range.
-- **Never Amiri** for UI/display purposes — it's a naskh-style text face
-  suited to long-form literary/religious typesetting, not product/marketing
-  UI; it reads as the wrong register for almost every brief this skill
-  serves.
-- Arabic type generally needs slightly larger sizes and more line-height
-  than the Latin equivalent at the same visual weight — don't reuse the
-  Latin type scale unchanged.
+---
 
-## Layout mirroring
-- Mirrors: navigation order, breadcrumbs, form label alignment, icon
-  direction for directional affordances (back/next arrows), the reading
-  flow of card grids.
-- Does NOT mirror: numerals (Arabic numerals in most modern digital
-  products are written left-to-right even inside RTL text), embedded Latin
-  brand names/wordmarks, code or tabular data blocks.
-- Use `unicode-bidi: isolate` (or `dir="ltr"` spans) around any LTR content
-  embedded inside RTL flow to prevent bidi algorithm artifacts (numbers or
-  Latin words appearing in the wrong order).
+## 1. Typography & Hierarchy Rules
+- **Display / Headings**: **El Messiri** or **Noto Kufi Arabic** — modern, geometric-leaning, high visual presence without breaking script joining.
+- **Body / Editorial**: **Tajawal** or **Noto Naskh Arabic** — high legibility at small sizes, wide weight range.
+- **Never Amiri for UI/display purposes**: It's a naskh-style text face suited to long-form literary/religious typesetting, not product/marketing UI.
+- **Arabic Line Heights**: Display headings need `1.15–1.25`; body text needs `1.65–1.85`.
+- **Zero Tracking Deformation**: Never apply negative `letter-spacing` to Arabic headings; it breaks cursive connections and destroys word silhouettes.
 
-## Logo & identity
-Logo/wordmark stays pixel-identical and unmirrored across locales — brand
-identity doesn't flip with the reading direction, even when everything
-around it does.
+---
 
-## Bilingual site patterns
-- **Separate localized pages** — clean, works with every command
-  unchanged, best when content structure genuinely differs by locale.
-- **Single page, dual-tree toggle** — both language trees present in one
-  file, toggled via `proto-nav.js` — best for fast side-by-side prototype
-  review with a client, worse for a real production site (both trees ship
-  to every visitor).
-Pick one per project and record it in `brand.json`; don't mix within a
-project.
+## 2. Strict Bidi & Logical Properties Contract
+- **`<bdi>` Isolation (Mandatory)**: Always wrap embedded LTR content (phone numbers, email addresses, prices, Latin product codes, URLs) in `<bdi dir="ltr">` or `<bdi lang="en">` inside Arabic prose.
+- **Tabular Numerals**: Apply `font-variant-numeric: tabular-nums;` and `font-feature-settings: "tnum" 1;` on all metrics, counters, and data tables.
+- **Logical CSS Properties**:
+  ```css
+  /* Required Logical Properties */
+  .card {
+    padding-inline: var(--space-6);
+    margin-inline-start: var(--space-4);
+    border-inline-start: 4px solid var(--primary);
+    inset-inline-end: 0;
+  }
+  ```
+- **Mirroring Rules**:
+  - Mirrors: navigation order, breadcrumbs, form label alignment, directional affordances (back/next arrows).
+  - Does NOT mirror: numerals, embedded Latin brand marks, media controls, clocks, and universal marks.
 
-## Voice & tone
-If `brand.json`'s `voice.*` block has a localized Arabic register, apply it
-directly — a good Arabic UI voice is not a literal translation of the
-English one; register, formality, and idiom differ by convention.
+---
 
-## Interaction states in RTL
-Re-check, don't just assume: dropdown/menu open-direction, modal
-close-button position, tooltip anchor side, and any icon implying
-directionality — all need a considered RTL equivalent, not just a global
-`transform: scaleX(-1)`.
+## 3. 6 Hero Architectures for Arabic Mode
+1. **The Arabic Typographic Monument**: One short Arabic phrase occupies 45–70% of the viewport with a low-contrast heritage material behind it.
+2. **The Inscription Aperture**: Content framed through a geometric or vaulted aperture mask.
+3. **The Bilingual Editorial Split**: Arabic owns the dominant side with compact Latin metadata opposite.
+4. **The Heritage Material Close-Up**: Macro textural study (papyrus, carved relief, woven wool, alabaster) as focal hero image.
+5. **The Horizontal Journey**: RTL timeline or cinematic strip traveling from right to left.
+6. **The Contemporary Data Constellation**: Maps, coordinates, and telemetry with Arabic typography and tabular numbers.

package/references/memory/10-python-tooling.md

@@ -1,18 +1,19 @@
+<!-- last-verified: 2026-09-02 -->
 # 10 · Python Tooling & Asset Refinement Guide
 
 The **TidyFactor Design** skill includes a lightweight Python tooling suite in `scripts/` to provide AI Agents with local media manipulation, palette extraction, background removal, and image optimization capabilities.
 
 ---
 
-## 🛠️ Tooling Suite Inventory
+## 🛠️ Tooling Suite Inventory & Latency Classes
+
+| Script | Responsibility | Latency Class | Isolation Scope | Invoked By |
+|---|---|---|---|---|
+| **`scripts/audit_design.py`** | Anti-pattern & token compliance auditor | Sub-second (<100ms) | In-process stdlib | `audit`, `perf` |
+| **`scripts/extract_palette.py`** | WCAG 2.1 AAA contrast & palette derivation | Sub-second (<150ms) | `Pillow` (stdlib fallback) | `tokens`, `palette`, `init` |
+| **`scripts/optimize_assets.py`** | Neural bg removal & WebP image optimization | Async Batch (2–8s) | `isolation_recommended: true` (`rembg`, `onnxruntime`) | `assets`, `deploy` |
+| **`scripts/minify_assets.py`** | CSS/JS minification | Sub-second (<100ms) | Standard Python | `deploy` |
 
-| Script | Primary Responsibility | Dependencies | Command Trigger |
-|---|---|---|---|
-| **`scripts/extract_palette.py`** | Image color quantization, WCAG 2.1 AA contrast check, `brand.json` & `tokens.css` sync | `Pillow` | `palette`, `tokens`, `init`, `clone` |
-| **`scripts/remove_backgrounds.py`** | AI background removal (`rembg`) for transparent PNG logos, product shots, & cutouts | `rembg`, `Pillow` | `init`, `components`, `page`, `retrofit` |
-| **`scripts/optimize_assets.py`** | Resizes heavy assets to design token bounds (heroes max 1200px, cards 400px, logos 240px) | `Pillow` | `deploy`, `audit` |
-| **`scripts/minify_assets.py`** | Bundles & minifies CSS/JS for presentation deployment | Standard Python | `deploy` |
-| **`scripts/inspect_images.py`** | Inspects image dimensions, color channels, and alpha channel status | Standard Python | `audit` |
 
 ---
 

package/references/memory/14-nav-footer-catalog.md

@@ -14,6 +14,37 @@ Reference catalog for Navigation (N1–N9) and Footer (Ft1–Ft8) components.
 - **N8: Vertical Rail** — Fixed left/right navigation rail for web app dashboards.
 - **N9: Fullscreen Overlay** — Trigger button opening full-viewport navigation overlay.
 
+---
+
+## 🏛️ Navigation & Header Design Invariants (Strict Quality Bar)
+
+### 1. Zero Emoji Invariant (`No Emojis in Nav/Menu`)
+- **Prohibition**: Emojis (e.g. 🏠, 📞, 📚, ⚡) are strictly prohibited in navigation links, headers, submenus, and action controls. Emojis represent an amateur AI-slop anti-pattern.
+- **Enforcement**: Use lightweight inline SVG vector icons or ultra-lightweight linear icon sets (Lucide, Feather, Heroicons with 1.5–2px stroke) styled dynamically via `currentColor` or brand tokens.
+
+### 2. Single-Line Discipline (`white-space: nowrap; flex-wrap: nowrap;`)
+- **One-Line Invariant**: Navigation items must strictly fit in a single horizontal row on desktop viewports. Multi-line navigation wrapping is unacceptable.
+- **Label Conciseness**: Labels must be 1 to 2 words maximum (e.g. `الرئيسية`, `المسيرة`, `المؤلفات`, `المبادرات`, `حاسبة الأسعار`).
+- **Stacked Sub-descriptor Option**: If descriptive context is needed, stack a micro-caption (`font-size: 0.7rem`) vertically under the primary title within the link container, preserving compact horizontal width.
+- **SEO vs Navigation Separation**: Full explanatory copy and SEO keywords belong in page body content and schema markup—navigation is dedicated exclusively to rapid, intuitive orientation.
+
+### 3. Submenu & Mega Menu Fallback Protocol
+- If a project requires more than 5–6 primary destinations, do NOT crowd the header bar.
+- **Mandatory Escalation**: Group links into structured **Submenus (Dropdowns)** or an architectural **Mega Menu** with frosted glass backdrops, golden borders, and categorical grouping.
+
+### 4. Mobile-First Navigation & Drawer Architecture (Must Rules)
+- **Automatic Viewport Folding**: On screens `< 1024px` or `< 768px`, desktop navigation links must seamlessly fold into a slide-out drawer (`.mobile-drawer`) or bottom sheet.
+- **Touch Target Integrity**: Minimum 44×44px hit areas for all hamburger triggers, menu links, and controls (WCAG 2.5.5).
+- **Body Scroll Lock**: Automatically lock document scrolling when the mobile drawer is active (`body.menu-open { overflow: hidden; }`).
+- **Zero Horizontal Overflow**: No absolute badge or floating frame element may cause horizontal scrolling on mobile viewports (`overflow-x: clip / hidden; width: 100vw;`).
+- **Compact Sticky Height**: Mobile header height capped at 52–62px with logo/brand text truncation protection (`text-overflow: ellipsis; white-space: nowrap;`).
+
+### 5. Header Action Controls Cap (Max 3 Controls)
+- Header action clusters must not exceed **3 controls maximum** (e.g. Primary CTA + Language Switcher + Theme Toggle).
+- All action controls must share geometric harmony (coordinated pill radii, consistent padding, and unified border treatment).
+
+---
+
 ## Footer Archetypes
 
 - **Ft1: Mast-Headed** — Giant brand wordmark overlaying top of footer section with multi-column links below.

package/references/memory/19-heritage-lanes-atmosphere.md

@@ -0,0 +1,95 @@
+# 19 · Egyptian & Regional Heritage Lanes (Atmosphere & Texture)
+<!-- last-verified: 2026-09-01 -->
+
+Complete operational grammar, palettes, atmospheric textures, and anti-patterns for Egyptian and Regional Heritage Design.
+
+---
+
+## 🏛️ 1. Nilotic Wadj & Sacred Lotus (أصالة النيل ولوتس مصر العليا)
+* **Cultural DNA**: Upper Egyptian heritage (Qena, Thebes, Dendera, Aswan), the Sacred Lotus (`Sesen`) representing awareness & resilience, and the sacred mineral green (`Wadj`) representing flourishing & wisdom.
+* **Palette**:
+  - `primary`: `#135E4E` (Wadj Emerald)
+  - `lotus-green`: `#24826D` (Flora Leaf)
+  - `terracotta`: `#B34A26` (Nile Silt Clay)
+  - `khesbed`: `#0E3C66` (Royal Lapis Lazuli)
+  - `nebu-gold`: `#C98818` (Sun Gold)
+  - `papyrus-bg`: `#FAF8F2` (Sacred Papyrus)
+* **Atmosphere & Texture**:
+  - Fine Papyrus grain overlay (`feTurbulence` with 0.035 opacity).
+  - Continuous Full-Width Frieze Ribbon (`.lotus-frieze-fullwidth` with SVG `<pattern>` repeat).
+  - 4-Corner Lotus Filigree Brackets (`.corner-bracket`) framing key academic and authority portraits.
+  - Shallow stone relief deboss on cards (`Low-Relief`).
+  - Warm sunlit alabaster ambient glow.
+* **Anti-Patterns**:
+  - Never use stock pyramids, pharaonic tourist masks, or fake pseudo-hieroglyphs.
+  - Never create segmented image dividers that break or produce seams on wide viewports (always use SVG `<pattern>`).
+
+---
+
+## 🏛️ 2. Egyptian Nubian Folk & Earth Vaults (النوبة المصرية والعمارة الطينية)
+* **Cultural DNA**: Aswan & West Suhail mud-brick vaulted architecture (Hassan Fathy tradition), geometric chevron/zigzag murals, and radiant folk warmth.
+* **Palette**:
+  - `sun-ochre`: `#F59E0B`
+  - `aswan-turquoise`: `#0284C7`
+  - `nubian-clay`: `#C2410C`
+  - `nile-green`: `#10B981`
+  - `lime-plaster`: `#FFFFFF`
+  - `cataract-indigo`: `#0C2340`
+* **Atmosphere & Texture**:
+  - Stepped triangles and chevron band dividers.
+  - Soft vaulted card headers (`border-top-left-radius: 28px; border-top-right-radius: 28px;`).
+  - Crisp lime plaster backgrounds with restrained vibrant accents.
+* **Anti-Patterns**:
+  - Never scatter colors uncontrollably; maintain crisp white/lime grounds with disciplined geometric borders.
+
+---
+
+## 🏛️ 3. Sinai Bedouin & Stitched Craft (البادية والتطريز السيناوي المصري)
+* **Cultural DNA**: Authentic Sinai Bedouin cross-stitch embroidery (North & South Sinai), St. Catherine granite peaks, desert flora, and hospitality.
+* **Palette**:
+  - `sinai-madder`: `#B91C1C`
+  - `wild-rose`: `#BE185D`
+  - `sinai-night`: `#0F172A`
+  - `wadi-ochre`: `#D97706`
+  - `raw-wool`: `#F8F6F0`
+  - `antique-silver`: `#94A3B8`
+* **Atmosphere & Texture**:
+  - Pixelated cross-stitch geometric borders (2px step grids).
+  - Embroidered rail lines under section headings.
+  - Granite stone texture and deep twilight indigo contrast.
+* **Anti-Patterns**:
+  - Never place busy embroidery behind long body text; preserve high-contrast reading.
+
+---
+
+## 🏛️ 4. Al-Muqarnas & Girih Geometry (التوريق والمقرنصات الهندسية)
+* **Cultural DNA**: Historic Cairo (Fatimid & Mamluk architecture), Andalusian zellij, mashrabiya woodwork, and Islamic mathematical astronomy.
+* **Palette**:
+  - `cobalt-lapis`: `#0E3A60`
+  - `turquoise-glaze`: `#0284A5`
+  - `antique-gold`: `#C4922A`
+  - `stucco-white`: `#F9F8F5`
+  - `mashrabiya-walnut`: `#20150E`
+* **Atmosphere & Texture**:
+  - Strict 4/6/8-fold geometric repeat networks.
+  - Aperture card masks and perforated shadow layers (`box-shadow` depth mimicking light through mashrabiya).
+* **Anti-Patterns**:
+  - Never place sacred or Quranic text on interactive, clickable, or croppable UI.
+  - Never force arbitrary horseshoe arches on every element.
+
+---
+
+## 🏛️ 5. Kufic Modernity & Luminescent Noor (العمارة الحروفية والنور المعاصر)
+* **Cultural DNA**: Sovereign Arabic minimalism, monumental contemporary Kufic letterforms, spacious architecture, and luminous daylight.
+* **Palette**:
+  - `modern-charcoal`: `#111827`
+  - `pure-alabaster`: `#FFFFFF`
+  - `limestone-grey`: `#E5E7EB`
+  - `brushed-bronze`: `#9A7B56`
+  - `single-accent`: Brand-specific vibrant hue (Electric Cyan / Mineral Teal)
+* **Atmosphere & Texture**:
+  - Monumental typographic heroes (45-70% viewport scale).
+  - Honed terrazzo, brushed bronze, and limestone materials.
+* **Anti-Patterns**:
+  - Never resort to tacky "gold on black" luxury clichés.
+  - Never squeeze Arabic letter tracking negatively.

package/references/memory/20-brain-baas-integration.md

@@ -0,0 +1,96 @@
+<!-- last-verified: 2026-09-02 -->
+# Brain MCP & Sovereign BaaS Integration Contract
+
+Authoritative operational specification governing how `tidyfactor-design` integrates with self-hosted `tidyfactor-brain` MCP instances and sovereign BaaS nodes without creating hard dependencies or blocking offline workflows.
+
+---
+
+## 🏛️ 1. Sovereign Architecture Model (Self-Hosted Primacy)
+
+TidyFactor operates on a **Sovereign, Self-Hosted Architecture**:
+- **Zero Centralized SaaS Dependency**: `tidyfactor-brain` and its MCP server run locally on the developer's machine or on an agency's self-hosted server instance (Apache G5 / PHP Flight / SQLite WAL).
+- **Tenant Definition**: In this sovereign architecture, a `tenant` represents an isolated client project / domain workspace (e.g. `tenant_dr_sh`, `tenant_alwkala`) mapped to a dedicated SQLite file (`data/tenants/{tenant_id}_brain.sqlite`) or scoped directory (`~/.gemini/knowledge/projects/{project_id}/`).
+- **No Global Auth Overhead**: Local stdio connections run authentication-free. Self-hosted remote SSE nodes authenticate via static bearer tokens configured in the agency's `mcp_config.json`.
+
+---
+
+## ⚡ 2. The Deterministic Fail-Open Contract
+
+Brain MCP is an **optional acceleration layer**, NEVER a required runtime dependency.
+
+### Strict Resolution Algorithm:
+
+```
+Step 1: Check Local Disk Workspace
+        ├── IF `BRAND-GUIDELINES.md` or `.tidyfactor/design-brief.md` exists:
+        │   └── LOAD directly from disk. Done.
+        └── ELSE: Proceed to Step 2.
+
+Step 2: Check Active MCP Toolset Availability
+        ├── IF tool `search_knowledge_base` is present in agent's active tool list:
+        │   ├── Execute: `search_knowledge_base(query="design tokens", scope="project", project_id=CURRENT_PROJECT)`
+        │   ├── IF valid design KI returned:
+        │   │   └── POPULATE context baseline. Done.
+        │   └── ELSE (Empty/Error):
+        │       └── Silent fallback (0ms delay) to Step 3.
+        └── ELSE (Tool not registered / Standalone environment / Offline):
+            └── Silent fallback (0ms delay) to Step 3.
+
+Step 3: Interactive Micro-Discovery (CDL 3-Question Dialogue)
+        └── Present concise, structured A/B/C/D choices to the user. Done.
+```
+
+### Invariants:
+1. **Zero Connection Attempts**: Skills must NEVER attempt raw HTTP connections or socket calls to non-existent servers. They only query native MCP tools if registered in the active agent session.
+2. **Zero Delay & Zero Noise**: Missing MCP server must NEVER yield warning messages, stack traces, or connection timeouts. The bypass must be instant and silent.
+
+---
+
+## 📦 3. Design System Knowledge Item (KI) Contract
+
+When exporting design baselines via explicit `--sync-brain` flag on `handoff`, the skill formats the deliverable as a structured Atomic KI conforming to the following JSON payload:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "ki_type": "design_system_baseline",
+  "project_id": "current-project-slug",
+  "timestamp": "2026-09-02T05:00:00Z",
+  "tokens": {
+    "css_foundation": "native|tailwind|daisyui|pico|hybrid",
+    "design_school": "neobrutalism|editorial-luxury|swiss-modern|minimal-mono|heritage-egyptian",
+    "palette": {
+      "primary": "#HEX",
+      "secondary": "#HEX",
+      "accent": "#HEX",
+      "surface": "#HEX",
+      "text": "#HEX"
+    },
+    "typography": {
+      "display_heading": "El Messiri",
+      "body_copy": "Tajawal",
+      "font_family_latin": "Inter"
+    },
+    "layout_archetype": "hero-split-canvas|editorial-asymmetric|command-center-grid"
+  },
+  "artifacts": [
+    "design-system/tokens.css",
+    "design-system/base.css",
+    "brand.json"
+  ]
+}
+```
+
+---
+
+## 🛠️ 4. Tooling Execution Bridge (`run_skill_tool`)
+
+When `tidyfactor-brain` executes `tidyfactor-design` scripts via `manifest.json`:
+
+| Tool Name | Script Entrypoint | Latency Class | Execution Mode |
+|---|---|---|---|
+| `audit_design` | `scripts/audit_design.py` | Sub-second (<100ms) | Direct CLI / In-memory AST |
+| `extract_palette` | `scripts/extract_palette.py` | Sub-second (<150ms) | WCAG Color Math Engine |
+| `optimize_media` | `scripts/optimize_assets.py` | Async Batch (2–8s) | `isolation_recommended: true` (rembg/onnx) |
+
+---

package/references/schemas/audit_design.output.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tidyfactor.dev/schemas/audit_design.output.schema.json",
+  "title": "Audit Design Output Schema",
+  "type": "object",
+  "required": ["status", "critique_stamp", "scores", "violations", "stats"],
+  "properties": {
+    "status": { "type": "string", "enum": ["PASS", "FAIL", "WARNING"] },
+    "critique_stamp": { "type": "string", "description": "e.g. /* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */" },
+    "scores": {
+      "type": "object",
+      "properties": {
+        "P": { "type": "integer" },
+        "H": { "type": "integer" },
+        "E": { "type": "integer" },
+        "S": { "type": "integer" },
+        "R": { "type": "integer" },
+        "V": { "type": "integer" },
+        "D": { "type": "integer" }
+      }
+    },
+    "violations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severity", "rule", "message", "file"],
+        "properties": {
+          "severity": { "type": "string", "enum": ["ERROR", "WARNING", "INFO"] },
+          "rule": { "type": "string" },
+          "file": { "type": "string" },
+          "line": { "type": "integer" },
+          "snippet": { "type": "string" },
+          "message": { "type": "string" }
+        }
+      }
+    },
+    "stats": {
+      "type": "object",
+      "properties": {
+        "emojis_count": { "type": "integer" },
+        "inline_styles_count": { "type": "integer" },
+        "untokenized_colors_count": { "type": "integer" },
+        "total_files_audited": { "type": "integer" }
+      }
+    }
+  }
+}

package/references/workflows/brief.md

@@ -6,20 +6,26 @@ Discovers and records core design system baselines (Foundation, School, Typograp
 
 ## Steps
 
-1. **Check Existing State**:
-   - Inspect `brand.json` and `.tidyfactor/design-brief.md` for existing tokens and school choices.
-
-2. **Conduct Structured Discovery (Max 3 Questions)**:
-   - If not specified, ask:
-     1. **CSS Foundation (D1)**: Native CSS, Tailwind, or DaisyUI?
-     2. **Design School (D2)**: Swiss Clean, Neo-Brutalist, Luxury Glassmorphic, or Warm Editorial?
-     3. **Layout Archetype (D4)**: L1 Landing Story, L2 Split Screen, or L3 Dashboard?
-
-3. **Record Decisions**:
-   - Save `.tidyfactor/design-brief.md` with confirmed parameters.
-
-4. **Report Summary**:
-   - Confirm baseline parameters and prompt user to invoke `/init` or `/components`.
+1. **Check Existing State (Local Auto-Sensing First)**:
+   - Scan workspace for `BRAND-GUIDELINES.md`, `brand.json`, and `.tidyfactor/design-brief.md`.
+   - If present, immediately extract tokens, typography, and palette baselines without prompting.
+
+2. **Check Active MCP Acceleration (Fail-Open Fallback)**:
+   - If local files do not exist AND `search_knowledge_base` is available in active agent tools:
+     Query `search_knowledge_base(query="design tokens", scope="project")` for existing project baselines.
+   - If MCP is unavailable, empty, or returns error: Silently proceed to Step 3 with 0ms delay.
+
+3. **Conduct Structured Discovery (Max 3 Questions)**:
+   - If parameters remain unresolved, present at most 3 concise multiple-choice options:
+     1. **CSS Foundation (D1)**: (A) Native CSS (Default), (B) Tailwind CSS, (C) daisyUI, (D) Pico CSS.
+     2. **Design School (D2)**: (A) Swiss Modern, (B) Neo-Brutalism, (C) Editorial Luxury, (D) Egyptian / Regional Heritage.
+     3. **Layout Archetype (D4)**: (A) Split Hero Canvas, (B) Narrative Editorial, (C) Command Dashboard.
+
+4. **Record Decisions**:
+   - Persist confirmed parameters into `.tidyfactor/design-brief.md`.
+
+5. **Report Summary**:
+   - Present a concise baseline summary and suggest next action (`/init`, `/tokens`, `/components`).
 
 ---
 

package/scripts/audit_design.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+TidyFactor Design Track — Automated Design & Quality Bar Auditor (scripts/audit_design.py)
+Scans HTML and CSS files for emoji usage, inline styles, untokenized colors, and the 16 AI anti-patterns.
+Conforms to: references/schemas/audit_design.output.schema.json
+"""
+
+import sys
+import os
+import re
+import json
+import argparse
+from pathlib import Path
+
+# Ensure UTF-8 output across Windows, Unix, and Mac
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+# Common emoji unicode ranges
+EMOJI_REGEX = re.compile(
+    r'[\U0001F600-\U0001F64F]'  # emoticons
+    r'|[\U0001F300-\U0001F5FF]'  # symbols & pictographs
+    r'|[\U0001F680-\U0001F6FF]'  # transport & map
+    r'|[\U0001F1E0-\U0001F1FF]'  # flags (iOS)
+    r'|[\U00002702-\U000027B0]'  # dingbats
+    r'|[\U000024C2-\U0001F251]'  # enclosed chars
+    r'|[\U0001F900-\U0001F9FF]'  # supplemental symbols
+    r'|[\U0001FA70-\U0001FAFF]'  # symbols and pictographs extended
+    r'|[\u2600-\u26FF]'          # misc symbols (moon, sun, star, etc.)
+)
+
+INLINE_STYLE_REGEX = re.compile(r'\bstyle\s*=\s*["\']([^"\']+)["\']', re.IGNORECASE)
+PRE_EMIT_STAMP_REGEX = re.compile(r'/\*\s*Pre-emit critique:\s*P([1-5])\s+H([1-5])\s+E([1-5])\s+S([1-5])\s+R([1-5])\s+V([1-5])(?:\s+D([1-5]))?\s*\*/')
+
+def audit_directory(target_path: Path, auto_fix: bool = False):
+    violations = []
+    stats = {
+        "emojis_count": 0,
+        "inline_styles_count": 0,
+        "untokenized_colors_count": 0,
+        "total_files_audited": 0
+    }
+
+    scores = {"P": 5, "H": 5, "E": 5, "S": 5, "R": 5, "V": 5, "D": 5}
+    critique_stamp = None
+
+    if not target_path.exists():
+        return {
+            "status": "FAIL",
+            "critique_stamp": "/* Pre-emit critique: P1 H1 E1 S1 R1 V1 D1 */",
+            "scores": {"P": 1, "H": 1, "E": 1, "S": 1, "R": 1, "V": 1, "D": 1},
+            "violations": [{
+                "severity": "ERROR",
+                "rule": "target-path-exists",
+                "file": str(target_path),
+                "line": 0,
+                "snippet": "",
+                "message": f"Target path does not exist: {target_path}"
+            }],
+            "stats": stats
+        }
+
+    # Gather HTML and CSS files
+    html_files = list(target_path.glob("*.html")) + list(target_path.glob("**/*.html"))
+    css_files = list(target_path.glob("design-system/*.css")) + list(target_path.glob("*.css"))
+    
+    # Filter out node_modules, .git, etc.
+    def is_valid_file(p: Path):
+        parts = p.parts
+        return not any(ignored in parts for ignored in [".git", "node_modules", "dist", ".gemini", "__pycache__"])
+
+    all_files = [f for f in set(html_files + css_files) if is_valid_file(f)]
+    stats["total_files_audited"] = len(all_files)
+
+    for file_path in all_files:
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="replace")
+            lines = content.splitlines()
+            rel_file = str(file_path.relative_to(target_path)) if target_path != file_path else file_path.name
+
+            # Check pre-emit stamp
+            stamp_match = PRE_EMIT_STAMP_REGEX.search(content)
+            if stamp_match and not critique_stamp:
+                critique_stamp = stamp_match.group(0)
+                scores["P"] = int(stamp_match.group(1))
+                scores["H"] = int(stamp_match.group(2))
+                scores["E"] = int(stamp_match.group(3))
+                scores["S"] = int(stamp_match.group(4))
+                scores["R"] = int(stamp_match.group(5))
+                scores["V"] = int(stamp_match.group(6))
+                if stamp_match.group(7):
+                    scores["D"] = int(stamp_match.group(7))
+
+            for idx, line in enumerate(lines, start=1):
+                # 1. Check for Emojis
+                emoji_matches = EMOJI_REGEX.findall(line)
+                if emoji_matches:
+                    stats["emojis_count"] += len(emoji_matches)
+                    violations.append({
+                        "severity": "ERROR",
+                        "rule": "anti-pattern-no-emoji",
+                        "file": rel_file,
+                        "line": idx,
+                        "snippet": line.strip()[:80],
+                        "message": f"Unacceptable emoji detected: {', '.join(emoji_matches)}. Replace with inline SVG icons."
+                    })
+                    scores["E"] = min(scores["E"], 3)
+                    scores["R"] = min(scores["R"], 3)
+
+                # 2. Check for Inline Styles in HTML
+                if file_path.suffix.lower() == ".html":
+                    inline_match = INLINE_STYLE_REGEX.search(line)
+                    if inline_match:
+                        stats["inline_styles_count"] += 1
+                        violations.append({
+                            "severity": "ERROR",
+                            "rule": "zero-inline-styles",
+                            "file": rel_file,
+                            "line": idx,
+                            "snippet": line.strip()[:80],
+                            "message": f"Inline style detected: 'style=\"{inline_match.group(1)[:40]}\"'. Move all styles to design-system/."
+                        })
+                        scores["E"] = min(scores["E"], 2)
+
+                # 3. Check for Anti-Pattern: Background Clip Text Gradient
+                if "background-clip: text" in line or "-webkit-background-clip: text" in line:
+                    violations.append({
+                        "severity": "WARNING",
+                        "rule": "anti-pattern-gradient-headline",
+                        "file": rel_file,
+                        "line": idx,
+                        "snippet": line.strip()[:80],
+                        "message": "Gradient headline anti-pattern detected (background-clip: text). Use solid typography."
+                    })
+                    scores["R"] = min(scores["R"], 4)
+
+                # 4. Check for Lazy-loaded LCP Hero image
+                if file_path.suffix.lower() == ".html" and "hero" in line.lower() and 'loading="lazy"' in line:
+                    violations.append({
+                        "severity": "WARNING",
+                        "rule": "anti-pattern-lazy-lcp",
+                        "file": rel_file,
+                        "line": idx,
+                        "snippet": line.strip()[:80],
+                        "message": "Lazy loading applied to hero element. Remove loading='lazy' for LCP asset."
+                    })
+
+        except Exception as e:
+            violations.append({
+                "severity": "WARNING",
+                "rule": "file-read-error",
+                "file": str(file_path),
+                "line": 0,
+                "snippet": "",
+                "message": f"Could not read file: {str(e)}"
+            })
+
+    # If no stamp was found in any file, flag missing critique stamp
+    if not critique_stamp:
+        violations.append({
+            "severity": "WARNING",
+            "rule": "pre-emit-critique-stamp-missing",
+            "file": "design-system/tokens.css",
+            "line": 1,
+            "snippet": "",
+            "message": "Missing required Pre-emit critique header comment: /* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */"
+        })
+        critique_stamp = "/* Pre-emit critique: P4 H4 E4 S4 R4 V4 D4 */"
+
+    # Determine overall status
+    has_errors = any(v["severity"] == "ERROR" for v in violations)
+    has_warnings = any(v["severity"] == "WARNING" for v in violations)
+    status = "FAIL" if has_errors else ("WARNING" if has_warnings else "PASS")
+
+    return {
+        "status": status,
+        "critique_stamp": critique_stamp,
+        "scores": scores,
+        "violations": violations,
+        "stats": stats
+    }
+
+def main():
+    parser = argparse.ArgumentParser(description="TidyFactor Design Quality Bar & Anti-Pattern Auditor")
+    parser.add_argument("--target", "-t", type=str, default=".", help="Target project directory to audit")
+    parser.add_argument("--fix", action="store_true", help="Automatically fix simple violations where safe")
+    parser.add_argument("--json", action="store_true", default=True, help="Output formatted JSON to stdout")
+    parser.add_argument("--pretty", action="store_true", help="Pretty print JSON output")
+    
+    args = parser.parse_args()
+    target_path = Path(args.target).resolve()
+
+    result = audit_directory(target_path, auto_fix=args.fix)
+
+    # Always output JSON to stdout as per Manifest contract
+    indent = 2 if args.pretty or not sys.stdout.isatty() else None
+    print(json.dumps(result, indent=indent, ensure_ascii=False))
+
+    # Exit code: 1 if FAIL, 0 otherwise
+    sys.exit(1 if result["status"] == "FAIL" else 0)
+
+if __name__ == "__main__":
+    main()