@tidyfactor/design 1.5.0

package/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/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/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/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/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/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/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/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"`.