██╗   ██╗███████╗██╗     ██╗███╗   ██╗███████╗████████╗██╗  ██╗██╗     ███████╗
██║   ██║██╔════╝██║     ██║████╗  ██║██╔════╝╚══██╔══╝██║  ██║██║     ██╔════╝
██║   ██║█████╗  ██║     ██║██╔██╗ ██║███████╗   ██║   ███████║██║     █████╗
╚██╗ ██╔╝██╔══╝  ██║     ██║██║╚██╗██║╚════██║   ██║   ██╔══██║██║     ██╔══╝
 ╚████╔╝ ███████╗███████╗██║██║ ╚████║███████║   ██║   ██║  ██║███████╗███████╗
  ╚═══╝  ╚══════╝╚══════╝╚═╝╚═╝  ╚═══╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚══════╝

Accessibility-first CSS Framework · Web Components · Design Intelligence · AI Workflows

One framework. One CLI. One design system. One AI-ready ecosystem.

npm i @birdapi/velinstyle

Website · Atelier · Docs · Demos · Getting Started · Architecture · Deutsch

VelinStyle is a production CSS + Web Components framework with WCAG 2.2 AAA-oriented defaults, a real CLI ship surface, the Transparency Framework (labeling + provenance, beta), and the first Design Intelligence / AI Foundation systems (beta). No external UI framework in the core.

VelinStyle Atelier is the curated surface on top: 2,600+ production-ready interfaces, four complete product worlds, and a browsable library — complete screens instead of empty component fragments.

Best fit today: marketing landings, docs shells, admin/SaaS starters, shop & community UIs via Atelier.
Not yet: sole primary stack for large multipage shop + enterprise admin without custom work.

Release: 1.4.0 (Tailwind migrate CLI · Migration Intelligence · Scanner diagnostics · Skills 2.0). Motion Clips from 1.3.0 remain via @birdapi/velinstyle-motion. Using VelinStyle does not certify your app — see the a11y matrix. Release notes: RELEASE_NOTES_1.4.0.md · Upgrade: UPGRADING.md

Why VelinStyle

| Need | What you get | |------|----------------| | Readable HTML | Semantic BEM (velin-btn--primary), not utility walls | | Accessibility | AAA-capable tokens, focus management, reduced motion — built in | | Ship without a build | CDN CSS + optional WCs; Vite/React when you want them | | Predictable overrides | Cascade layers + OKLCH design tokens | | Quality gates | scan, review, check — catch real defects before merge | | AI that helps | Skills, workflows, and agent metadata — Mensch → Framework → KI |

The Tailwind sprawl problem

Heavy Tailwind use often turns HTML into a class salad — a simple button can need 10–15 utilities (flex items-center … hover:bg-blue-700 … focus:ring-2 …). VelinStyle still uses a velin- prefix, but ships semantic, ready-made components (plus utilities for one-off tweaks) instead of assembling every surface from atomic pieces. You get shorter markup, built-in a11y defaults, and optional blueprints / plan recipes — not a finished Studio product (Studio remains planned).

<!-- Tailwind sprawl -->
<button class="inline-flex items-center justify-center px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white text-sm font-medium rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500">
  Save
</button>

<!-- VelinStyle -->
<button class="velin-btn velin-btn--primary">Save</button>

Compared to Tailwind: less class sprawl, stronger defaults for contrast and semantics. See the Migration Guide.
Compared to Bootstrap: modern tokens/layers, optional progressive WCs, CLI automation instead of jQuery-era chrome.

Feature highlights

| | Area | What it does | |---|------|----------------| | 🎨 | CSS Framework | OKLCH themes, utilities, components, lite preset for marketing budgets | | 🧩 | Web Components | 43 canonical custom elements; use CSS alone when you need no JS | | ⚡ | Runtime | Search, motion, highlight, attributes, bootFromDOM tree-shaking | | 🛠 | CLI | create · serve · doctor · check · scan · migrate · blocks · review · skills · transparency | | 🔎 | Transparency | Labeling + provenance (AI / trust / compliance / metadata) — beta foundation | | 🧠 | Design Intelligence | Plan → constraints → page/section registry → review (beta) | | 🤖 | AI Skills | 58 skills (registry 1.0.0), packs, bundles, templates, workflow graphs (Skills 2.0) | | 📦 | Registry | Skills + page/section registries as machine-readable contracts | | 📄 | AI Metadata | velin-agent.json, llms.txt, /.well-known/ai.json, scan policy | | 📚 | Documentation | Dogfooded site — 100% VelinStyle | | 🔍 | Review Engine | Heuristic design / a11y / SEO / conversion gates (beta) | | 🛡 | Scan Engine | A11y, security, CSS honesty, PII, link integrity, structured diagnostics, SAFE Apply | | 🚀 | Performance | Lite CSS, chunked runtime, CLS placeholders | | ♿ | Accessibility | Contracts, WCAG 2.2 tooling, keyboard + ARIA patterns | | 🖼 | Atelier | Curated library of complete interfaces, layouts & studio blocks | | 🔄 | Migration | Tailwind → VelinStyle CLI + Migration Intelligence; optional @birdapi/velinstyle-tailwind compat |

VelinStyle Atelier

Atelier is the product showcase for VelinStyle: complete interfaces, not isolated buttons and cards. Browse by intent (apps, marketing, commerce, auth…), open live worlds, copy source, or download ZIPs.

| Surface | What you get | Link | |---------|--------------|------| | Atelier home | Brand hub — why Atelier, four worlds, build paths | Open | | Library | 2,638 templates — filter by mode, category, tags, quality | Browse | | Cascade Console | Enterprise / SaaS dashboard world | Live demo | | LUMEN | Full shop — catalog, cart, checkout | Live demo | | FORGE | Community & forum system | Live demo |

Library shortcuts: Apps · Studio blocks · Recipes · Marketing · Dashboards · Auth

German Atelier hub: atelier/index.de.html

What's new in 1.4.0

Tailwind → VelinStyle migration CLI · Migration Intelligence · Scanner diagnostics & link integrity · Skills 2.0 · Adaptive Runtime foundations.

npx velinstyle migrate tailwind ./my-app          # dry-run (default)
npx velinstyle migrate tailwind ./my-app --write  # apply mapped changes
npx velinstyle scan . --json --fix-dry-run        # preview SAFE fixes
npx velinstyle scan . --sarif                     # SARIF 2.1.0 output
npx velinstyle blocks list

| Area | Highlights | | --- | --- | | Migration | migrate tailwind / migrate rollback; Migration Intelligence (23 User Actions, 6 Strategy Blocks); optional @birdapi/velinstyle-tailwind compat | | Scanner | Link integrity (detect-only links/*); structured diagnostic on findings; --fix-dry-run; fail-closed SAFE Apply (5 rules) | | AI / Agent | Skills registry 1.0.0 with 58 skills; Agent Workflows docs; velin-agent.json + llms.txt from registry SoT | | Runtime | Studio Inspector Core, Velin Blocks (10 official), Safe Adaptation Engine (@birdapi/velinstyle/adapt) | | Motion | Motion Clips from 1.3.0 remain via @birdapi/velinstyle-motion |

Counts aligned with velin-agent.json: 43 canonical Web Components · 45 lazy loaders · 36 attribute bridges · 58 skills.

Docs: docs/guides/tailwind-migrate.md · docs/guides/agent-workflows.md · RELEASE_NOTES_1.4.0.md

What's new in 1.3.0

Velin Motion Clips — image→clip CLI (local HTML/CSS + optional PixVerse AI).

npx velinstyle motion create hero.webp --preset cinematic
npx velinstyle motion providers
npx velinstyle motion setup pixverse

• Package @birdapi/velinstyle-motion / export @birdapi/velinstyle/motion-clip
• Local clip engine: zoom · pan · rotate · particles · intro/outro · transitions
• Clip presets · interactive wizard · optional PixVerse provider (external credits + API key)
• PixVerse setup: account + API key (motion setup pixverse) — PixVerse account · site guide
• Docs: docs/guides/velin-motion-clips.md · RELEASE_NOTES_1.3.0.md

What's new in 1.2.5

Velin Experience — the product layer behind velinstyle (1.2.3 Foundation · 1.2.4 Engine · 1.2.5 Product Surface).

npx velinstyle doctor .
npx velinstyle dashboard
npx velinstyle production . --explain
npx velinstyle doctor . --record
npx velinstyle replay .velin/records/<file>.json

• Output Contract · Event Bus · Registry Help · Themes/Modes
• Content Scanner: Blade first-class + Twig / Astro / MDX / Vue / React
• Production Report breakdown (CSS · Runtime · Icons · Themes · Motion · Components)
• dashboard · --record / replay · plugin skeleton · local analytics hints

See RELEASE_NOTES_1.2.5.md · docs/guides/velin-experience.md.

What's new in 1.2.2

Production Release — Build only what your project actually uses.

VelinStyle analyzes your project and creates an optimized production package instead of shipping the complete framework. This release also adds the first Atelier CLI (beta) and new production-ready components.

Production Builder

npx velinstyle build --production --explain
# → ./dist/velin-production/ (CSS, JS stub, themes, icons, report)

• CSS only for used components · runtime only for needed Web Components
• Themes / icons / motion only when used · size report

Atelier CLI (Beta)

npx velinstyle atelier list
npx velinstyle atelier 24
npx velinstyle scaffold --atelier 24

Atelier Library ≠ Velin Studio (Studio remains planned). See docs/guides/atelier-cli.md.

New components & improvements

• <velin-otp-input>, <velin-password-strength>, <velin-empty-state>
• Table severity states · dynamic overlay titles (modal / drawer / sheet)

See RELEASE_NOTES_1.2.2.md and docs/guides/production-build.md.

What's new in 1.2.1

• Transparency Framework (beta) — @birdapi/velinstyle/transparency, velin-transparency bridge, claim taxonomy, CLI transparency doctor|validate|report|export|migrate
• Builds on 1.2.0 foundation: ship surface, Design Intelligence, AI Skills, new WC primitives

Details: CHANGELOG.md · 1.2.0 overview: RELEASE_NOTES_1.2.0.md

Installation

npm i @birdapi/velinstyle
pnpm add @birdapi/velinstyle
yarn add @birdapi/velinstyle
bun add @birdapi/velinstyle

CDN (pin a version):

<link rel="stylesheet" href="https://unpkg.com/@birdapi/[email protected]/dist/velinstyle.min.css">
<script type="module" src="https://unpkg.com/@birdapi/[email protected]/dist/velinstyle-components.min.js"></script>

Pin @1.4.0 (or @latest after publish). Examples above match this package version.

| Export | Use | |--------|-----| | @birdapi/velinstyle/css | Full stylesheet | | @birdapi/velinstyle/bundle | Web Components ESM | | /search /motion /attributes /highlight /meta /sanitize | Tree-shakeable modules |

After clone: npm install && npm run build — dist/ is generated, not committed.

Quick start

<!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/[email protected]/dist/velinstyle.min.css">
  <script type="module" src="https://unpkg.com/@birdapi/[email protected]/dist/velinstyle-components.min.js"></script>
</head>
<body class="velin-p-6">
  <button type="button" class="velin-btn velin-btn--primary">Ship it</button>
  <velin-toast></velin-toast>
</body>
</html>

Scaffold + gate (local 1.2 tree / after publish):

npx @birdapi/velinstyle create landing ./my-site
cd my-site && npx @birdapi/velinstyle serve . && npx @birdapi/velinstyle check .

More: GETTING_STARTED.md

CLI

| Command | Role | |---------|------| | init | Project config | | create | Opinionated scaffolds (landing · dashboard · docs · auth) | | build | CSS build (--preset lite for marketing) | | serve | Static preview | | doctor | Install / path health | | check | doctor + blueprints + scan + review (+ Transparency scores) | | scan | A11y / security / CSS / PII / link integrity; --json · --sarif · --fix-dry-run · SAFE Apply | | migrate | Tailwind → VelinStyle (tailwind, rollback); dry-run default | | blocks | Official Velin Blocks registry (list · info · add) | | review | Design-intelligence gate (beta) | | transparency | doctor · validate · report · export · migrate (beta) | | plan | Prompt → plan JSON → render (beta); --atelier Library plan (beta) | | scaffold | Prompt HTML or --atelier Library compose (beta) | | atelier | Pull curated Library showcase by number/id (--format wrappers) | | skills / workflow | AI skill registry & graphs (beta) | | meta | Agent bundle + llms.txt | | wc api <tag> | Human-readable WC API from source |

npx @birdapi/velinstyle check . --profile marketing
npx @birdapi/velinstyle scan . --json --fix-dry-run
npx @birdapi/velinstyle migrate tailwind ./my-app
npx @birdapi/velinstyle transparency doctor . --policy examples/transparency.policy.json
npx @birdapi/velinstyle blocks list
npx @birdapi/velinstyle atelier 36 -o ./velin-atelier/36-calendar
npx @birdapi/velinstyle scaffold --atelier 04,07 -o compose.html
npx @birdapi/velinstyle wc api velin-toast

Atelier pull / compose details and limitations (wrappers ≠ native Blade/Vue/React; Studio planned): docs/guides/atelier-cli.md.

AI Skills & Design Intelligence

AI Skills give agents and humans a shared vocabulary: skill records, packs, bundles, templates, and workflow graphs. They exist so tooling can scaffold, review, and ship without inventing VelinStyle from scratch.

Design Intelligence adds structure ordinary CSS frameworks lack: a knowledge graph seed, page/section registries, design constraints, and plan / review so pages are assembled from known patterns — then checked against profiles (marketing · app · docs · ecommerce).

Atelier compose (beta): scaffold --atelier / plan --atelier can assemble pages from curated Atelier Library ids. This is Library compose — not Velin Studio (planned). Framework --format shells are wrappers only; native Blade/Vue/React blocks are planned later. See docs/guides/atelier-cli.md.

Deep dive: ARCHITECTURE.md · VELINSTYLE_2030.md · Strategy (lokal, nicht im Git): docs/strategy/README.md

Components

43 canonical custom elements (45 lazy-loader entries including legacy *-wc aliases; 3 helpers: flip / haptic / reveal).

Philosophy: progressive enhancement — semantic HTML + CSS first; upgrade to a Web Component only when you need behavior (focus traps, sorting, offline search).

Highlights: velin-modal, velin-drawer, velin-search, velin-data-table, velin-form-summary, velin-calendar, velin-file-dropzone, velin-toast, velin-code-block.

React: @velinstyle/react wraps every canonical tag.

Accessibility

Accessibility is a default, not a plugin.

• WCAG 2.2 AAA-oriented token defaults (data-velin-contrast="aa" when you need the lighter palette)
• Semantic HTML patterns and BEM components
• Keyboard support, focus management, inert overlays
• prefers-reduced-motion gating
• Component a11y contracts + scanner rules

Docs: a11y matrix · AAA marketing language: see VELINSTYLE_2030.md (strategy ADRs are local-only)

Documentation map

| Layer | File / link | Audience | |-------|-------------|----------| | Landing | This README | First 30 seconds | | First build | GETTING_STARTED.md | New adopters | | FAQ | FAQ.md | Common questions | | Troubleshooting | TROUBLESHOOTING.md | When stuck | | Deploy | DEPLOY.md | Ship to production | | Systems | ARCHITECTURE.md | Advanced / AI / DI | | Design Intelligence | docs/guides/design-intelligence.md | Plan / review | | CLI ship surface | docs/guides/cli-ship-surface.md | create / check / wc | | Tailwind migrate | docs/guides/tailwind-migrate.md | migrate CLI + Intelligence | | AI Skills | docs/guides/ai-skills.md | Skills / workflows | | Agent workflows | docs/guides/agent-workflows.md | Skills 2.0 routing | | Product site | velinstyle.info/docs | Guides, demos, reference | | AI Resources | velinstyle.info/docs/guides/ai-resources.html | Agent discovery hub | | Atelier | velinstyle.info/atelier | Template library + product worlds | | Transparency | Site guide · @birdapi/velinstyle/transparency | Labeling + provenance | | Upgrade | UPGRADING.md | 1.3.0 → 1.4.0 · 1.2.x → 1.3.0 · 1.2.0 → 1.2.1 · 1.1 → 1.2 | | North star | VELINSTYLE_2030.md | Long-term vision |

Repository structure

velinstyle/
├── src/                 # CSS source (tokens, base, components, utilities)
├── components/          # Web Components (JS)
├── core/                # Runtime: search, motion, highlight, attributes, meta, transparency
├── cli/                 # velinstyle binary
├── packages/            # React wrappers, skill-engine, skills registry
├── schemas/             # Design Intelligence + skill contracts
├── docs/                # Docs + strategy ADRs
├── samples/             # Local HTML samples
├── templates/           # Starters (e.g. Vite + React)
├── fixtures/            # Scanner / chaos fixtures
└── showcase-demos/      # Full-page demos

Philosophy

Mensch → Framework → Design Intelligence → AI

Humans own product intent. The framework ships reliable CSS and components. Design Intelligence encodes patterns and constraints. AI skills and workflows accelerate scaffolding and review — they support developers; they do not replace judgment, accessibility ownership, or design responsibility.

Roadmap (maturity)

| Status | Surfaces | |--------|----------| | Stable | CSS · Utilities · Runtime · Web Components · CLI core · Blueprints · Tailwind migrate CLI | | Beta | Transparency Framework · Review Engine · Prompt Engine · Knowledge Graph · AI Metadata · Design Constraints · Velin Blocks | | Foundation | AI Skills 2.0 (58) · Workflow Graphs · Registries · Migration Intelligence · Safe Adaptation Engine | | Planned | Velin Studio builder · Utility Engine Generator · native Blade/Vue/React blocks |

Comparison

| | Bootstrap | Tailwind | VelinStyle | |---|:---:|:---:|:---:| | HTML readability | Medium | Low | High | | Markup density | Low | High | Controlled | | Utility sprawl | Low | High | Controlled | | A11y defaults | Partial | DIY | AAA-capable tokens | | Dark mode | Manual | dark: everywhere | Token swap | | Build required | No | Usually | CDN optional | | Design / AI gates | — | — | plan · review · skills · transparency |

Contributing

1. Fork → npm install && npm run build
2. Change code · run npm test, npm run test:a11y, npm run test:e2e
3. Open a PR

See CONTRIBUTING.md.

License

MIT — © 2026 VelinStyle · SkyliteDesign

Live demos & modules

Explore finished surfaces — Atelier worlds, the template library, and classic component demos.

Atelier product worlds

| Module | Focus | Demo | |--------|-------|------| | Cascade Console | Enterprise API / AI dashboard | Open | | LUMEN | E-commerce storefront | Open | | FORGE | Community forum | Open | | Atelier Library | Full template hub (2,638) | Open | | Atelier home | Marketing hub (EN) | Open | | Atelier home | Marketing hub (DE) | Open |

Classic demo modules

| Module | Focus | Demo | |--------|-------|------| | Demo index | All classic showcases | Open | | Crypto dashboard | Dense admin / charts | Open | | Dashboard | App shell & KPIs | Open | | SaaS | Product marketing | Open | | E-commerce | Shop patterns | Open | | Forum | Community UI | Open | | UI Kit | Component gallery | Open | | Interactive | WC behavior samples | Open | | Runtime | Search / motion / boot | Open |

Library by intent

| Intent | Link | |--------|------| | Applications | library/?mode=apps | | Studio blocks | library/?mode=studio | | Recipes | library/?mode=recipes | | Marketing | library/?cat=marketing | | Dashboards | library/?cat=dashboards | | Commerce | library/?cat=commerce | | Authentication | library/?cat=authentication | | Community | library/?cat=community | | Admin | library/?cat=admin |