vibe-ui-suite 4.0.0

package/README.md

@@ -0,0 +1,151 @@
+# vibe-ui-suite
+
+<p align="center">
+  <strong>Deterministic design contracts, component recipes, and WCAG evaluation gates for AI coding agents.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/vibe-ui-suite"><img src="https://img.shields.io/npm/v/vibe-ui-suite?color=blue&style=flat-square" alt="NPM Version" /></a>
+  <a href="https://marketplace.visualstudio.com/items?itemName=omid-io.vibe-ui-vscode"><img src="https://img.shields.io/visual-studio-marketplace/v/omid-io.vibe-ui-vscode?color=blue&style=flat-square&logo=visual-studio-code" alt="VS Code Marketplace" /></a>
+  <a href="https://open-vsx.org/extension/omid-io/vibe-ui-vscode"><img src="https://img.shields.io/open-vsx/v/omid-io/vibe-ui-vscode?color=blue&style=flat-square" alt="Open-VSX Version" /></a>
+  <a href="https://github.com/omid-io/vibe-ui-suite/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" /></a>
+</p>
+
+---
+
+## ⚡ What is Vibe UI Suite?
+
+Modern AI coding agents (Cursor, Claude Code, Windsurf, v0) are fast, but they often produce **"AI Slop"**:
+- Clichéd, low-contrast purple/indigo gradients that fail basic accessibility (WCAG AA).
+- Uncalibrated spacing, broken mobile layouts, and excessive blur overlays.
+- Broken bidirectional text (RTL/BiDi) and inverted business formulas.
+
+**`vibe-ui-suite`** acts as a **machine-verifiable design linter and contrast gatekeeper**. It equips your project with typed OKLCH color spaces, physics animation curves, accessible component recipes, and automated editor rule contracts (`.cursorrules`, `CLAUDE.md`, `.windsurfrules`).
+
+---
+
+## 🚀 Quick Start (3 Seconds)
+
+### 1. Initialize Workspace Contracts (`init`)
+
+Scaffold AI editor contracts and OKLCH CSS variables in your project with zero manual configuration:
+
+```bash
+npx vibe-ui-suite init
+```
+
+This interactive command sets up:
+- `.cursorrules` / `CLAUDE.md` / `.windsurfrules` with strict anti-slop invariants.
+- 5 distinct visual chemistry themes (Minimalist SaaS, Swiss Editorial, Neobrutalism, Luxury Glass 2.0, Stripe Crisp Light).
+- Native Tailwind CSS v4 variables or Tailwind v3 configuration.
+
+---
+
+### 2. Add Accessible Component Primitives (`add`)
+
+Add verified, zero-emoji, accessible React 19 component templates directly into your codebase (`components/vibe-ui/`):
+
+```bash
+# Add an expandable reasoning / thinking trace drawer
+npx vibe-ui-suite add thinking-drawer
+
+# Add a dense telemetry HUD with live metric formatting
+npx vibe-ui-suite add telemetry-hud
+
+# Add a real-time WCAG AAA contrast indicator badge
+npx vibe-ui-suite add contrast-badge
+```
+
+### 3. List Registry Components (`list`)
+
+```bash
+npx vibe-ui-suite list
+```
+
+---
+
+## 🎨 Programmatic Usage
+
+### 1. Native Tailwind CSS v4 (`@theme`) — Recommended
+
+In your global stylesheet (e.g. `app/globals.css` or `src/index.css`):
+
+```css
+@import "tailwindcss";
+@import "vibe-ui-suite/v4.css";
+```
+
+Zero JavaScript configuration files required. Instantly unlocks:
+- **Semantic Color Utilities:** `bg-vibe-canvas`, `bg-vibe-surface`, `text-vibe-primary`, `border-vibe-border`
+- **Physics Springs:** `transition-vibe-spring`, `transition-vibe-snap`, `transition-vibe-glide`
+- **Surface Elevation:** `shadow-vibe-brutal`, `shadow-vibe-glass`
+
+---
+
+### 2. Direct Token Imports (TypeScript / JavaScript)
+
+Access typed OKLCH color spaces and mathematical contrast verification utilities:
+
+```typescript
+import { VISUAL_CHEMISTRIES, MOTION_CURVES, getContrastRatio } from 'vibe-ui-suite';
+
+// Access typed OKLCH color tokens
+const saasColors = VISUAL_CHEMISTRIES.MINIMALIST_SAAS.colors;
+console.log(saasColors.primaryAccent); // 'oklch(0.65 0.22 260)'
+
+// Verify real-time WCAG contrast mathematics
+const contrast = getContrastRatio('#0F172A', '#F8FAFC');
+console.log(`Contrast ratio: ${contrast.toFixed(2)}:1`); // e.g. 15.8:1 (AAA Certified)
+```
+
+---
+
+### 3. Tailwind CSS v3 Legacy Plugin (Backward Compatible)
+
+In your `tailwind.config.js` or `tailwind.config.ts`:
+
+```javascript
+import vibeUiPlugin from 'vibe-ui-suite/tailwind';
+
+export default {
+  content: ['./app/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}'],
+  plugins: [vibeUiPlugin],
+};
+```
+
+---
+
+## 🛠️ CLI Command Reference
+
+| Command | Description |
+| :--- | :--- |
+| `npx vibe-ui-suite init` | Interactively scaffold AI editor contracts & OKLCH variables |
+| `npx vibe-ui-suite init --dry-run` | Preview file operations without modifying disk |
+| `npx vibe-ui-suite add <name>` | Copy an accessible component primitive into `components/vibe-ui/` |
+| `npx vibe-ui-suite add <name> -f` | Overwrite existing component with automated `.bak` backup |
+| `npx vibe-ui-suite list` | List all available component primitives in the registry |
+| `npx vibe-ui-suite -v` | Display installed version |
+| `npx vibe-ui-suite -h` | Display full help menu |
+
+---
+
+## 🧩 Companion IDE Extensions
+
+Install the companion extension for real-time contrast auditing, instant color inspection, and 1-click component templates right inside your editor:
+
+- **VS Code Marketplace:** [`omid-io.vibe-ui-vscode`](https://marketplace.visualstudio.com/items?itemName=omid-io.vibe-ui-vscode)
+- **Open-VSX Registry:** [`omid-io.vibe-ui-vscode`](https://open-vsx.org/extension/omid-io/vibe-ui-vscode) (for Cursor, Windsurf, VSCodium)
+
+---
+
+## 🌐 Community & Ecosystem
+
+- **Documentation & Live Showcase:** [https://omid-io.github.io/vibe-ui-suite/](https://omid-io.github.io/vibe-ui-suite/)
+- **GitHub Repository:** [https://github.com/omid-io/vibe-ui-suite](https://github.com/omid-io/vibe-ui-suite)
+- **Issue Tracker:** [https://github.com/omid-io/vibe-ui-suite/issues](https://github.com/omid-io/vibe-ui-suite/issues)
+
+---
+
+## 📄 License
+
+MIT © [Omid Zaferi](https://github.com/omid-io)

package/build.js

@@ -0,0 +1,23 @@
+const fs = require('fs');
+const path = require('path');
+
+const srcDistDir = path.resolve(__dirname, '../tokens/dist');
+const targetDistDir = path.resolve(__dirname, 'dist');
+
+if (!fs.existsSync(srcDistDir)) {
+  console.error('Error: ../tokens/dist does not exist. Please build @omid-io/tokens first.');
+  process.exit(1);
+}
+
+// Copy recursively from tokens/dist to vibe-ui-suite/dist
+fs.cpSync(srcDistDir, targetDistDir, { recursive: true });
+
+// Ensure executable permission on dist/cli.js
+const cliPath = path.join(targetDistDir, 'cli.js');
+if (fs.existsSync(cliPath)) {
+  try {
+    fs.chmodSync(cliPath, 0o755);
+  } catch (e) {}
+}
+
+console.log('✅ vibe-ui-suite build complete: synchronized dist/ from tokens package.');

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const components_1 = require("./registry/components");
+const index_1 = require("./index");
+const VERSION = '4.0.0';
+function printBanner() {
+    console.log(`
+\x1b[35m  ▲ VIBE UI CLI v${VERSION}\x1b[0m
+  \x1b[90mDeterministic UI contracts & component primitives for AI coding assistants\x1b[0m
+`);
+}
+function printHelp() {
+    printBanner();
+    console.log(`\x1b[1mUSAGE:\x1b[0m
+  npx vibe-ui-suite <command> [options]
+  npx @omid-io/tokens <command> [options]
+  vibe-ui <command> [options]
+
+\x1b[1mCOMMANDS:\x1b[0m
+  \x1b[32minit\x1b[0m               Initialize Vibe UI contracts, OKLCH tokens & AI rules in current project
+  \x1b[32madd <component>\x1b[0m     Add an accessible, AI-native component template to your project
+  \x1b[32mlist\x1b[0m               List all available component primitives in the registry
+
+\x1b[1mOPTIONS:\x1b[0m
+  -f, --force        Overwrite existing files (creates automated .bak backups)
+  --dry-run          Preview file operations without making actual modifications
+  -v, --version      Show CLI version
+  -h, --help         Show help menu
+
+\x1b[1mEXAMPLES:\x1b[0m
+  npx vibe-ui-suite init
+  npx vibe-ui-suite init --dry-run
+  npx vibe-ui-suite add thinking-drawer
+  npx vibe-ui-suite add thinking-drawer --force
+`);
+}
+function prompt(rl, query) {
+    return new Promise((resolve) => rl.question(query, resolve));
+}
+function safeWriteFile(filePath, content, options) {
+    const relPath = path.relative(process.cwd(), filePath);
+    if (options.dryRun) {
+        console.log(`  \x1b[34m[dry-run]\x1b[0m Would write: ${relPath}`);
+        return { written: false, skipped: false };
+    }
+    if (fs.existsSync(filePath) && !options.force) {
+        console.log(`  \x1b[33m[skip]\x1b[0m ${relPath} already exists. (Use --force to overwrite)`);
+        return { written: false, skipped: true };
+    }
+    if (fs.existsSync(filePath) && options.force) {
+        const backupPath = `${filePath}.bak`;
+        fs.copyFileSync(filePath, backupPath);
+        fs.writeFileSync(filePath, content, 'utf-8');
+        console.log(`  \x1b[35m[backup]\x1b[0m Backed up existing file to ${path.relative(process.cwd(), backupPath)}`);
+        return { written: true, skipped: false, backup: backupPath };
+    }
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return { written: true, skipped: false };
+}
+const CONTRACT_RULES = `# Vibe UI Design & Code Quality Contract
+# Generated via npx vibe-ui-suite init
+
+Follow strict anti-slop guidelines:
+- Zero raw unicode emojis (use inline SVGs only)
+- Strict WCAG 2.2 AA contrast (>= 4.5:1 body, >= 3.0:1 headings)
+- Use typed OKLCH color spaces for perceptual accuracy
+- Strict maximum of 3 backdrop-filter / glass layers
+- Semantic RTL: preserve physical macro coordinate stability
+`;
+async function handleInit(options) {
+    printBanner();
+    if (options.dryRun) {
+        console.log('\x1b[34m[DRY-RUN MODE ACTIVATED: No files will be modified on disk]\x1b[0m\n');
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        console.log('\x1b[1mInitialize Vibe UI in current workspace:\x1b[0m\n');
+        // 1. Select Visual Chemistry
+        console.log('\x1b[36m1. Select Visual Chemistry:\x1b[0m');
+        console.log('  [1] Minimalist SaaS (Monochrome restraint, high signal - Recommended)');
+        console.log('  [2] Luxury Glass 2.0 (Specular Fresnel, deep dark, gold accents)');
+        console.log('  [3] Neobrutalism (Hard 3px black offset shadows, bold high saturation)');
+        console.log('  [4] Swiss Editorial (Asymmetric grid, typography-first, high contrast)');
+        console.log('  [5] Stripe Crisp Light (Developer docs, precision micro-borders)');
+        const chemChoice = (await prompt(rl, 'Choice [1-5] (default: 1): ')).trim() || '1';
+        const chemMap = {
+            '1': 'MINIMALIST_SAAS',
+            '2': 'LUXURY_GLASS_2',
+            '3': 'NEOBRUTALISM',
+            '4': 'SWISS_EDITORIAL',
+            '5': 'STRIPE_CRISP_LIGHT',
+        };
+        const selectedChemKey = chemMap[chemChoice] || 'MINIMALIST_SAAS';
+        const selectedChem = index_1.VISUAL_CHEMISTRIES[selectedChemKey];
+        // 2. Select AI Editor
+        console.log('\n\x1b[36m2. Select AI Coding Environment:\x1b[0m');
+        console.log('  [1] Cursor (.cursorrules - Recommended)');
+        console.log('  [2] Claude Code (CLAUDE.md)');
+        console.log('  [3] Windsurf (.windsurfrules)');
+        console.log('  [4] All of the above');
+        const editorChoice = (await prompt(rl, 'Choice [1-4] (default: 1): ')).trim() || '1';
+        // 3. Write contract rules safely
+        const cwd = process.cwd();
+        const createdFiles = [];
+        if (editorChoice === '1' || editorChoice === '4') {
+            const res = safeWriteFile(path.join(cwd, '.cursorrules'), CONTRACT_RULES, options);
+            if (res.written)
+                createdFiles.push('.cursorrules');
+        }
+        if (editorChoice === '2' || editorChoice === '4') {
+            const claudePath = path.join(cwd, 'CLAUDE.md');
+            if (options.dryRun) {
+                console.log('  \x1b[34m[dry-run]\x1b[0m Would update CLAUDE.md');
+            }
+            else if (fs.existsSync(claudePath)) {
+                fs.appendFileSync(claudePath, `\n\n${CONTRACT_RULES}`, 'utf-8');
+                createdFiles.push('CLAUDE.md (appended)');
+            }
+            else {
+                const res = safeWriteFile(claudePath, CONTRACT_RULES, options);
+                if (res.written)
+                    createdFiles.push('CLAUDE.md');
+            }
+        }
+        if (editorChoice === '3' || editorChoice === '4') {
+            const res = safeWriteFile(path.join(cwd, '.windsurfrules'), CONTRACT_RULES, options);
+            if (res.written)
+                createdFiles.push('.windsurfrules');
+        }
+        // 4. Generate CSS Tokens file safely
+        const cssContent = `:root {
+  /* Vibe UI Chemistry: ${selectedChem.name} (${selectedChem.id}) */
+  --vibe-canvas: ${selectedChem.colors.canvas};
+  --vibe-surface: ${selectedChem.colors.surface};
+  --vibe-border: ${selectedChem.colors.border};
+  --vibe-primary-accent: ${selectedChem.colors.primaryAccent};
+  --vibe-text-primary: ${selectedChem.colors.textPrimary};
+  --vibe-text-muted: ${selectedChem.colors.textMuted};
+  --vibe-ring: ${selectedChem.colors.ring};
+}
+`;
+        const cssPath = path.join(cwd, 'vibe-tokens.css');
+        const cssRes = safeWriteFile(cssPath, cssContent, options);
+        if (cssRes.written)
+            createdFiles.push('vibe-tokens.css');
+        console.log('\n\x1b[32m✔ Initialized successfully!\x1b[0m');
+        if (createdFiles.length > 0) {
+            console.log('\x1b[90mGenerated/Updated files:\x1b[0m');
+            createdFiles.forEach((f) => console.log(`  + ${f}`));
+        }
+        console.log(`
+\x1b[1mNext Steps:\x1b[0m
+1. Import \x1b[35mvibe-tokens.css\x1b[0m into your layout or globals.css
+2. Run \x1b[32mnpx @omid-io/tokens add thinking-drawer\x1b[0m to add your first AI component
+`);
+    }
+    finally {
+        rl.close();
+    }
+}
+function handleAdd(componentName, options = { force: false, dryRun: false }) {
+    if (!componentName) {
+        console.log('\x1b[33mError: Please specify a component to add.\x1b[0m\n');
+        handleList();
+        console.log('\nUsage: npx @omid-io/tokens add <component> [--force]');
+        process.exit(1);
+        return;
+    }
+    const comp = components_1.COMPONENT_REGISTRY[componentName.toLowerCase()];
+    if (!comp) {
+        console.log(`\x1b[31mError: Unknown component "${componentName}".\x1b[0m\n`);
+        handleList();
+        process.exit(1);
+        return;
+    }
+    const cwd = process.cwd();
+    const targetDir = path.join(cwd, 'components', 'vibe-ui');
+    if (!options.dryRun) {
+        fs.mkdirSync(targetDir, { recursive: true });
+    }
+    const targetFile = path.join(targetDir, comp.filename);
+    const writeRes = safeWriteFile(targetFile, comp.code, options);
+    if (writeRes.skipped) {
+        console.log(`\n\x1b[33mWarning: Component already exists at components/vibe-ui/${comp.filename}\x1b[0m`);
+        console.log(`To overwrite with automated .bak backup, re-run with:`);
+        console.log(`  \x1b[32mnpx @omid-io/tokens add ${componentName} --force\x1b[0m\n`);
+        return;
+    }
+    if (writeRes.written) {
+        console.log(`\x1b[32m✔ Added component "${comp.name}"!\x1b[0m`);
+        console.log(`  \x1b[90mLocation:\x1b[0m components/vibe-ui/${comp.filename}`);
+        console.log(`  \x1b[90mDescription:\x1b[0m ${comp.description}\n`);
+        console.log(`\x1b[1mUsage in your page or view:\x1b[0m`);
+        console.log(`  import { ${comp.filename.replace('.tsx', '')} } from '@/components/vibe-ui/${comp.filename.replace('.tsx', '')}';\n`);
+    }
+}
+function handleList() {
+    console.log('\x1b[1mAvailable Vibe UI Components:\x1b[0m');
+    Object.values(components_1.COMPONENT_REGISTRY).forEach((comp) => {
+        console.log(`  \x1b[32m${comp.name.padEnd(18)}\x1b[0m \x1b[90m${comp.description}\x1b[0m`);
+    });
+}
+async function main() {
+    const rawArgs = process.argv.slice(2);
+    const force = rawArgs.includes('--force') || rawArgs.includes('-f');
+    const dryRun = rawArgs.includes('--dry-run');
+    const filteredArgs = rawArgs.filter((a) => !['--force', '-f', '--dry-run'].includes(a));
+    const cmd = filteredArgs[0]?.toLowerCase();
+    const options = { force, dryRun };
+    if (!cmd || cmd === '--help' || cmd === '-h') {
+        printHelp();
+        return;
+    }
+    if (cmd === '--version' || cmd === '-v') {
+        console.log(`v${VERSION}`);
+        return;
+    }
+    switch (cmd) {
+        case 'init':
+            await handleInit(options);
+            break;
+        case 'add':
+            handleAdd(filteredArgs[1], options);
+            break;
+        case 'list':
+            printBanner();
+            handleList();
+            break;
+        default:
+            console.log(`\x1b[31mUnknown command "${cmd}".\x1b[0m`);
+            printHelp();
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error('\x1b[31mFatal CLI error:\x1b[0m', err);
+    process.exit(1);
+});