@tidyfactor/design 1.5.0 → 1.6.0

package/.tidyfactor

@@ -2,10 +2,10 @@
   "ecosystem": "tidyfactor",
   "track": "design",
   "name": "tidyfactor-design",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "npmPackage": "@alwkala/tidyfactor-design",
   "github": "https://github.com/TidyFactor/Design",
-  "skillFile": "../tidyfactor-design-v1.4.0.skill",
+  "skillFile": "../tidyfactor-design-v1.6.0.skill",
   "category": "design-system",
   "type": "interactive-prototyping",
   "outputs": [

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the **[@tidyfactor/design](https://www.npmjs.com/package/@tidyfactor/design)** package will be documented in this file.
 
+## [1.6.0] - 2026-09-01
+
+### Added - Runtime Tooling Manifest & Egyptian Heritage Design Lanes
+- **Rule 10 Runtime Tooling Contract (`manifest.json`)**: Declared portable `audit_design`, `extract_palette`, and `optimize_media` executable tooling with schema validation.
+- **Automated Design Quality Auditor (`scripts/audit_design.py`)**: Standalone and MCP-compatible CLI engine scanning HTML/CSS for unicode emojis, inline styles, untokenized colors, and the 16 AI anti-patterns with UTF-8 support.
+- **Output JSON Schema (`references/schemas/audit_design.output.schema.json`)**: Standard schema defining structured quality audit reports and pre-emit critique stamps.
+- **Egyptian & Regional Heritage Lanes (`references/memory/19-heritage-lanes-atmosphere.md`)**: Operational design grammar covering Nilotic Wadj & Lotus, Egyptian Nubian Folk & Earth Vaults, Sinai Bedouin Craft, Al-Muqarnas Geometry, and Kufic Modernity.
+- **Bilingual & Responsive Enhancements**: Refined `01-design-schools.md`, `04-motion-principles.md`, `05-component-anatomy.md`, and `08-arabic-bilingual.md`.
+
 ## [1.5.0] - 2026-08-29
 
 ### Added - Global Multi-Tier & Multi-Language Documentation Architecture

package/README.ar.md

@@ -4,7 +4,7 @@
   <img src="assets/hero-banner.png" alt="TidyFactor Design Hero Banner" width="100%">
 </p>
 
-# 🎨 TidyFactor Design `v1.5.0`
+# 🎨 TidyFactor Design `v1.6.0`
 ### محرك دورة حياة تصميم الواجهات ومحرك النماذج التفاعلية المناهض للتكرار
 
 **البداية الرسمية لبناء نظام التصميم والدورة الكاملة لتصميم الواجهات التفاعلية ضمن منظومة TidyFactor Ecosystem.**

package/README.md

@@ -4,7 +4,7 @@
   <img src="assets/hero-banner.png" alt="TidyFactor Design Hero Banner" width="100%">
 </p>
 
-# 🎨 TidyFactor Design `v1.5.0`
+# 🎨 TidyFactor Design `v1.6.0`
 ### Code-Native UI Design Lifecycle Engine & Anti-Slop Design System Suite
 
 **The official UI design & interactive prototyping foundation for the TidyFactor Ecosystem.**

package/bin/add-skill.js

@@ -1,31 +1,65 @@
-#!/usr/bin/env node
-/**
- * bin/add-skill.js — CLI installer wrapper for tidyfactor-design
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const targetDir = process.cwd();
-const skillSource = path.resolve(__dirname, '..');
-const agentSkillsDir = path.join(targetDir, '.agents', 'skills', 'tidyfactor-design');
-
-fs.mkdirSync(agentSkillsDir, { recursive: true });
-
-function copyRecursive(src, dest) {
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (['.git', 'node_modules', 'dist'].includes(entry.name)) continue;
-    if (entry.isDirectory()) {
-      fs.mkdirSync(destPath, { recursive: true });
-      copyRecursive(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-copyRecursive(skillSource, agentSkillsDir);
-console.log('✓ Successfully injected tidyfactor-design skill into .agents/skills/tidyfactor-design');
+#!/usr/bin/env node
+/**
+ * bin/add-skill.js — Multi-Agent Skill Installer Wrapper for tidyfactor-design
+ * Supports Trae, Cursor, Windsurf, Antigravity, GitHub Copilot, RooCode, OpenCode, KiloCode, Warp, and Universal.
+ *
+ * @license Apache-2.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const targetDir = process.cwd();
+const skillSource = path.resolve(__dirname, '..');
+const skillName = 'tidyfactor-design';
+
+const AGENT_MAP = [
+  { name: 'Trae AI IDE',               dir: path.join(targetDir, '.trae', 'skills', skillName),        test: path.join(targetDir, '.trae') },
+  { name: 'Cursor IDE',                dir: path.join(targetDir, '.cursor', 'skills', skillName),      test: path.join(targetDir, '.cursor') },
+  { name: 'Windsurf Cascade',          dir: path.join(targetDir, '.windsurf', 'skills', skillName),    test: path.join(targetDir, '.windsurf') },
+  { name: 'GitHub Copilot',            dir: path.join(targetDir, '.github', 'prompts', skillName),     test: path.join(targetDir, '.github') },
+  { name: 'RooCode',                   dir: path.join(targetDir, '.roo', 'skills', skillName),         test: path.join(targetDir, '.roo') },
+  { name: 'OpenCode / Zen',            dir: path.join(targetDir, '.opencode', 'skills', skillName),    test: path.join(targetDir, '.opencode') },
+  { name: 'KiloCode',                  dir: path.join(targetDir, '.kilocode', 'skills', skillName),    test: path.join(targetDir, '.kilocode') },
+  { name: 'Warp Terminal',             dir: path.join(targetDir, '.warp', 'skills', skillName),        test: path.join(targetDir, '.warp') },
+  { name: 'Kiro Spec IDE',             dir: path.join(targetDir, '.kiro', 'skills', skillName),        test: path.join(targetDir, '.kiro') },
+  { name: 'Claude Code',               dir: path.join(targetDir, '.claude', 'skills', skillName),      test: path.join(targetDir, '.claude') },
+  { name: 'Zed AI Agent',              dir: path.join(targetDir, '.zed', 'skills', skillName),         test: path.join(targetDir, '.zed') },
+  { name: 'Google Antigravity/Gemini', dir: path.join(targetDir, '.agents', 'skills', skillName),      test: path.join(targetDir, '.agents') },
+];
+
+function copyRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (['.git', 'node_modules', 'dist'].includes(entry.name)) continue;
+    if (entry.isDirectory()) {
+      copyRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// Determine installation targets
+let mountedTargets = [];
+
+for (const agent of AGENT_MAP) {
+  if (fs.existsSync(agent.test)) {
+    copyRecursive(skillSource, agent.dir);
+    mountedTargets.push(agent.name + ' (' + path.relative(targetDir, agent.dir) + ')');
+  }
+}
+
+// Always ensure universal fallback in .agents/skills/
+const defaultDir = path.join(targetDir, '.agents', 'skills', skillName);
+copyRecursive(skillSource, defaultDir);
+if (!mountedTargets.some(t => t.includes('.agents'))) {
+  mountedTargets.push('Universal Default (.agents/skills/' + skillName + ')');
+}
+
+console.log('✨ Successfully injected ' + skillName + ' into:');
+mountedTargets.forEach(t => console.log('  • ' + t));

package/brand.json

@@ -1,13 +1,13 @@
 {
   "name": "TidyFactor Design",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "schemaVersion": "brand-core-v2",
   "meta": {
     "product": "TidyFactor Design System",
     "tagline": "Code-Native Interactive Prototyping Engine",
     "description": "A zero-bundler, framework-free design system and UI prototyping engine with pluggable CSS foundations and full Arabic/RTL support.",
-    "version": "1.4.0",
-    "lastUpdated": "2026-08-25"
+    "version": "1.6.0",
+    "lastUpdated": "2026-09-01"
   },
   "identity": {
     "logo": {

package/manifest.json

@@ -0,0 +1,59 @@
+{
+  "manifest_schema_version": "1.0.0",
+  "skill_id": "tidyfactor-design",
+  "skill_root_anchor": "self",
+  "tools": [
+    {
+      "name": "audit_design",
+      "description": "Scans index.html and design-system/*.css for emoji, inline styles, off-token colors, and the 16 AI anti-patterns.",
+      "entrypoint": { "runtime": "python3", "script": "scripts/audit_design.py" },
+      "invocation": {
+        "cli_pattern": "{runtime} \"{skill_root}/{script}\" --target \"{target_path}\" {flags}",
+        "args": [
+          { "name": "target_path", "type": "path", "required": true, "description": "Absolute path to the client project being audited" },
+          { "name": "fix", "type": "boolean", "required": false, "default": false, "flag": "--fix", "description": "Auto-fix violations where safe" }
+        ]
+      },
+      "output": {
+        "format": "json",
+        "channel": "stdout",
+        "schema_ref": "references/schemas/audit_design.output.schema.json"
+      },
+      "runtime_requirements": { "isolation_recommended": false, "dependencies": [] },
+      "invoked_by_commands": ["audit", "perf"]
+    },
+    {
+      "name": "extract_palette",
+      "description": "Computes WCAG AAA contrast ratios and generates tokens.css + brand.json from source colors.",
+      "entrypoint": { "runtime": "python3", "script": "scripts/extract_palette.py" },
+      "invocation": {
+        "cli_pattern": "{runtime} \"{skill_root}/{script}\" --target \"{target_path}\" {flags}",
+        "args": [
+          { "name": "target_path", "type": "path", "required": true, "description": "Absolute path to the client project" },
+          { "name": "source", "type": "string", "required": false, "flag": "--source", "description": "Hex seed color or image path to derive the palette from" }
+        ]
+      },
+      "output": { "format": "json", "channel": "stdout" },
+      "runtime_requirements": { "isolation_recommended": false, "dependencies": [] },
+      "invoked_by_commands": ["tokens", "palette", "init"]
+    },
+    {
+      "name": "optimize_media",
+      "description": "Compresses images, removes backgrounds, and generates WebP variants.",
+      "entrypoint": { "runtime": "python3", "script": "scripts/optimize_assets.py" },
+      "invocation": {
+        "cli_pattern": "{runtime} \"{skill_root}/{script}\" --target \"{target_path}\" {flags}",
+        "args": [
+          { "name": "target_path", "type": "path", "required": true, "description": "Absolute path to the client project" },
+          { "name": "remove_bg", "type": "boolean", "required": false, "default": false, "flag": "--remove-bg" }
+        ]
+      },
+      "output": { "format": "json", "channel": "stdout" },
+      "runtime_requirements": {
+        "isolation_recommended": true,
+        "dependencies": ["Pillow", "rembg", "onnxruntime"]
+      },
+      "invoked_by_commands": ["assets"]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tidyfactor/design",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "TidyFactor Design track — code-native UI design lifecycle engine (Figma alternative) with Contextual Decision Layer (CDL)",
   "main": "SKILL.md",
   "bin": {
@@ -55,6 +55,7 @@
     "assets",
     "bin",
     "brand.json",
+    "manifest.json",
     "memory",
     "references",
     "scripts",

package/references/memory/01-design-schools.md

@@ -1,13 +1,46 @@
-# Design Schools & Movements — Quick Calibration Index
+# Design Schools & Movements — Unified Calibration Index
+<!-- last-verified: 2026-09-01 -->
 
-For complete operational rules, visual tokens, typography pairings, color systems, CSS rules, shadow styles, and anti-patterns across all 20 visual aesthetics, see:
-👉 **[`memory/16-design-movements-guide.md`](16-design-movements-guide.md)** (All 20 Visual Movements & Design Tokens)  
-👉 **[`memory/17-storytelling-industries-ux.md`](17-storytelling-industries-ux.md)** (4 Storytelling Archetypes, 8 Industry Registers, 8 UX Philosophies)  
+A complete working index of design aesthetics, universal movements, and regional heritage art-direction lanes across all TidyFactor design engines.
+
+👉 **[`memory/16-design-movements-guide.md`](16-design-movements-guide.md)** (All 20 Universal Visual Movements)  
+👉 **[`memory/19-heritage-lanes-atmosphere.md`](19-heritage-lanes-atmosphere.md)** (5 Egyptian & Regional Heritage Lanes)  
+👉 **[`memory/17-storytelling-industries-ux.md`](17-storytelling-industries-ux.md)** (Storytelling Archetypes & Industry Registers)  
 👉 **[`memory/18-design-decision-engine.md`](18-design-decision-engine.md)** (9-Step Decision Tree & Anti-Design-Soup Constraint)
 
 ---
 
-## 🎨 20 Visual Aesthetics At-A-Glance Index
+## 🏛️ 5 Regional & Egyptian Heritage Art-Direction Lanes
+
+1. **Nilotic Wadj & Sacred Lotus (أصالة النيل ولوتس مصر العليا)**:
+   - *DNA*: Upper Egyptian heritage (Qena, Dendera, Thebes, Aswan), Sacred Lotus (`Sesen`), mineral green (`Wadj`), Nile terracotta (`Khem`), Royal Lapis (`Khesbed`), Sun Gold (`Nebu`).
+   - *Grammar*: Ascending registers, shallow stone deboss (`Low-Relief`), tactile papyrus & alabaster light texture (`Subtle Noise`).
+   - *Fits*: Community development, educational leadership, inclusive education, scholarly platforms, Upper Egyptian institutions.
+
+2. **Egyptian Nubian Folk & Earth Vaults (النوبة المصرية والعمارة الطينية)**:
+   - *DNA*: Aswan & West Suhail mud-brick vaulted architecture (Hassan Fathy), geometric chevron & zigzag bands, vibrant folk warmth.
+   - *Grammar*: Stepped triangles, Nubian vaulted card tops, sunny ochre, turquoise cataracts, terracotta clay, white lime plaster.
+   - *Fits*: Cultural platforms, eco-tourism, community initiatives, youth & child development.
+
+3. **Sinai Bedouin & Stitched Craft (البادية والتطريز السيناوي المصري)**:
+   - *DNA*: Authentic Sinai Bedouin cross-stitch embroidery (North & South Sinai), St. Catherine granite mountains, wild flora.
+   - *Grammar*: Pixelated cross-stitch geometric rails, embroidered dividers, madder red, wild rose magenta, deep Sinai night indigo, raw wool ivory.
+   - *Fits*: Heritage crafts, environmental foundations, field campaigns, national culture.
+
+4. **Al-Muqarnas & Girih Geometry (التوريق والمقرنصات الهندسية)**:
+   - *DNA*: Historic Cairo (Fatimid & Mamluk), Andalusian & Maghrebi architecture, mashrabiya woodwork, mathematical astronomy.
+   - *Grammar*: 4/6/8-fold repeat geometry, architectural aperture masks, perforated shadows (`Perforated Shadowing`), cobalt lapis, turquoise glaze, antique ochre.
+   - *Fits*: Cultural foundations, academic conferences, endowment platforms, classical Islamic arts.
+
+5. **Kufic Modernity & Luminescent Noor (العمارة الحروفية والنور المعاصر)**:
+   - *DNA*: Contemporary regional minimalism led by monumental Arabic typography and generous spatial purity.
+   - *Grammar*: Monumental Arabic wordmark/phrase hero, polished terrazzo, limestone, brushed bronze, single vibrant accent.
+   - *Fits*: Technology, sovereign wealth, venture studios, knowledge economy, international consulting.
+
+---
+
+## 🎨 20 Universal Visual Movements At-A-Glance Index
+
 1. **Swiss Style**: Objective 12-column grid, sans-serif, high contrast.
 2. **Flat Design**: 2D vector, zero shadows, vibrant color blocks.
 3. **Material Design**: Paper/ink depth, elevation shadows, touch ripples.
@@ -29,57 +62,16 @@ For complete operational rules, visual tokens, typography pairings, color system
 19. **Organic / Amorphous UI**: Fluid blob shapes (`border-radius: 60% 40% ...`), natural tones.
 20. **Frutiger Aero & Y2K**: Glossy glass buttons, lens flares, vibrant sky blue/lime gradients.
 
-## Bauhaus
-Geometric shapes as structural/decorative elements, primary-plus-black
-palettes, function-follows-form typography. Fits: education, design tools,
-brands wanting to signal craft/foundational thinking. Avoid: costume-party
-Bauhaus (circles+triangles as decoration with no structural logic).
-
-## Brutalism (web)
-Raw, unstyled-looking HTML elements used deliberately, harsh contrast,
-visible grid lines, monospace accents, intentionally "undesigned". Fits:
-developer tools, portfolios, brands wanting to signal authenticity/anti-
-polish. Avoid: actual unstyled defaults mistaken for the aesthetic —
-brutalism is a considered choice, not the absence of one.
-
-## Editorial / Broadsheet
-Hairline rules, dense multi-column text, serif display, byline/dateline
-conventions borrowed from print journalism. Fits: publications, long-form
-content, thought-leadership brands. Avoid: applying hairline-column density
-to a page that has nothing to say at that density (see `frontend-design`'s
-warning on this as an overused AI-design default).
-
-## Minimalism
-Extreme restraint, one accent color maximum, huge whitespace, type doing
-almost all the work. Fits: luxury, premium single-product brands. Avoid:
-minimalism as an excuse for lack of a real design decision — every
-remaining element must be precisely placed.
-
-## Glassmorphism
-Frosted-glass translucent panels, soft shadows, layered depth over a
-blurred background. Fits: modern consumer apps, dashboards wanting a soft/
-approachable data-density feel. Avoid: layering glass panels on glass
-panels — contrast and legibility break down fast.
-
-## Material-influenced
-Elevation via shadow, clear touch targets, motion as spatial logic (things
-move the way physical objects would). Fits: cross-platform app UI,
-utilitarian dashboards. Avoid: importing Material's specific component
-shapes wholesale when the brand wants its own identity — take the
-principles, not the skin.
+---
 
-## Modern SaaS (Vercel/Linear-influenced)
-Near-black or pure-white grounds, one saturated accent, monospace for data/
-code, tight type scale, subtle gradient accents, generous but efficient
-spacing. Fits: developer tools, B2B SaaS, technical dashboards. Avoid:
-defaulting here just because the brief is "a SaaS product" — this look is
-common enough now to read as generic if the brand has no other point of
-view.
+## 🏆 Award-Winning Regional Reference Evidence
+Treat award galleries as evidence of interaction and composition patterns:
+- **Webook (Riyadh Season)**: Immersive event storytelling, WebGL and sound.
+- **Masar Destination**: Saudi destination storytelling with responsive WebGL.
+- **IoT Squared**: Sovereign technology positioning via animation & parallax without heritage cliches.
+- **Kode**: New Cairo sports brand using bold color, animation, and WebGL.
+- **Ali Ali**: Cairo creative portfolio driven by minimal typography and film.
+- **Sivik Atelier**: Dubai studio portfolio using grid, parallax, and minimal typography.
+- **Jazean Coffee**: Saudi heritage framed as interactive scroll storytelling.
 
-## Calibration: defaults to avoid unless the brief asks for them
-Per `frontend-design`'s own calibration: warm-cream + terracotta-serif,
-near-black + single acid-green/vermilion accent, and broadsheet-hairline-
-columns applied regardless of subject are the three most common AI-design
-tells right now. Choosing one deliberately because it fits the brief is
-fine; landing on one by default is the failure mode `school` exists to
-prevent.
+*Rule: Establish a contemporary editorial system first, then use one culturally meaningful material, narrative, or spatial idea as the signature.*

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

@@ -1,44 +1,29 @@
 # Motion Principles — Reference for `motion`
+<!-- last-verified: 2026-09-01 -->
 
-Adapted from the classic animation principles, applied to UI motion rather
-than character animation.
+Adapted from 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.
+## 1. Core Principles
+- **Staging**: One focal change communicated at a time. Stagger card reveals by ~60-80ms.
+- **Anticipation**: Small pre-state before a bigger change helps the eye track what's about to happen.
+- **Ease-out for entrances, ease-in for exits**: Natural deceleration on entry, acceleration on exit.
+- **Secondary motion**: Delayed subtle trail (e.g. shadow settling a beat later).
+- **Restraint**: An orchestrated single moment lands harder than scattered effects everywhere.
 
-## 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.
+## 2. Cursor Spotlight & Ambient Glow Engine (Interactive Depth)
+- **Per-Card Cursor Spotlight**:
+  - Dynamically track `--mouse-x` and `--mouse-y` via `getBoundingClientRect()` on `.bento-card`, `.card`, and showcase tiles.
+  - Reveal a subtle `radial-gradient` (350-400px radius) in dark mode to illuminate surface borders and textures.
+- **Viewport Ambient Spotlight**:
+  - Desktop-only (`min-width: 992px`), single fixed layer driven by `requestAnimationFrame` and `translate3d(x, y, 0)`.
+  - Illuminates the underlying papyrus, granite, or obsidian texture with zero layout thrashing.
+  - Must automatically disable under `prefers-reduced-motion: reduce`.
 
-## 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.
+## 3. Non-negotiable: `prefers-reduced-motion`
+Every entrance, scroll, parallax, or ambient spotlight effect in `motion.js` must check `window.matchMedia('(prefers-reduced-motion: reduce)')` and fall back to instant or opacity-only transitions globally.

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

@@ -1,34 +1,31 @@
 # Component Anatomy — Reference for `components`/`states`
+<!-- last-verified: 2026-09-01 -->
 
-## 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.
+## 1. Atomic Hierarchy (Atomic Design, Adapted)
+- **Atoms**: Button, input, label, icon, badge, watermark stamp.
+- **Molecules**: Form field, stat counter, nav item, floating verification badge.
+- **Organisms**: Card, data table, navbar, 3D book/exhibition card, timeline, modal.
+- **Templates**: Organisms arranged into page layout with zero per-page CSS.
+
+---
+
+## 2. Advanced Specialized Organisms & Molecules
+
+### A. Watermark Stamp & Media Protection (`.watermark-stamp`)
+- Floating glassmorphic pill badge positioned over showcase media (e.g. `bottom: 12px; inset-inline-start: 12px;`).
+- Visuals: `background: rgba(8, 7, 5, 0.85); backdrop-filter: blur(8px); border: 1px solid var(--border-gold);`.
+- Protection: Non-draggable images (`-webkit-user-drag: none; user-select: none;`).
+
+### B. 3D Exhibition & Editorial Book Showcase Card (`.book-card`)
+- Layout: Asymmetric split (Cover viewport on one side, editorial hierarchy on the other).
+- Visuals: Multi-layered spine shadow (`box-shadow: -8px 10px 24px rgba(0,0,0,0.25)`), dynamic hover lift (`translateY(-4px)`), and category badge.
+
+---
+
+## 3. The Full 8-State Matrix (Apply per Interactive Component)
+`default → hover → focus-visible → active/pressed → disabled`, plus: `loading` (spinner/skeleton), `empty` (illustrated container), `error`, and `success`.
+
+---
+
+## 4. Naming Discipline
+One canonical name per real pattern. Use BEM modifiers (`.card--featured`, `.badge--accent`) or data attributes (`[data-theme]`, `[data-filter]`) rather than creating duplicate component structures.

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

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

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

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

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

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

package/scripts/audit_design.py

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