@tidyfactor/design 1.5.0 → 1.7.0

package/.tidyfactor

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

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to the **[@tidyfactor/design](https://www.npmjs.com/package/@tidyfactor/design)** package will be documented in this file.
 
+## [1.7.0] - 2026-09-02
+
+### 🧠 Added — Sovereign Brain MCP Integration & Deterministic Fail-Open Protocol
+- **Brain Integration Contract (`references/memory/20-brain-baas-integration.md`)**: Operational specification codifying the sovereign self-hosted architecture, tenant isolation within local/agency SQLite databases, Design System Knowledge Item (KI) payload schemas, and tool latency classes.
+- **Fail-Open Resolution Protocol (`references/workflows/brief.md`)**: Embedded deterministic context discovery: (1) Local workspace auto-sensing first, (2) Optional Brain MCP context acceleration (`search_knowledge_base`) when active, (3) Instant 0ms silent fallback to 3-question CDL interview if MCP is absent or offline.
+- **Optional Knowledge Item Sync (`references/commands/handoff.md`)**: Added explicit `--sync-brain` flag to export verified Design System Baselines and token maps to local Brain MCP storage.
+- **Tooling Scope & Latency Declarations**: Enriched `SKILL.md` with explicit Rule 10 Tooling Scope and updated `10-python-tooling.md` with execution latency classifications (sub-second AST audits vs async batch media inference).
+
+---
+
+## [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/SKILL.md

@@ -44,3 +44,11 @@ Read only the command file that matches the request. Do not load all commands si
 3. **Single CSS Foundation**: Lock Native, Tailwind, daisyUI, Pico, or Hybrid once per project; never mix foundations.
 4. **Typography Discipline**: Arabic display headings use El Messiri, body copy uses Tajawal. Never use Amiri for headings above 24px.
 5. **7-Axis Pre-Emit Critique**: All components and layouts must be evaluated with `/* Pre-emit critique: P5 H5 E5 S5 R5 V5 D5 */`.
+
+## Tooling Scope (Rule 10)
+
+- **Languages**: Python 3 (stdlib, Pillow/rembg for asset optimization)
+- **Mutations**: Read-only audits (`audit_design`), file creation (`extract_palette`), image processing (`optimize_assets`)
+- **Network**: None required
+- **Companion MCP**: Invocable via `tidyfactor-brain`'s `run_skill_tool(skill_id="tidyfactor-design", ...)`
+

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.7.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.7.0",
+    "lastUpdated": "2026-09-02"
   },
   "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.7.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/commands/handoff.md

@@ -44,6 +44,10 @@ For each shared component in `design-system/components.css`:
 - Cubic-bezier curves and duration values
 - Reduced-motion fallback rules (`prefers-reduced-motion: reduce`)
 
+### 5. Optional Brain MCP Sync (`--sync-brain`)
+When invoked with `--sync-brain`, the command packages the Design System Baseline into an Atomic Knowledge Item (KI) per `20-brain-baas-integration.md` and exports it to the active project's Brain MCP storage via `extract_knowledge_item`.
+- **Fail-Open Policy**: If Brain MCP is unavailable or offline, silently skip KI export and complete the local `docs/handoff/` generation.
+
 ## Checklist
 
 - [ ] Complete token mapping table generated

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/02-design-tokens.md

@@ -29,9 +29,14 @@ the palette, not pure black).
 (ease-out for entrances, ease-in for exits, a signature easing curve for
 the brand's characteristic motion if `school` calls for one).
 
+**Decorative Patterns & Friezes** — continuous horizontal ribbons, architectural
+friezes, and cultural repeating motifs. Defined via SVG `<pattern>` tokens with
+exact waveform bounding boxes (`patternUnits="userSpaceOnUse"`) to guarantee 0px gap
+interlocking across 100% viewport width without manual DOM duplication or layout shifts.
+
 ## Naming convention
 `--color-*`, `--font-*`, `--space-*`, `--radius-*`, `--shadow-*`,
-`--ease-*`/`--duration-*` — consistent prefixing so any command (or a human
+`--ease-*`/`--duration-*`, `--pattern-*`, `--motif-*` — consistent prefixing so any command (or a human
 reading the CSS) can immediately tell a value's category.
 
 ## Contrast policy

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

@@ -1,44 +1,42 @@
 # Motion Principles — Reference for `motion`
+<!-- last-verified: 2026-09-01 -->
 
-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.
+Adapted from classic animation principles, applied to UI motion rather than character animation.
+
+---
+
+## 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.
+
+---
+
+## 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`.
+
+---
+
+## 3. SVG Stroke Dash & Parallax Choreography
+
+### A. SVG Stroke Dash Tracing (`.lotus-stroke-animated`)
+- For cultural emblems, watermarks, and architectural line art, set `strokeDasharray` and `strokeDashoffset` equal to the total path perimeter (e.g. `1200-1600px` or `.getTotalLength()`).
+- Animate `strokeDashoffset: 0` using GSAP timeline `power2.inOut` with micro-staggers (100-150ms) across petals/lines during initial page load.
+
+### B. Interactive Parallax with Optical Counter-Movement (Desktop $\ge 992px$)
+- Foreground hero visual frames receive soft directional tilt (`xOffset * 0.5`, `yOffset * 0.5`).
+- Deep background watermarks and particles receive inverted counter-movement (`-xOffset * 0.8`, `-yOffset * 0.8`) with longer easing durations (1.2s vs 0.8s) to establish multi-plane spatial depth.
+- On `mouseleave`, smoothly tween all planes back to origin `(0, 0)` via `power2.out`.
+
+---
+
+## 4. 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,50 @@
 # 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.
+
+### C. Continuous Architectural Friezes & Motifs (`.lotus-frieze-fullwidth`)
+- Layout: Full-width continuous ribbon utilizing SVG `<pattern patternUnits="userSpaceOnUse">` tiled over a single `<rect width="100%" />` element with zero gap.
+- Break Pattern: Optional centered floating medallion (`.lotus-frieze-center-emblem`) with subtle border elevation and micro-rotation on hover.
+
+### D. Royal Cartouche & Shenu Ribbon Badges (`.section-eyebrow`, `.badge`)
+- Styling: Dual-tone background gradients, gold border (`rgba(201, 136, 24, 0.45)`), inset highlight glow, and authentic cultural iconography.
+
+### E. Responsive Positioning Protocol for Floating Badges & Frame Elements
+- Desktop (`min-width: 992px`): Positioned absolutely outside frame boundaries (`position: absolute; inset-inline-end: -8px;`).
+- Mobile (`max-width: 768px`): Must convert to centered static blocks (`position: relative; inset: auto; width: 100%; justify-content: center;`) to eliminate mobile horizontal scrolling and layout clipping.
+
+### F. Header & Navigation Bar (`.navbar`)
+- Layout: Single-line sticky frosted glass island with gold rim (`white-space: nowrap`).
+- Brand Lockup: Logo emblem medallion (`.brand-emblem`) + Bold title (`.brand-title`) + Micro pedigree (`.brand-pedigree`).
+- Prohibition: Zero emojis anywhere in the navigation bar. Use crisp inline SVGs (`currentColor`).
+
+### G. Mobile Navigation Drawer (`.mobile-drawer`)
+- Structure: Full-height frosted overlay (`backdrop-filter: blur(20px)`), body scroll lock, $\ge 44\times 44\text{px}$ touch targets, and docked bottom action buttons.
+
+---
+
+## 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/06-quality-bar.md

@@ -66,6 +66,15 @@ Before handing back any output, score the artifact on 6 axes:
 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.
 
+---
+
+## 🚫 5 Header & Navigation Anti-Pattern Traps (Auto-Reject)
+1. **Vertical Text-Wrapping Link Trap**: Link labels breaking/wrapping into 2 stacked lines inside a single link container (e.g. `المبادرات \n والتدريب` or `المؤلفات \n والأبحاث`). Navigation items must strictly stay 1–2 words and enforce `white-space: nowrap;`.
+2. **The Escaping Action Overflow Trap**: Primary CTA buttons or action toggles spilling outside the navbar pill container due to link congestion or missing container boundaries. Header items must never cause horizontal clipping or overflow.
+3. **Compound Title Congestion**: Cramming 6+ verbose compound phrases side-by-side (`المؤهلات والأكاديميا`, `المؤلفات والأبحاث`, `المسيرة المهنية`, `الأثر الميداني`, `المبادرات والتدريب`). When links exceed 5–6 items, mandatory escalation to Submenu/Mega Menu applies.
+4. **Duplicate Primary CTA Intent**: Duplicating the conversion action in both the menu links and the header button (e.g. having `حجز استشارة` in the nav links right next to `تواصل مباشر` on the CTA button). The CTA is the single primary conversion button.
+5. **Amateur Avatar & Emoji Trap**: Using plain circular placeholder avatars with raw single letters (e.g. a teal circle with a plain letter "ش") or emoji labels (`🌙 ليلي`). Always use authentic SVG royal emblems, cartouches, or clean linear SVG icons.
+
 ## 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`.