Vibe UI Suite

Contract-driven frontend engineering, design-system constraints, and runtime verification for AI coding assistants.

فارسی (Persian Documentation) • Architecture Specification • Enterprise Guide • Interactive Studio Playground

What happens when you ask a standard AI assistant to generate a frontend component?

┌──────────────────────────────────────┐  vs  ┌──────────────────────────────────────┐
│ ❌ VANILLA AI SLOP                   │      │ ✨ VIBE UI v6.1.1 MASTERPIECE        │
├──────────────────────────────────────┤      ├──────────────────────────────────────┤
│ • Generic purple gradient buttons    │      │ • Strict Light-First Canvas & Depth  │
│ • Low contrast text (3.2:1 FAILS AA) │      │ • Mathematical WCAG 2.2 AAA (18.8:1) │
│ • Lazy dark-canvas bias              │      │ • Ambient Hero Video & Fluid Loops   │
│ • Hallucinated raw emojis            │      │ • Crisp Vector SVGs & Clean Icons    │
│ • Dead toggle cards & static mockups │      │ • Living React 19 TSX + Dual Theme   │
│ • Rushed, flat, uninspired output    │      │ • Trend-First Harvest (Dribbble/etc) │
│ • Empty blank or broken image links  │      │ • Curated 24-Domain Unsplash CDN CDN │
│ • Broken mobile overflow (375px)     │      │ • Headless Multi-Viewport Screenshots│
│ • Mixed direction text / numbers     │      │ • On-Demand Scoped RTL & BiDi Guard  │
└──────────────────────────────────────┘      └──────────────────────────────────────┘

👉 Launch the Interactive Design Compiler Studio Live — Zero server latency, instantaneous client-side domain inference & component preview.

Vibe UI Suite gives AI coding assistants (Cursor, Claude Code, Windsurf, Antigravity) a structured, machine-checkable framework to plan, implement, and verify frontend interfaces.

Instead of relying on fragile prompt engineering ("make this dashboard look clean and modern"), Vibe UI establishes an explicit compiler-style pipeline:

User Intent
    ↓
Intent Expansion (Structured 6-Dimensional Design Contract)
    ↓
Machine-Readable Schema (design-spec.v1.schema.json)
    ↓
Macro Archetype Selection (7 Visual Archetypes Vault)
    ↓
Code Implementation (Next.js 15 / React 19 TSX / Tailwind OKLCH)
    ↓
Static Evaluation (Schema, luminance math, negative fixtures)
    ↓
Headless Browser Evaluation (Playwright 375px mobile overflow)
    ↓
Verified Output or Actionable Failure Diagnostics

Day-One Transparency: Vibe UI Suite is at v6.1.0 (built upon v6.0.0 The Two Golden Pillars: Trend Inspiration & Living Visual Feedback Loop with the Living Micro-Interactions & Galaxy Inspiration Standard). Anchored on Pillar 1 (deep trend research across Mobbin, Dribbble, Figma Community, and Awwwards with Vibrant Light Mode default) and Pillar 2 (deterministic Playwright multi-viewport screenshot verification across Desktop 1440px and Mobile 390px with zero orphaned processes), Galaxy Inspiration Engine (3,800+ community elements with offline caching), Curated High-Res Unsplash Asset Vault covering all 24 canonical domains with tested HTTP 200 CDN URLs, clean 9-pillar component catalog with living interactive micro-interactions (shimmer-button, cyber-loader, holographic-card, tactile-switch, glow-input), living React 19 TSX generation (-f tsx), and synchronized cross-platform tooling across npm, Python CLI, and VS Code. Constructive criticism, issues, and contributions from frontend engineers and AI researchers are warmly welcomed.

Frontend design should not require developers to study color contrast mathematics, OKLCH formulas, CSS spring physics, or memorizing style taxonomies. That cognitive burden belongs entirely to the agent.

Vibe UI Suite includes a dedicated master architect agent: vibe-ui-agent (AGENT.md). Powered by an autonomous Stack Sensor (<1ms) and Domain Director, it reads your project's package.json, existing Tailwind configuration, and component libraries, autonomously deciding the optimal design archetype, color harmony, and component flow without asking tedious setup questions.

flowchart LR
    User["User Prompt<br/>'@vibe-ui-agent ...'"] --> Sensor["Stack Sensor &lt;1ms<br/>(Framework, Tailwind v4, Icons)"]
    Sensor --> Director["Autonomous Director<br/>(Domain, Light/Dark, Archetype)"]
    Director --> AntiSlop["Anti-Slop Compiler<br/>(OKLCH, No Emojis, &lt;bdi&gt; RTL)"]
    AntiSlop --> ClosedLoop["Closed-Loop Critic<br/>(Headless Chromium &amp; Touch Gate)"]
    ClosedLoop --> Output["Production-Grade UI<br/>(Zero Prompt Grind)"]

Just give your AI assistant (Antigravity, Cursor, Hermes, Claude Code) a single sentence describing what you need:

@vibe-ui-agent build a modern, high-conversion landing page for my project.

Optional Domain or Vibe Hints (Never Required):

• @vibe-ui-agent build an analytics billing dashboard with Apple Cupertino fluid style
• @vibe-ui-agent design a crypto staking interface with dark terminal HUD aesthetic
• @vibe-ui-agent create a patient booking screen for an aesthetic dental clinic

What vibe-ui-agent guarantees automatically (Lazy-Prompt Protocol & The 5 Gates):

• Mandatory Pre-Edit Visual Audit: Captures headless browser screenshot (screenshots/before.png) before touching code to diagnose spatial and typographic flaws with multimodal vision.
• Architectural Paradigm & Trend Anchoring: Autonomously selects proven paradigms (Bento Grid, Linear Minimal, Stripe Crisp Light, Swiss Editorial) benchmarked from Dribbble, Mobbin, and Awwwards.
• Structural DOM & Spatial Rhythm Overhaul: Re-architects real layout structures and 8pt spatial rhythm (Zero Cosmetic-Only Patch Invariant).
• Living Component & Rich Media Synthesis: Injects tactile Galaxy micro-interactions (shimmer buttons, tactile switches, cyber loaders), ambient hero loops, and authentic photography.
• Silent Table-Stakes (Internal Worker Delegation): OKLCH color math, WCAG AAA contrast, inline SVGs, and <bdi> isolation are handled invisibly by internal workers and never clutter primary deliverables.

When an existing screen looks flat, amateur, or cluttered (unbalanced spacing, dead layouts, or lack of visual hierarchy):

@vibe-ui-agent this UI feels cluttered and dated. Re-architect and modernize it using Vibe UI structural standards.

The Agent's Autonomous Multi-Step Pipeline:

1. Renders current screen in browser and saves screenshots/before.png to audit layout balance and ergonomic flaws.
2. Dismantles the dead container structure and replaces it with a clean Bento Grid or modern minimal architecture.
3. Rewires all buttons, inputs, and state into living micro-interaction primitives without breaking existing business logic.
4. Captures post-implementation screenshots (screenshots/after.png, Desktop 1440px / Mobile 390px) for multi-viewport visual verification.
5. Delivers a report focused 100% on spatial and structural transformation, keeping low-level styling baselines in the background.

When starting a new project or onboarding Vibe UI Suite without touching the terminal:

Install and configure vibe-ui-suite in this project and activate vibe-ui-agent rules.

The agent autonomously:

1. Runs npm install vibe-ui-suite in your project terminal.
2. Injects @import "vibe-ui-suite/v4.css"; into your main stylesheet (app/globals.css or src/index.css).
3. Creates your editor rule file (.cursorrules, CLAUDE.md, or AGENTS.md) with the full vibe-ui-agent protocol.

You never need to choose a style—vibe-ui-agent automatically selects the ideal archetype based on your domain. However, you can explicitly request any archetype from the Design Vault (data/design_vault/archetypes.json):

Generate complete, production-grade standalone web applications or React 19 components directly from your terminal:

# 1. Generate autonomous masterpiece HTML with interactive sliders & macOS chrome:
python vibe_cli.py generate "یک سایت کلینیک زیبایی با رزرو آنلاین و نمونه کارهای قبل و بعد" -o clinic.html

# 2. Generate living React 19 / TypeScript component (.tsx) with stateful hooks:
python vibe_cli.py generate "A modern developer observability dashboard with latency metrics" -f tsx -o DevDashboard.tsx

# 3. Verify any generated artifact against all 6 production audit gates:
python vibe_cli.py verify clinic.html

If you prefer running a guided interactive wizard in your terminal:

npx vibe-ui-suite init

In your app/globals.css or main stylesheet:

@import "tailwindcss";
@import "vibe-ui-suite/v4.css";

Zero JavaScript configuration files needed. Instantly unlocks:

• Semantic OKLCH colors: bg-vibe-canvas, bg-vibe-surface, text-vibe-primary, border-vibe-border
• Physics curves: ease-vibe-spring, ease-vibe-snap, ease-vibe-glide (or utility .vibe-spring)
• Material shadows: shadow-vibe-brutal, shadow-vibe-glass

Add production-ready, accessible component templates directly into components/vibe-ui/:

# Core AI & Telemetry Primitives:
npx vibe-ui-suite add thinking-drawer
npx vibe-ui-suite add telemetry-hud
npx vibe-ui-suite add contrast-badge
npx vibe-ui-suite add theme-toggle

# Living Micro-Interactions (v6.1.0):
npx vibe-ui-suite add shimmer-button
npx vibe-ui-suite add cyber-loader
npx vibe-ui-suite add holographic-card
npx vibe-ui-suite add tactile-switch
npx vibe-ui-suite add glow-input

List all available registry components:

npx vibe-ui-suite list

Tap into a curated offline knowledge graph of over 3,800+ micro-interactions and component patterns directly from your terminal or AI coding agent:

# Query community components with sub-10ms offline cache:
python vibe_cli.py inspire "neon cyber button"
python vibe_cli.py inspire "holographic card" -l 3

# Or via npm CLI:
npx vibe-ui-suite inspire "orbit loader"

Vibe UI is available directly inside your IDE sidebar:

• VS Code Marketplace: omid-io.vibe-ui-vscode
• Open-VSX Registry: omid-io.vibe-ui-vscode (for Cursor, Windsurf, VSCodium)

• Interactive WCAG 2.2 Contrast Calculator: Real-time color pickers with instant relative luminance calculation ($L_1 / L_2$) and dynamic Pass/Fail badges.
• 1-Click Component Inserter: Insert component templates directly into your active text editor.
• In-Editor Audit Command: Ctrl+Shift+P ➔ Vibe UI: Audit Active File Contrast.

The system is coordinated by a lead architect agent (vibe-ui-agent) that orchestrates 6 specialized sub-skills:

               ┌──────────────────────────────┐
               │  User Prompt: "Build a UI"   │
               └──────────────┬───────────────┘
                              │
                              ▼
               ┌──────────────────────────────┐
               │       vibe-ui-agent         │
               │  (Lead Frontend Architect)   │
               └──────────────┬───────────────┘
                              │
       ┌──────────────┬───────┴───────┬──────────────┐
       ▼              ▼               ▼              ▼
┌──────────────┐┌──────────────┐┌──────────────┐┌──────────────┐
│  autonomous- ││   visual-    ││   ui-kit     ││    vibe-     │
│    intent-   ││  chemistry-  ││  (70+ AI     ││   physics-   │
│   expander   ││    engine    ││   Recipes)   ││    engine    │
└──────┬───────┘└──────┬───────┘└──────┬───────┘└──────┬───────┘
       │               │               │               │
       └───────────────┼───────────────┴───────────────┘
                       │
                       ▼
       ┌──────────────────────────────┐
       │   conversion-copy-engine     │
       │   (PAS, JTBD, Anti-Deception)│
       └──────────────┬───────────────┘
                      │
                      ▼
       ┌──────────────────────────────┐
       │         ui-verifier          │
       │  (5-Pillar Quality Gate)     │
       └──────────────┬───────────────┘
                      │
                      ▼
       ┌──────────────────────────────┐
       │ Evaluated Frontend Code + Log│
       └──────────────────────────────┘

Vibe UI defines five visual systems for consistent design decisions:

1. Minimalist SaaS: Monochrome restraint, precision borders, high information density, functional typography (oklch(0.12 0.01 260)).
2. Luxury Obsidian / Glass 2.0: Dark substrates, specular Fresnel highlights, subtle gold accents, controlled GPU backdrop blur budget (oklch(0.08 0.02 270)).
3. Neobrutalism: High-contrast saturated cards, hard 3px black offset geometric drop-shadows, zero blur, explicit physical boundaries (oklch(0.98 0.02 95)).
4. Swiss Editorial: Asymmetric typographic grid, content-first layout inspired by the International Typographic Style (oklch(0.97 0.005 80)).
5. Stripe Crisp Light: Developer-first documentation aesthetic, micro-borders, clean typography, subtle shadows (oklch(0.99 0.002 250)).

Production web experiences must feel tactile, responsive, and alive. Vibe UI v6.0 codifies 6 mandatory kinetic living principles:

1. Kinetic Arrow Cursor & Trailing Physics:
   • Total suppression of the default OS cursor (cursor: none !important).
   • Ultra-responsive, zero-lag glowing focal dot (#vibeCursorDot) tracking mouse coordinates 1:1.
   • Angled SVG chevron follower (#vibeCursorFollower) with spring inertia and velocity rotation physics (Math.atan2).
2. Spotlight Dot-Matrix Mesh:
   • Subtle dot-matrix substrate revealed through an interactive radial gradient spotlight cone (radial-gradient(circle at X Y, ...)).
3. Infinite Marquee Velocity Rails:
   • Hardware-accelerated ticker ribbons utilizing translate3d(0, 0, 0) to translate3d(-50%, 0, 0) with pause-on-hover and zero scroll-reveal transform collision.
4. Curated Editorial Photography (AssetDirector):
   • Automatic injection of high-resolution, thematic Unsplash editorial imagery with verified domain relevance and graceful SVG fallbacks.
5. Cinematic Stagger Scroll-Reveals:
   • Progressive IntersectionObserver triggers animating elements into view with simultaneous opacity, Y-axis translation, and blur removal.
6. Progressive Lazy Image Blur-Up:
   • High-craft image loading transition shifting from filter: blur(12px) to crisp native rendering on load.

Standard AI-generated interfaces frequently fail on Right-to-Left (RTL) languages by naively flipping the entire DOM tree with dir="rtl", inverting navigation columns, telemetry charts, and numeric sequences.

Vibe UI enforces Fixed-Structure Semantic RTL:

• Physical Macro Stability: Application layout coordinates (sidebars, toolbars, chart axes) remain physically stable.
• Content-Level RTL: RTL is applied strictly to typography, paragraphs, and reading flows using CSS logical properties (margin-inline-start, text-align: start).
• BiDi Resilience: Technical identifiers, code blocks, URLs, and telemetry HUDs are explicitly isolated with <bdi> or dir="ltr".

The repository includes an automated test runner:

# 1. Run deterministic static checks & negative fixtures
python evals/run_evals.py

# 2. Run machine-readable CI output
python evals/run_evals.py --json

# 3. Run headless browser DOM verification (Chromium via Playwright)
python evals/run_evals.py --browser

A reference production starter is available under examples/nextjs-starter/:

• Core: Next.js 15 App Router, React 19, TypeScript 5, Tailwind CSS.
• Typed OKLCH Tokens: lib/tokens.ts exporting all 5 chemistries.
• AI Primitives: AiThinkingDrawer.tsx with zero-JS CSS Grid height transitions and accessible ARIA live regions.
• Verified Clean Build: Compiles in production mode (npm run build) in CI with zero type errors.

• A contract-driven linter, design system, and verification layer for AI coding assistants.
• An orchestration DAG that separates intent, visual rules, component code, copy, and verification.
• A set of executable evaluation gates that reject measurable UI regressions with non-zero exit codes.

• It is not a guarantee that an AI-generated interface is 100% bug-free or production-ready without human review.
• It is not a replacement for comprehensive manual accessibility testing (screen readers, voice control).
• It is not an enterprise design system replacement; it is designed to bind into your existing @company/ui library via docs/ENTERPRISE_ADAPTATION.md.

Vibe UI Suite is open-source under the MIT License. We actively welcome community contributions:

• New evaluation fixtures & negative tests
• Framework adapters (Vue, Svelte, Angular)
• Component recipes for the registry
• Real-world bug reports with minimal reproductions

git clone https://github.com/omid-io/vibe-ui-suite.git
cd vibe-ui-suite
python evals/run_evals.py

Maintainer: Omid Zaferi • Issues: GitHub Issues