@birdapi/velinstyle 1.1.0 → 1.2.1

package/README.de.md

@@ -9,222 +9,150 @@
   ╚═══╝  ╚══════╝╚══════╝╚═╝╚═╝  ╚═══╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚══════╝
 ```
 
+**Accessibility-first CSS-Framework · Web Components · Design Intelligence · AI-Workflows**
+
+Ein Framework. Eine CLI. Ein Design System. Ein AI-fähiges Ökosystem.
+
 [![Lizenz: MIT](https://img.shields.io/badge/Lizenz-MIT-2563eb?style=flat-square)](LICENSE)
-[![Release](https://img.shields.io/badge/Release-v1.0.0-2563eb?style=flat-square)](https://github.com/SkyliteDesign/velinstyle/releases/tag/v1.0.0)
-[![npm version](https://img.shields.io/npm/v/@birdapi/velinstyle?style=flat-square)](https://www.npmjs.com/package/@birdapi/velinstyle)
-[![WCAG 2.2 AAA](https://img.shields.io/badge/WCAG_2.2-AAA-16a34a?style=flat-square)](https://velinstyle.info/docs/a11y.html)
+[![npm](https://img.shields.io/npm/v/@birdapi/velinstyle?style=flat-square)](https://www.npmjs.com/package/@birdapi/velinstyle)
+[![npm downloads](https://img.shields.io/npm/dm/@birdapi/velinstyle?style=flat-square)](https://www.npmjs.com/package/@birdapi/velinstyle)
 [![GitHub Stars](https://img.shields.io/github/stars/SkyliteDesign/velinstyle?style=flat-square)](https://github.com/SkyliteDesign/velinstyle/stargazers)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square)](https://nodejs.org/)
+[![Browser](https://img.shields.io/badge/Browser-modern-0ea5e9?style=flat-square)](https://velinstyle.info/docs/getting-started/introduction.html)
+[![WCAG 2.2 AAA Support](https://img.shields.io/badge/WCAG_2.2-AAA_Support-16a34a?style=flat-square)](https://velinstyle.info/docs/getting-started/accessibility.html)
 [![PRs Welcome](https://img.shields.io/badge/PRs-willkommen-2563eb?style=flat-square)](CONTRIBUTING.de.md)
 
 ```bash
 npm i @birdapi/velinstyle
 ```
 
-**[Website](https://velinstyle.info)** · **[Doku](https://velinstyle.info/docs/)** · **[Demos](https://velinstyle.info/demos/)** · **[npm](https://www.npmjs.com/package/@birdapi/velinstyle)** · **[Stern auf GitHub](https://github.com/SkyliteDesign/velinstyle)**
-
-**[English](README.md)** · **Deutsch**
+**[Website](https://velinstyle.info)** · **[Doku](https://velinstyle.info/docs/getting-started/introduction.html)** · **[Demos](https://velinstyle.info/demos/)** · **[Getting Started](GETTING_STARTED.md)** · **[Architecture](ARCHITECTURE.md)** · **[English](README.md)**
 
 </div>
 
 ---
 
-**VelinStyle** ist das **WCAG-2.2-AAA-CSS-Framework** mit nativer JavaScript-Runtime und Web Components — CSS-Utilities, 1.0.0-Module (Search, Motion, Highlight, Attributes, Meta) und Security-Toolchain, **ohne externe UI-Framework-Abhängigkeiten** im Kern.
+VelinStyle ist ein **produktives CSS- + Web-Components-Framework** mit **WCAG-2.2-AAA-orientierten Defaults**, einer echten **CLI-Ship-Surface**, dem **Transparency Framework** (Kennzeichnung + Nachweis, Beta) und den ersten **Design-Intelligence- / AI-Foundation**-Systemen (Beta). Kein externes UI-Framework im Kern.
 
-Gedacht für Teams mit **lesbarem HTML**, **AAA-Token-Defaults** (AA über `data-velin-contrast="aa"`) und **CLI-Automatisierung** statt Utility-Chaos.
+**Passung heute:** Marketing-Landings, Docs-Shells, einfache Admin-Starter.  
+**Noch nicht:** alleiniger Primary-Stack für große Multipage-Shops + Enterprise-Admin ohne Custom-Arbeit.
 
-> **Dogfooding:** Die gesamte VelinStyle-Website und Dokumentation läuft zu 100 % mit VelinStyle — ohne externe Skripte oder UI-Frameworks.
+> **Release:** **1.2.1** (Transparency Framework + Core + Design Intelligence Foundation + Trust/Ship). VelinStyle **zertifiziert keine Anwendung** — siehe [A11y-Matrix](https://velinstyle.info/docs/getting-started/accessibility.html).
 
 ---
 
-## Features auf einen Blick
-
-- **CSS-Utilities** — `velin-*` Spacing, Farbe, Flex, Motion, Safe-Area; Cascade Layers + OKLCH-Tokens
-- **35+ Komponenten** — semantische BEM-Klassen (`velin-btn`, `velin-card`, `velin-grid`, …)
-- **Motion-Runtime** — Reveal, Stagger, scroll-getriebene Animation, rAF-Scheduler
-- **VelinSearch** — fuzzy Offline-Suche mit Highlighting und Kategorien
-- **Syntax-Highlighting** — lazy In-View für JS, TS, HTML, CSS, JSON, Bash, Python, YAML, Go, Rust und mehr
-- **HTML-Attribute** — 27 deklarative Bridges (`velin-modal`, `velin-reveal`, `velin-scroll-top`, `velin-code`, …)
-- **Qualität** — 38/38 A11y-Component-Contracts, Playwright Cross-Browser-Smoke (`npm run test:e2e`), CLS-Platzhalter (`wc-placeholder.css`)
-- **Security-Tools** — `scan`, PII-Regeln, Sanitize-API, gehärtete Komponenten
-- **CLI** — init, build, scan, scaffold, tokens, docs generate, perf audit, layout audit
-- **Velin-Meta** — `velin-agent.json`, `llms.txt` und Page-Level-Agent-JSON für KI-Assistenten
-- **React-Adapter** — `@velinstyle/react` umhüllt jede kanonische Web Component mit typisierten Props und Events
-- **Release-Guard** — `npm run release:check` bricht den Build bei Versions- oder Docs-Drift zwischen Framework und Site ab
-
----
-
-## Installation
-
-```bash
-npm i @birdapi/velinstyle
-```
-
-| Pfad | Verwendung |
-| --- | --- |
-| `@birdapi/velinstyle/css` | Vollständiges minifiziertes Stylesheet |
-| `@birdapi/velinstyle/bundle` | Web-Components-ESM-Bundle |
-| `@birdapi/velinstyle/search` | VelinSearch-Modul |
-| `@birdapi/velinstyle/motion` | Motion-Runtime |
-| `@birdapi/velinstyle/attributes` | HTML-Attribut-Bridges |
-| `@birdapi/velinstyle/highlight` | Syntax-Highlighting |
-| `@birdapi/velinstyle/meta` | Agent-Metadaten-API |
-
-**CDN (Version pinnen):**
+## Warum VelinStyle
 
-```html
-<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@1.1.0/dist/velinstyle.min.css">
-<script type="module" src="https://unpkg.com/@birdapi/velinstyle@1.1.0/dist/velinstyle-components.min.js"></script>
-```
+| Bedarf | Was du bekommst |
+|--------|-----------------|
+| Lesbares HTML | Semantisches BEM (`velin-btn--primary`), keine Utility-Wände |
+| Accessibility | AAA-fähige Tokens, Fokus-Management, Reduced Motion — eingebaut |
+| Ship ohne Build | CDN-CSS + optionale WCs; Vite/React wenn gewünscht |
+| Vorhersehbare Overrides | Cascade Layers + OKLCH Design Tokens |
+| Quality Gates | `scan`, `review`, `check` — echte Defekte vor dem Merge |
+| KI, die hilft | Skills, Workflows, Agent-Metadata — **Mensch → Framework → KI** |
 
-Nach dem Klonen: `npm install && npm run build` — `dist/` wird erzeugt, nicht committet.
+Gegenüber **Tailwind**: weniger Class-Sprawl, stärkere Defaults für Kontrast und Semantik.  
+Gegenüber **Bootstrap**: moderne Tokens/Layers, progressive WCs, CLI-Automation statt Legacy-JS-Chrome.
 
 ---
 
-## Quickstart
-
-```html
-<!DOCTYPE html>
-<html lang="de" 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@1.1.0/dist/velinstyle.min.css">
-  <script type="module" src="https://unpkg.com/@birdapi/velinstyle@1.1.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">Loslegen</button>
-  <velin-code-block language="html" line-numbers>&lt;p class="velin-text-muted"&gt;Hallo VelinStyle&lt;/p&gt;</velin-code-block>
-</body>
-</html>
-```
+## Feature-Highlights
+
+| | Bereich | Kurz |
+|---|--------|------|
+| 🎨 | **CSS-Framework** | OKLCH-Themes, Utilities, Komponenten, Lite-Preset |
+| 🧩 | **Web Components** | 40 kanonische Custom Elements; CSS allein reicht oft |
+| ⚡ | **Runtime** | Search, Motion, Highlight, Attributes, Tree-Shaking |
+| 🛠 | **CLI** | `create` · `serve` · `doctor` · `check` · `scan` · `review` · `skills` · `transparency` |
+| 🔎 | **Transparency** | Kennzeichnung + Nachweis (KI / Trust / Compliance / Metadaten) — Beta-Foundation |
+| 🧠 | **Design Intelligence** | Plan → Constraints → Registry → Review (Beta) |
+| 🤖 | **AI Skills** | 40 Skills, Packs, Bundles, Templates, Workflows (Beta) |
+| 📦 | **Registry** | Skills + Page/Section als maschinenlesbare Verträge |
+| 📄 | **AI Metadata** | `velin-agent.json`, `llms.txt`, Page-Level-Agent-JSON |
+| 📚 | **Dokumentation** | Dogfooding — 100 % VelinStyle |
+| 🔍 | **Review Engine** | Heuristische Design-/A11y-/SEO-Gates (Beta) |
+| 🛡 | **Scan Engine** | A11y, Security, CSS-Honesty, PII |
+| 🚀 | **Performance** | Lite-CSS, Chunked Runtime, CLS-Platzhalter |
+| ♿ | **Accessibility** | Contracts, WCAG-2.2-Tooling, Keyboard + ARIA |
 
 ---
 
-## Core-Module (1.0.0)
-
-| Export | Beschreibung |
-| --- | --- |
-| `@birdapi/velinstyle/search` | Fuzzy Offline-Suche, Provider, optional Web Worker |
-| `@birdapi/velinstyle/motion` | `initMotion`, Stagger, Smooth Scroll, einheitlich `.velin-in-view` |
-| `@birdapi/velinstyle/attributes` | Registry deklarativer `velin-*` HTML-Attribut-Bridges |
-| `@birdapi/velinstyle/highlight` | `velinSyntax`, lazy Language Packs, OKLCH-Token-Farben |
-| `@birdapi/velinstyle/meta` | `buildAgentBundle`, Page-Meta MIME `application/vnd.velinstyle.meta+json` |
+## Neu in 1.2.1
 
----
+- **Transparency Framework (Beta)** — `@birdapi/velinstyle/transparency`, Bridge `velin-transparency`, Claim-Taxonomie, CLI `transparency doctor|validate|report|export|migrate`
+- Baut auf der **1.2.0**-Foundation auf: Ship Surface, Design Intelligence, AI Skills, neue WC-Primitives
 
-## Web Components
-
-**38 kanonische** Custom Elements (40 Lazy-Loader-Einträge inkl. Legacy `velin-tooltip-wc` und `velin-stepper-wc`) — reines CSS, wenn kein Verhalten nötig ist. `src/base/wc-placeholder.css` verringert Layout-Shift vor dem Upgrade.
-
-Beispiele: `velin-modal`, `velin-search`, `velin-code-block`, `velin-drawer`, `velin-stepper`, `velin-tooltip`, `velin-toast`, `velin-persist`, `velin-data-table`, `velin-form-summary`.
-
-React-Wrapper für alle kanonischen Elemente liefert [`@velinstyle/react`](./packages/react/README.md).
-
-- [Komponenten-Dokumentation](https://velinstyle.info/docs/components/buttons.html)
-- [Generierte Web-Component-API](https://velinstyle.info/docs/generated/components/README.md)
+Details: [`CHANGELOG.md`](CHANGELOG.md) · 1.2.0-Überblick: [`RELEASE_NOTES_1.2.0.md`](RELEASE_NOTES_1.2.0.md)
 
 ---
 
-## CLI
-
-| Befehl | Zweck |
-| --- | --- |
-| `npx velinstyle init` | `velinstyle.config.js` im Projekt anlegen |
-| `npx velinstyle scan` | Security, Accessibility, CSS und PII prüfen |
-| `npx velinstyle search index` | `dist/search-index.json` für Offline-Docs-Suche |
-| `npx velinstyle tokens build` | Design-Tokens-JSON nach CSS kompilieren |
-| `npx velinstyle meta` | `velin-agent.json` und `llms.txt` erzeugen |
-
-Außerdem: `npx velinstyle docs generate` — Markdown-Referenz unter `docs/generated/`.
-
----
-
-## Security
-
-VelinStyle bringt **Security-Tooling mit**, nicht als Nachgedanke:
-
-- **`velinstyle scan`** — Markup- und A11y-Regeln; PII-Scanner (`--only pii`, `--fix`)
-- **`@birdapi/velinstyle/sanitize`** — URL- und Text-Sanitization
-- **`<velin-secure-field>`** — keine Klartext-Secrets im DOM; gehärtete Search-/Copy-URLs
-
-[Security-Dokumentation](https://velinstyle.info/docs/extend/security.html)
-
----
+## Installation
 
-## Velin-Meta
+```bash
+npm i @birdapi/velinstyle
+pnpm add @birdapi/velinstyle
+yarn add @birdapi/velinstyle
+bun add @birdapi/velinstyle
+```
 
-Maschinenlesbarer Kontext für **Cursor, Copilot und eigene Agenten**:
+**CDN** (Version pinnen):
 
-- **Globaler 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`
+```html
+<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@1.2.1/dist/velinstyle.min.css">
+<script type="module" src="https://unpkg.com/@birdapi/velinstyle@1.2.1/dist/velinstyle-components.min.js"></script>
+```
 
-[Velin-Meta-Guide](https://velinstyle.info/docs/guides/velin-meta.html)
+> Pin **`@1.2.1`** (oder `@latest` nach Publish). Nach Clone: `npm install && npm run build`.
 
 ---
 
-## Doku & Website
-
-- [velinstyle.info](https://velinstyle.info) — Produktseite und Demos
-- [Guides](https://velinstyle.info/docs/guides/index.html) · [Feature scope](https://velinstyle.info/docs/guides/feature-scope.html)
-- [API-Referenz](https://velinstyle.info/docs/guides/api-reference.html) — aus dem Quellcode generiert
-- [Generiertes Markdown](https://velinstyle.info/docs/generated/index.html) — Komponenten, Tokens, Utilities, CLI, Regeln
-
----
+## Quick Start
 
-## Changelog
+```bash
+npx @birdapi/velinstyle create landing ./my-site
+cd my-site && npx @birdapi/velinstyle serve . && npx @birdapi/velinstyle check .
+```
 
-Alle Releases, Breaking Changes und Migrationsschritte: [CHANGELOG.md](CHANGELOG.md).
+Minimal-HTML und Import-Pfade: [`GETTING_STARTED.md`](GETTING_STARTED.md) · Systeme: [`ARCHITECTURE.md`](ARCHITECTURE.md) · FAQ: [`FAQ.md`](FAQ.md) · Troubleshooting: [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md)
 
 ---
 
-## Vergleich
+## CLI (Kurz)
 
-| | Bootstrap | Tailwind | Shoelace | **VelinStyle** |
-| --- | :---: | :---: | :---: | :---: |
-| HTML-Lesbarkeit | Mittel | Niedrig | Mittel | **Hoch** |
-| Klassen-Vorhersagbarkeit | Mittel | Niedrig | Mittel | **`velin-btn--primary`** |
-| Utility-Wucher | Niedrig | **Hoch** | Niedrig | **Kontrolliert** |
-| Override-Story | Schwer | Config-Datei | Shadow DOM | **CSS-Layer + Tokens** |
-| Barrierefreiheit | Teilweise | DIY | Gute WC | **WCAG 2.2 AAA-Tokens** |
-| Dark Mode | Manuell | `dark:` überall | Theme-Attribut | **Token-Tausch** |
-| App-Chrome | Legacy-JS | BYO | nur WC | **CSS + optionale WCs** |
-| Liefergeschwindigkeit | Schnell | Schnell (mit Build) | Schnell | **CDN, kein Build nötig** |
-| Runtime-Module | — | — | — | **Search, Motion, Meta, …** |
+| Befehl | Rolle |
+|--------|------|
+| `create` | Scaffolds (`landing` · `dashboard` · `docs` · `auth`) |
+| `check` | doctor + blueprints + scan + review (+ Transparency-Scores) |
+| `scan` / `review` | Statische bzw. Design-Intelligence-Gates |
+| `transparency` | doctor · validate · report · export · migrate (Beta) |
+| `skills` / `workflow` | AI-Registry & Graphen (Beta) |
+| `wc api <tag>` | WC-API aus dem Source |
+| `meta` | Agent-Bundle + `llms.txt` |
 
 ---
 
-## Live-Demos
+## Komponenten & Accessibility
 
-Vollständige Anwendungsseiten auf [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) · [Alle Demos](https://velinstyle.info/demos/) · [showcase-demos forken](https://github.com/SkyliteDesign/velinstyle/tree/main/showcase-demos)
+**40 kanonische** Custom Elements (**42** Lazy-Loader inkl. Legacy-`*-wc`). Progressive Enhancement: HTML/CSS first, WC nur bei Verhalten.
 
-<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>
+AAA-orientierte Token-Defaults, Fokus-Management, Reduced Motion, Scanner-Contracts — siehe [A11y-Matrix](https://velinstyle.info/docs/getting-started/accessibility.html).
 
 ---
 
-## Mitwirken
+## Reifegrad
 
-PRs sind willkommen.
-
-1. Repository forken
-2. `npm install && npm run build`
-3. Änderung umsetzen · `npm test`, `npm run test:a11y` und `npm run test:e2e` ausführen (nach `npm run build`)
-4. Pull Request öffnen
-
-Details: [CONTRIBUTING.de.md](CONTRIBUTING.de.md)
+| Status | Surfaces |
+|--------|----------|
+| **Stable** | CSS · Runtime · WC · CLI-Kern · Blueprints |
+| **Beta** | Transparency Framework · Review · Prompt · Knowledge Graph · AI Metadata · Constraints |
+| **Foundation** | AI Skills · Workflow Graphs · Registries · Transparency pillars |
+| **Planned** | Studio · Utility Engine Generator |
 
 ---
 
-## Lizenz
-
-[MIT](LICENSE) — Copyright © 2026 VelinStyle
+## Mitwirken & Lizenz
 
-<div align="center">
-
-Mit Sorgfalt fürs Web von [SkyliteDesign](https://github.com/SkyliteDesign)
+Siehe [`CONTRIBUTING.de.md`](CONTRIBUTING.de.md). Lizenz: [MIT](LICENSE).
 
-</div>
+Vollständige englische README: [`README.md`](README.md).