@tidyfactor/design 1.5.0

package/references/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/references/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/references/memory/architecture.md

@@ -0,0 +1,39 @@
+# Memory: architecture (Design System & Prototype Macrostructure)
+
+Defines the zero-build design system file tree, component encapsulation, and 7 lifecycle stages.
+
+---
+
+## 📁 Standard Prototype Directory Layout
+
+```
+project-root/
+├── brand.json                    # Single source of truth for design tokens & identity
+├── design-system/
+│   ├── tokens.css                # CSS Custom Properties (Colors, Radii, Shadows, Typography)
+│   ├── base.css                  # Reset, font imports, and typography scale
+│   ├── components/               # Pure reusable component wrappers (zero page styling)
+│   │   ├── buttons.css
+│   │   ├── cards.css
+│   │   ├── navigation.css
+│   │   ├── forms.css
+│   │   └── modals.css
+│   └── motion.css                # Easing curves, transitions, reduced-motion rules
+├── pages/                        # Individual HTML pages (markup only, loads design-system/)
+│   ├── index.html
+│   ├── dashboard.html
+│   └── settings.html
+└── assets/                       # Compressed SVGs, WebP icons, and optimized imagery
+```
+
+---
+
+## 🏛️ 7 Lifecycle Stages
+
+1. **Discovery**: Reference study, mood extraction, and 3-question CDL brief resolution.
+2. **Foundation**: CSS foundation locking, brand tokens, typography pairing, palette calibration.
+3. **Architecture**: Layout archetypes (L1–L4), navigation (N1–N9), footer (Ft1–Ft8) catalog.
+4. **Components**: 8-state wrappers (Default, Hover, Active, Focus, Disabled, Loading, Error, Success).
+5. **Motion**: Kinetic principles, transition choreography, and reduced-motion fallback.
+6. **Quality**: 7-axis pre-emit self-critique, anti-slop checks, and token drift audits.
+7. **Delivery**: Developer handoff specs, Figma token exports, and static deployment.

package/references/memory/decision-points.md

@@ -0,0 +1,50 @@
+# Memory: decision-points (Contextual Decision Layer — CDL v1.0)
+
+A thin arbitration protocol for resolving high-impact design system foundations and aesthetic school ambiguities before code emission.
+
+---
+
+## 🏛️ Decision Matrix (D1–D5)
+
+| Code | Decision Dimension | Options (Reference SSOT) | Default Fallback | Trigger / Ambiguity Condition |
+|:---:|---|---|---|---|
+| **D1** | **CSS Foundation Layer** | • `native` (Zero-dep vanilla CSS tokens)<br>• `tailwind` (Utility-first CDN/configured)<br>• `daisyui` (Tailwind semantic component classes)<br>• `pico` (Semantic HTML micro-framework)<br>• `hybrid` (Design tokens + utility classes) | `native` | When prompt asks to build a UI prototype without declaring the CSS engine. |
+| **D2** | **Design System School** | • `swiss-international` (Clean, grid-disciplined, high whitespace)<br>• `neo-brutalist` (High contrast, bold borders, sharp shadows)<br>• `luxury-glassmorphic` (Deep dark obsidian, gold/cyan glows, frosted glass)<br>• `warm-editorial` (Serif elegance, earth tones, literary rhythm) | `swiss-international` | When request lacks specific visual styling directions. |
+| **D3** | **Arabic Typography Pairing** | • `classic-display` (El Messiri + Tajawal)<br>• `modern-geometric` (Alexandria + Readex Pro)<br>• `contemporary-tech` (Cairo + IBM Plex Sans Arabic) | `classic-display` | When targeting bilingual or Arabic-first interfaces. |
+| **D4** | **Layout Archetype** | • `L1` (Fullbleed Hero + Story Flow)<br>• `L2` (Split Screen App Walkthrough)<br>• `L3` (Sidebar Dashboard + Metrics Grid)<br>• `L4` (Multi-Column Magazine / Portal) | `L1` (Landing) / `L3` (App) | When building pages or app screens. |
+| **D5** | **Output Scope & Depth** | • `single-screen` (Single interactive HTML prototype)<br>• `complete-design-system` (`design-system/` + multi-page prototype suite) | `single-screen` | When request could mean a quick mock or full design kit. |
+
+---
+
+## ⚡ Boolean Skip Conditions (Deterministic Bypass)
+
+Skip interactive elicitation and proceed silently when ANY of the following are true:
+1. **Cached Brief Exists**: `.tidyfactor/design-brief.md` or root `brand.json` exists.
+2. **Explicit User Declaration**: Prompt explicitly declares foundation and school (e.g. `"Build a neo-brutalist dashboard with Tailwind"`).
+3. **Direct Command Invocation**: User invokes explicit foundation commands (`/tokens`, `/school`, `/typography`, `/layout`).
+4. **Maintenance / Audit Task**: Auditing (`/audit`), performance profiling (`/perf`), or CSS retrofit (`/retrofit`) silently preserves existing design system.
+
+---
+
+## 🎯 Single-Round Batching & Priority Overflow
+
+When elicitation is required:
+1. **Max 3 Questions**: Ask at most 3 concise questions in a single round.
+2. **Priority Order**:
+   $$\mathbf{D1 \text{ (Foundation)}} > \mathbf{D2 \text{ (School)}} > \mathbf{D3 \text{ (Typography)}} > \mathbf{D4 \text{ (Layout)}} > \mathbf{D5 \text{ (Scope)}}$$
+3. **Conservative Default**: Any unasked or unanswered dimensions automatically adopt the **Default Fallback**.
+
+---
+
+## 💾 Brief Persistence Protocol
+
+When `/brief` runs, save confirmed decisions to `.tidyfactor/design-brief.md`:
+```markdown
+# Design System Brief
+- Foundation: [native | tailwind | daisyui | pico | hybrid]
+- Design School: [swiss-international | neo-brutalist | luxury-glassmorphic | warm-editorial]
+- Typography Pairing: [classic-display | modern-geometric | contemporary-tech]
+- Layout Archetype: [L1 | L2 | L3 | L4]
+- Output Scope: [single-screen | complete-design-system]
+- Confirmed At: YYYY-MM-DD
+```

package/references/memory/foundations.md

@@ -0,0 +1,15 @@
+# Memory: foundations (Pluggable CSS Foundations Catalog)
+
+Operational rules and tokens for each pluggable CSS foundation layer.
+
+---
+
+## 🛠️ Supported CSS Foundations
+
+| Foundation | Engine | Deliverable Shape | CDN / Runtime |
+|---|---|---|---|
+| `native` | Vanilla CSS | Custom properties in `design-system/tokens.css` + zero dependency reset | None (Pure CSS) |
+| `tailwind` | Utility-First | Configured via `tailwind.config.js` or Tailwind CDN script | `https://cdn.tailwindcss.com` |
+| `daisyui` | Semantic Components | Tailwind + DaisyUI component classes | Tailwind CDN + DaisyUI plugin |
+| `pico` | Semantic Micro-CSS | Pure HTML semantic tags styled via Pico CSS | `https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css` |
+| `hybrid` | Tokens + Utilities | Shared custom properties with micro-utility helpers | Custom bundle |

package/references/memory/quality-bar.md

@@ -0,0 +1,20 @@
+# Memory: quality-bar (Anti-Slop & Design Quality Gate)
+
+Enforces uncompromising design rigor, zero per-page CSS/JS, and token consistency.
+
+---
+
+## 🛡️ 7-Axis Pre-Emit Self-Critique Stamp
+
+Every generated prototype component, token set, or layout must be stamped:
+`/* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */`
+
+| Axis | Dimension | Score 1 (Slop / Reject) | Score 5 (Production Pass) |
+|:---:|---|---|---|
+| **P** | **Philosophy & School Authenticity** | Generic Bootstrap look; inconsistent corner radii and shadows. | Pure school adherence (Swiss, Neo-Brutalist, Luxury, Editorial). |
+| **H** | **Hierarchy & Layout Balance** | Crowded sections; poor whitespace ratio; no clear visual anchor. | Archetype-aligned macrostructure (L1–L4); strong focal hierarchy. |
+| **E** | **Encapsulation & Architecture** | Inline styles on elements (`style="..."`); per-page CSS files. | 100% tokens in `design-system/`; clean semantic HTML pages. |
+| **S** | **State Completeness** | Missing hover, focus, disabled, or loading states on inputs/buttons. | Complete 8-state wrappers across all interactive components. |
+| **R** | **RTL & Typography Rigor** | Broken flow on `dir="rtl"`; Amiri used on giant display headlines. | Curated Arabic typography (El Messiri display, Tajawal body); full RTL. |
+| **V** | **Velocity & Motion Polish** | Janky transitions; missing `prefers-reduced-motion` fallbacks. | Sub-200ms cubic-bezier easing curves; accessible reduced-motion rules. |
+| **D** | **Decision Alignment** | Inconsistent foundation; arbitrary colors ignoring `brand.json`. | 100% synchronized with `.tidyfactor/design-brief.md` and `brand.json`. |

package/references/tidyfactor-vision.md

@@ -0,0 +1,66 @@
+# TidyFactor — Shared Philosophy (all tracks)
+
+Condensed from the ecosystem VISION.md. Every TidyFactor skill — this one
+included — should be judged against this before adding any feature.
+
+## Design tenets
+- Simple before clever.
+- Explicit before implicit.
+- Structured before generated.
+- Portable before proprietary.
+- Content before presentation.
+- Standards before conventions.
+- Small before bloated.
+- AI-native before AI-powered.
+
+## The TidyFactor Test
+- Is it simpler? Is it more maintainable?
+- Does it improve interoperability? Does it reduce lock-in?
+- Is it AI-native (structured, machine-readable, portable)?
+- Can it survive future technology changes?
+- Would we still choose this approach five years from now?
+
+## Standalone by design — why that's not a contradiction
+
+Every other TidyFactor track shares infrastructure with its siblings
+(`tidyfactor-php-micro` and `tidyfactor-htmx` compose; `tidyfactor-html`'s
+componentization methods echo across tracks). `tidyfactor-design` is
+deliberately different: it shares the **philosophy and command-library
+format** with the family, but calls into no other skill, and no other skill
+calls into it. This is itself an application of "portable before
+proprietary" — a prototyping tool that only works alongside other specific
+skills isn't portable to a designer's actual workflow, which usually starts
+before any stack decision is made.
+
+## What the tenets mean concretely for this track
+
+- **Structured before generated**: `tokens.css` + `brand.json` are the
+  structured source of truth. Every page is a *derivation* of them, never
+  hand-tuned in isolation — this is the mechanism, not just a guideline, per
+  the locked architecture in `SKILL.md`.
+- **Portable before proprietary, applied to CSS foundations**: the choice
+  between Native / Tailwind / daisyUI / Hybrid (`references/foundations/`)
+  is the user's, made once, documented — never silently defaulted. A daisyUI
+  project stays portable because daisyUI itself is MIT-licensed, CDN-only,
+  and framework-agnostic; choosing it isn't lock-in the way a proprietary
+  design tool's file format would be.
+- **Small before bloated**: one `components.css`, one `tokens.css`, one
+  `motion.js` — extending the component set is a confirmed decision routed
+  through the `components` command, not an ad hoc addition wherever a page
+  needed it.
+- **AI-native**: the fixed sequencing (tokens → school → components → pages)
+  means any agent opening this project for the first time already knows the
+  build order, without re-deriving it.
+- **Content before presentation**: copy in every page is real content for
+  that page's job — a prototype with lorem ipsum where real content should
+  be is treated as incomplete, same as a production page would be.
+
+## Relationship to Alwkala
+
+TidyFactor is stewarded by Alwkala (alwkala.com). This track exists because
+Alwkala's own production work (client landing pages, dashboard prototypes,
+bilingual Arabic/English sites) repeatedly needed a fast, consistent,
+code-native prototyping stage before development — `references/commands/i18n.md`
+and `memory/08-arabic-bilingual.md` in particular carry conventions
+(El Messiri/Tajawal, RTL correctness) drawn directly from that production
+experience, not generic defaults.

package/references/workflow.md

@@ -0,0 +1,49 @@
+# TidyFactor Design — Workflow Discipline
+
+Applies underneath every command in `commands/`.
+
+## 1. Audit
+- Check for `design-system/tokens.css` and `components.css` first — their
+  presence/absence and content decide what every later command can safely
+  assume.
+- Check `design-system/brand.json` for a declared `cssFoundation` field
+  (`native` / `tailwind` / `daisyui` / `hybrid`) — if the project has pages
+  already, this MUST already be set; never re-ask, never silently switch it.
+- Scan `pages/*.html` for violations of the locked architecture: inline
+  `<style>`, inline `<script>` logic, or a per-page `.css`/`.js` file. Any
+  hit is the primary finding, ahead of anything else.
+- Report findings and the proposed changes before acting.
+
+## 2. Execute in batches
+- One page, one component addition, or one concern at a time.
+- New component need discovered while building a page → stop, route it
+  through the `components` command, resume the page after.
+- Never touch `tokens.css` and add a new page in the same batch — token
+  changes affect every existing page; verify the token change alone first.
+
+## 3. Verify
+- Serve locally (`python -m http.server 8123` or `npx serve`) and check in a
+  **visible** browser tab.
+- Run the `audit` command's structural check (no page-level CSS/JS) plus the
+  quality-bar checklist (`memory/06-quality-bar.md`) before calling any page
+  "done".
+- Confirm the new/changed page still reads identically in whichever
+  `cssFoundation` the project locked in — no accidental foundation mixing.
+
+## Mode-specific notes
+
+**Init** — Step 0/0b answers replace the audit step. Foundation and school
+choices happen here, once, and are never re-litigated per page.
+
+**Convert (`clone`)** — audit the *reference* (existing site, screenshots)
+for its actual token values (colors, type scale, spacing rhythm) before
+proposing a `tokens.css`. The output is never a scrape or a copy of the
+reference's markup — it's our own token/component system that produces the
+same *impression*, built from `references/commands/clone.md`'s extraction
+method.
+
+**Improve (`retrofit`)** — `audit` is the primary deliverable if the user
+just wants a report. Only unify pages once the user confirms which findings
+to act on. A page with heavy inline styling is not deleted and rebuilt
+blind — its content and layout intent are preserved, only its styling
+mechanism is migrated onto `components.css`.

package/references/workflows/audit-prototype.md

@@ -0,0 +1,26 @@
+# Workflow: audit-prototype
+
+Audits design system consistency, token hygiene, responsive layout behavior, and 8-state completeness.
+
+---
+
+## Steps
+
+1. **Verify Token & Invariant Compliance**:
+   - Check that all elements reference CSS custom properties.
+   - Check that no Amiri headings exceed 24px.
+   - Check that all interactive elements support focus states and reduced motion.
+
+2. **Generate Audit Scorecard**:
+   - Grade prototype against 7-axis quality gate.
+
+3. **Pre-Emit Self-Critique**:
+   - `/* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */`
+
+---
+
+## Validation checklist
+
+- [ ] Complete audit report produced with concrete recommendations.
+- [ ] Token coverage verified across all views.
+- [ ] Pre-emit critique stamp included.

package/references/workflows/brief.md

@@ -0,0 +1,30 @@
+# Workflow: brief
+
+Discovers and records core design system baselines (Foundation, School, Typography, Archetype) using the Contextual Decision Layer (CDL).
+
+---
+
+## 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`.
+
+---
+
+## Validation checklist
+
+- [ ] `.tidyfactor/design-brief.md` exists and contains confirmed values for D1–D5.
+- [ ] No more than 3 questions were asked in a single round.
+- [ ] Design baseline conforms to `references/memory/quality-bar.md`.

package/references/workflows/clone-prototype.md

@@ -0,0 +1,27 @@
+# Workflow: clone-prototype
+
+Extracts design tokens, component styles, and layouts from an existing website or reference asset into the TidyFactor design system structure.
+
+---
+
+## Steps
+
+0. **Step 0: CDL Resolution & Brief Check**:
+   - Confirm extraction target and destination foundation.
+
+1. **Extract Visual DNA**:
+   - Extract primary/secondary colors, font families, base spacing units, and radius scale into `brand.json` and `design-system/tokens.css`.
+
+2. **Reconstruct Components**:
+   - Recreate core UI components (buttons, cards, navigation) as reusable CSS classes.
+
+3. **Pre-Emit Self-Critique**:
+   - `/* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */`
+
+---
+
+## Validation checklist
+
+- [ ] Extracted tokens populated in `brand.json` and `design-system/tokens.css`.
+- [ ] Components follow 8-state model.
+- [ ] Pre-emit critique stamp included.

package/references/workflows/init-prototype.md

@@ -0,0 +1,28 @@
+# Workflow: init-prototype
+
+Scaffolds a brand-new design system and interactive code-native prototype with zero build step.
+
+---
+
+## Steps
+
+0. **Step 0: CDL Resolution & Brief Check**:
+   - Check `.tidyfactor/design-brief.md` and `brand.json`. If missing, apply default `native` foundation and `swiss-international` school.
+
+1. **Scaffold Design System**:
+   - Create `design-system/tokens.css`, `base.css`, `motion.css`, and `components/`.
+
+2. **Assemble Prototype Page**:
+   - Create semantic HTML page (`pages/index.html` or requested view) linking `design-system/`.
+
+3. **Pre-Emit Self-Critique**:
+   - `/* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */`
+
+---
+
+## Validation checklist
+
+- [ ] Zero per-page CSS/JS; all styling lives in `design-system/`.
+- [ ] Single CSS foundation applied consistently.
+- [ ] Interactive component states defined.
+- [ ] Pre-emit critique stamp included.

package/references/workflows/retrofit-prototype.md

@@ -0,0 +1,25 @@
+# Workflow: retrofit-prototype
+
+Unifies a drifted prototype by moving hardcoded inline styles and custom per-page CSS into the centralized design system.
+
+---
+
+## Steps
+
+1. **Scan For Drift**:
+   - Locate inline `style="..."` attributes and one-off CSS classes across HTML files.
+
+2. **Migrate to Design System**:
+   - Replace one-off values with CSS custom properties from `design-system/tokens.css`.
+   - Extract recurring HTML patterns into reusable component classes in `design-system/components/`.
+
+3. **Pre-Emit Self-Critique**:
+   - `/* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */`
+
+---
+
+## Validation checklist
+
+- [ ] All inline styles and ad-hoc rules replaced with design system tokens.
+- [ ] Visual consistency restored across all pages.
+- [ ] Pre-emit critique stamp included.