36 added, 44 removed. Audit B to B.
- # AGENTS.md — TidyFactor Design System & Prototyping Engine
+ # AGENTS.md — TidyFactor Design System & Full UI Design Lifecycle Engine
Build **interactive, code-native HTML/CSS/JS design prototypes** (Figma alternative) with strict structural visual consistency across all pages. Zero per-page CSS/JS, zero inline `<style>` or `<script>` tags, zero build step. Every visual and interaction decision is made once and lives in `design-system/`.
---
- ## ⚡ Skill & Modular Slash Commands
+ ## ⚡ Skill & 24 Modular Slash Commands (7 Lifecycle Stages)
- This project exposes an Agentic Skill under `.agents/skills/tidyfactor-design/SKILL.md` (and `.claude-skill/SKILL.md`). The following 14 modular sub-commands are supported:
+ This project exposes an Agentic Skill under `.agents/skills/tidyfactor-design/SKILL.md` (and `.claude-skill/SKILL.md`). The following 24 slash commands covering all 7 stages of the UI Design Lifecycle are supported:
- | Command | Purpose | Reference Spec |
- |---|---|---|
- | `init` | **Primary deliverable** — scaffold design system, tokens, foundation, base components & initial page | `.agents/skills/tidyfactor-design/references/commands/init.md` |
- | `school` | Select and document design-movement direction (Brutalism, Glassmorphism, Neumorphism, Minimalist, Swiss, Luxury) | `.agents/skills/tidyfactor-design/references/commands/school.md` |
- | `tokens` | Read/scaffold `design-system/tokens.css` & `brand.json` single source of truth | `.agents/skills/tidyfactor-design/references/commands/tokens.md` |
- | `palette` | Extract color palette & WCAG 2.1 AA contrast scores via `extract_palette.py` | `.agents/skills/tidyfactor-design/references/commands/palette.md` |
- | `components` | Build reusable component library in `design-system/components.css` | `.agents/skills/tidyfactor-design/references/commands/components.md` |
- | `page` | Add a new marketing or content page (markup-only, zero page-specific CSS/JS) | `.agents/skills/tidyfactor-design/references/commands/page.md` |
- | `dashboard` | Add a new app or dashboard screen with data surfaces and shell layouts | `.agents/skills/tidyfactor-design/references/commands/dashboard.md` |
- | `motion` | Motion tokens, micro-interactions, scroll-reveals & transition choreography in `motion.js` | `.agents/skills/tidyfactor-design/references/commands/motion.md` |
- | `states` | Define component interactive states (hover, active, focus, disabled, loading, empty, error, success) | `.agents/skills/tidyfactor-design/references/commands/states.md` |
- | `flow` | Wire clickable prototype navigation toolbar (`proto-nav.js`) between screens | `.agents/skills/tidyfactor-design/references/commands/flow.md` |
- | `i18n` | Arabic/English RTL support, modesty rules & identity typography (El Messiri/Tajawal, never Amiri) | `.agents/skills/tidyfactor-design/references/commands/i18n.md` |
- | `audit` | Comprehensive quality-bar & design consistency audit report | `.agents/skills/tidyfactor-design/references/commands/audit.md` |
- | `clone` | Convert mode — extract design tokens & component system from reference site/design | `.agents/skills/tidyfactor-design/references/commands/clone.md` |
- | `retrofit` | Improve mode — unify a drifted multi-page prototype into a single design system | `.agents/skills/tidyfactor-design/references/commands/retrofit.md` |
- | `deploy` | Preview server, static asset packaging & prototype presentation export | `.agents/skills/tidyfactor-design/references/commands/deploy.md` |
+ | Stage | Command | Purpose | Reference Spec |
+ |---|---|---|---|
+ | **1. Discovery** | `study` | Extract Design DNA (colors, typography, macrostructure) from reference URL/image | `.agents/skills/tidyfactor-design/references/commands/study.md` |
+ | **1. Discovery** | `brief` | Establish 3-Question Design Context Brief & Fit Test | `.agents/skills/tidyfactor-design/references/commands/brief.md` |
+ | **2. Foundation** | `init` | **Primary deliverable** — scaffold design system, tokens, foundation, base components & initial page | `.agents/skills/tidyfactor-design/references/commands/init.md` |
+ | **2. Foundation** | `brand` | Scaffold, extract, or migrate `brand.json` v2 schema | `.agents/skills/tidyfactor-design/references/commands/brand.md` |
+ | **2. Foundation** | `typography` | Select mood-routed font pairing (7 Arabic + Latin routes) | `.agents/skills/tidyfactor-design/references/commands/typography.md` |
+ | **2. Foundation** | `school` | Select and document design-movement direction (Minimalist, Brutalism, Glassmorphism, Neumorphism, Swiss, Luxury) | `.agents/skills/tidyfactor-design/references/commands/school.md` |
+ | **2. Foundation** | `tokens` | Read/scaffold `design-system/tokens.css` & `brand.json` single source of truth | `.agents/skills/tidyfactor-design/references/commands/tokens.md` |
+ | **2. Foundation** | `palette` | Extract color palette & WCAG 2.1 AA contrast scores via `extract_palette.py` | `.agents/skills/tidyfactor-design/references/commands/palette.md` |
+ | **2. Foundation** | `assets` | Asset hygiene, web compression & Python image tools | `.agents/skills/tidyfactor-design/references/commands/assets.md` |
+ | **3. Architecture** | `layout` | Select surface layout archetype (`fullbleed`, `editorial`, `spatial`, `interface`, `minimal`, `product`, `store`, `auto`) | `.agents/skills/tidyfactor-design/references/commands/layout.md` |
+ | **3. Architecture** | `nav-footer` | Choose Navigation (N1-N9) and Footer (Ft1-Ft8) archetypes | `.agents/skills/tidyfactor-design/references/commands/nav-footer.md` |
+ | **3. Architecture** | `page` | Add a new marketing or content page (markup-only, zero page-specific CSS/JS) | `.agents/skills/tidyfactor-design/references/commands/page.md` |
+ | **3. Architecture** | `dashboard` | Add a new app or dashboard screen with data surfaces and shell layouts | `.agents/skills/tidyfactor-design/references/commands/dashboard.md` |
+ | **4. Components** | `components` | Build reusable component library in `design-system/components.css` with 8-state wrappers | `.agents/skills/tidyfactor-design/references/commands/components.md` |
+ | **4. Components** | `states` | Define component interactive states (hover, active, focus, disabled, loading, empty, error, success) | `.agents/skills/tidyfactor-design/references/commands/states.md` |
+ | **5. Motion** | `motion` | Motion tokens, micro-interactions, ambient layers, scroll-film & z-stack layers in `motion.js` | `.agents/skills/tidyfactor-design/references/commands/motion.md` |
+ | **5. Motion** | `flow` | Wire clickable prototype navigation toolbar (`proto-nav.js`) between screens | `.agents/skills/tidyfactor-design/references/commands/flow.md` |
+ | **5. Motion** | `i18n` | Arabic/English RTL support, modesty rules & identity typography (El Messiri/Tajawal, never Amiri above 24px) | `.agents/skills/tidyfactor-design/references/commands/i18n.md` |
+ | **6. Quality** | `perf` | Verify numeric asset performance budgets (hero ≤ 400KB, logo ≤ 40KB, fonts ≤ 3 families / 4 weights) | `.agents/skills/tidyfactor-design/references/commands/perf.md` |
+ | **6. Quality** | `audit` | Comprehensive quality-bar & design consistency audit report | `.agents/skills/tidyfactor-design/references/commands/audit.md` |
+ | **6. Quality** | `clone` | Convert mode — extract design tokens & computed styles from reference site | `.agents/skills/tidyfactor-design/references/commands/clone.md` |
+ | **6. Quality** | `retrofit` | Improve mode — unify a drifted multi-page prototype into a single design system | `.agents/skills/tidyfactor-design/references/commands/retrofit.md` |
+ | **7. Delivery** | `handoff` | Export developer handoff specs, token map, and component state matrix | `.agents/skills/tidyfactor-design/references/commands/handoff.md` |
+ | **7. Delivery** | `deploy` | Preview server, static asset packaging & prototype presentation export | `.agents/skills/tidyfactor-design/references/commands/deploy.md` |
---
## Critical Architecture (Non-Negotiable)
1. **Zero Per-Page Styles/Scripts**:
- `pages/<page-name>.html` contains HTML markup ONLY.
- **NEVER** write `<style>` blocks, page-specific `.css` files, or page-specific inline `<script>` logic.
2. **Centralized `design-system/` Directory**:
```
design-system/
tokens.css ← Color, typography, spacing, border-radius, shadows, motion tokens
base.css ← CSS reset, element defaults, typography rules
components.css ← Universal component styles (buttons, cards, badges, navbars, modals)
utilities.css ← Foundation-dependent layout & utility classes
motion.js ← Shared animations, scroll triggers & transition choreography
interactions.js ← Shared component behaviors (dropdowns, tabs, accordions, modals)
+ brand.json ← Identity tokens and brand defaults (v2 schema)
```
3. **Pluggable CSS Foundations** (chosen once per project):
- **Native**: Pure CSS custom properties & semantic component classes (zero dependencies).
- **Tailwind Utility**: Utility-first CSS via CDN.
- **daisyUI**: Tailwind CDN + daisyUI component library themed via tokens.
- **Hybrid**: daisyUI for composite app widgets + Native CSS for signature brand elements.
+ - **shadcn/ui**: Tailwind v4 + Radix UI accessible primitive tokens & components.
+ - **Pico CSS v2**: Semantic classless/lightweight CSS foundation.
+ - **Bootstrap 5.3**: Enterprise-ready CSS custom properties & native dark mode themes.
+ - **Alpine + Tailwind**: Alpine.js micro-interactions + Tailwind v4 utility engine.
4. **Bilingual & Luxury Typography**:
- - Arabic: **El Messiri** (headings) + **Tajawal** (body). **Never Amiri**.
- - Latin: Cormorant Garamond, Oswald, Inter, or Outfit.
+ - Arabic: **El Messiri** (headings) + **Tajawal** (body). **Never Amiri** above 24px.
+ - Latin: Cormorant Garamond, Oswald, Inter, Fraunces, or Outfit.
- RTL native: Always support `dir="rtl"` and logical padding/margins (`margin-inline-start`, etc.).
-
- ---
-
- ## Token Load Routing (Memory Budget Optimization)
-
- | Command | Load ONLY these memory files |
- |---|---|
- | `init` | `memory/01-design-schools.md` + `memory/02-design-tokens.md` + `memory/05-component-anatomy.md` |
- | `school` | `memory/01-design-schools.md` |
- | `tokens` | `memory/02-design-tokens.md` |
- | `palette` | `memory/02-design-tokens.md` + `memory/10-python-tooling.md` |
- | `components` | `memory/05-component-anatomy.md` + `memory/07-consistency-contract.md` |
- | `page` | `memory/03-narrative-conversion.md` + `memory/05-component-anatomy.md` |
- | `dashboard` | `memory/09-prototype-flow.md` + `memory/05-component-anatomy.md` |
- | `motion` | `memory/04-motion-principles.md` |
- | `states` | `memory/05-component-anatomy.md` + `memory/07-consistency-contract.md` |
- | `flow` | `memory/09-prototype-flow.md` |
- | `i18n` | `memory/08-arabic-bilingual.md` |
- | `audit` | `memory/06-quality-bar.md` + `memory/07-consistency-contract.md` + `memory/10-python-tooling.md` |
- | `clone` | `memory/02-design-tokens.md` + `memory/03-narrative-conversion.md` + `memory/10-python-tooling.md` |
- | `retrofit` | `memory/06-quality-bar.md` + `memory/07-consistency-contract.md` |
- | `deploy` | `memory/09-prototype-flow.md` + `memory/10-python-tooling.md` |