vibe-ui-suite 4.8.0 → 6.3.0

package/README.md

@@ -46,14 +46,18 @@ This interactive command sets up:
 Add verified, zero-emoji, accessible React 19 component templates directly into your codebase (`components/vibe-ui/`):
 
 ```bash
-# Add an expandable reasoning / thinking trace drawer
+# Core AI & Telemetry Primitives:
 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
+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
 ```
 
 ### 3. List Registry Components (`list`)
@@ -62,6 +66,13 @@ npx vibe-ui-suite add contrast-badge
 npx vibe-ui-suite list
 ```
 
+### 4. Galaxy Inspiration Engine (`inspire`)
+
+Search 3,800+ community micro-interactions with offline caching:
+```bash
+npx vibe-ui-suite inspire "neon button"
+```
+
 ---
 
 ## 🎨 Programmatic Usage

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vibe-ui-suite",
-  "version": "4.8.0",
-  "description": "Deterministic design contracts, component recipes, and WCAG AA evaluation gates for AI coding agents (Cursor, Claude Code, Windsurf, Antigravity).",
+  "version": "6.3.0",
+  "description": "Deterministic design contracts, 11 visual paradigms, flagship component recipes, and WCAG AA evaluation gates for AI coding agents.",
   "bin": {
     "vibe-ui-suite": "./dist/cli.js",
     "vibe-ui": "./dist/cli.js"
@@ -21,15 +21,30 @@
       "require": "./dist/tailwind.js"
     },
     "./v4": "./dist/v4.css",
-    "./v4.css": "./dist/v4.css"
+    "./v4.css": "./dist/v4.css",
+    "./registry": {
+      "types": "./dist/registry/components.d.ts",
+      "import": "./dist/registry/components.mjs",
+      "require": "./dist/registry/components.js"
+    },
+    "./registry/*": {
+      "types": "./dist/registry/*.d.ts",
+      "import": "./dist/registry/*.mjs",
+      "require": "./dist/registry/*.js"
+    }
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "scripts": {
     "build": "node build.js"
   },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.3"
+  },
   "keywords": [
     "vibe-ui",
     "vibe-ui-suite",

package/skills/autonomous-intent-expander/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: autonomous-intent-expander
+description: Streamlined intent expansion engine that synthesizes architectural specifications from sparse prompts anchored in the Two Golden Pillars (Trend Inspiration & Living Visual Feedback).
+triggers: ["expand intent", "auto-spec", "read my mind", "full architecture", "scale this", "deepen constraints", "lazy prompt", "complete website design", "requirements spec"]
+---
+
+# 🧠 Autonomous Intent Expander (v6.1.1 Architecture Core)
+
+## 🎯 Purpose & Philosophy
+The `autonomous-intent-expander` skill eliminates friction and interrogation fatigue while preventing blind hallucinations. When a user provides a minimal or ambiguous prompt (e.g., *"Build gym website"*, *"Design aesthetic dental clinic website"*), this engine applies **opinionated default inference** strictly governed by **The 5 Immutable Execution Gates (پروتکل ۵ مرحله ای مهندسی شاهکار)**:
+1. **Gate 1: Intent & Domain Deliberation** (Deeply understanding persona, trust factors, conversion goals, and enforcing crisp Light-First canvas with unbounded deliberate craft).
+2. **Gate 2: Deep Trend & Pattern Hunting** (Benchmarking premier aesthetics from Dribbble, Figma Community, Mobbin, and Awwwards; harvesting Galaxy micro-interactions; planning real HD media).
+3. **Gate 3: Clean Semantic Architecture & Library Synthesis** (Standard React 19, Tailwind v4, Lucide vector icons, and typed OKLCH tokens with zero imaginary packages).
+4. **Gate 4: Multi-Viewport Living Visual Audit & Self-Critique** (Mandatory browser rendering, Desktop 1440px / Mobile 390px screenshots into `screenshots/`, and multimodal self-correction).
+5. **Gate 5: Dual Functional & Mathematical Quality Assurance** (Verifying 100% interactive state feedback, WCAG AAA contrast >= 18:1, 0px horizontal overflow, and zero raw emojis).
+
+
+---
+
+## ⚙️ Operating Rules & Ambiguity Budget
+
+1. **The 3-Tier Ambiguity Budget:**
+   - **Tier 1: Visual, Aesthetic & Component Selection (100% Autonomous):**
+     Do NOT interrogate the user for layout, color palettes, visual chemistries, or component choices. Select the most cohesive, modern default and implement it directly.
+   - **Tier 2: Product Architecture & Standard Workflows (Autonomous with Stated Assumptions):**
+     Infer standard industry user flows and data shapes. Always report these under a clear `⚠️ Assumptions Made:` section so the user can steer if needed, without halting execution.
+   - **Tier 3: High-Risk Logic, Financials, Auth & Legal/Compliance (Zero Guesswork):**
+     Never blindly guess transaction logic, payment split math, HIPAA/GDPR constraints, or authentication models. If critical information is missing that changes liability or data integrity, surface the exact decision fork.
+
+2. **Domain Archetype & 24 Taxonomy Classification:**
+   The expander queries `scripts/search.py` (<10ms zero-token retrieval) and aligns with the 24 canonical domains in `data/taxonomy.json`, 24 architectural blueprints in `data/domain_blueprints.json`, and 26 orthogonal style families in `data/styles.json`:
+   - `beauty_clinical_wellness` (Quiet Luxury / Soft Humanist / Warm Light)
+   - `fintech_banking` (Clean Stripe / Minimal Swiss / High-Trust Light)
+   - `crypto_trading_web3` (Linear Dark / Terminal HUD / Live Telemetry)
+   - `devops_cloud_terminal` (Data-Dense Terminal / Linear Dark)
+   - `saas_b2b_enterprise` (Clean Stripe / Minimal Swiss / Executive ROI)
+   - `ai_developer_platform` (Linear Dark / Modern Glass 2.0 / Reasoning HUD)
+   - `creative_portfolio_agency` (Neo-Brutalism / Editorial / Magnetic Bento)
+   - Plus 17 additional specialized domains with bilingual Persian/English blueprints.
+   - **Stack-Sensor Integration:** Automatically detects React 18/19, Tailwind v3/v4, and existing CSS tokens via `vibe_core.stack_sensor`.
+
+2.1. **Fast Zero-Token Retrieval Command:**
+   ```bash
+   python scripts/search.py "<user prompt>" --pretty
+   ```
+
+3. **The 6-Dimensional Streamlined Architecture:**
+   Instead of overwhelming the agent's attention window with legacy parameter bloat, the expander synthesizes 6 essential dimensions:
+   1. **D1: Domain Archetype & Target Persona** (Operational stakes, trust level, and primary conversion goal).
+   2. **D2: Living Visual Direction & Vibrant Light Mode Default** (Crisp white canvas `#ffffff` / `oklch(0.99 0.002 260)`, surface `oklch(0.97 0.005 260)`, dark slate text `#0f172a`, and vibrant primary accent `oklch(0.55 0.22 260)`).
+   3. **D3: Curated Real Imagery Specification** (High-res Unsplash CDN URLs from `data/unsplash_assets.json` and `skills/ui-kit/references/curated_unsplash_vault.md`).
+   4. **D4: Typography & 8pt Spatial Rhythm** (Bold display headers, readable body font, and generous padding).
+   5. **D5: Living Micro-States & Components** (Modular cards, active navigation, interactive sliders/tabs from `skills/ui-kit`).
+   6. **D6: On-Demand RTL & Language Protocol** (Disabled by default; activated strictly on-demand for Persian/Arabic queries with `<bdi>` isolation).
+
+---
+
+## 📄 4. Canonical Machine-Readable Output (`design-spec.json`)
+
+When requested or when compiling specs for downstream build pipelines, `autonomous-intent-expander` outputs this clean JSON Design Contract:
+
+```json
+{
+  "$schema": "../../schemas/design-spec.v1.schema.json",
+  "spec_version": "6.0.0",
+  "domain_archetype": "HIGH_PERFORMANCE_SAAS",
+  "visual_chemistry": "STRIPE_CRISP_LIGHT",
+  "core_parameters": {
+    "primary_palette": {
+      "canvas_oklch": "oklch(0.99 0.002 260)",
+      "surface_oklch": "oklch(0.97 0.005 260)",
+      "primary_accent_oklch": "oklch(0.55 0.22 260)",
+      "border_oklch": "oklch(0.92 0.008 260)"
+    },
+    "typography_pair": {
+      "display_font": "Plus Jakarta Sans, Inter, system-ui, sans-serif",
+      "body_font": "Inter, system-ui, sans-serif",
+      "mono_font": "JetBrains Mono, monospace"
+    },
+    "surface_treatment": "crisp_light_with_subtle_elevation",
+    "grid_density": "bento_asymmetric",
+    "hero_composition": "split_visual_showcase"
+  },
+  "asset_strategy": {
+    "provider": "curated_unsplash_vault",
+    "domain_key": "saas_b2b_enterprise",
+    "dimensions": {
+      "hero": "&auto=format&fit=crop&w=1200&q=80",
+      "card": "&auto=format&fit=crop&w=600&h=400&q=80"
+    }
+  },
+  "accessibility_contract": {
+    "wcag_level": "AA",
+    "min_touch_target_px": 24,
+    "target_recommendation_px": 44,
+    "focus_visible_required": true,
+    "reduced_motion_strategy": "functional_only"
+  },
+  "semantic_rtl_contract": {
+    "enabled": false,
+    "physical_macro_stability": true,
+    "bidi_isolation": false,
+    "code_ltr_enforced": true
+  },
+  "novelty_budget": {
+    "dimensions_varied": [
+      "hero_composition",
+      "grid_density",
+      "accent_palette"
+    ],
+    "entropy_heuristic": 0.85
+  }
+}
+```

package/skills/conversion-copy-engine/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: conversion-copy-engine
+description: Strategic value copywriting, objection neutralization frameworks, and domain-calibrated narrative architecture with strict anti-dark-pattern compliance.
+triggers: ["write copy", "conversion", "sales page", "persuasive", "CTA", "landing page copy", "a/b test copy", "cro copy"]
+---
+
+# ✍️ Conversion Copy Engine & Strategic Value Architecture
+
+## 🎯 Purpose
+The `conversion-copy-engine` transforms standard marketing filler into high-converting, domain-calibrated narrative architecture anchored in **Pillar 1: Deep Trend Research & World-Class Inspiration** (benchmarking premier SaaS and product copy from Linear, Stripe, Apple, Notion, and Framer). It applies behavioral clarity, objection neutralization, and transparent risk reversal to maximize conversion rates without resorting to manipulative tricks.
+
+---
+
+## 🧩 1. Domain-Calibrated Copy Frameworks
+
+Choose the narrative formula that matches the product category (avoid forcing acute pain/embarrassment onto professional tools):
+
+| Product Domain | Primary Framework | Core Hook & Narrative Focus |
+| :--- | :--- | :--- |
+| **B2B SaaS / DevTools** | **JTBD + ROI + Friction Reduction** | Quantifiable efficiency gain, hours saved per sprint, zero workflow disruption. |
+| **Luxury / High-Ticket** | **Status + Exclusivity + Craftsmanship** | Heritage, discerning taste, white-glove concierge, scarcity. |
+| **Healthcare / Clinical** | **Trust + Clinical Evidence + Clarity** | Board certification, verified outcomes, transparent methodology, peace of mind. |
+| **Consumer / Creator** | **Identity + Convenience + Desire** | Frictionless self-expression, lifestyle alignment, immediate gratification. |
+| **Local Services / Trades** | **Proximity + Reliability + Fast Availability** | 24/7 dispatched response, upfront transparent pricing, licensed & insured guarantee. |
+
+---
+
+## ⚡ 2. Universal Conversion Mechanics
+
+### A. The Hero Headline Formula
+$$\mathbf{\text{Hero Headline}} = [\text{Dream Outcome}] + [\text{Without Main Fear / Friction}] + [\text{Unique Mechanism / Timeframe}]$$
+
+### B. PAS Framework (Problem - Agitation - Solution)
+*Best for: Consumer, Health, High-Pain problem spaces.*
+1. **Problem (Acute Friction):** State the persistent obstacle or wasted cost.
+2. **Agitation (Cost of Inaction):** Highlight the compounding risk, missed opportunity, or frustration.
+3. **Solution (Proprietary Mechanism):** Present the unique, credible vehicle that reliably resolves it.
+
+### C. Objection Inversion Microcopy
+Place risk-reversal microcopy directly below primary CTAs to dissolve hesitation at the point of action:
+- *«No credit card required • 2-minute instant setup • Cancel anytime»*
+- *«Transparent pricing • Free migration • Live 24/7 human support»*
+- *«14-day free trial • No credit card required • Instant 2-minute setup»*
+
+### D. Direct Concierge Conversion Funnel
+Move high-intent traffic into direct 1-on-1 conversations using context-aware, pre-filled deep links (WhatsApp, Telegram, or Live Chat).
+
+---
+
+## 🛡️ 3. Inviolable Anti-Dark-Pattern Policy
+
+High conversion is built on radical trust, not deceptive manipulation:
+1. **Zero Synthetic Social Proof:** Never fabricate customer testimonials, invent user avatars, or generate fake reviews.
+2. **Zero Fake Scarcity or Urgency:** Never generate countdown timers that reset on page reload, or false stock counters ("Only 1 seat left!").
+3. **Zero Unsubstantiated ROI Claims:** Never promise arbitrary financial multiples ("300% guaranteed ROI in 7 days") unless backed by verifiable customer case studies.
+4. **Transparent Cancellation & Terms:** Clearly state trial periods, billing cadences, and cancellation rights.
+
+---
+
+## 🌐 4. Multilingual & Persian Copy Protocol (Zero ZWNJ Standard)
+
+When synthesizing Persian or bilingual conversion copy:
+1. **Natural Standard Persian:** Write compelling, fluent copy using standard Persian with regular spaces exclusively.
+2. **Absolute Prohibition of ZWNJ:** Never use the zero-width non-joiner (`\u200c` / half-space) in any headline, body text, or CTA label per User Global Rule 9. Standard spaces must be used exclusively (e.g., `ثبت نام سریع`, `شروع رایگان`, `پشتیبانی مداوم`).
+3. **On-Demand `<bdi>` Isolation:** Wrap Latin brand tokens, acronyms, and product terms inside `<bdi>` elements when embedded within Persian phrases to prevent bidirectional text reversals.

package/skills/ui-kit/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: ui-kit
+description: Exhaustive, domain-agnostic UI/UX Component Engine & Design Intelligence. Curated from Beautiful UI (beautifului.dev - 20 AI primitives), Shadcn UI (ui.shadcn.com - 50+ components), BeUI (beui.dev), Rare UI (rareui.com), and Transitions.dev. Provides copy-paste primitives for AI Thinking states, Streaming text, Tool chips, Approval cards, Task rows, Flowcharts, Insight sparklines, Bento grids, Physics transitions, and accessible UI controls for any tech stack (React, Next.js, Vue, Tailwind, HTML/Vanilla, Flutter) in any visual style or language (LTR/RTL).
+triggers: ["ui-kit", "uikit", "beautifului", "beui", "rareui", "transitions.dev", "shadcn", "component library", "ui components", "ai ui", "components", "ui design", "frontend design"]
+---
+
+# 🎨 UI-Kit: Exhaustive AI-Native & Modern Component Recipes
+
+`ui-kit` is a 100% domain-agnostic component encyclopedia and design intelligence engine. It contains 70+ accessible component recipes and reference implementations across premier modern design ecosystems, anchored directly in **The Two Golden Pillars** (Trend Inspiration & Living Visual Feedback).
+
+---
+
+## 🏛️ The Two Golden Pillars of Component Selection
+
+1. **Pillar 1: Deep Trend Inspiration & Benchmark Aesthetics**:
+   Select components sourced from elite design benchmarks (Beautiful UI, Shadcn, BeUI, Rare UI, Transitions.dev, and Curated Unsplash Vault). Default to vibrant, modern light mode with high-contrast typography, avoiding dark-mode bias unless the domain explicitly demands it (e.g., terminal or crypto trading).
+2. **Pillar 2: Living Visual Feedback & Render Verifiability**:
+   Every component enforces deterministic container sizing, responsive aspect ratios (`16:9`, `3:2`, `4:5`, `1:1`), zero cumulative layout shift (CLS), and explicit demarcation slots, calibrated for headless Playwright multi-viewport screenshot auditing and automated healing.
+
+---
+
+## 🌐 The 9 Pillar Resource Catalogs
+
+| Catalog Reference | Source / Provenance | Component Scope |
+| :--- | :--- | :--- |
+| [`references/living_micro_interactions.md`](references/living_micro_interactions.md) | **Uiverse Galaxy & Living Micro-Interactions** | **Living Micro-Interactions:** Shimmer Button, Cyber Loader, Holographic 3D Tilt Card, Tactile Switch, Glow Input, Autonomous Living Injection Matrix, and Zero-Hallucination Guardrails. |
+| [`references/ai_native_full_catalog.md`](references/ai_native_full_catalog.md) | **[Beautiful UI](https://beautifului.dev)** (Adapted) | **20 AI Primitives:** Loading State, Thinking State, Streaming Text, Approval Card, Tool Chips, Task Rows, Chat, Prompt Bar, Recommendation Card, Context Cards, Diff Table, Records Table, Filter Table, Sidebar Nav, Search HUD, Insight Cards / Sparklines, Code Block with Copy, Fine-tune Card, Selection Actions. |
+| [`references/shadcn_full_catalog.md`](references/shadcn_full_catalog.md) | **[Shadcn UI](https://ui.shadcn.com)** (MIT) | **50+ UI Primitives:** Forms & Inputs (Input, Textarea, Select, Checkbox, Switch, InputOTP, Slider), Overlays & Modals (Dialog, Sheet/Drawer, Popover, Tooltip, Dropdown), Navigation (Command Palette `Cmd+K`, Tabs, Breadcrumb), Feedback (Sonner Toast, Skeleton Shimmer, Progress), Data Display (Accordion, Avatar, Table). |
+| [`references/bento_grids_and_cards.md`](references/bento_grids_and_cards.md) | **[BeUI](https://beui.dev) & [Rare UI](https://rareui.com)** (MIT) | **Bento & Interactive Cards:** 3-Col & 4-Col Asymmetric Bento Grids, Glassmorphism 2.0 Inset Specular Cards, Animated Gradient Shimmer Buttons, Metric HUD Tiles. |
+| [`references/modern_vibe_components.md`](references/modern_vibe_components.md) | **[Aceternity](https://ui.aceternity.com) & [Magic UI](https://magicui.design)** (Adapted) | **Modern Vibe Recipes:** Aurora Glow Background, Spotlight Hero, Neon Border-Beam Cards, 3D Tilt Cards, Infinite Smooth Marquee, Shimmer Glow Buttons, Floating Dock Island. |
+| [`references/data_and_flow.md`](references/data_and_flow.md) | **Flow & Metric Visualization** | **Workflow & Canvas Nodes:** Modular Trigger Nodes, If/Else Conditional Splitters, Action Execution Cards, Micro Sparkline Meters, Dotted Grid Canvas. |
+| [`references/physics_transitions_catalog.md`](references/physics_transitions_catalog.md) | **[Transitions.dev](https://transitions.dev)** (Zero-Dep) | **Zero-Dependency Motion:** Pure CSS Grid Dynamic Height Accordions (`0fr` -> `1fr`), Spring Easing Bezier Curves, Staggered List Reveals, JS Number Flip Counters, 3D Tilt Cards. |
+| [`references/tokens_and_theme_engine.md`](references/tokens_and_theme_engine.md) | **Universal Design System** | **Tokens & Layouts:** Theme Variables (Light, Dark, Custom), Directional Logical CSS (`ms-*`, `me-*`, `start-*`, `end-*`) for universal LTR & RTL support. |
+| [`references/curated_unsplash_vault.md`](references/curated_unsplash_vault.md) | **Curated Unsplash Asset Vault** | **24 Canonical Domains:** Verified high-resolution CDN photography with responsive WebP focal dimensions (`w=1200` heroes, `w=600&h=400` cards) across all 24 industry domains with zero gray placeholder boxes. |
+
+---
+
+## ♿ Mandatory Accessibility & Quality Contract (WCAG AA)
+
+When generating or adapting any component from this kit, the AI Agent must strictly uphold:
+1. **Semantic HTML Elements:** Use `<button>` for clickables (never `<div onclick>`), `<nav>`, `<aside>`, `<dialog>`, etc.
+2. **Keyboard Operability & Visible Focus:** All interactive controls must respond to `Enter`/`Space` and feature high-contrast `focus-visible:ring-2` states.
+3. **Screen Reader Semantics:** Provide `aria-expanded`, `aria-controls`, `aria-label`, and `role="region"` for collapsing or stateful elements.
+4. **Functional Motion Sensitivity:** Disable non-essential decorative loops, parallax, and continuous spring animations under `@media (prefers-reduced-motion: reduce)`; preserve essential functional state transitions (e.g. accordion disclosure, button states) with short, non-disorienting durations ($\le 150\text{ms}$).
+
+---
+
+## ⚡ Universal Usage Workflow
+
+Whenever asked to build, design, or refactor any frontend component or view:
+1. **Identify the Component Domain & Aesthetic Anchor:** Anchor to Pillar 1 by selecting cohesive primitives matching domain blueprints. Default to vibrant light mode unless domain explicitly dictates otherwise.
+2. **Read the Target Reference:** Pull exact markup, Tailwind utility classes, zero-JS transitions, and verified photography from `references/`.
+3. **Adapt Seamlessly:** Match the target framework (React, Vue, HTML/JS, Tailwind), color theme, and language direction.
+4. **Verify Living Visuals:** Align with Pillar 2 by ensuring all media containers and layout nodes render cleanly under multi-viewport Playwright screenshot audits.
+
+---
+
+## 📐 On-Demand Scoped RTL & Semantic Architecture
+
+RTL layout rules and `<bdi>` bidirectional contracts are strictly scoped to on-demand Persian/Arabic execution (never enforced by default on universal or English interfaces). When explicitly executing for Persian, Arabic, or bilingual viewports:
+1. **Preserve Macro Layout & Coordinates:**
+   Global grid columns, module cards, slider tracks, and navigation bars remain physically stable. Do not indiscriminately flip entire layout grids.
+2. **Target Textual & Paragraph Direction:**
+   Apply `direction: rtl` and text alignments to text nodes, headings, and descriptions.
+3. **Mirror Semantic Directional Affordances:**
+   Navigation arrows (previous/next), sequential timelines, step wizards, and back-buttons must mirror semantically to follow reading flow.
+4. **BiDi Resilience & Strict Monospace LTR:**
+   Mixed English brand names or tech terms inside Persian sentences must not scramble punctuation (`unicode-bidi: plaintext` or `<bdi>`).
+   Code blocks, numbers, metric counters (`99.98%`), and URLs always stay strictly `direction: ltr !important; text-align: left !important`.
+5. **Zero ZWNJ Protocol:**
+   All Persian text in copy, comments, and configuration must use standard spaces exclusively. The zero-width non-joiner (`\u200c`) is strictly forbidden.
+
+---
+
+## 📱 Mobile-Native Resilience & Touch Polish
+
+To ensure web interfaces feel as polished and responsive as native iOS and Android apps, enforce the following ergonomic invariants:
+
+1. **Dynamic Viewport Height (`100dvh`):**
+   - Never use static `height: 100vh` for full-screen modals, sheets, or mobile heroes. Mobile browser address bars collapse/expand on scroll, causing jarring layout jumps.
+   - Use `min-height: 100dvh;` with graceful fallback:
+     ```css
+     min-height: 100vh;
+     min-height: 100dvh;
+     ```
+
+2. **iOS Safari Input Auto-Zoom Guard:**
+   - In iOS Safari, any `<input>`, `<select>`, or `<textarea>` with `font-size < 16px` triggers an involuntary, disruptive zoom on touch focus.
+   - Always ensure base font size for form controls on mobile is at least `16px` (`text-base` in Tailwind):
+     ```css
+     @media (max-width: 640px) {
+       input, select, textarea {
+         font-size: 16px !important;
+       }
+     }
+     ```
+
+3. **Tap Highlight Suppression:**
+   - Remove default WebKit gray rectangular tap flash on clickable elements:
+     ```css
+     button, a, [role="button"] {
+       -webkit-tap-highlight-color: transparent;
+       touch-action: manipulation; /* Eliminates 300ms tap delay */
+     }
+     ```
+
+4. **Sticky Hover State Elimination:**
+   - Touch devices emulate mouse hover upon touch tap, leaving buttons permanently stuck in their hover visual state after the finger lifts.
+   - Strictly encapsulate all hover pseudo-classes in fine pointer media queries:
+     ```css
+     @media (hover: hover) and (pointer: fine) {
+       .interactive-element:hover {
+         /* Hover transformation/glow here */
+       }
+     }
+     ```
+
+5. **Physical Touch Target Dimensions (WCAG 2.5.8):**
+   - All interactive touch targets (buttons, icon triggers, pills) must provide an active bounding box of at least **44px × 44px** on touch viewports, even if the visible icon is smaller (use transparent hit padding or pseudo-elements).
+
+---
+
+## 📜 Provenance, Adaptation & Legal Licensing
+
+- **Clean-Room Implementation:** All 70+ components in this encyclopedia are clean-room adaptations, re-written from scratch as portable semantic Tailwind CSS / HTML / React recipes.
+- **No Proprietary Runtime Bundles:** This library does not import or re-distribute proprietary binaries or runtime npm packages.
+- **MIT & Open Source Attribution:**
+  - **Shadcn UI:** Re-implemented following the open-source patterns under the MIT License.
+  - **Transitions.dev:** Pure CSS motion patterns adapted from open CSS specifications.
+  - **Beautiful UI, BeUI & Rare UI:** Conceptual layout patterns synthesized into production-ready accessible code recipes.
+