diff --git a/.tidyfactor b/.tidyfactor index fb339b9..82fafa3 100644 --- a/.tidyfactor +++ b/.tidyfactor @@ -2,10 +2,10 @@ "ecosystem": "tidyfactor", "track": "design", "name": "tidyfactor-design", - "version": "1.6.0", + "version": "1.7.0", "npmPackage": "@alwkala/tidyfactor-design", "github": "https://github.com/TidyFactor/Design", - "skillFile": "../tidyfactor-design-v1.6.0.skill", + "skillFile": "../tidyfactor-design-v1.7.0.skill", "category": "design-system", "type": "interactive-prototyping", "outputs": [ diff --git a/CHANGELOG.md b/CHANGELOG.md index 2bbd79b..04ca2b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,16 @@ 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 diff --git a/SKILL.md b/SKILL.md index 9bb7f9f..b71adf2 100644 --- a/SKILL.md +++ b/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", ...)` + diff --git a/brand.json b/brand.json index 96eef03..a4ee2de 100644 --- a/brand.json +++ b/brand.json @@ -1,13 +1,13 @@ { "name": "TidyFactor Design", - "version": "1.6.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.6.0", - "lastUpdated": "2026-09-01" + "version": "1.7.0", + "lastUpdated": "2026-09-02" }, "identity": { "logo": { diff --git a/dist/tidyfactor-design.skill b/dist/tidyfactor-design.skill index a19cd3f..279de5d 100644 Binary files a/dist/tidyfactor-design.skill and b/dist/tidyfactor-design.skill differ diff --git a/dist/tidyfactor-design/.tidyfactor b/dist/tidyfactor-design/.tidyfactor index fb339b9..82fafa3 100644 --- a/dist/tidyfactor-design/.tidyfactor +++ b/dist/tidyfactor-design/.tidyfactor @@ -2,10 +2,10 @@ "ecosystem": "tidyfactor", "track": "design", "name": "tidyfactor-design", - "version": "1.6.0", + "version": "1.7.0", "npmPackage": "@alwkala/tidyfactor-design", "github": "https://github.com/TidyFactor/Design", - "skillFile": "../tidyfactor-design-v1.6.0.skill", + "skillFile": "../tidyfactor-design-v1.7.0.skill", "category": "design-system", "type": "interactive-prototyping", "outputs": [ diff --git a/dist/tidyfactor-design/CHANGELOG.md b/dist/tidyfactor-design/CHANGELOG.md index 2bbd79b..04ca2b6 100644 --- a/dist/tidyfactor-design/CHANGELOG.md +++ b/dist/tidyfactor-design/CHANGELOG.md @@ -2,6 +2,16 @@ 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 diff --git a/dist/tidyfactor-design/SKILL.md b/dist/tidyfactor-design/SKILL.md index 9bb7f9f..b71adf2 100644 --- a/dist/tidyfactor-design/SKILL.md +++ b/dist/tidyfactor-design/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", ...)` + diff --git a/dist/tidyfactor-design/brand.json b/dist/tidyfactor-design/brand.json index 96eef03..a4ee2de 100644 --- a/dist/tidyfactor-design/brand.json +++ b/dist/tidyfactor-design/brand.json @@ -1,13 +1,13 @@ { "name": "TidyFactor Design", - "version": "1.6.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.6.0", - "lastUpdated": "2026-09-01" + "version": "1.7.0", + "lastUpdated": "2026-09-02" }, "identity": { "logo": { diff --git a/dist/tidyfactor-design/package.json b/dist/tidyfactor-design/package.json index a0907bd..0c2bff2 100644 --- a/dist/tidyfactor-design/package.json +++ b/dist/tidyfactor-design/package.json @@ -1,6 +1,6 @@ { "name": "@tidyfactor/design", - "version": "1.6.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": { diff --git a/dist/tidyfactor-design/references/commands/handoff.md b/dist/tidyfactor-design/references/commands/handoff.md index a94eff4..32e6ca0 100644 --- a/dist/tidyfactor-design/references/commands/handoff.md +++ b/dist/tidyfactor-design/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 diff --git a/dist/tidyfactor-design/references/memory/02-design-tokens.md b/dist/tidyfactor-design/references/memory/02-design-tokens.md index 3b11bed..0b300b2 100644 --- a/dist/tidyfactor-design/references/memory/02-design-tokens.md +++ b/dist/tidyfactor-design/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 `` 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 diff --git a/dist/tidyfactor-design/references/memory/04-motion-principles.md b/dist/tidyfactor-design/references/memory/04-motion-principles.md index 04213e3..74d8f54 100644 --- a/dist/tidyfactor-design/references/memory/04-motion-principles.md +++ b/dist/tidyfactor-design/references/memory/04-motion-principles.md @@ -25,5 +25,18 @@ Adapted from classic animation principles, applied to UI motion rather than char --- -## 3. Non-negotiable: `prefers-reduced-motion` +## 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. diff --git a/dist/tidyfactor-design/references/memory/05-component-anatomy.md b/dist/tidyfactor-design/references/memory/05-component-anatomy.md index 069b277..f60f757 100644 --- a/dist/tidyfactor-design/references/memory/05-component-anatomy.md +++ b/dist/tidyfactor-design/references/memory/05-component-anatomy.md @@ -20,6 +20,25 @@ - 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 `` tiled over a single `` 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) diff --git a/dist/tidyfactor-design/references/memory/06-quality-bar.md b/dist/tidyfactor-design/references/memory/06-quality-bar.md index 19a5d73..d548901 100644 --- a/dist/tidyfactor-design/references/memory/06-quality-bar.md +++ b/dist/tidyfactor-design/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`. diff --git a/dist/tidyfactor-design/references/memory/10-python-tooling.md b/dist/tidyfactor-design/references/memory/10-python-tooling.md index c74513f..4d41d9c 100644 --- a/dist/tidyfactor-design/references/memory/10-python-tooling.md +++ b/dist/tidyfactor-design/references/memory/10-python-tooling.md @@ -1,18 +1,19 @@ + # 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 +## 🛠️ Tooling Suite Inventory & Latency Classes + +| Script | Responsibility | Latency Class | Isolation Scope | Invoked By | +|---|---|---|---|---| +| **`scripts/audit_design.py`** | Anti-pattern & token compliance auditor | Sub-second (<100ms) | In-process stdlib | `audit`, `perf` | +| **`scripts/extract_palette.py`** | WCAG 2.1 AAA contrast & palette derivation | Sub-second (<150ms) | `Pillow` (stdlib fallback) | `tokens`, `palette`, `init` | +| **`scripts/optimize_assets.py`** | Neural bg removal & WebP image optimization | Async Batch (2–8s) | `isolation_recommended: true` (`rembg`, `onnxruntime`) | `assets`, `deploy` | +| **`scripts/minify_assets.py`** | CSS/JS minification | Sub-second (<100ms) | Standard Python | `deploy` | -| 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` | --- diff --git a/dist/tidyfactor-design/references/memory/14-nav-footer-catalog.md b/dist/tidyfactor-design/references/memory/14-nav-footer-catalog.md index 5bd84b2..79d6da4 100644 --- a/dist/tidyfactor-design/references/memory/14-nav-footer-catalog.md +++ b/dist/tidyfactor-design/references/memory/14-nav-footer-catalog.md @@ -14,6 +14,37 @@ Reference catalog for Navigation (N1–N9) and Footer (Ft1–Ft8) components. - **N8: Vertical Rail** — Fixed left/right navigation rail for web app dashboards. - **N9: Fullscreen Overlay** — Trigger button opening full-viewport navigation overlay. +--- + +## 🏛️ Navigation & Header Design Invariants (Strict Quality Bar) + +### 1. Zero Emoji Invariant (`No Emojis in Nav/Menu`) +- **Prohibition**: Emojis (e.g. 🏠, 📞, 📚, ⚡) are strictly prohibited in navigation links, headers, submenus, and action controls. Emojis represent an amateur AI-slop anti-pattern. +- **Enforcement**: Use lightweight inline SVG vector icons or ultra-lightweight linear icon sets (Lucide, Feather, Heroicons with 1.5–2px stroke) styled dynamically via `currentColor` or brand tokens. + +### 2. Single-Line Discipline (`white-space: nowrap; flex-wrap: nowrap;`) +- **One-Line Invariant**: Navigation items must strictly fit in a single horizontal row on desktop viewports. Multi-line navigation wrapping is unacceptable. +- **Label Conciseness**: Labels must be 1 to 2 words maximum (e.g. `الرئيسية`, `المسيرة`, `المؤلفات`, `المبادرات`, `حاسبة الأسعار`). +- **Stacked Sub-descriptor Option**: If descriptive context is needed, stack a micro-caption (`font-size: 0.7rem`) vertically under the primary title within the link container, preserving compact horizontal width. +- **SEO vs Navigation Separation**: Full explanatory copy and SEO keywords belong in page body content and schema markup—navigation is dedicated exclusively to rapid, intuitive orientation. + +### 3. Submenu & Mega Menu Fallback Protocol +- If a project requires more than 5–6 primary destinations, do NOT crowd the header bar. +- **Mandatory Escalation**: Group links into structured **Submenus (Dropdowns)** or an architectural **Mega Menu** with frosted glass backdrops, golden borders, and categorical grouping. + +### 4. Mobile-First Navigation & Drawer Architecture (Must Rules) +- **Automatic Viewport Folding**: On screens `< 1024px` or `< 768px`, desktop navigation links must seamlessly fold into a slide-out drawer (`.mobile-drawer`) or bottom sheet. +- **Touch Target Integrity**: Minimum 44×44px hit areas for all hamburger triggers, menu links, and controls (WCAG 2.5.5). +- **Body Scroll Lock**: Automatically lock document scrolling when the mobile drawer is active (`body.menu-open { overflow: hidden; }`). +- **Zero Horizontal Overflow**: No absolute badge or floating frame element may cause horizontal scrolling on mobile viewports (`overflow-x: clip / hidden; width: 100vw;`). +- **Compact Sticky Height**: Mobile header height capped at 52–62px with logo/brand text truncation protection (`text-overflow: ellipsis; white-space: nowrap;`). + +### 5. Header Action Controls Cap (Max 3 Controls) +- Header action clusters must not exceed **3 controls maximum** (e.g. Primary CTA + Language Switcher + Theme Toggle). +- All action controls must share geometric harmony (coordinated pill radii, consistent padding, and unified border treatment). + +--- + ## Footer Archetypes - **Ft1: Mast-Headed** — Giant brand wordmark overlaying top of footer section with multi-column links below. diff --git a/dist/tidyfactor-design/references/workflows/brief.md b/dist/tidyfactor-design/references/workflows/brief.md index c547fd6..55ad3f2 100644 --- a/dist/tidyfactor-design/references/workflows/brief.md +++ b/dist/tidyfactor-design/references/workflows/brief.md @@ -6,20 +6,26 @@ Discovers and records core design system baselines (Foundation, School, Typograp ## Steps -1. **Check Existing State**: - - Inspect `brand.json` and `.tidyfactor/design-brief.md` for existing tokens and school choices. - -2. **Conduct Structured Discovery (Max 3 Questions)**: - - If not specified, ask: - 1. **CSS Foundation (D1)**: Native CSS, Tailwind, or DaisyUI? - 2. **Design School (D2)**: Swiss Clean, Neo-Brutalist, Luxury Glassmorphic, or Warm Editorial? - 3. **Layout Archetype (D4)**: L1 Landing Story, L2 Split Screen, or L3 Dashboard? - -3. **Record Decisions**: - - Save `.tidyfactor/design-brief.md` with confirmed parameters. - -4. **Report Summary**: - - Confirm baseline parameters and prompt user to invoke `/init` or `/components`. +1. **Check Existing State (Local Auto-Sensing First)**: + - Scan workspace for `BRAND-GUIDELINES.md`, `brand.json`, and `.tidyfactor/design-brief.md`. + - If present, immediately extract tokens, typography, and palette baselines without prompting. + +2. **Check Active MCP Acceleration (Fail-Open Fallback)**: + - If local files do not exist AND `search_knowledge_base` is available in active agent tools: + Query `search_knowledge_base(query="design tokens", scope="project")` for existing project baselines. + - If MCP is unavailable, empty, or returns error: Silently proceed to Step 3 with 0ms delay. + +3. **Conduct Structured Discovery (Max 3 Questions)**: + - If parameters remain unresolved, present at most 3 concise multiple-choice options: + 1. **CSS Foundation (D1)**: (A) Native CSS (Default), (B) Tailwind CSS, (C) daisyUI, (D) Pico CSS. + 2. **Design School (D2)**: (A) Swiss Modern, (B) Neo-Brutalism, (C) Editorial Luxury, (D) Egyptian / Regional Heritage. + 3. **Layout Archetype (D4)**: (A) Split Hero Canvas, (B) Narrative Editorial, (C) Command Dashboard. + +4. **Record Decisions**: + - Persist confirmed parameters into `.tidyfactor/design-brief.md`. + +5. **Report Summary**: + - Present a concise baseline summary and suggest next action (`/init`, `/tokens`, `/components`). --- diff --git a/package.json b/package.json index a0907bd..0c2bff2 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@tidyfactor/design", - "version": "1.6.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": { diff --git a/references/commands/handoff.md b/references/commands/handoff.md index a94eff4..32e6ca0 100644 --- a/references/commands/handoff.md +++ b/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 diff --git a/references/memory/02-design-tokens.md b/references/memory/02-design-tokens.md index 3b11bed..0b300b2 100644 --- a/references/memory/02-design-tokens.md +++ b/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 `` 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 diff --git a/references/memory/04-motion-principles.md b/references/memory/04-motion-principles.md index 04213e3..74d8f54 100644 --- a/references/memory/04-motion-principles.md +++ b/references/memory/04-motion-principles.md @@ -25,5 +25,18 @@ Adapted from classic animation principles, applied to UI motion rather than char --- -## 3. Non-negotiable: `prefers-reduced-motion` +## 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. diff --git a/references/memory/05-component-anatomy.md b/references/memory/05-component-anatomy.md index 069b277..f60f757 100644 --- a/references/memory/05-component-anatomy.md +++ b/references/memory/05-component-anatomy.md @@ -20,6 +20,25 @@ - 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 `` tiled over a single `` 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) diff --git a/references/memory/06-quality-bar.md b/references/memory/06-quality-bar.md index 19a5d73..d548901 100644 --- a/references/memory/06-quality-bar.md +++ b/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`. diff --git a/references/memory/10-python-tooling.md b/references/memory/10-python-tooling.md index c74513f..4d41d9c 100644 --- a/references/memory/10-python-tooling.md +++ b/references/memory/10-python-tooling.md @@ -1,18 +1,19 @@ + # 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 +## 🛠️ Tooling Suite Inventory & Latency Classes + +| Script | Responsibility | Latency Class | Isolation Scope | Invoked By | +|---|---|---|---|---| +| **`scripts/audit_design.py`** | Anti-pattern & token compliance auditor | Sub-second (<100ms) | In-process stdlib | `audit`, `perf` | +| **`scripts/extract_palette.py`** | WCAG 2.1 AAA contrast & palette derivation | Sub-second (<150ms) | `Pillow` (stdlib fallback) | `tokens`, `palette`, `init` | +| **`scripts/optimize_assets.py`** | Neural bg removal & WebP image optimization | Async Batch (2–8s) | `isolation_recommended: true` (`rembg`, `onnxruntime`) | `assets`, `deploy` | +| **`scripts/minify_assets.py`** | CSS/JS minification | Sub-second (<100ms) | Standard Python | `deploy` | -| 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` | --- diff --git a/references/memory/14-nav-footer-catalog.md b/references/memory/14-nav-footer-catalog.md index 5bd84b2..79d6da4 100644 --- a/references/memory/14-nav-footer-catalog.md +++ b/references/memory/14-nav-footer-catalog.md @@ -14,6 +14,37 @@ Reference catalog for Navigation (N1–N9) and Footer (Ft1–Ft8) components. - **N8: Vertical Rail** — Fixed left/right navigation rail for web app dashboards. - **N9: Fullscreen Overlay** — Trigger button opening full-viewport navigation overlay. +--- + +## 🏛️ Navigation & Header Design Invariants (Strict Quality Bar) + +### 1. Zero Emoji Invariant (`No Emojis in Nav/Menu`) +- **Prohibition**: Emojis (e.g. 🏠, 📞, 📚, ⚡) are strictly prohibited in navigation links, headers, submenus, and action controls. Emojis represent an amateur AI-slop anti-pattern. +- **Enforcement**: Use lightweight inline SVG vector icons or ultra-lightweight linear icon sets (Lucide, Feather, Heroicons with 1.5–2px stroke) styled dynamically via `currentColor` or brand tokens. + +### 2. Single-Line Discipline (`white-space: nowrap; flex-wrap: nowrap;`) +- **One-Line Invariant**: Navigation items must strictly fit in a single horizontal row on desktop viewports. Multi-line navigation wrapping is unacceptable. +- **Label Conciseness**: Labels must be 1 to 2 words maximum (e.g. `الرئيسية`, `المسيرة`, `المؤلفات`, `المبادرات`, `حاسبة الأسعار`). +- **Stacked Sub-descriptor Option**: If descriptive context is needed, stack a micro-caption (`font-size: 0.7rem`) vertically under the primary title within the link container, preserving compact horizontal width. +- **SEO vs Navigation Separation**: Full explanatory copy and SEO keywords belong in page body content and schema markup—navigation is dedicated exclusively to rapid, intuitive orientation. + +### 3. Submenu & Mega Menu Fallback Protocol +- If a project requires more than 5–6 primary destinations, do NOT crowd the header bar. +- **Mandatory Escalation**: Group links into structured **Submenus (Dropdowns)** or an architectural **Mega Menu** with frosted glass backdrops, golden borders, and categorical grouping. + +### 4. Mobile-First Navigation & Drawer Architecture (Must Rules) +- **Automatic Viewport Folding**: On screens `< 1024px` or `< 768px`, desktop navigation links must seamlessly fold into a slide-out drawer (`.mobile-drawer`) or bottom sheet. +- **Touch Target Integrity**: Minimum 44×44px hit areas for all hamburger triggers, menu links, and controls (WCAG 2.5.5). +- **Body Scroll Lock**: Automatically lock document scrolling when the mobile drawer is active (`body.menu-open { overflow: hidden; }`). +- **Zero Horizontal Overflow**: No absolute badge or floating frame element may cause horizontal scrolling on mobile viewports (`overflow-x: clip / hidden; width: 100vw;`). +- **Compact Sticky Height**: Mobile header height capped at 52–62px with logo/brand text truncation protection (`text-overflow: ellipsis; white-space: nowrap;`). + +### 5. Header Action Controls Cap (Max 3 Controls) +- Header action clusters must not exceed **3 controls maximum** (e.g. Primary CTA + Language Switcher + Theme Toggle). +- All action controls must share geometric harmony (coordinated pill radii, consistent padding, and unified border treatment). + +--- + ## Footer Archetypes - **Ft1: Mast-Headed** — Giant brand wordmark overlaying top of footer section with multi-column links below. diff --git a/references/memory/19-heritage-lanes-atmosphere.md b/references/memory/19-heritage-lanes-atmosphere.md index f310896..fc000ae 100644 --- a/references/memory/19-heritage-lanes-atmosphere.md +++ b/references/memory/19-heritage-lanes-atmosphere.md @@ -16,10 +16,13 @@ Complete operational grammar, palettes, atmospheric textures, and anti-patterns - `papyrus-bg`: `#FAF8F2` (Sacred Papyrus) * **Atmosphere & Texture**: - Fine Papyrus grain overlay (`feTurbulence` with 0.035 opacity). + - Continuous Full-Width Frieze Ribbon (`.lotus-frieze-fullwidth` with SVG `` repeat). + - 4-Corner Lotus Filigree Brackets (`.corner-bracket`) framing key academic and authority portraits. - 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. + - Never create segmented image dividers that break or produce seams on wide viewports (always use SVG ``). --- diff --git a/references/memory/20-brain-baas-integration.md b/references/memory/20-brain-baas-integration.md new file mode 100644 index 0000000..0eb7603 --- /dev/null +++ b/references/memory/20-brain-baas-integration.md @@ -0,0 +1,96 @@ + +# Brain MCP & Sovereign BaaS Integration Contract + +Authoritative operational specification governing how `tidyfactor-design` integrates with self-hosted `tidyfactor-brain` MCP instances and sovereign BaaS nodes without creating hard dependencies or blocking offline workflows. + +--- + +## 🏛️ 1. Sovereign Architecture Model (Self-Hosted Primacy) + +TidyFactor operates on a **Sovereign, Self-Hosted Architecture**: +- **Zero Centralized SaaS Dependency**: `tidyfactor-brain` and its MCP server run locally on the developer's machine or on an agency's self-hosted server instance (Apache G5 / PHP Flight / SQLite WAL). +- **Tenant Definition**: In this sovereign architecture, a `tenant` represents an isolated client project / domain workspace (e.g. `tenant_dr_sh`, `tenant_alwkala`) mapped to a dedicated SQLite file (`data/tenants/{tenant_id}_brain.sqlite`) or scoped directory (`~/.gemini/knowledge/projects/{project_id}/`). +- **No Global Auth Overhead**: Local stdio connections run authentication-free. Self-hosted remote SSE nodes authenticate via static bearer tokens configured in the agency's `mcp_config.json`. + +--- + +## ⚡ 2. The Deterministic Fail-Open Contract + +Brain MCP is an **optional acceleration layer**, NEVER a required runtime dependency. + +### Strict Resolution Algorithm: + +``` +Step 1: Check Local Disk Workspace + ├── IF `BRAND-GUIDELINES.md` or `.tidyfactor/design-brief.md` exists: + │ └── LOAD directly from disk. Done. + └── ELSE: Proceed to Step 2. + +Step 2: Check Active MCP Toolset Availability + ├── IF tool `search_knowledge_base` is present in agent's active tool list: + │ ├── Execute: `search_knowledge_base(query="design tokens", scope="project", project_id=CURRENT_PROJECT)` + │ ├── IF valid design KI returned: + │ │ └── POPULATE context baseline. Done. + │ └── ELSE (Empty/Error): + │ └── Silent fallback (0ms delay) to Step 3. + └── ELSE (Tool not registered / Standalone environment / Offline): + └── Silent fallback (0ms delay) to Step 3. + +Step 3: Interactive Micro-Discovery (CDL 3-Question Dialogue) + └── Present concise, structured A/B/C/D choices to the user. Done. +``` + +### Invariants: +1. **Zero Connection Attempts**: Skills must NEVER attempt raw HTTP connections or socket calls to non-existent servers. They only query native MCP tools if registered in the active agent session. +2. **Zero Delay & Zero Noise**: Missing MCP server must NEVER yield warning messages, stack traces, or connection timeouts. The bypass must be instant and silent. + +--- + +## 📦 3. Design System Knowledge Item (KI) Contract + +When exporting design baselines via explicit `--sync-brain` flag on `handoff`, the skill formats the deliverable as a structured Atomic KI conforming to the following JSON payload: + +```json +{ + "schema_version": "1.0.0", + "ki_type": "design_system_baseline", + "project_id": "current-project-slug", + "timestamp": "2026-09-02T05:00:00Z", + "tokens": { + "css_foundation": "native|tailwind|daisyui|pico|hybrid", + "design_school": "neobrutalism|editorial-luxury|swiss-modern|minimal-mono|heritage-egyptian", + "palette": { + "primary": "#HEX", + "secondary": "#HEX", + "accent": "#HEX", + "surface": "#HEX", + "text": "#HEX" + }, + "typography": { + "display_heading": "El Messiri", + "body_copy": "Tajawal", + "font_family_latin": "Inter" + }, + "layout_archetype": "hero-split-canvas|editorial-asymmetric|command-center-grid" + }, + "artifacts": [ + "design-system/tokens.css", + "design-system/base.css", + "brand.json" + ] +} +``` + +--- + +## 🛠️ 4. Tooling Execution Bridge (`run_skill_tool`) + +When `tidyfactor-brain` executes `tidyfactor-design` scripts via `manifest.json`: + +| Tool Name | Script Entrypoint | Latency Class | Execution Mode | +|---|---|---|---| +| `audit_design` | `scripts/audit_design.py` | Sub-second (<100ms) | Direct CLI / In-memory AST | +| `extract_palette` | `scripts/extract_palette.py` | Sub-second (<150ms) | WCAG Color Math Engine | +| `optimize_media` | `scripts/optimize_assets.py` | Async Batch (2–8s) | `isolation_recommended: true` (rembg/onnx) | + +--- diff --git a/references/workflows/brief.md b/references/workflows/brief.md index c547fd6..55ad3f2 100644 --- a/references/workflows/brief.md +++ b/references/workflows/brief.md @@ -6,20 +6,26 @@ Discovers and records core design system baselines (Foundation, School, Typograp ## Steps -1. **Check Existing State**: - - Inspect `brand.json` and `.tidyfactor/design-brief.md` for existing tokens and school choices. - -2. **Conduct Structured Discovery (Max 3 Questions)**: - - If not specified, ask: - 1. **CSS Foundation (D1)**: Native CSS, Tailwind, or DaisyUI? - 2. **Design School (D2)**: Swiss Clean, Neo-Brutalist, Luxury Glassmorphic, or Warm Editorial? - 3. **Layout Archetype (D4)**: L1 Landing Story, L2 Split Screen, or L3 Dashboard? - -3. **Record Decisions**: - - Save `.tidyfactor/design-brief.md` with confirmed parameters. - -4. **Report Summary**: - - Confirm baseline parameters and prompt user to invoke `/init` or `/components`. +1. **Check Existing State (Local Auto-Sensing First)**: + - Scan workspace for `BRAND-GUIDELINES.md`, `brand.json`, and `.tidyfactor/design-brief.md`. + - If present, immediately extract tokens, typography, and palette baselines without prompting. + +2. **Check Active MCP Acceleration (Fail-Open Fallback)**: + - If local files do not exist AND `search_knowledge_base` is available in active agent tools: + Query `search_knowledge_base(query="design tokens", scope="project")` for existing project baselines. + - If MCP is unavailable, empty, or returns error: Silently proceed to Step 3 with 0ms delay. + +3. **Conduct Structured Discovery (Max 3 Questions)**: + - If parameters remain unresolved, present at most 3 concise multiple-choice options: + 1. **CSS Foundation (D1)**: (A) Native CSS (Default), (B) Tailwind CSS, (C) daisyUI, (D) Pico CSS. + 2. **Design School (D2)**: (A) Swiss Modern, (B) Neo-Brutalism, (C) Editorial Luxury, (D) Egyptian / Regional Heritage. + 3. **Layout Archetype (D4)**: (A) Split Hero Canvas, (B) Narrative Editorial, (C) Command Dashboard. + +4. **Record Decisions**: + - Persist confirmed parameters into `.tidyfactor/design-brief.md`. + +5. **Report Summary**: + - Present a concise baseline summary and suggest next action (`/init`, `/tokens`, `/components`). ---