@tidyfactor/design 1.5.0

package/references/memory/04-motion-principles.md

@@ -0,0 +1,44 @@
+# Motion Principles — Reference for `motion`
+
+Adapted from the classic animation principles, applied to UI motion rather
+than character animation.
+
+## Staging
+One focal change communicated at a time. A section revealing five cards
+simultaneously reads as noise; the same five staggered by ~60-80ms each
+read as a considered sequence.
+
+## Anticipation
+A small pre-state before a bigger change helps the eye track what's about
+to happen (a button's subtle scale-down before a bigger transition, a
+skeleton before content pops in) — used sparingly, not on every
+interaction.
+
+## Ease-out for entrances, ease-in for exits
+Things entering the screen should decelerate into place (ease-out);
+things leaving should accelerate away (ease-in). Using the same easing
+for both reads as mechanical rather than natural.
+
+## Follow-through / slight overshoot
+A very small overshoot-and-settle on an entrance (a card that slightly
+overshoots its final position before settling) reads as more alive than a
+purely linear arrival — use subtly, it's easy to overdo into "bouncy" and
+undermine a restrained direction like Minimalism or Swiss.
+
+## Secondary motion
+A primary element moving (e.g. a hero image entering) can carry a small,
+delayed secondary motion (a shadow settling a beat later, an accent
+element trailing slightly) — this is what separates "orchestrated" motion
+from "everything moves in lockstep".
+
+## Restraint is a choice, not an absence
+Per `frontend-design`: an orchestrated single moment usually lands harder
+than scattered effects everywhere, and excess ambient animation is one of
+the strongest tells that a design is AI-generated. `school`'s chosen
+direction should determine how much motion is appropriate — Minimalism and
+Swiss call for very little; Modern SaaS and Glassmorphism can carry more.
+
+## Non-negotiable: `prefers-reduced-motion`
+Every entrance/scroll/parallax effect in `motion.js` must check this media
+query and fall back to instant or opacity-only transitions — applied
+globally in the shared file, not per page.

package/references/memory/05-component-anatomy.md

@@ -0,0 +1,34 @@
+# Component Anatomy — Reference for `components`/`states`
+
+## Atomic hierarchy (Atomic Design, adapted)
+- **Atoms** — button, input, label, icon, badge. The smallest named unit;
+  never composed of other named components.
+- **Molecules** — a form field (label + input + error text), a stat
+  (label + value + trend), a nav item (icon + label + active state).
+- **Organisms** — a card, a data table, a navbar, a pricing tile, a modal.
+  Composed from atoms/molecules, still a single reusable named unit.
+- **Templates** (this skill's `page`/`dashboard` output) — organisms
+  arranged into a page's actual layout. This is the one level that's
+  allowed to be page-specific — it's arrangement, not new styling.
+
+A new visual need almost always belongs at the atom/molecule/organism
+level, added once to `components.css`/the foundation library — not
+invented at the template level.
+
+## The full state matrix (apply per interactive component)
+`default → hover → focus-visible → active/pressed → disabled`, plus where
+relevant: `loading`, `empty`, `error`, `success`. A component "supports"
+these states means each has an intentional look, not that the browser
+default happens to apply.
+
+## Naming discipline
+One canonical name per real pattern. A "featured pricing card" and a
+"testimonial card" that share 90% of their structure should be one `.card`
+component with modifiers (`.card--featured`), not two components that will
+quietly diverge over time.
+
+## When something looks like it needs a new component but doesn't
+If the only difference from an existing component is a token value (a
+different accent color, a different size) — that's a modifier class or a
+data attribute, not a new component. New components are for genuinely
+different structure/behavior, not restyled instances.

package/references/memory/06-quality-bar.md

@@ -0,0 +1,83 @@
+# Quality Bar — Auto-Reject Checklist for `audit`
+
+A prototype fails review if any of these are true, regardless of how good individual pages look in isolation.
+
+## Pre-Emit Self-Critique (1–5 Scores on 6 Axes)
+Before handing back any output, score the artifact on 6 axes:
+- **Philosophy (P)**: Opinionated stance vs generic template default.
+- **Hierarchy (H)**: Clear visual weight & focal structure.
+- **Execution (E)**: Clean layout alignment, zero inline overrides, valid tokens.
+- **Specificity (S)**: Customized specifically to the subject's world/materials.
+- **Restraint (R)**: Zero clutter, excess gradients, or fake cards.
+- **Variety (V)**: Non-repetitive section rhythm across project pages.
+
+*Any score < 3 triggers an automatic revision pass. Output must be stamped:*
+`/* Pre-emit critique: P5 H4 E5 S4 R5 V5 */`
+
+## Compositing & Blend Rules
+- **The Blend Trap**: `mix-blend-mode` (multiply or screen) breaks on any element transformed by GSAP or CSS 3D transforms, creating a visible light/dark rectangle. Use background-removed transparent PNG cutouts (`rembg` + `Pillow`) for animated hero assets. Reserve `mix-blend-mode` strictly for static, untransformed imagery.
+
+
+## Structural (highest severity — breaks the skill's core promise)
+- **Anti-Design-Soup Violation**: Combining more than 1 Primary School, 1 Secondary Influence, 1 Motion Language, 1 Storytelling Style, or 1 UX Philosophy on a single page (unless explicitly requested).
+- Any page has an inline `<style>` block or `style="..."` attribute.
+- Any page has a `<script>` block that isn't `src`-linked to a shared `design-system/*` file.
+- A value (color, font-size, spacing, radius, shadow) appears as a literal in any page without tracing to a token.
+- Two pages render visually different versions of "the same" component (drift), or two components that are 90%+ identical exist under different names (near-duplicate).
+
+## The 16 Named AI Anti-Pattern Tells (Auto-Reject)
+1. **Purple-Gradient Hero**: Purple-to-pink/blue background gradient with white centered text.
+2. **Inter-Everywhere**: Single unpaired font family used across display and body.
+3. **3-Column Feature Grid**: 3 equal columns with icon above 2-line heading above 3-line body.
+4. **Card-in-Card**: Nested container cards with no semantic structural reason.
+5. **Gradient Headline**: `background-clip: text` linear gradient fill on headlines.
+6. **Side-Stripe Card**: 4–6px thick colored border on left edge of card.
+7. **Full-Viewport Centered Hero**: `min-height: 100vh` centered short sentence + big CTA.
+8. **Pure Black / Pure White**: Pure `#000000` or `#ffffff` flat surfaces (must use tinted neutrals).
+9. **Default-Attractor Sameness**: Reusing the same macrostructure on consecutive project pages.
+10. **Specimen Fall-Through**: Defaulting to editorial `01 - HELLO` specimen layout for SaaS/B2B.
+11. **The AI Nav**: Wordmark left, 4-5 links center, CTA right, 1px bottom border.
+12. **The AI Footer**: 4 columns (Product, Company, Resources, Legal) + social row + copyright line.
+13. **Aurora-Blob Background**: Flowing organic mesh blobs in purple/cyan behind hero text.
+14. **Floating-Orb Decoration**: 3D spheres or blurred circles drifting behind hero.
+15. **Italic Headers**: Flipping one word in a headline to italic (`Built to <em>think</em>`) to "look editorial".
+16. **Lazy-Loaded LCP**: Adding `loading="lazy"` to the main hero LCP image (tanks performance).
+
+## Mechanical Anti-Slop & Anti-Generic UI (Rule 8)
+- **Ubiquitous Eyebrows**: More than 1 eyebrow tag (uppercase tracking small label) per 3 sections (`count > ceil(sectionCount / 3)`).
+- **Floating Mid-Screen Hero**: Hero top padding exceeds `pt-24` (6rem) on desktop; headline > 2 lines; subtext > 20 words / 4 lines; primary CTA not visible without scroll.
+- **Wrapped CTA Buttons**: Primary CTA button text wraps to 2+ lines on desktop; CTA text > 3 words.
+- **Duplicate CTA Intent**: Multiple CTAs with the same underlying intent (e.g. mixing "Contact us", "Get in touch", and "Let's talk" on one page).
+- **Un-aligned Card CTAs**: Buttons in a card grid not pinned to the bottom (`mt-auto`), creating jagged horizontal lines.
+- **Invented Metrics**: Inventing fake statistics (*"+47% conversion"*, *"trusted by 50,000+ teams"*)—must use real data or `—` metric placeholders.
+- **Re-Drawn Fake Chrome**: Fake CSS browser window frames (red/yellow/green traffic lights wrapping an iframe) or fake IDE title bars.
+- **Fake Div Screenshots**: Using `<div>` rectangles to fake product UI instead of real images or real component previews.
+
+## ⛔ 11 Explicit Codex & AI-Slop Defect Bans
+1. **Ghost Cards**: Pairing 1px border with soft wide drop shadows `box-shadow: 0 Npx Mpx ...` (M ≥ 16px). Pick a solid border OR a shadow under 8px blur, never both as decoration.
+2. **Over-Rounding (32px+)**: Applying `border-radius: 24px/32px/40px` to rectangular cards and sections. Cards top out at 12–16px radius (pills strictly for tags/buttons).
+3. **Decorative Grid Background Overlays**: Adding two-axis `linear-gradient(... 1px, transparent 1px)` grid background patterns unless the page is an actual map, blueprint, canvas, or measurement tool.
+4. **Side-Stripe Accent Borders**: Colored `border-left` or `border-right` > 1px as a card/alert callout crutch. Rewrite with solid borders or subtle background tinting.
+5. **Warm Cream / Sand Saturated Neutral Default**: Defaulting all body backgrounds to warm beige/sand (`#F5F2EB` or token names like `--sand`, `--cream`, `--paper`). Pick a true neutral or brand-derived hue tint.
+6. **Side-by-Side Saturated Text Gradients**: Applying `background-clip: text` gradients for emphasis. Use weight, size, or solid accent color.
+7. **Reflexive Glassmorphism**: Adding decorative blurs and glass cards without clear spatial/layering purpose.
+8. **Numbered Section Markers on Non-Sequences**: Prefixing non-sequential sections with `01 / 02 / 03`. Sequence numbers earn their place only on real multi-step processes or timelines.
+9. **Sketchy SVG Illustrations**: Using crude 5-30 path SVG illustrations or doodle filters as fallback graphics.
+10. **Diagonal Stripe Background Overlays**: Using `repeating-linear-gradient(...)` stripe overlays in hero/section backgrounds.
+11. **Disjointed Display Heading Letter-Spacing**: Using letter-spacing tighter than `-0.04em` on H1 display headings causing characters to collide.
+
+## Optical Alignment & Typography Hygiene
+- **Data Table Numbers**: Multi-digit metrics or numbers missing `font-variant-numeric: tabular-nums` or monospace font alignment.
+- **Orphaned Headline Words**: Single hanging words on display headers missing `text-wrap: balance` or `text-wrap: pretty`.
+- **Optical Offsets**: Inline icons adjacent to text baselines missing 1-2px vertical optical adjustment.
+- **Sudden Dark Sections**: A random dark-mode section breaking an otherwise light-mode page (or vice versa), reading as a copy-paste AI artifact.
+
+## Interaction Completeness
+- An interactive component is missing hover, active (`scale-[0.98]`), focus-visible, or disabled states.
+- Focus rings are invisible or use browser default instead of token-colored ring.
+
+## Arabic / Bilingual & Accessibility Floor
+- Arabic display type uses any family other than El Messiri (headings) / Tajawal (body).
+- Contrast fails WCAG AA on any token-derived text/background pairing.
+- Touch targets under 44px on mobile/touch viewports.
+- `prefers-reduced-motion` not respected globally.

package/references/memory/07-consistency-contract.md

@@ -0,0 +1,33 @@
+# The Consistency Contract — Why the Architecture Is Strict
+
+This is the mechanism, stated once so every command can refer back to it
+instead of re-justifying it each time.
+
+## The problem this skill exists to solve
+A designer (or an agent) building a website one page at a time, with each
+page free to write its own CSS/JS, will drift — not from carelessness, but
+because "just this once" always feels justified in the moment a page needs
+something slightly different. At 5 pages the drift is invisible. At 50
+pages it's the whole project.
+
+## The rule
+Structural separation, not review discipline, is what prevents drift: if a
+page *cannot* carry its own styling logic (no `<style>`, no inline
+`style=`, no per-page `.css`/`.js` file), then drift becomes structurally
+impossible rather than merely discouraged. This is why `page`/`dashboard`
+treat a missing component as a hard stop, not a judgment call — "just add
+it inline this once" is exactly the failure mode being designed against.
+
+## The escape valve
+The rule only works long-term if extending the shared system stays easy —
+if adding a genuinely new component to `components.css` were harder than
+writing 10 lines of scoped CSS, people would route around the rule. The
+`components` command exists specifically to make the correct path (extend
+the shared system) faster than the wrong path (patch locally), not just
+more virtuous.
+
+## What `audit` is actually checking
+Every finding in `audit`'s structural scan traces back to this contract:
+inline styles, per-page scripts, untraced literal values, and near-
+duplicate components are all the same underlying failure — a page solved
+its own problem instead of extending the shared one.

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

@@ -0,0 +1,54 @@
+# Arabic & Bilingual Design — Reference for `i18n`
+
+Conventions carried consistently across Alwkala's production work and the
+rest of the TidyFactor ecosystem (`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).
+
+## 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.
+
+## 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)`.

package/references/memory/09-prototype-flow.md

@@ -0,0 +1,36 @@
+# Prototype Flow & Present Mode — Reference for `flow`
+
+## What makes this a "prototype" rather than a set of pages
+A Figma prototype's core value isn't the individual frames — it's the
+click-through experience that lets a stakeholder feel the product before
+it's built. This skill's `flow` command exists to reproduce that
+experience in real, running HTML rather than a design tool's simulation.
+
+## Journey-first, not link-everything
+Map 2-4 real journeys from the brief (e.g. "visitor discovers pricing →
+signs up → sees the empty-state dashboard → adds first item → sees
+populated dashboard") and wire those specifically. A prototype where every
+page links to every other page has no narrative — it's a sitemap, not a
+journey.
+
+## The prototype toolbar
+A small, clearly-a-tool-not-part-of-the-design floating control
+(`proto-nav.js`) giving:
+- Jump to any page (for the reviewer exploring freely)
+- "Restart flow" (return to the journey's first page)
+- State toggles where a page/screen has meaningful alternate states
+  (empty vs. populated dashboard, logged-out vs. logged-in) without
+  needing separate physical pages for each
+
+## State toggles without a backend
+A dashboard's empty/loading/error/populated states can be selected via a
+URL query parameter (`?state=empty`) read by a small inline check in the
+shared `interactions.js`, or via the toolbar directly — this keeps the
+prototype's states real and inspectable without simulating an actual data
+layer.
+
+## What to strip before a production handoff
+`proto-nav.js` and any state-toggle scaffolding are prototype-only tools —
+flag them explicitly in `deploy`'s output so they don't accidentally ship
+if this project is later handed to `tidyfactor-html`/`tidyfactor-php-*` for
+production.

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

@@ -0,0 +1,64 @@
+# 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
+
+| 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` |
+
+---
+
+## 1 · Color Palette Extraction (`scripts/extract_palette.py`)
+
+Extracts primary, secondary, and accent colors from reference images, photos, or logos. Computes WCAG 2.1 AA contrast scores.
+
+```bash
+# Extract palette and sync brand.json + tokens.css
+python scripts/extract_palette.py assets/logo.png --json brand.json --css design-system/tokens.css
+```
+
+---
+
+## 2 · AI Background Removal (`scripts/remove_backgrounds.py`)
+
+Isolates product shots, logos, or hero items into transparent PNG cutouts using `rembg`:
+
+```bash
+# Single file background removal
+python scripts/remove_backgrounds.py assets/product.jpg -o assets/product-cut.png
+
+# Batch processing
+python scripts/remove_backgrounds.py assets/logo1.jpg:assets/logo1.png assets/card.jpg:assets/card.png
+```
+
+---
+
+## 3 · Asset Resizing & Optimization (`scripts/optimize_assets.py`)
+
+Constrains image dimensions to design system tokens to prevent layout shifts and heavy page loads:
+
+```bash
+# Resize hero images to max 1200px dimension
+python scripts/optimize_assets.py assets/hero.jpg --max-dim 1200
+
+# Resize logo assets to max 240px dimension
+python scripts/optimize_assets.py assets/logo.png --max-dim 240
+```
+
+---
+
+## 📋 Dependency Management
+
+Dependencies are documented in `requirements.txt`:
+```bash
+pip install -r requirements.txt
+```
+If `rembg` or `Pillow` is missing, scripts output clear installation guidance without crashing.

package/references/memory/11-brand-json-v2.md

@@ -0,0 +1,86 @@
+# 11 · brand.json v2 Schema Reference
+
+The single source of truth for brand identity across all TidyFactor surfaces. Every
+design-system file, component, and page reads tokens from this file — never hardcode
+a hex value or font name inline.
+
+## Schema version
+
+`"schemaVersion": "brand-core-v2"` — the v2 schema adds dual-mode colors, shadows, radius,
+spacing scale, motion tokens, breakpoints, iconography, component token refs,
+localization, and accessibility floor.
+
+## Required sections
+
+| Section | Purpose |
+|---|---|
+| `meta` | Product name, tagline, description, version, lastUpdated |
+| `identity` | Logo paths (full, fullDark, mark, favicon), social preview (ogImage) |
+| `voice` | Tone, personality, registers (professional/casual/error/success), doNotUse words |
+| `colors.light` | 16 semantic tokens for light mode (background, surface, surface2, border, text, textMuted, primary, primaryForeground, secondary, secondaryForeground, accent, success, warning, danger, info, codeBackground) |
+| `colors.dark` | Mirror 16 tokens for dark mode |
+| `typography` | Families (heading, body, display, mono, arabicHeading, arabicBody), weights, scale, lineHeight, letterSpacing, googleFontsUrl |
+| `spacing` | baseUnit (4px) + scale (0–24) |
+| `radius` | none, sm, md, lg, xl, full, default |
+| `shadows` | sm, md, lg, focusRing (uses `color-mix()`) |
+| `motion` | duration (fast/base/slow), easing (standard/emphasized/spring), reducedMotion policy, scope |
+| `breakpoints` | sm, md, lg, xl, 2xl |
+| `iconography` | set (lucide), strokeWidth, sizes, rule |
+| `components` | Token refs for button, input, card, codeBlock |
+| `localization` | defaultLocale, supportedLocales, rtl, rtlLocales, mirrorOnRtl, dateFormat |
+| `accessibility` | minTouchTarget (44px), focusVisible policy, altTextPolicy |
+| `foundation` | Locked CSS foundation (native, tailwind, daisyui, hybrid, shadcn, pico, bootstrap, alpine) |
+| `school` | Design school (minimalist, brutalist, neo-skeuomorphic, glassmorphic, editorial, playful) |
+| `usage` | sharedBy (which kits consume this file), rules (governance) |
+
+## Dual-mode colors rule
+
+Brand colors (`primary`, `accent`) do NOT change between light/dark — only
+`background`, `surface`, `border`, and `text` tokens shift. This ensures brand
+recognition across modes.
+
+## Token reference convention (components section)
+
+Component specs reference other sections via dot-path strings:
+```json
+"button": {
+  "radius": "radius.md",
+  "primaryBg": "colors.primary",
+  "primaryFg": "colors.primaryForeground"
+}
+```
+These are resolved at build-time by the design-system generator — they are NOT
+runtime CSS variable references.
+
+## `focusRing` shadow using `color-mix()`
+
+```json
+"focusRing": "0 0 0 3px color-mix(in srgb, var(--primary) 40%, transparent)"
+```
+This produces a 40%-opacity brand-colored focus ring that automatically adapts
+to the active primary color. Supported in all modern browsers (Safari 16.4+,
+Chrome 111+, Firefox 113+).
+
+## Backward compatibility (v1 → v2 migration)
+
+| v1 token | v2 equivalent |
+|---|---|
+| `colors.primary` | `colors.light.primary` / `colors.dark.primary` |
+| `colors.neutralDark` | `colors.light.text` |
+| `colors.neutralLight` | `colors.light.surface` |
+| `colors.paper` | `colors.light.background` |
+| `colors.ink` | `colors.light.text` |
+| `colors.inkSoft` | `colors.light.textMuted` |
+| `typography.headings.arabic` | `typography.families.arabicHeading` |
+| `typography.body.arabic` | `typography.families.arabicBody` |
+| `typography.headings.latin` | `typography.families.display.primary` |
+| `typography.body.latin` | `typography.families.body.primary` |
+
+## Checklist
+- [ ] `$schema` is `"brand-core-v2"`
+- [ ] Both `colors.light` and `colors.dark` have all 16 tokens
+- [ ] `contrastPolicy` specifies WCAG AA minimum
+- [ ] `motion.reducedMotion` policy is stated
+- [ ] `accessibility.minTouchTarget` is ≥ 44px
+- [ ] `foundation` is one of the 8 supported options
+- [ ] `googleFontsUrl` loads ONLY families referenced in `typography.families`

package/references/memory/12-typography-matrix.md

@@ -0,0 +1,31 @@
+# 12 · Typography Matrix — Mood-Routed Font Pairings
+
+This document defines the 7 mood-routed typography pairings for `tidyfactor-design`. 
+While the default pairing (`El Messiri` + `Tajawal` + `Cormorant Garamond`) remains safe and clean for general builds, brand personality often demands a distinctive font pairing matching the visual layout's emotional register.
+
+## Constraint Rules
+1. **Clean over calligraphic for display headings**: Never use **Amiri** or any Naskh/manuscript script face above ~24px.
+2. **Display-only font rules**: Faces like **Jomhuria** are display-only (≥48px) and must never be used for body text.
+3. **CDN-only**: All fonts must be available via Google Fonts. No self-hosting or build step required.
+
+## Mood → Typography Pairing Matrix
+
+| Mood | Arabic Heading | Arabic Body | Latin Accent | Best Layouts | Avoid For |
+|---|---|---|---|---|---|
+| **Default luxury** | El Messiri | Tajawal | Cormorant Garamond | Any | — |
+| **Editorial / literary** | Markazi Text | IBM Plex Sans Arabic | Fraunces | `story` (editorial) | `app` (too soft for UI chrome) |
+| **Art-Deco / high fashion** | Jomhuria *(display ≥48px)* | Cairo | Bodoni Moda | `film` (fullbleed) | `creator` (too loud) |
+| **Modern minimal / tech** | Cairo | Cairo (weight-differentiated) | Marcellus | `app` (interface), `creator` | `space` (reads cold) |
+| **Warm hospitality / travel** | El Messiri | Almarai | Prata | `space` (spatial) | — |
+| **E-Commerce & conversion** | El Messiri | Tajawal | Cormorant Garamond | `product`, `store` | — |
+| **Automotive / performance** | El Messiri + Oswald (numerals) | Tajawal | Oswald | `film`, `story` (auto) | non-automotive |
+
+## Google Fonts Loading Standard
+
+Always use preconnect links and load only the required families to satisfy the performance budget (≤3 families, ≤4 weights):
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=El+Messiri:wght@400;600;700&family=Tajawal:wght@400;500;700&display=swap" rel="stylesheet">
+```

package/references/memory/13-layout-archetypes.md

@@ -0,0 +1,30 @@
+# 13 · Layout Archetypes — Surface Blueprints
+
+This document specifies the 8 macrostructure layout archetypes available in `tidyfactor-design`.
+
+## Archetype Overview
+
+| Layout | Codename | Hero Type | Section Rhythm | Best For |
+|---|---|---|---|---|
+| **Film** | `fullbleed` | Cutout + aura + motes | Hero → Film (600vh canvas) → Product reveal → Lifestyle → CTA | Physical luxury goods, brand stories |
+| **Story** | `editorial` | Split-screen image & copy | Hero → Film (420vh) → Feature grid → Origin story → CTA | Specs-heavy products, events, founders |
+| **Space** | `spatial` | Wide architectural shot | Hero → Spatial film (500vh) → Space details → Location → CTA | Real estate, architecture, hospitality |
+| **App** | `interface` | Device mockup frame | Hero → UI flow film (420vh) → Feature highlights → Proof → CTA | SaaS, web/mobile applications |
+| **Creator** | `minimal` | Centered cutout / photo | Hero → Statement → Story & Portrait → Portfolio → CTA | Personal brands, digital products |
+| **Product** | `product` | Product + Price + Buy CTA | Hero product → Spec highlights → Reviews → Purchase CTA | High-conversion single-product store |
+| **Store** | `store` | Banner + Category nav | Store banner → Category filter → Catalog grid → Footer | Multi-product catalog store |
+| **Auto** | `auto` | Hero vehicle + HUD gauge | Hero → 3D stage slider → Tech specs → Performance gallery → CTA | Automotive, performance engineering |
+
+## Hero Layering Architecture
+
+Every cinematic or luxury layout uses nested container layers so each layer owns a single transform channel without conflicts:
+
+```
+.stage (perspective)
+  .aura            → Radial background glow (CSS pulse + parallax)
+  .motes           → Floating particles drift
+  .hero-inner
+    .media-float   → CSS float animation (translateY bob)
+      .media-tilt  → JS pointer-driven 3D rotateX/rotateY
+        img.cutout → GSAP entrance transform (scale/opacity)
+```

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

@@ -0,0 +1,26 @@
+# 14 · Navigation & Footer Catalogs
+
+Reference catalog for Navigation (N1–N9) and Footer (Ft1–Ft8) components.
+
+## Navigation Archetypes
+
+- **N1: Floating Pill** — Glassmorphic floating navigation pill (`max-w-fit mx-auto`), rounded corners. Ideal for modern SaaS and mobile interfaces.
+- **N2: Newspaper Masthead** — Traditional publishing layout with centered brand title, divider rule, and category links below.
+- **N3: Brutal Slab** — Stark 4px bottom border, monochrome uppercase labels, sharp edges.
+- **N4: Terminal / CLI** — Monospace typography with prompt caret `>` markers on dark background.
+- **N5: Edge-Aligned Minimal** — Wordmark aligned hard left, navigation links hard right. Zero center clutter.
+- **N6: Split Brand** — Centered brand emblem with links balanced on left and right sides.
+- **N7: Double-Decker Utility** — Top notification/language bar paired with main brand header.
+- **N8: Vertical Rail** — Fixed left/right navigation rail for web app dashboards.
+- **N9: Fullscreen Overlay** — Trigger button opening full-viewport navigation overlay.
+
+## Footer Archetypes
+
+- **Ft1: Mast-Headed** — Giant brand wordmark overlaying top of footer section with multi-column links below.
+- **Ft2: Minimal Inline** — Clean single-line layout containing wordmark, links, and copyright notice.
+- **Ft3: Colophon / Credits** | Displays build metadata, typography credits, server location, and license.
+- **Ft4: Big Statement** | Prominent quote or mission statement block preceding link navigation.
+- **Ft5: Letter Close** | Personal signed letter from founder/creator with CTA before footer links.
+- **Ft6: Newsletter-First** | Large email signup form occupying primary focal space.
+- **Ft7: Marquee Scroll** | Continuous horizontal text ticker banner above secondary links.
+- **Ft8: Sitemap Grid** | Comprehensive multi-column link directory with locale and theme switchers.

package/references/memory/15-performance-budget.md

@@ -0,0 +1,18 @@
+# 15 · Performance Budget Specification
+
+Mechanical performance budgets for asset weight and DOM performance across all prototypes in `tidyfactor-design`.
+
+## Asset Class Budget Table
+
+| Asset Class | Budget Limit | Validation Command / Check |
+|---|---|---|
+| Frame Sequence (`assets/seq/*.jpg`) | ≤ 6.0 MB total | Sum of directory file sizes |
+| Individual Frame JPG | ≤ 60 KB at 1280px | Individual file size check |
+| Hero Cutout Image | ≤ 400 KB | Image optimizer `scripts/optimize_assets.py` |
+| Logo / Emblem Asset | ≤ 40 KB | Image optimizer check |
+| Font Families | ≤ 3 families, ≤ 4 weights | Count in Google Fonts `<link>` tag |
+| Design System CSS | ≤ 150 KB total | Combined size of `design-system/*.css` |
+
+## LCP Image Optimization Rule
+Hero LCP (Largest Contentful Paint) images MUST NOT use `loading="lazy"`. Doing so degrades load performance and violates Quality Bar Rule #16.
+Below-the-fold images MUST use `loading="lazy"`.