ui-kratos 1.0.0

package/README.md

@@ -0,0 +1,33 @@
+# Kratos UI Portal — Portable UI/UX DNA System
+
+`ui-kratos` is a zero-dependency CLI tool and highly portable "AI Skill" designed to distribute, initialize, and inspect the design tokens, visual architecture, micro-animations, and security systems of your premium dashboard template.
+
+---
+
+## Direct Execution (No Installation Required 🚀)
+
+Once published, you and your AI agents can execute it instantly without installation:
+
+### To view tokens:
+```bash
+npx ui-kratos view
+```
+
+### To generate the UI/UX DNA reference:
+```bash
+npx ui-kratos init
+```
+
+### To query for AI Agent prompts:
+```bash
+npx ui-kratos skill
+```
+
+---
+
+## Why Use `ui-kratos`?
+
+* **Zero Dependencies:** Boots instantly over `npx` with zero download overhead.
+* **Console Design Tokens:** Outputs beautifully formatted, ANSI-colored HSL palettes, shadow layers, spring constants, and motion timings right in your terminal.
+* **Portable Reference Initializer:** Spin up the unified design blueprint (`UI_UX_DNA_REFERENCE.md`) in any new workspace with `npx ui-kratos init`.
+* **AI Agent Prompt Feeding:** The `skill` command outputs dense, structured JSON. AI coding assistants can parse this directly to implement perfectly matching visual systems.

package/bin/index.js

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// ANSI Terminal Colors
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+  red: '\x1b[31m'
+};
+
+const DNA_MARKDOWN = `# Prestige Dashboard: UI/UX DNA Reference Guide
+### The Unified Design System, Visual Tokens, and Interactive Experience Guide
+
+This document captures the visual style, interaction mechanics, and design system architecture of the **Prestige Dashboard System**. It serves as a comprehensive reference (combining \`DESIGN_SYSTEM.md\` + \`DESIGN_TOKENS.md\` + \`UI_STYLE_GUIDE.md\`) to recreate, extend, or maintain the visual identity of this application.
+
+---
+
+## 1. Brand Philosophy & Identity
+
+The portal's brand identity sits at the intersection of **trustworthy enterprise authority** (inspired by McKinsey & Co.) and **hyper-modern digital execution** (inspired by Stripe). The branding values:
+*   **Absolute Compliance & Security:** Layout structures prioritize safety, print prevention, and strict document acknowledgment controls.
+*   **Visual Precision:** High-contrast elements, zero clutter, and beautiful typography.
+*   **Interactive Delight:** Understated yet highly premium micro-animations (e.g., particle explosions, liquid hover transitions, spring-loaded modals) that provide subtle feedback without detracting from corporate seriousness.
+
+---
+
+## 2. Global Design Tokens (DESIGN_TOKENS.md)
+
+### A. Color Palette
+The color system utilizes a **Microsoft Blue (#0078D4)** primary palette for Light Mode, and transitions to a Vercel-style, ultra-clean **neutral absolute dark** for Dark Mode to avoid blue light fatigue.
+
+#### **Light Mode (Corporate Blue & Sleek Slate)**
+*   \`--background\` (HSL \`210 40% 98%\`): Soft, cool blue-grey background.
+*   \`--foreground\` (HSL \`215 39% 10%\`): High-contrast dark charcoal (Stripe dark blue \`#0a2540\`).
+*   \`--primary\` (HSL \`206 100% 41%\`): The signature **Microsoft Blue (#0078D4)** corporate accent.
+*   \`--secondary\` (HSL \`215 28% 95%\`): Light, cool blue-grey for secondary cards and pills.
+*   \`--muted-foreground\` (HSL \`220 13% 41%\`): Stripe slate blue (\`#424770\`) for captions and secondary text.
+*   \`--destructive\` (HSL \`339 100% 61%\`): Stripe Danger Pink/Red (\`#ff5996\`) for destructive buttons/banners.
+*   \`--border\` / \`--input\` (HSL \`220 14% 88%\`): Delicate boundaries.
+
+#### **Dark Mode (Vercel-Style Deep Charcoal)**
+*   \`--background\` (HSL \`0 0% 4%\`): Pure pitch black, perfect for high-end dark aesthetics.
+*   \`--foreground\` (HSL \`0 0% 96%\`): Crisp white.
+*   \`--card\` (HSL \`0 0% 7%\`): Slightly elevated dark charcoal.
+*   \`--popover\` (HSL \`0 0% 9%\`): Popover elevations.
+*   \`--primary\` (HSL \`206 100% 50%\`): Electric neon-blue for dark mode clarity.
+*   \`--border\` / \`--input\` (HSL \`0 0% 16%\`): Stealth dividers.
+
+---
+
+### B. Typography & Font System
+*   **Primary Sans Font (\`--font-sans\`):** \`Inter\` (loaded via Google Fonts) is the default body font, optimized for readability.
+    *   *Typography Utility:* Configured with specialized OpenType features to enhance aesthetic appeal:
+        \`\`\`css
+        font-feature-settings: "cv02", "cv03", "cv04", "cv11";
+        \`\`\`
+        This turns on the curved lowercase \`a\`, distinct straight-top \`t\`, and unambiguous \`l\`.
+*   **Primary Mono Font (\`--font-mono\`):** \`Source Code Pro\`. In visual sections (e.g., stats or numerical indicators), this font provides clean tabular numbers layout while keeping high structural alignment.
+*   **Base Metrics:**
+    *   Base font size: \`14px\` (with standard Tailwind \`text-sm\` mappings).
+    *   Line-height: \`1.5\` for high-density readable text.
+    *   Heading adjustments: \`letter-spacing: -0.02em\` and \`font-weight: 600\`.
+
+---
+
+### C. Elevation & Shadows (Stripe Shadow Scale)
+Elevation defines layers. The app maps exactly to the custom Stripe shadow layers:
+\`\`\`css
+/* Light Mode shadows */
+--shadow-subtle:   0 1px 3px 0 rgba(50,50,93,.06), 0 1px 2px 0 rgba(0,0,0,.04);
+--shadow-raised:   0 3px 6px 0 rgba(50,50,93,.08), 0 1px 3px 0 rgba(0,0,0,.04);
+--shadow-floating: 0 6px 12px -2px rgba(50,50,93,.10), 0 3px 7px -3px rgba(0,0,0,.06);
+--shadow-overlay:  0 30px 60px -12px rgba(50,50,93,.25), 0 18px 36px -18px rgba(0,0,0,.30);
+--shadow-sidebar:  2px 0 8px -2px rgba(50,50,93,.08);
+--stripe-border:   1px solid rgba(0,0,0,.07);
+
+/* Dark Mode shadows */
+--shadow-subtle:   0 1px 3px 0 rgba(0,0,0,.20);
+--shadow-raised:   0 3px 6px 0 rgba(0,0,0,.28), 0 1px 3px 0 rgba(0,0,0,.16);
+--shadow-floating: 0 6px 12px -2px rgba(0,0,0,.36), 0 3px 7px -3px rgba(0,0,0,.24);
+--shadow-overlay:  0 30px 60px -12px rgba(0,0,0,.70), 0 18px 36px -18px rgba(0,0,0,.60);
+--shadow-sidebar:  2px 0 8px -2px rgba(0,0,0,.30);
+--stripe-border:   1px solid rgba(255,255,255,.06);
+\`\`\`
+
+---
+
+### D. Motion, Timing, & Easing
+The interaction flow is designed around clean, rapid movement curves mimicking high-end dashboard experiences.
+*   **EASING FUNCTION:** Exponential ease-out transitions:
+    \`\`\`css
+    --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+    --ease-in-out:   cubic-bezier(0.65, 0, 0.35, 1);
+    \`\`\`
+*   **DURATIONS:**
+    *   \`--duration-fast: 150ms\` (button hover, theme toggle, simple tooltips).
+    *   \`--duration-base: 250ms\` (cards, sidebar collapse, state expansions).
+    *   \`--duration-slow: 400ms\` (modal popovers, sliding views).
+
+---
+
+## 3. Layout & Structure (DESIGN_SYSTEM.md)
+
+### A. Fixed-Viewport Dashboard Layout (\`h-screen overflow-hidden\`)
+The layout structure of the dashboard is built to behave like a native desktop app, preventing natural browser scrollbars on the outer page wrapper.
+\`\`\`
++--------------------------------------------------------------+
+| ASIDE          | HEADER (Breadcrumb, theme, user menu, exit) |
+| (Collapsible)  |---------------------------------------------|
+|                | MAIN (Scrollable viewport, paddings: p-6)   |
+|                |                                             |
+|                |                                             |
+|                |                                             |
++--------------------------------------------------------------+
+\`\`\`
+*   **Sidebar Navigation (Collapsible \`aside\`):**
+    *   Expands to \`w-56\`, collapses to \`w-[52px]\` smoothly using \`.transition-[width] duration-200 ease-out\`.
+    *   On mobile, a sliding drawer overlay transitions in/out with standard touch controls.
+*   **Scroll Management:**
+    *   The \`main\` viewport has \`.overflow-y-auto\` and \`.min-h-0\` to keep content scrolling within its boundaries while keeping headers fixed.
+*   **Responsive Breakpoints:**
+    *   Paddings shift from \`p-4\` (mobile/tablet) to \`p-6\` (desktop).
+
+---
+
+## 4. Third-Party Library Directory & Visual Integration
+
+To recreate this system, specific packages are leveraged to form structural layout logic, high-performance physical models, secure parsing, and charts:
+
+### A. Headless Architecture & Logic Elements
+*   **\`@base-ui-components/react\` (v1.0.0-rc.0):** Used specifically for custom high-fidelity, float-based components like the animated tooltips. It manages collision detection, screen-boundary adjustments, and anchor configurations.
+*   **\`@radix-ui/react-*\` (Radix Primitives):** Powers WAI-ARIA compliant foundations (Accordions, Dialogs, Checkboxes, Dropdowns, Avatar, Separators, and Scroll Areas).
+*   **\`cmdk\` (v1.0.4) & \`vaul\` (v0.9.6):** Powers advanced modal search components and responsive touch drawers.
+
+### B. Micro-Animations & Springs
+*   **\`framer-motion\` & \`motion\` (v^12.38.0):** Leveraged for highly detailed layout morphs, modal scales (\`dialog-spring-in\`), custom theme swipes, and physics-based coordinate springs.
+*   **\`tailwindcss-animate\` (v^1.0.7):** Standardizes transitions within Tailwind classes using predefined keyframe timings.
+
+### C. Visual Charts & Layout Graphics
+*   **\`recharts\` (latest):** Standard React chart package rendering visual analytics (Area, Stacked Bar, and Pie Charts). Configured to match the project’s custom light and dark color variables dynamically.
+
+### D. Secure Document Streams
+*   **\`react-pdf\` (v^7.7.3) & \`pdfjs-dist\` (v^3.11.174):** Powers the secure browser document reader, rendering individual PDF pages as immutable canvas drawings without copyable underlying layers.
+*   **\`pdf-lib\` (v^1.17.1):** Operates under document compilation, structural metadata, and custom stamping utilities.
+
+---
+
+## 5. Component Patterns & Visual Design (UI_STYLE_GUIDE.md)
+
+### A. Button Design & Custom Interactions
+
+#### **1. LiquidButton (Hover Flow Effect)**
+A premium action button that appears outline-based in its static state but smoothly fills its background with color from the bottom up on hover.
+*   **Styling:**
+    \`\`\`css
+    [--liquid-button-background-color: var(--accent)]
+    [--liquid-button-color: var(--primary)]
+    \`\`\`
+    This utilizes relative positioning and a custom overflow clip layer that animates fluidly behind the text.
+*   **Variants:** Standard states (Primary Blue, Destructive Red, Green Acceptance).
+
+#### **2. IconButton (Interactive Particle Explosions)**
+IconButton triggers a burst of tiny round particles radiating from the click origin to give tactile confirmation.
+*   **Behavior:** On click, \`ParticlesEffect\` generates a key-refreshed element list, rendering a tiny sequence of floating dots which travel outwards and fade.
+
+#### **3. ThemeTogglerButton**
+A smooth, LTR sliding, interactive toggle that shifts through \`light\` (Sun), \`dark\` (Moon), and \`system\` (Monitor) modes. Uses micro-transforms on the SVG paths to morph cleanly as states resolve.
+
+---
+
+### B. Accordions
+*   Built on \`@radix-ui/react-accordion\`.
+*   **Styling:** Delicate, light gray bottom borders (\`border-b border-zinc-200 dark:border-zinc-800\`), with an elegant, rapid transition of \`0.2s ease-out\` on toggle.
+*   **Arrow Mechanics:** The Lucide \`ChevronDown\` rotates \`180\` degrees only on \`[data-state=open]\`:
+    \`\`\`css
+    [&[data-state=open]>svg]:rotate-180 transition-transform duration-200
+    \`\`\`
+
+---
+
+### C. Advanced Cursor-Tracking Tooltips
+The tooltip system is heavily customized using **Base UI Tooltips** coupled with **Framer Motion spring physics** for interactive float dynamics.
+*   **Aesthetic:** 
+    *   **Background:** \`bg-primary\` (Electric Blue).
+    *   **Text:** \`text-primary-foreground\` (White).
+    *   **Arrow:** Formed as a rotated square element (\`rotate-45\`) styled with \`bg-primary fill-primary z-50\` fitting flush against the anchor.
+*   **Interactive Spring Mechanics:** 
+    *   When the cursor hovers over the trigger, an \`onMouseMove\` event dynamically measures the event coordinates relative to the bounding box.
+    *   The \`x\` and \`y\` values are fed to Framer Motion’s physics engine:
+        \`\`\`typescript
+        const translateX = useSpring(x, { stiffness: 200, damping: 17 });
+        const translateY = useSpring(y, { stiffness: 200, damping: 17 });
+        \`\`\`
+    *   This makes the tooltip pop up at the cursor and lag slightly behind it with elastic spring mechanics as the user shifts their mouse, providing a highly premium experience.
+
+---
+
+### D. Table UIs
+Tables are styled for dense analytical data reading.
+*   **Header:** \`bg-zinc-50 dark:bg-zinc-900/80\` with a sharp border-b (\`border-zinc-200 dark:border-zinc-700\`). Small headers, uppercase with high letter spacing.
+*   **Rows:**
+    *   Delicate separator borders (\`divide-y divide-gray-200 dark:divide-zinc-800\`).
+    *   Clean hover state highlight: \`.hover:bg-zinc-100 dark:hover:bg-zinc-800/50\`.
+*   **Semantics:** Status indicators mapped to light translucent colors:
+    *   \`Active\` / \`Accepted\` -> \`bg-green-100 text-green-800\`
+    *   \`Needs Review\` / \`Overdue\` -> \`bg-yellow-100 text-yellow-800\` / \`bg-red-100 text-red-800\`
+
+---
+
+### E. Graph & Chart Patterns (Recharts)
+Analytics visualizers feature modern aesthetic traits matching the light/dark themes:
+*   **Dynamic Tooltips:** Styled using matching HSL variables for dark mode compatibility:
+    \`\`\`javascript
+    const tooltipStyle = {
+      backgroundColor: isDark ? "hsl(0 0% 9%)" : "hsl(0 0% 100%)",
+      border: \`1px solid \${isDark ? "hsl(0 0% 16%)" : "hsl(220 14% 88%)"}\`,
+      borderRadius: "8px",
+      boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1)",
+      color: isDark ? "hsl(0 0% 96%)" : "hsl(215 39% 10%)",
+    }
+    \`\`\`
+*   **Colors & Gradients:**
+    *   Bar/Area charts use soft gradient fills (opacity \`0.6\` to \`0.8\`).
+    *   Acceptance metrics display in a progression: Gray (Unassigned) -> Light Blue (Viewed) -> Primary Blue (Reviewed) -> Emerald Green (Accepted).
+
+---
+
+### F. Profile Modal & Settings
+The profile overlay operates as a centered card popup:
+*   **Identities:** Giant round initials-avatar utilizing signature primary backgrounds. Underneath, user roles are rendered as pill-badges (e.g., Super Admin in \`#0078D4\` light blue pill).
+*   **Information Rows:** Encased in a single cohesive wrapper utilizing double border elevations (\`box-shadow: var(--shadow-subtle); border: var(--stripe-border)\`).
+*   **Field Headers:** Labeled in very small, wide tracking uppercase sub-labels (\`text-[10px] font-semibold uppercase tracking-widest text-slate-400 dark:text-zinc-500\`).
+*   **Actions:** Styled like clickable list items with subtle chevron arrows on the right, providing clear affordances.
+
+---
+
+## 6. High-Fidelity Light / Dark Mode Architecture
+
+The portal features a robust theme switching system. Rather than standard sudden flashes, the app implements a custom sweeping visual mask when switching themes.
+
+### A. Next-Themes Syncing
+*   **\`next-themes\` Integration:** Manages the root class toggle (\`.dark\` on \`<html>\`). The \`ThemeProvider\` wraps the app in layout setup, setting \`attribute="class"\` and matching system preferences via \`window.matchMedia\`.
+*   **Hydration Defense:** Integrates \`suppressHydrationWarning\` on the HTML tag, keeping server-rendered templates consistent while the client resolves theme states.
+
+### B. Custom Clip-Path Wipe Wipe Transition (View Transitions API)
+The theme toggler does not immediately swap colors. If supported, it runs a spectacular full-viewport sweeping reveal.
+
+\`\`\`
+VIEWPORT:
++------------------------------------------+
+|  [Click Theme Toggle]                    |
+|  [Capture Visual State of Old Theme]      |
+|                                          |
+|  SWIPE DIRECTION (LTR) ->                |
+|  +=========+                             |
+|  | NEW     |  CLIP MASK: inset(0 0 0 0)  |
+|  | THEME   |                             |
+|  | VISUALS |                             |
+|  +=========+                             |
+|  CLIP BOUNDARY: inset(0 100% 0 0)        |
++------------------------------------------+
+\`\`\`
+
+1.  **View State Capture:** When a theme toggle is clicked, the primitive checks browser support:
+    \`\`\`typescript
+    if (!document.startViewTransition) {
+      setTheme(theme); // Fallback to instant swap
+      return;
+    }
+    \`\`\`
+2.  **Synchronous Dom Updates:** If supported, \`document.startViewTransition\` captures a screenshot of the existing theme. Inside the transition callback, \`flushSync\` from \`react-dom\` forces the state update immediately:
+    \`\`\`typescript
+    await document.startViewTransition(() => {
+      flushSync(() => {
+        setPreview({ effective: theme, resolved });
+        document.documentElement.classList.toggle('dark', resolved === 'dark');
+      });
+    }).ready;
+    \`\`\`
+3.  **Clip-Path Waving Animation (Web Animations API):** Once ready, the root element triggers a clip path sweeping reveal:
+    \`\`\`typescript
+    document.documentElement.animate(
+      { clipPath: ['inset(0 100% 0 0)', 'inset(0 0 0 0)'] }, // LTR sweep
+      {
+        duration: 700,
+        easing: 'ease-in-out',
+        pseudoElement: '::view-transition-new(root)',
+      }
+    )
+    \`\`\`
+    This sweeps the screen from left to right smoothly. The direction coordinates support custom masking mappings (Left-to-Right, Right-to-Left, Top-to-Bottom, and Bottom-to-Top).
+4.  **Transition Blinks Avoidance:** Leverages customized global styles to disable standard cross-fades during the clip mask swipe:
+    \`\`\`css
+    ::view-transition-old(root), ::view-transition-new(root) {
+      animation: none;
+      mix-blend-mode: normal;
+    }
+    \`\`\`
+
+---
+
+## 7. Interaction Styles & UX Workflows
+
+### A. Security & Copy Protection Mechanisms
+To maintain high compliance and prevent intellectual property theft:
+1.  **Selection Blocking:** Apply copy locks across policy content wrappers using CSS:
+    \`\`\`css
+    .policy-content {
+      -webkit-user-select: none;
+      -moz-user-select: none;
+      -ms-user-select: none;
+      user-select: none;
+      -webkit-touch-callout: none;
+      -webkit-tap-highlight-color: transparent;
+    }
+    \`\`\`
+2.  **PDF Scraping Defenses:** SecurePdfModal loads and renders individual PDF pages as **pure image canvas layers**, omitting \`renderTextLayer={false}\` and \`renderAnnotationLayer={false}\` entirely. This prevents users from inspecting DOM elements or scraping text from policy documents.
+3.  **Print Prevention:** If a user tries to trigger a browser print action, the screen is hidden via print media CSS:
+    \`\`\`css
+    @media print {
+      body { display: none !important; }
+    }
+    \`\`\`
+`;
+
+const DNA_JSON = {
+  appName: "Prestige Dashboard System",
+  brandPhilosophy: "Trustworthy enterprise authority meets hyper-modern visual execution.",
+  typography: {
+    bodyFont: "Inter",
+    monospaceFont: "Source Code Pro",
+    specialFeatures: ["cv02", "cv03", "cv04", "cv11"]
+  },
+  colors: {
+    light: {
+      background: "hsl(210 40% 98%)",
+      foreground: "hsl(215 39% 10%)",
+      primary: "hsl(206 100% 41%) [Microsoft Blue #0078D4]",
+      destructive: "hsl(339 100% 61%) [Stripe Danger #ff5996]"
+    },
+    dark: {
+      background: "hsl(0 0% 4%) [Vercel Absolute Dark]",
+      card: "hsl(0 0% 7%)",
+      primary: "hsl(206 100% 50%)",
+      border: "hsl(0 0% 16%)"
+    }
+  },
+  shadowScale: {
+    subtle: "0 1px 3px 0 rgba(50,50,93,.06)",
+    raised: "0 3px 6px 0 rgba(50,50,93,.08) [Stripe Raised]"
+  },
+  motion: {
+    easing: "cubic-bezier(0.16, 1, 0.3, 1) [Expo-out]",
+    durations: { fast: "150ms", base: "250ms", slow: "400ms" }
+  },
+  customEffects: {
+    themeToggler: "Wipe wipe mask driven by native CSS View Transitions and clip-paths",
+    tooltipSpring: "Elastic cursor-tracking tooltip floating vectors (stiffness: 200, damping: 17)",
+    liquidButton: "Outline state with dynamic bottom-up liquid fluid overflow fills",
+    iconParticles: "Key-refreshed radial particle burst explosion on click events"
+  },
+  complianceShields: {
+    scrapingProtection: "Canvas-only react-pdf rendering disabling selection layers",
+    copyBlock: "Selection locks and context disabling",
+    printBlock: "Media query body hidden locks"
+  }
+};
+
+function printBanner() {
+  console.log(`\n${C.bold}${C.blue}================================================================${C.reset}`);
+  console.log(`${C.bold}${C.cyan}    _  __ ____    _  _____ ___  ____   _   _ ___                ${C.reset}`);
+  console.log(`${C.bold}${C.cyan}   | |/ /|  _ \\  / \\|_   _/ _ \\/ ___| | | | |_ _|               ${C.reset}`);
+  console.log(`${C.bold}${C.cyan}   | ' / | |_) |/ _ \\ | || | | \\___ \\ | | |  | |                ${C.reset}`);
+  console.log(`${C.bold}${C.cyan}   | . \\ |  _ < / ___ \\| || |_| |___) || |_|  | |                ${C.reset}`);
+  console.log(`${C.bold}${C.cyan}   |_|\\_\\|_| \\_/_/   \\_\\_| \\___/|____/  \\___/|___|               ${C.reset}`);
+  console.log(`${C.bold}${C.blue}----------------------------------------------------------------${C.reset}`);
+  console.log(`     ${C.bold}${C.magenta}Kratos UI Portal — Portable UI/UX DNA System${C.reset}`);
+  console.log(`${C.bold}${C.blue}================================================================${C.reset}\n`);
+}
+
+function handleHelp() {
+  printBanner();
+  console.log(`${C.bold}AVAILABLE COMMANDS:${C.reset}\n`);
+  console.log(`  ${C.bold}${C.green}init${C.reset}     Initialize and output the ${C.bold}UI_UX_DNA_REFERENCE.md${C.reset} file inside the current directory.`);
+  console.log(`  ${C.bold}${C.green}view${C.reset}     Output design tokens, color HSL codes, and physics springs to console.`);
+  console.log(`  ${C.bold}${C.green}skill${C.reset}    Output detailed, dense JSON token properties for AI Agent context feeding.`);
+  console.log(`  ${C.bold}${C.green}help${C.reset}     Show this help guide.\n`);
+  console.log(`${C.dim}Usage: npx ui-kratos <command>${C.reset}\n`);
+}
+
+function handleInit() {
+  const targetPath = path.join(process.cwd(), 'UI_UX_DNA_REFERENCE.md');
+  try {
+    fs.writeFileSync(targetPath, DNA_MARKDOWN, 'utf8');
+    printBanner();
+    console.log(`✨ ${C.bold}${C.green}Success!${C.reset} UI/UX DNA Reference file initialized at:`);
+    console.log(`📂 ${C.bold}${C.cyan}${targetPath}${C.reset}\n`);
+    console.log(`You can now read this document in your IDE to replicate the visual system.`);
+  } catch (err) {
+    console.error(`❌ ${C.bold}${C.red}Error writing reference document:${C.reset}`, err.message);
+  }
+}
+
+function handleView() {
+  printBanner();
+  console.log(`${C.bold}${C.cyan}--- VISUAL SYSTEM DESIGN TOKENS ---${C.reset}\n`);
+  
+  console.log(`${C.bold}1. LIGHT MODE HSL PALETTE:${C.reset}`);
+  console.log(`   🎨 Primary Color:    ${C.green}HSL 206 100% 41%${C.reset} (Microsoft Blue #0078D4)`);
+  console.log(`   🎨 Background:       ${C.green}HSL 210 40% 98%${C.reset}  (Soft grey-blue)`);
+  console.log(`   🎨 Secondary/Muted:  ${C.green}HSL 215 28% 95%${C.reset}  (Cool grey)`);
+  console.log(`   🎨 Destructive:      ${C.green}HSL 339 100% 61%${C.reset} (Stripe Danger #ff5996)`);
+  console.log();
+
+  console.log(`${C.bold}2. DARK MODE HSL PALETTE (Vercel Neutral Dark):${C.reset}`);
+  console.log(`   🎨 Canvas Base:      ${C.cyan}HSL 0 0% 4%${C.reset}    (Absolute Black)`);
+  console.log(`   🎨 Surface Card:     ${C.cyan}HSL 0 0% 7%${C.reset}    (Elevated Charcoal)`);
+  console.log(`   🎨 Electric Accent:  ${C.cyan}HSL 206 100% 50%${C.reset} (Neon Blue)`);
+  console.log(`   🎨 Subtle Border:    ${C.cyan}HSL 0 0% 16%${C.reset}   (Dark stealth divider)`);
+  console.log();
+
+  console.log(`${C.bold}3. SPRING INERTIA VECTOR CODES:${C.reset}`);
+  console.log(`   💫 Tooltip stiffness: ${C.yellow}200${C.reset}`);
+  console.log(`   💫 Tooltip damping:   ${C.yellow}17${C.reset}`);
+  console.log(`   💫 Modal transitions: ${C.yellow}stiffness: 300, damping: 25${C.reset}`);
+  console.log();
+
+  console.log(`${C.bold}4. MICRO-ANIMATIONS ARCHITECTURE:${C.reset}`);
+  console.log(`   ✨ Theme Switches:   ${C.magenta}Browser View Transitions API + Clip-Path sweep animations (700ms LTR)${C.reset}`);
+  console.log(`   ✨ Hover Action:     ${C.magenta}LiquidButton bottom-up clip fills${C.reset}`);
+  console.log(`   ✨ Click Burst:      ${C.magenta}IconButton key-refreshed multi-colored particle bursts${C.reset}`);
+  console.log();
+}
+
+function handleSkill() {
+  // Output clean, dense stringified JSON for AI agents to load as prompt context
+  console.log(JSON.stringify(DNA_JSON, null, 2));
+}
+
+// Route Commands
+const command = process.argv[2] ? process.argv[2].toLowerCase() : 'help';
+
+switch (command) {
+  case 'init':
+    handleInit();
+    break;
+  case 'view':
+  case 'tokens':
+    handleView();
+    break;
+  case 'skill':
+  case 'agent':
+    handleSkill();
+    break;
+  case 'help':
+  default:
+    handleHelp();
+    break;
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "ui-kratos",
+  "version": "1.0.0",
+  "description": "Portable CLI tool and AI skill for the Prestige Dashboard UI/UX DNA system.",
+  "main": "bin/index.js",
+  "bin": {
+    "ui-kratos": "./bin/index.js"
+  },
+  "keywords": [
+    "prestige-ui",
+    "design-system",
+    "design-tokens",
+    "ai-agent",
+    "ai-skill",
+    "view-transitions",
+    "tailwind"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "author": "",
+  "license": "MIT"
+}