Tailwind → VelinStyle migrate 1.4.0

Automatisierte, ehrliche Migration für Tailwind-v3/v4-Projekte. Standard: Dry-run. Unresolved Tokens werden nie still überschrieben. Kein Fake-1:1-Anspruch. English: Tailwind migrate

Architektur: Core (@birdapi/velinstyle) → optionale Compatibility (@birdapi/velinstyle-tailwind) → optionale Heuristik (--heuristic palette-roles). Compatibility ist kein zweites Design System.

Voraussetzungen

Node.js 18+
Arbeit an einer Kopie der Site (Produktion nie ohne Backup überschreiben)
Optional: @birdapi/velinstyle-tailwind bei --compat tailwind

Drei CLI-Modi

# Nur Core (Standard: Dry-run)
velinstyle migrate tailwind ./my-project

# Core + Compatibility-Catalog
velinstyle migrate tailwind ./my-project --compat tailwind

# Core + Compat + opt-in Palette→Rollen-Heuristik
velinstyle migrate tailwind ./my-project --compat tailwind --heuristic palette-roles

# Nur Mapped Rewrites anwenden
velinstyle migrate tailwind ./my-project --write
velinstyle migrate rollback ./my-project

Modus	Catalog	Hinweise
Nur Core	nur Core	Compat-Klassen bleiben unresolved / suggested
`--compat tailwind`	Core ∪ Compat	lädt `@birdapi/velinstyle-tailwind`
`--heuristic palette-roles`	Core ∪ Compat + map-only Rollen	semantische Näherung — kein visuelles 1:1

Dry-run (Standard)

erkennt Tailwind (inkl. v3/v4 CSS-first)
analysiert statische class / className / @apply
schreibt .velin/migration/last-dry-run.json (+ .md)
ändert keine Quelldateien und erzeugt keinen Snapshot

Apply (`--write` / `--apply`)

Snapshot unter .velin/migration/snapshots/<id>/
schreibt nur Mapped Tokens um
Unresolved / Warning bleiben unberührt
Tailwind-Dependencies werden nie automatisch entfernt

Klassenbeispiele (mit Compat)

Tailwind	VelinStyle Compat
`px-4`	`velin-px-4`
`w-4`	`velin-w-4`
`grid-cols-3`	`velin-grid-cols-3`
`flex-1`	`velin-flex-1`
`rounded-md`	`velin-rounded-md`
`space-y-4`	`velin-space-y-4`
`bg-emerald-500/10`	`velin-bg-emerald-500-10` (Slash-Opacity)

Slash-Opacity

Tier 1: plain bg/text/border + /N → velin-{prop}-{color}-{N} via color-mix()
Tier 2: from/via/to/shadow/ring/outline/divide + /N
benötigt --compat tailwind
State-präfixierte Slash-Formen (z. B. hover:bg-…/10) bleiben unresolved

Responsive Compat

Unterstützte Wrapper: sm, md, lg, xl → velin-{bp}-*, wenn die Basisklasse im Catalog ist.

2xl wird nicht unterstützt und bleibt unresolved. Keine volle Tailwind-Breakpoint-Parität.

Palette-Rollen-Heuristik

Nur opt-in: --heuristic palette-roles. Mappt Palette-Solids auf vorhandene Core-Rollen, wenn ein sicheres Ziel existiert:

emerald → success
red → danger
amber → warning
blue / cyan → info
zinc / slate → surface / muted

Heuristik ≠ 1:1-Farbkonversion. Palette ohne Core-Ziel bleibt unresolved.

Reports

Dry-run-JSON enthält unter anderem:

compatibilityPackage — absent | used | suggested
heuristic — angeforderte Id + Honesty-Hinweis
dynamicAttrsSkipped — dynamische className/cn() (eigene KPI, nicht im Coverage-Nenner)
compat.requested, compat.root, compat.catalogSize, compat.gapCount
tier2SlashOpacity, paletteRoleList
Mapping-Gründe z. B. catalog-1to1, compat-slash-opacity, compat-slash-opacity-tier2, palette-role, breakpoint:sm, …

Pilotmessung (velisch.info-Kopie)

Keine Tailwind-Kompatibilitätsgarantie. Zahlen eines Pilotprojekts (velisch.info-Kopie), nicht „VelinStyle unterstützt X % von Tailwind“.

Metrik	Wert
Detected	806
Mapped (Compat + Heuristik)	559
CoverageMapped%	69.4%
Warnings	74
Unresolved	173
DynamicAttrsSkipped	351 (eigene KPI)
Compat Catalog	2736
Core Catalog	1427
Tests (Intelligence + migrate)	94
Tests (+ release-sync)	102
Historische Core-only-Baseline	162 / 806 = 20.1% (historisch)

Ein ≥80 %-Gate wurde nicht erreicht — und darf nicht behauptet werden. Realistische statische Obergrenze ohne neue Engines: etwa 70–71 %. Bewusste Architekturentscheidung in 1.4.x.

Migration Intelligence

Nach der Migrate-Analyse werden Residuals als 23 User Actions und 6 Strategy Blocks strukturiert. Acceptance, Rewrite Manifest, Preflight, Dry-Run und Apply-Gate sind verfügbar — Residual-Rewrites brauchen aber ein explizites Mapping.

SAFE_REWRITE = 0: keine freigegebenen Residual-source→target-Mappings im aktuellen Pilot. Intelligence erfindet keine Ziele. Details: Migration Intelligence.

P1 --write schreibt weiterhin nur Catalog-Mapped Tokens. Dieser Pfad ist getrennt vom Intelligence-Residual-Apply.