# 🏛️ Vibe UI Suite — System Architecture & Data Contract Specification **Version:** 6.3.0 (Autonomous Maturity & Clean Architecture Extension Sync) **Status:** Feature Freeze (Production Certified) **Document Type:** Core Architectural Specification **Machine Contract Reference:** [`schemas/design-spec.v1.schema.json`](schemas/design-spec.v1.schema.json) --- ## 1. Executive Overview & Architectural Philosophy The **Vibe UI Skills Suite** is a contract-driven design engineering ecosystem designed for autonomous AI coding agents (such as Claude Code, Cursor, Antigravity, GitHub Copilot, and Windsurf). Standard frontier models default to generic visual archetypes—predictable `border-radius: 8px` cards, flat gray borders, cliché blue-to-purple gradients, missing AI execution states, and unstable RTL layout flips. Vibe UI replaces ad-hoc prompt hacking with a **deterministic, contract-governed multi-skill architecture**. Commanded by the lead frontend architect agent **`vibe-ui-agent`**, the system coordinates six modular sub-skills in a unidirectional pipeline that enforces strict visual diversity, mathematical physics, WCAG 2.2 AA accessibility, anti-dark-pattern copy, and structurally stable bidirectional rendering. ### Core Architectural Invariants 1. **Semantic Understanding First (Domain Soul):** Deep comprehension of product domain, user emotional state, and primary jobs-to-be-done precedes all styling decisions. Mechanical hygiene (no slop, emoji stripping, BiDi isolation) executes silently in background. 2. **Universal Dual-Theme Invariant:** Every interface natively implements both Light and Dark themes via semantic design tokens (`--bg-primary`, `--surface`, `--border`, `--text`, `--accent`) with an accessible toggle switch. 3. **Mandatory Full-Page Visual Screenshot Audit:** Final verification requires capturing and visually inspecting a **full-page screenshot of the entire vertical height of the site** (`page.screenshot({ fullPage: true })`), not merely the initial viewport. The agent must examine all sections down to the footer to ensure zero contrast breaks, orphaned dark blocks, or visual inconsistencies. 4. **Zero Hallucination of Data Shapes:** All UI generations are parameterized through the canonical JSON Schema (`design-spec.v1.schema.json`). 5. **Fixed-Structure Semantic RTL:** Macro layout grids remain physically stable; RTL directionality is scoped exclusively to text nodes, paired with `` BiDi punctuation isolation and pure LTR telemetry. 6. **Strict Compositing Performance Budget:** A maximum cap of $\le 3$ active `backdrop-filter` blur surfaces is enforced across all viewports to protect GPU fill-rate. 7. **Frame-Rate-Independent Physics:** Motion decay and scroll physics rely on mathematical deltaTime integration ($\alpha = 1 - e^{-\lambda \cdot \Delta t}$, $\lambda = 14$) rather than frame-locked CSS keyframes. 8. **Zero Unicode Emojis in Production UI:** All iconography mandates inline SVG vectors with `currentColor` stroke binding. --- ## 2. The 6-Skill Orchestration Pipeline The system operates as a unidirectional Directed Acyclic Graph (DAG) commanded by `vibe-ui-agent`: ``` ┌─────────────────────────────────┐ │ Raw User Prompt │ │ "Build an analytics engine" │ └────────────────┬────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 👑 vibe-ui-agent │ │ (Master Frontend Architect) │ └────────────────┬────────────────┘ │ ┌─────────────────────────────────┴─────────────────────────────────┐ ▼ ▼ ┌───────────────────────────┐ ┌───────────────────────────┐ │ 🧠 autonomous-intent- │ │ 🎨 visual-chemistry- │ │ expander │ │ engine │ │ - 3-Tier Ambiguity Budget │ │ - 5 Visual Chemistries │ │ - 8 Domain Archetypes │ │ - Anti-Repetition Rules │ │ - P01-P30 Parameter Specs │ │ - OKLCH Color Engine │ └─────────────┬─────────────┘ └─────────────┬─────────────┘ │ │ └─────────────────────────────────┬─────────────────────────────────┘ ▼ ┌───────────────────────────────────────────────────────────────────────────────────────────────┐ │ Canonical Machine Contract: design-spec.json (Validated via Draft 2020-12 JSON Schema) │ └───────────────────────────────────────────────┬───────────────────────────────────────────────┘ │ ┌───────────────────────────────┼───────────────────────────────┐ ▼ ▼ ▼ ┌───────────────────────────┐ ┌───────────────────────────┐ ┌───────────────────────────┐ │ 🧩 ui-kit │ │ ⚡ vibe-physics-engine │ │ ✍️ conversion-copy-engine │ │ - 20 AI-Native Primitives │ │ - DeltaTime Physics Loop │ │ - B2B JTBD / ROI Engine │ │ - 50+ Shadcn Components │ │ - Lenis Momentum Smooth │ │ - PAS Narrative Matrix │ │ - Asymmetric Bento Grids │ │ - GPU Composite Only │ │ - Objection Inversion │ │ - Zero-JS CSS Grid Acc. │ │ - Strict Zero-Emoji SVG │ │ - Anti-Dark-Pattern Rules │ └─────────────┬─────────────┘ └─────────────┬─────────────┘ └─────────────┬─────────────┘ │ │ │ └───────────────────────────────┼───────────────────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ 🔍 ui-verifier │ │ 5-Pillar Autonomous Gate: │ │ 1. Visual Anti-Slop Check │ │ 2. Responsive (375/768/1440px) │ │ 3. WCAG 2.2 AA (>=4.5:1 / 3:1) │ │ 4. Blur Compositing (<=3 layers)│ │ 5. Semantic RTL & BiDi Stability│ └────────────────┬────────────────┘ │ [PASS] ▼ ┌─────────────────────────────────┐ │ ✨ Production Output Code │ │ (Next.js 15 / React / HTML5) │ └─────────────────────────────────┘ ``` ### Flow Mechanics & Skill Responsibilities 1. **Stage 1: Intent Expansion (`autonomous-intent-expander`)** - Ingests raw user prompt and runs it through the **3-Tier Ambiguity Budget**. - Classifies domain intent into 1 of 8 Master Archetypes (`LUXURY_CLINICAL`, `HIGH_PERFORMANCE_SAAS`, `HIGH_TICKET_SERVICE`, `HEAVY_INDUSTRIAL_ECOMMERCE`, `CREATIVE_EDITORIAL`, `HOSPITALITY_EXPERIENCE`, `HYPER_LOCAL_TRADES`, `EDTECH_ACADEMY`). - Synthesizes Core Parameters (P01–P24) and activates relevant Conditional Parameters (P25–P30). - Generates and passes canonical `design-spec.json`. 2. **Stage 2: Chemistry Selection (`visual-chemistry-engine`)** - Evaluates the archetype against recent project state to enforce the **Anti-Repetition Protocol** across $\ge 3$ structural dimensions. - Establishes mathematical color ramps in OKLCH space (preserving lightness contrast under gamut mapping). - Generates the primary palette tokens, surface treatment (e.g. SVG noise fractal + mesh glow), and elevation layers. 3. **Stage 3: Primitive Composition (`ui-kit`)** - References 6 curated component catalogs (`ai_native_full_catalog.md`, `shadcn_full_catalog.md`, `bento_grids_and_cards.md`, `physics_transitions_catalog.md`, `data_and_flow.md`, `tokens_and_theme_engine.md`). - Injects AI-native primitives (collapsible reasoning drawer, tool execution chip, streaming token cursor, approval gate, diff inspector). - Implements asymmetric grid structures and CSS logical properties (`margin-inline-start`, `padding-inline-end`). 4. **Stage 4: Mathematical Physics Integration (`vibe-physics-engine`)** - Binds interactive transitions to the exponential decay easing function: $$\alpha = 1 - e^{-\lambda \cdot \Delta t} \quad (\lambda = 14)$$ - Injects zero-dependency native smooth scroll fallback or progressive modern Lenis momentum. - Enforces GPU-accelerated compositing rules (`transform: translate3d(...)`, `will-change: transform`). - Replaces unicode emojis with scalable inline SVG vectors (`stroke="currentColor"`). 5. **Stage 5: Narrative Architecture (`conversion-copy-engine`)** - Replaces placeholder filler with domain-tailored copy formulas: $$\mathbf{\text{Hero Headline}} = [\text{Dream Outcome}] + [\text{Without Main Fear/Friction}] + [\text{Unique Mechanism/Timeframe}]$$ - Formulates Objection Inversion microcopy positioned directly beneath primary CTAs. - Enforces the Anti-Dark-Pattern standard: zero synthetic countdown timers, zero falsified testimonial quotes, and full pricing transparency. 6. **Stage 6: Autonomous Verification Gate (`ui-verifier`)** - Audits rendered code across 5 mandatory pillars before marking completion: - **Pillar 1 (Visual Anti-Slop):** Confirms adherence to the chosen chemistry and guarantees novelty across $\ge 2$ structural axes. - **Pillar 2 (Multi-Device Responsive):** Tests 375px mobile (0px horizontal overflow, $\ge 24\text{px}$ touch targets), 768px tablet, and 1440px desktop container bounds. - **Pillar 3 (WCAG 2.2 AA Accessibility):** Verifies keyboard reachability, visible focus indicators (`focus-visible:ring-2`), semantic clickables (`

`–`