Migrationsleitfaden 1.2.0

Mechanische Zuordnungen von Tailwind und Bootstrap zu VelinStyle — Utilities, Komponenten, Layout und Themes — damit du ohne Rätselraten wechseln kannst. English: Migration Guide

Reifegrad: CSS- und Komponenten-Zuordnungen sind stabil. Nach der Migration sind optionale plan- / review- / Agent-Meta-Funktionen Beta / Foundation — siehe Prompt scaffolding und Upgrading to 1.2.0.

Wann verwenden?

Du ersetzt Bootstrap- oder Tailwind-Klassennamen durch velin-*-Utilities und Komponenten.
Du brauchst eine Checkliste plus velinstyle prefix für mechanische Umschreibungen.

Wann nicht?

Greenfield-Projekte — starte stattdessen bei Introduction / Download.
Versionssprünge innerhalb von VelinStyle — nutze Upgrading.

WCAG-2.2-AAA-Farbdefaults

VelinStyle liefert AAA-Kontrast-Token-Defaults in :root, im Dark Mode und in allen 13 Themes. Text- und semantische Farben zielen auf mindestens 7:1 auf hellen Oberflächen (npm run test:contrast im Framework-Repo).

Wenn dein Produkt auf hellere Muted-Texte oder pastellige Primärfarben aus älteren Pins gebaut hat, kannst du auf <html> herunterstufen:

<html data-velin-contrast="aa">

Dadurch wird AA-Fließtext (4.5:1) geladen, während Focus-, Skip-Link- und Target-Size-Defaults erhalten bleiben. Siehe Accessibility und AAA matrix.

Empfohlener Runtime-Bootstrap:

import { initA11y } from '@birdapi/velinstyle/a11y';
initA11y({ announcer: true, scrollPadding: true });

Überblick

VelinStyle nutzt den Prefix velin- für Utilities, um Kollisionen zu vermeiden. Komponenten verwenden velin-*-BEM-Klassen (z. B. velin-btn, velin-card) — nicht die unpräfixierten Bootstrap-Namen. Nutze die Tabellen unten als Ausgangspunkt für Suchen/Ersetzen und öffne danach die verlinkten Docs für die Markup-Struktur.

Migration in 5 Minuten

Derselbe Primary Button in drei Stilen. VelinStyle bündelt Absichten in weniger, semantischen Klassen, besonders bei Buttons.

<button class="btn btn-primary">Speichern</button>

<button class="px-4 py-2 bg-blue-500 text-white rounded">
  Speichern
</button>

<button class="velin-btn velin-btn--primary">Speichern</button>

Tailwind → VelinStyle Utilities

Präfixe Tailwind-artige Utilities mit velin-, wenn ein direktes Gegenstück existiert. Die Spacing-Skalen sind nicht identisch mit Tailwinds Standard-rem-Schritten — prüfe Bulk-Replacements im Browser stichprobenartig.

Tailwind	VelinStyle	Hinweise
`p-4`	`.velin-p-4`	Padding-Skala
`text-center`	`.velin-text-center`	Gleiche Absicht
`bg-blue-500`	`.velin-bg-primary`	Semantisches Token statt beliebiger Farbe
`rounded-lg`	`.velin-rounded-lg`	Radius-Tokens
`flex`	`.velin-flex`	Oder Layout-Helfer `.velin-flex--*`
`hidden`	`.velin-hidden`
`mt-4`	`.velin-mbs-4` oder `.velin-m-4`	Logisches `mbs` = margin-block-start; siehe Spacing
`shadow-md`	`.velin-shadow`	Siehe Shadows
`max-w-md`	`.velin-max-w-md`	Breitenbegrenzungen
`opacity-50`	`.velin-opacity-50`

Vollständiger Utility-Index: Utilities API · Spacing-Details: Spacing.

Bootstrap → VelinStyle Utilities

Display-, Spacing-, Typografie- und Farb-Utilities lassen sich nach dem Hinzufügen des Prefixes gut abbilden.

Bootstrap	VelinStyle	Hinweise
`.d-flex`	`.velin-flex`	Display-Utility
`.d-none`	`.velin-hidden`	Gleiches Verhalten
`.mt-3`	`.velin-mbs-4` oder `.velin-m-3`	Spacing-Skala prüfen
`.p-4`	`.velin-p-4`
`.text-center`	`.velin-text-center`
`.bg-primary`	`.velin-bg-primary`	Nutzt Design Tokens
`.text-muted`	`.velin-text-muted`	Semantische Textfarbe
`.rounded`	`.velin-rounded`	Standardradius
`.shadow`	`.velin-shadow`

Merke: Bootstrap-Komponentenklassen (.btn, .card) werden nicht eins zu eins übernommen — nutze die Komponententabelle unten.

Bootstrap → VelinStyle Komponenten

VelinStyle ist ein vollständiges UI-Kit: CSS-Komponenten plus optionale Web Components. Starte für jedes Pattern auf der jeweiligen Docs-Seite.

Bootstrap	VelinStyle	Doc
`.btn` / `.btn-primary`	`.velin-btn .velin-btn--primary`	Buttons
`.modal` / `.modal-dialog`	`.velin-modal-overlay` + `.velin-modal` (+ BEM-Teile)	Modal · imperativ `<velin-dialog>`
`.alert` / `.alert-info`	`.velin-alert .velin-alert--info`	Alerts
`.navbar`	`.velin-nav` + `.velin-nav__*`	Navbar
`.card`	`.velin-card` + `.velin-card__*`	Card
`.badge`	`.velin-badge .velin-badge--primary` (etc.)	Badge
`.form-control`	`.velin-input` (+ Modifier)	Form control
`.list-group`	`.velin-list-group` + `.velin-list-group__item`	List group

Layout- & Theme-Migration

Layout: Ersetze .container / .row / .col-* durch .velin-container, Grid-Utilities (.velin-grid, .velin-col-*) und optionale Page Shells (.velin-layout-*).
Themes: Bilde Bootstrap data-bs-theme / Tailwind Dark Mode auf data-velin-theme ab, optional mit CSS-Variablen / dist/themes/*.css-Presets.

Einzigartige VelinStyle-Features

Extras über Bootstrap-/Tailwind-Parität hinaus:

color-mix()-Utilities — dynamische Tints ohne Präprozessor
Scroll-driven animations — reines CSS
View Transitions API-Helfer
CSS @layer — vorhersagbare Cascade
Web Components — optional und framework-agnostisch
Zero build step — eine CSS-Datei plus optionales JS

CLI: mechanische Klassenmigration (`velinstyle prefix`)

Die CLI kann class und className in HTML, Vue, JSX und TSX umschreiben: Sie fügt velin- hinzu, wo eine passende Utility existiert, kann Bootstrap-d-*-Display-Klassen mit --bootstrap-display abbilden und lädt für alles Weitere eine explizite JSON-Map.

npx velinstyle prefix ./src
npx velinstyle prefix ./src --write
npx velinstyle prefix ./src --bootstrap-display --write
npx velinstyle prefix ./src --map ./velinstyle-prefix-map.json --write

Wenn velinstyle-prefix-map.json im übergebenen Verzeichnis liegt, wird sie automatisch geladen. Nutze --map, um eine eigene Datei zu mergen. Dry-run ist der Default; füge --write hinzu, um Änderungen anzuwenden.

Migrationscheckliste

VelinStyle hinzufügen — CSS + optionale Komponenten-JS
Parallel betreiben — Layers und präfixierte Utilities reduzieren Kollisionen
Utilities zuerst — Display/Spacing/Typografie mit den Tabellen oben ersetzen
Danach Komponenten — Markup auf velin-*-Patterns umstellen (siehe Docs-Links)
Integrieren — Existing project guide · CLI (scan, Blueprints); optional plan / review (Beta)
Altes CSS entfernen — wenn die Abdeckung vollständig ist, Bootstrap/Tailwind aus dem Bundle nehmen
1.2.0 pinnen — nach der Migration Upgrading für Overlay-Lifecycle und Agent-Meta-Hinweise folgen