@birdapi/velinstyle 0.8.0 → 0.9.0

package/README.md

@@ -1,21 +1,26 @@
 <div align="center">
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/readme-banner-dark.svg">
-  <img src=".github/assets/readme-banner.svg" alt="VelinStyle — accessibility-first CSS and Web Components" width="100%">
-</picture>
-
-<br>
+```
+██╗   ██╗███████╗██╗     ██╗███╗   ██╗███████╗████████╗██╗  ██╗██╗     ███████╗
+██║   ██║██╔════╝██║     ██║████╗  ██║██╔════╝╚══██╔══╝██║  ██║██║     ██╔════╝
+██║   ██║█████╗  ██║     ██║██╔██╗ ██║███████╗   ██║   ███████║██║     █████╗
+╚██╗ ██╔╝██╔══╝  ██║     ██║██║╚██╗██║╚════██║   ██║   ██╔══██║██║     ██╔══╝
+ ╚████╔╝ ███████╗███████╗██║██║ ╚████║███████║   ██║   ██║  ██║███████╗███████╗
+  ╚═══╝  ╚══════╝╚══════╝╚═╝╚═╝  ╚═══╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚══════╝
+```
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-2563eb?style=flat-square)](LICENSE)
-[![Release](https://img.shields.io/badge/Release-v0.8.0-2563eb?style=flat-square)](CHANGELOG.md)
-[![WCAG AA](https://img.shields.io/badge/WCAG-AA-16a34a?style=flat-square)](docs/a11y.html)
-[![CSS min](https://img.shields.io/badge/CSS_min-~46KB-15803d?style=flat-square)]()
-[![JS min](https://img.shields.io/badge/JS_min-~66KB-15803d?style=flat-square)]()
+[![Release](https://img.shields.io/badge/Release-v0.9.0-2563eb?style=flat-square)](https://github.com/SkyliteDesign/velinstyle/releases/tag/v0.9.0)
 [![npm version](https://img.shields.io/npm/v/@birdapi/velinstyle?style=flat-square)](https://www.npmjs.com/package/@birdapi/velinstyle)
-[![GitHub Pages](https://img.shields.io/badge/docs-GitHub_Pages-2563eb?style=flat-square)](https://skylitedesign.github.io/velinstyle/)
+[![WCAG 2.2 AAA](https://img.shields.io/badge/WCAG_2.2-AAA-16a34a?style=flat-square)](https://velinstyle.info/docs/a11y.html)
+[![GitHub stars](https://img.shields.io/github/stars/SkyliteDesign/velinstyle?style=flat-square)](https://github.com/SkyliteDesign/velinstyle/stargazers)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-2563eb?style=flat-square)](CONTRIBUTING.md)
 
-[Documentation](https://skylitedesign.github.io/velinstyle/) · [npm](https://www.npmjs.com/package/@birdapi/velinstyle) · [Samples](samples/) · [Playground](tools/playground/index.html) · [Theme Builder](tools/theme-builder/index.html) · [Issues](https://github.com/SkyliteDesign/velinstyle/issues)
+```bash
+npm i @birdapi/velinstyle
+```
+
+**[Website](https://velinstyle.info)** · **[Docs](https://velinstyle.info/docs/)** · **[Demos](https://velinstyle.info/demos/)** · **[npm](https://www.npmjs.com/package/@birdapi/velinstyle)** · **[Star on GitHub](https://github.com/SkyliteDesign/velinstyle)**
 
 **English** · **[Deutsch](README.de.md)**
 
@@ -23,304 +28,190 @@
 
 ---
 
-## Contents
-
-- [The problem & the fix](#the-problem--the-fix)
-- [What you get](#what-you-get)
-- [Architecture](#architecture)
-- [Quick start](#quick-start)
-- [Why VelinStyle?](#why-velinstyle)
-- [Demo gallery](#demo-gallery)
-- [CLI reference](#cli-reference)
-- [Ecosystem](#ecosystem)
-- [Join in](#join-in)
-- [Browser support](#browser-support)
-- [License](#license)
-
----
-
-## The problem & the fix
-
-<table>
-<tr>
-<td width="50%" valign="top">
-
-### The problem
-
-Teams ship UI under pressure. **Accessibility** and **consistent theming** are often bolted on late—if at all. Heavy bundles, Bootstrap sameness, or Tailwind sprawl frustrate designers and engineers alike.
-
-</td>
-<td width="50%" valign="top">
-
-### The VelinStyle answer
-
-**WCAG AA patterns**, **OKLCH tokens**, **container-aware layout**, and **interactive Web Components** are part of the system—not an afterthought. Readable CSS, optional CLI automation, zero preprocessor lock-in.
-
-</td>
-</tr>
-</table>
+**VelinStyle** is the **WCAG 2.2 AAA CSS framework** with native JavaScript runtime and Web Components — CSS utilities, 0.9.0 modules (search, motion, highlight, attributes, meta), and security tooling, with **no external UI framework dependencies** in the core.
 
----
+Built for teams who want **readable HTML**, **AAA token defaults** (AA via `data-velin-contrast="aa"`), and **CLI automation** instead of utility sprawl.
 
-## What you get
-
-<table>
-<thead>
-<tr><th></th><th>Capability</th><th>What it means for you</th></tr>
-</thead>
-<tbody>
-<tr><td align="center">♿</td><td><strong>WCAG AA by design</strong></td><td>Focus, ARIA, and keyboard patterns in components and overlays</td></tr>
-<tr><td align="center">🎨</td><td><strong>OKLCH + 13 theme presets</strong></td><td>Perceptually uniform colors; dark mode via token swap</td></tr>
-<tr><td align="center">📦</td><td><strong>~46 KB CSS + ~66 KB JS (min)</strong></td><td>Lean defaults vs. heavier all-in-one stacks</td></tr>
-<tr><td align="center">📐</td><td><strong>Container Queries + utilities</strong></td><td>Components adapt to <em>their</em> container, not only the viewport</td></tr>
-<tr><td align="center">🧩</td><td><strong>25 CSS modules · 29 Web Components</strong></td><td>Modals, tabs, drawers, toasts, icons—documented APIs in <a href="docs/css-components.html">CSS</a> &amp; <a href="docs/components.html">WC docs</a></td></tr>
-<tr><td align="center">🛠️</td><td><strong>Optional CLI</strong></td><td><code>init</code>, <code>build</code>, <code>icons</code>, <code>scan</code>, <code>prefix</code>, <code>blueprint</code>, <code>scaffold</code>, <code>layout</code>, <code>tokens build</code></td></tr>
-<tr><td align="center">🌍</td><td><strong>RTL-ready</strong></td><td>Logical properties and layout-minded defaults · <a href="samples/rtl.html">RTL sample</a></td></tr>
-</tbody>
-</table>
+> **Dogfooding:** The entire VelinStyle website and documentation runs 100% on VelinStyle — no external scripts or UI frameworks.
 
 ---
 
-## Architecture
-
-```mermaid
-flowchart LR
-  tokens[tokens] --> reset[reset]
-  reset --> base[base]
-  base --> a11y[a11y]
-  a11y --> layout[layout]
-  layout --> components[components]
-  components --> utilities[utilities]
-  utilities --> themes[themes]
-```
+## Features at a glance
 
-Entry: [`src/velinstyle.css`](src/velinstyle.css) · Build output: `dist/` (`npm run build`)
-
-```css
-@layer tokens, reset, base, a11y, layout, components, utilities, themes;
-```
+- **CSS utilities** — `velin-*` spacing, color, flex, motion, safe-area; cascade layers + OKLCH tokens
+- **35+ components** — semantic BEM classes (`velin-btn`, `velin-card`, `velin-grid`, …)
+- **Motion runtime** — reveal, stagger, scroll-driven animation, rAF scheduler
+- **VelinSearch** — fuzzy offline search with highlighting and categories
+- **Syntax highlighting** — lazy in-view highlighting for JS, HTML, CSS, JSON, and more
+- **HTML attributes** — 27 declarative bridges (`velin-modal`, `velin-reveal`, `velin-scroll-top`, `velin-code`, …)
+- **Quality** — 36/36 component a11y contracts, Playwright cross-browser smoke (`npm run test:e2e`), CLS placeholders (`wc-placeholder.css`)
+- **Security tools** — `scan`, PII rules, sanitize API, hardened components
+- **CLI** — init, build, scan, scaffold, tokens, docs generate, perf audit, layout audit
+- **Velin-Meta** — `velin-agent.json`, `llms.txt`, and page-level agent JSON for AI assistants
 
 ---
 
-## Quick start
-
-### <span>①</span> Install
+## Installation
 
 ```bash
-npm install @birdapi/velinstyle
-```
-
-### <span>②</span> Link CSS + components (ES modules)
-
-```html
-<link rel="stylesheet" href="node_modules/@birdapi/velinstyle/dist/velinstyle.min.css">
-<script type="module" src="node_modules/@birdapi/velinstyle/dist/velinstyle-components.min.js"></script>
+npm i @birdapi/velinstyle
 ```
 
-<details>
-<summary><strong>CDN alternative</strong> (skip npm install)</summary>
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@latest/dist/velinstyle.min.css">
-<script type="module" src="https://unpkg.com/@birdapi/velinstyle@latest/dist/velinstyle-components.min.js"></script>
-```
-
-</details>
+| Path | Use |
+| --- | --- |
+| `@birdapi/velinstyle/css` | Full minified stylesheet |
+| `@birdapi/velinstyle/bundle` | Web Components ESM bundle |
+| `@birdapi/velinstyle/search` | VelinSearch module |
+| `@birdapi/velinstyle/motion` | Motion runtime |
+| `@birdapi/velinstyle/attributes` | HTML attribute bridges |
+| `@birdapi/velinstyle/highlight` | Syntax highlighting |
+| `@birdapi/velinstyle/meta` | Agent metadata API |
 
-### <span>③</span> Mark up your first screen
+**CDN (pin version):**
 
 ```html
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<div class="velin-container velin-p-6">
-  <p class="velin-lead velin-text-muted">Hello, VelinStyle.</p>
-  <button type="button" class="velin-btn velin-btn--primary">Primary action</button>
-</div>
+<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@0.9.0/dist/velinstyle.min.css">
+<script type="module" src="https://unpkg.com/@birdapi/velinstyle@0.9.0/dist/velinstyle-components.min.js"></script>
 ```
 
-> **Cloning this repo?** `dist/` is not committed. Run `npm install` and `npm run build`, then point HTML at `dist/velinstyle.min.css` and `dist/velinstyle-components.min.js`. Legacy pages without modules: `velinstyle-components.iife.js` — see [docs](docs/index.html).
+After cloning, run `npm install && npm run build` — `dist/` is generated, not committed.
 
 ---
 
-## Why VelinStyle?
+## Quickstart
 
-A **coherent product language**—prefix classes (`velin-`), explicit `@layer` architecture, modern CSS (`@scope`, nesting, `:has()`)—without sacrificing **ship speed**.
-
-| | Bootstrap | Tailwind | **VelinStyle** |
-| --- | :---: | :---: | :---: |
-| A11y | ⚠️ Partial | — Not built-in | ✅ **WCAG AA structurally** |
-| Color | HEX/RGB | HEX/RGB | ✅ **OKLCH** + tokenized themes |
-| Dark mode | ⚠️ Build / manual | `dark:` variants | ✅ **Token swap** (`data-velin-theme`) |
-| Layout | Viewport-first | Viewport utilities | ✅ **Container Queries** + media |
-| Interactivity | ⚠️ Legacy JS patterns | Bring your own | ✅ **Web Components** |
-| Bundle (indicative) | ~230 KB CSS+JS | JIT / varies | ✅ **~46 KB CSS + ~66 KB JS (min)** |
+```html
+<!DOCTYPE html>
+<html lang="en" data-velin-theme="ocean">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@0.9.0/dist/velinstyle.min.css">
+  <script type="module" src="https://unpkg.com/@birdapi/velinstyle@0.9.0/dist/velinstyle-components.min.js"></script>
+</head>
+<body class="velin-p-6">
+  <button type="button" class="velin-btn velin-btn--primary" velin-reveal="slide-up">Ship it</button>
+  <velin-code-block language="html" line-numbers>&lt;p class="velin-text-muted"&gt;Hello VelinStyle&lt;/p&gt;</velin-code-block>
+</body>
+</html>
+```
 
 ---
 
-## Demo gallery
-
-| Demo | Page | Demo | Page |
-| --- | --- | --- | --- |
-| Landing | [samples/landing.html](samples/landing.html) | Dashboard | [samples/dashboard.html](samples/dashboard.html) |
-| Login | [samples/login.html](samples/login.html) | Sign up | [samples/signup.html](samples/signup.html) |
-| Pricing | [samples/pricing.html](samples/pricing.html) | E-commerce | [samples/ecommerce.html](samples/ecommerce.html) |
-| Blog | [samples/blog.html](samples/blog.html) | Portfolio | [samples/portfolio.html](samples/portfolio.html) |
-| Chat | [samples/chat.html](samples/chat.html) | Email | [samples/email.html](samples/email.html) |
-| Kanban | [samples/kanban.html](samples/kanban.html) | Settings | [samples/settings.html](samples/settings.html) |
-| RTL layout | [samples/rtl.html](samples/rtl.html) | A11y patterns | [samples/a11y-patterns.html](samples/a11y-patterns.html) |
+## Core modules (0.9.0)
 
-| Tool | Page |
+| Export | Description |
 | --- | --- |
-| HTML playground | [tools/playground/index.html](tools/playground/index.html) |
-| OKLCH theme builder | [tools/theme-builder/index.html](tools/theme-builder/index.html) |
+| `@birdapi/velinstyle/search` | Fuzzy offline search, providers, optional Web Worker |
+| `@birdapi/velinstyle/motion` | `initMotion`, stagger, smooth scroll, unified `.velin-in-view` |
+| `@birdapi/velinstyle/attributes` | Registry of declarative `velin-*` HTML attribute bridges |
+| `@birdapi/velinstyle/highlight` | `velinSyntax`, lazy language packs, OKLCH token colors |
+| `@birdapi/velinstyle/meta` | `buildAgentBundle`, page meta MIME `application/vnd.velinstyle.meta+json` |
 
 ---
 
-## CLI reference
-
-All commands: `npx velinstyle <command>` · `npx velinstyle --help`
-
-<details>
-<summary><strong>Project &amp; build</strong> — <code>init</code>, <code>build</code>, <code>themes</code>, <code>add</code></summary>
-
-- **`npx velinstyle init`** — creates `velinstyle.config.js` (layer selection, theme, scan options).
-- **`npx velinstyle build`** — custom CSS bundle from selected layers (`--output` / `-o`, `--minify`).
-- **`npx velinstyle themes`** — lists 13 theme presets.
-- **`npx velinstyle add &lt;component&gt;`** — copies a single component CSS file into your project.
-
-</details>
-
-<details>
-<summary><strong>Icons</strong> — multi-provider sprite workflow</summary>
-
-- **`npx velinstyle icons list`** — Lucide, Heroicons, Bootstrap Icons, Material Symbols, Font Awesome, Tabler.
-- **`npx velinstyle icons add lucide --icons menu,search,check`**
-- **`npx velinstyle icons add heroicons --icons arrow-left --variant outline`**
-- **`npx velinstyle icons build`** — rebuilds sprite (from a VelinStyle clone: writes `icons/svg/` and rebuilds).
-
-</details>
+## Web Components
 
-<details>
-<summary><strong>scan</strong> — security, a11y &amp; CSS lint</summary>
+**36 canonical** custom elements (38 lazy-loader entries including legacy `velin-tooltip-wc` and `velin-stepper-wc`) — use plain CSS when you do not need behavior. `src/base/wc-placeholder.css` reduces layout shift before elements upgrade.
 
-- **`npx velinstyle scan [path]`** — HTML, CSS, JS; **`--format json`** for CI.
-- **`--severity`** — filter minimum level: `error` | `warning` | `info`.
-- **`--fix`** — safe auto-fixes only; **`--fix-dry-run`** lists files without writing.
-- **`--fix-lang`** — BCP 47 for setting `lang` on `<html>` (default `en`).
+Examples: `velin-modal`, `velin-search`, `velin-code-block`, `velin-drawer`, `velin-stepper`, `velin-tooltip`, `velin-toast`, `velin-persist`.
 
-**Auto-fixes (examples):** `rel="noopener noreferrer"` on risky `target="_blank"`; `lang` on `<html>`; skip link when `id="main"` exists; raw `z-index` → `--velin-z-*`.
+- [Component documentation](https://velinstyle.info/docs/components/buttons.html)
+- [Generated Web Component API](https://velinstyle.info/docs/generated/components/README.md)
 
-**Not auto-fixed:** `javascript:` URLs, `eval`, raw `innerHTML`, inline event handlers — fix in source.
-
-**Trusted Types / XSS:** the scanner does not replace CSP policies. Web Components use `escapeHTML()` / `sanitizeURL()`; see [docs/security.html](docs/security.html).
-
-</details>
-
-<details>
-<summary><strong>prefix</strong> — class codemod &amp; JSON maps</summary>
-
-- **`npx velinstyle prefix &lt;folder&gt;`** — dry-run by default; **`--write`** applies changes.
-- **`--bootstrap-display`** — maps Bootstrap `d-*` to Velin display classes.
-- **`velinstyle-prefix-map.json`** in the target folder or **`--map file.json`** — explicit token → class mappings (overrides catalog and Bootstrap aliases). Sample: [examples/velinstyle-prefix-map.sample.json](examples/velinstyle-prefix-map.sample.json).
-
-</details>
-
-<details>
-<summary><strong>scaffold</strong> — prompt → HTML (0.8.0)</summary>
-
-- **`npx velinstyle scaffold list-intents`**
-- **`npx velinstyle scaffold "Navbar with search" -o nav.html`**
-- **`npx velinstyle scaffold "…" --json`** — for agents/CI
+---
 
-See [docs/guides/prompt-scaffolding.html](docs/guides/prompt-scaffolding.html).
+## CLI
 
-</details>
+| Command | Purpose |
+| --- | --- |
+| `npx velinstyle init` | Create `velinstyle.config.js` in your project |
+| `npx velinstyle scan` | Security, accessibility, CSS, and PII checks |
+| `npx velinstyle search index` | Build `dist/search-index.json` for offline doc search |
+| `npx velinstyle tokens build` | Compile design tokens JSON to CSS |
+| `npx velinstyle meta` | Generate `velin-agent.json` and `llms.txt` |
 
-<details>
-<summary><strong>layout</strong> — responsive audit (0.8.0)</summary>
+Also: `npx velinstyle docs generate` — Markdown reference under `docs/generated/`.
 
-- **`npx velinstyle layout audit [path]`**
-- **`npx velinstyle layout suggest [path]`**
-- **`npx velinstyle layout fix [path] --write`**
+---
 
-See [docs/guides/responsive-layout.html](docs/guides/responsive-layout.html).
+## Security
 
-</details>
+VelinStyle ships **first-class security tooling**, not an afterthought:
 
-<details>
-<summary><strong>blueprint</strong> — 22 HTML snippets</summary>
+- **`velinstyle scan`** — markup and a11y rules; PII scanner (`--only pii`, `--fix`)
+- **`@birdapi/velinstyle/sanitize`** — URL and text sanitization helpers
+- **`<velin-secure-field>`** — no plaintext secrets in the DOM; hardened search/copy URLs
 
-- **`npx velinstyle blueprint list`**
-- **`npx velinstyle blueprint &lt;name&gt; -o snippet.html`**
+[Security documentation](https://velinstyle.info/docs/extend/security.html)
 
-Ids: `modal`, `form-login`, `layout-dashboard`, `navbar-header`, `hero-section`, `card-grid`, `table-responsive`, `alert-stack`, `breadcrumb-bar`, `footer-simple`, `form-contact`, `pagination-bar`, `search-field`, `sidebar-layout`.
+---
 
-</details>
+## Velin-Meta
 
-<details>
-<summary><strong>tokens build</strong> — design tokens → CSS</summary>
+Machine-readable context for **Cursor, Copilot, and custom agents**:
 
-```bash
-npx velinstyle tokens build --input examples/tokens.sample.json -o tokens-out.css
-```
+- **Global bundle** — `dist/velin-agent.json` + `dist/llms.txt` via `velinstyle meta`
+- **Page-level meta** — `<script type="application/vnd.velinstyle.meta+json" id="velin-meta">`
+- **CLI** — `velinstyle meta page my.html --write`
 
-</details>
+[Velin-Meta guide](https://velinstyle.info/docs/guides/velin-meta.html)
 
 ---
 
-## Ecosystem
+## Docs & website
 
-<table>
-<tr>
-<td width="50%" valign="top">
+- [velinstyle.info](https://velinstyle.info) — product site and demos
+- [Guides](https://velinstyle.info/docs/guides/index.html) · [Feature scope](https://velinstyle.info/docs/guides/feature-scope.html)
+- [API reference](https://velinstyle.info/docs/guides/api-reference.html) — generated from source
+- [Generated Markdown](https://velinstyle.info/docs/generated/index.html) — components, tokens, utilities, CLI, rules
 
-**Starters &amp; packages**
+---
 
-- [templates/vite-velinstyle](templates/vite-velinstyle) — Vite + 3 pages + theme toggle
-- [@velinstyle/react](packages/react) — experimental thin React wrappers
+## Changelog
 
-**Docs**
+See [CHANGELOG.md](CHANGELOG.md) for releases, breaking changes, and migration notes.
 
-- [Getting started](docs/getting-started.html) · [Migration](docs/migration.html)
-- [A11y patterns](docs/a11y-patterns/index.html) · [Security](docs/security.html)
+---
 
-</td>
-<td width="50%" valign="top">
+## Comparison
 
-**Development (this repo)**
+| | Bootstrap | Tailwind | Shoelace | **VelinStyle** |
+| --- | :---: | :---: | :---: | :---: |
+| HTML readability | Medium | Low | Medium | **High** |
+| Class predictability | Medium | Low | Medium | **`velin-btn--primary`** |
+| Utility sprawl | Low | **High** | Low | **Controlled** |
+| Override story | Hard | Config file | Shadow DOM | **CSS layers + tokens** |
+| Accessibility | Partial | DIY | Good WC | **WCAG 2.2 AAA tokens** |
+| Dark mode | Manual | `dark:` everywhere | Theme attr | **Token swap** |
+| App chrome | Legacy JS | BYO | WC only | **CSS + optional WCs** |
+| Ship speed | Fast | Fast (with build) | Fast | **CDN, no build required** |
+| Runtime modules | — | — | — | **Search, motion, meta, …** |
 
-```bash
-npm install
-npm run dev      # serve on :3000
-npm run build
-npm test
-npm run test:a11y
-```
+---
 
-**Themes (13):** `brutalist`, `corporate`, `earth`, `forest`, `midnight`, `neon`, `nordic`, `ocean`, `pastel`, `retro`, `sharp`, `soft`, `sunset` — see [docs/themes.html](docs/themes.html).
+## Live demos
 
-</td>
-</tr>
-</table>
+Full application pages on [velinstyle.info/demos/](https://velinstyle.info/demos/) — [Crypto](https://velinstyle.info/demos/showcase-crypto.html) · [E-Commerce](https://velinstyle.info/demos/showcase-ecommerce.html) · [Dashboard](https://velinstyle.info/demos/showcase-dashboard.html) · [All demos](https://velinstyle.info/demos/) · [Fork showcase-demos](https://github.com/SkyliteDesign/velinstyle/tree/main/showcase-demos)
 
-<!-- Maintainers: add .github/social-preview.png (1280×640) in repo Settings → Social preview -->
+<p align="center">
+  <a href="https://velinstyle.info/demos/showcase-crypto.html">
+    <img src=".github/assets/readme/hero-demo.webp" alt="VelinStyle crypto dashboard demo" width="720">
+  </a>
+</p>
 
 ---
 
-## Join in
-
-If VelinStyle saves you time or raises the bar for inclusive UI:
-
-1. **Star the repo** so others discover it.
-2. **Open an issue** with feedback, edge cases, or ideas.
-3. **Open a PR** following [CONTRIBUTING.md](CONTRIBUTING.md).
+## Contributing
 
-Maintainers: [RELEASING.md](RELEASING.md) · [SECURITY.md](SECURITY.md)
+PRs welcome.
 
----
-
-## Browser support
+1. Fork the repo
+2. `npm install && npm run build`
+3. Make your change · run `npm test`, `npm run test:a11y`, and `npm run test:e2e` (after `npm run build`)
+4. Open a pull request
 
-VelinStyle is **mobile-first**. Use a **current evergreen browser** (recent Safari on iOS, Chrome/Firefox on Android and desktop). OKLCH, Container Queries, `@layer`, and Web Components need modern engines. Include the viewport `meta` tag. Older in-app WebViews may mis-render colors or layout.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for code style and review process.
 
 ---
 
@@ -328,8 +219,6 @@ VelinStyle is **mobile-first**. Use a **current evergreen browser** (recent Safa
 
 [MIT](LICENSE) — Copyright © 2026 VelinStyle
 
----
-
 <div align="center">
 
 Made with care for the web by [SkyliteDesign](https://github.com/SkyliteDesign)

package/cli/blueprints/onboarding.html

@@ -1,4 +1,4 @@
-<velin-stepper-wc id="onboard" labels="Welcome,Profile,Done" active="0">
+<velin-stepper id="onboard" labels="Welcome,Profile,Done" active="0">
   <section class="velin-p-6">
     <h2 class="velin-text-xl velin-mbe-2">Welcome</h2>
     <p class="velin-mbe-4">Set up your workspace in a few steps.</p>
@@ -13,7 +13,7 @@
     <h2 class="velin-text-xl velin-mbe-2">Done</h2>
     <p>You are ready to go.</p>
   </section>
-</velin-stepper-wc>
+</velin-stepper>
 <script type="module">
   import '../../dist/velinstyle-components.min.js';
   const stepper = document.getElementById('onboard');

package/cli/cli-manifest.json

@@ -0,0 +1,97 @@
+{
+  "version": "0.9.0",
+  "commands": [
+    {
+      "name": "init",
+      "summary": "Create velinstyle.config.js",
+      "flags": [],
+      "example": "velinstyle init"
+    },
+    {
+      "name": "build",
+      "summary": "Build custom CSS with selected layers from config",
+      "flags": [],
+      "example": "velinstyle build"
+    },
+    {
+      "name": "themes",
+      "summary": "List available built-in themes",
+      "flags": [],
+      "example": "velinstyle themes"
+    },
+    {
+      "name": "add",
+      "summary": "Add a single component CSS file to your project",
+      "flags": [],
+      "example": "velinstyle add button"
+    },
+    {
+      "name": "icons",
+      "summary": "Manage icon providers (list, add, remove, build)",
+      "flags": ["--icons", "--variant"],
+      "subcommands": ["list", "add", "remove", "build"],
+      "example": "velinstyle icons add lucide --icons menu,search"
+    },
+    {
+      "name": "scan",
+      "summary": "Security, accessibility, CSS, and PII scanner",
+      "flags": ["--format", "--severity", "--only", "--fix", "--fix-dry-run", "--fix-lang"],
+      "example": "velinstyle scan . --only pii --fix-dry-run"
+    },
+    {
+      "name": "prefix",
+      "summary": "Add missing velin- prefix to classes (dry-run; use --write)",
+      "flags": ["--write", "--map", "--bootstrap-display"],
+      "example": "velinstyle prefix src/ --write"
+    },
+    {
+      "name": "blueprint",
+      "summary": "Print HTML blueprint snippets",
+      "flags": ["--output", "-o"],
+      "subcommands": ["list"],
+      "example": "velinstyle blueprint modal -o snippet.html"
+    },
+    {
+      "name": "scaffold",
+      "summary": "Generate layout HTML from natural language prompt",
+      "flags": ["--output", "-o", "--json"],
+      "subcommands": ["list-intents"],
+      "example": "velinstyle scaffold \"dashboard with sidebar\""
+    },
+    {
+      "name": "layout",
+      "summary": "Responsive layout audit (flex, grid, viewport)",
+      "flags": ["--json", "--write", "--dry-run"],
+      "subcommands": ["audit", "suggest", "fix"],
+      "example": "velinstyle layout suggest index.html"
+    },
+    {
+      "name": "perf",
+      "summary": "Performance audit for images and scripts",
+      "flags": ["--json", "--write", "--dry-run"],
+      "subcommands": ["audit", "suggest", "fix"],
+      "example": "velinstyle perf audit samples/"
+    },
+    {
+      "name": "tokens",
+      "summary": "Build or validate design tokens JSON",
+      "flags": ["--input", "--output", "-o"],
+      "subcommands": ["build", "validate"],
+      "example": "velinstyle tokens validate --input examples/tokens.full.json"
+    },
+    {
+      "name": "docs",
+      "summary": "Generate developer reference Markdown",
+      "flags": ["--scope", "--out"],
+      "subcommands": ["generate"],
+      "example": "velinstyle docs generate --scope all"
+    },
+    {
+      "name": "meta",
+      "summary": "Build Velin-Meta agent bundle (velin-agent.json, llms.txt)",
+      "flags": ["--out", "--llms-out", "--base-url", "--no-llms"],
+      "subcommands": ["page"],
+      "example": "velinstyle meta"
+    }
+  ]
+}