@birdapi/velinstyle-tailwind

Optional Compatibility Layer for migrating Tailwind CSS projects to VelinStyle.

Compatibility ≠ Design System.
This package is not a second design system, not full Tailwind parity, and not a replacement for Core. Coverage is directional — there is no guaranteed 1:1 visual or class compatibility with Tailwind.

| Package | Role | |---------|------| | @birdapi/velinstyle | Core — tokens, utilities, components, runtime, CLI | | @birdapi/velinstyle-tailwind | Optional migration / Tailwind-near CSS (opt-in) |

Opt-in usage

npm install @birdapi/velinstyle @birdapi/velinstyle-tailwind

@import '@birdapi/velinstyle';
@import '@birdapi/velinstyle-tailwind';

Import Core first so Compat can reuse Core tokens / theme vars when present.

Class names use the velin-* prefix (e.g. Tailwind px-4 → velin-px-4). The package is the compatibility namespace — there is no velin-tw-* prefix.

CLI

# Core-only
velinstyle migrate tailwind <project>

# Core + Compat (this package)
velinstyle migrate tailwind <project> --compat tailwind

# Core + Compat + opt-in palette→role heuristic (map-only; not CSS from this package)
velinstyle migrate tailwind <project> --compat tailwind --heuristic palette-roles

• Compat is optional. --compat tailwind loads this package’s catalog on top of Core. Without the flag, migrate stays Core-only (Compat classes are never applied silently).
• Heuristic is optional. Requires an explicit --heuristic palette-roles flag.
• Dry-run is default. Unresolved tokens are never auto-replaced. Tailwind deps are never auto-removed.

Report field compatibilityPackage: used | suggested | absent.

MVP utilities (layout / spacing)

| Sheet | Classes | |-------|---------| | spacing.css | velin-px-*, velin-pl-*, velin-pr-*, velin-mx-*, velin-ml-*, velin-mr-*, velin-space-x-*, velin-space-y-* | | sizing.css | numeric velin-w-*, velin-h-* (not Core keywords like velin-w-full) | | flex-grid.css | velin-flex-1, velin-flex-none, velin-grow, velin-shrink, velin-shrink-0, velin-grid-cols-1…12 | | misc.css | velin-z-0…50, velin-rounded-md |

Scale (no arbitrary values): spacing 0 1 2 3 4 5 6 8 10 12 16 20 24 32; sizing adds px + extra rem stops.

velin-grid-cols-* is CSS Grid (grid-template-columns) — not Core velin-col-*.

Static-scale gaps (Phase 7E)

Sheet: static-scale.css (generated).

| Tailwind | Compat | Notes | |----------|--------|-------| | pt-8 | velin-pt-8 | physical padding-top (alias pbs falls through when missing) | | pb-1 | velin-pb-1 | only keys not in Core (Core pb-* = logical padding-block) | | py-5 | velin-py-5 | physical top+bottom; Core collisions skipped | | mt-12 / mb-10 / my-16 | velin-mt-* / velin-mb-* / velin-my-* | Compat scale | | gap-12 | velin-gap-12 | keys beyond Core gap-0…8 | | opacity-5/10/70 | velin-opacity-* | extras only | | rounded-3xl | velin-rounded-3xl | uses --velin-radius-2xl (1.5rem) | | shadow-md | velin-shadow-md | uses existing --velin-shadow-md token |

Out of scale (not generated): half-steps, pl-7, pt-36 / pb-48.

Medium-static (Phase 7F)

Sheet: medium-static.css (generated). Selective deterministic utilities only.

| Area | Examples | |------|----------| | Typography | text-8xl, italic, font-black, leading-7, tracking-tighter/widest, antialiased | | Sizing | max-w-3xl…7xl, min-w-0, size-2/3/4, size-full | | Insets | top-4, left-0, -bottom-6 → velin--bottom-6 | | Border | border-t/b/l/r/x/y, border-dashed, border-l-2/4 | | Cursor | cursor-*-resize; Core alias pointer-events-none → velin-pointer-none | | Misc | list-*, mx-auto, gap-x-8, gap-y-2, col-span-2, outline-none, -z-10 |

Not included: theme roles (bg-card), half-steps, fractions (left-1/2), motion/gradients direction, rounded-tl-sm (see Phase 7G).

Final-static (Phase 7G)

Sheet: final-static.css (generated). Last safe static leftovers only.

| Tailwind | Compat | |----------|--------| | scroll-m-20 | velin-scroll-m-20 | | fill-current | velin-fill-current | | auto-rows-max | velin-auto-rows-max | | bg-clip-text | velin-bg-clip-text | | rounded-r-lg / rounded-tl-sm | corner radii via Core tokens | | from-white / from-transparent / to-black / to-transparent | gradient stop vars (not direction) | | pl-7 / pt-36 / pb-48 | pilot rem keys | | border-bottom | alias → velin-border-b |

Slash-opacity (Tier-1)

Sheet: opacity-color.css (generated).

| Tailwind | Compat | |----------|--------| | bg-emerald-500/10 | velin-bg-emerald-500-10 | | border-emerald-500/30 | velin-border-emerald-500-30 | | text-emerald-400/80 | velin-text-emerald-400-80 |

• Slash / becomes - in the class name.
• Implementation: dedicated classes + color-mix(in oklab, … N%, transparent) inside this package only.
• Palette colors use Compat-local --velin-tw-* tokens (only hues/shades needed by the Tier-1 list).
• Theme stems (muted, card, background, …) use host CSS vars (--muted, …) — not remapped to Velin semantic roles.

Tier-1 scope

• Plain static bg-* / text-* / border-* with slash opacity
• Generated from the Phase-6A pilot inventory (124 classes in the current cut)

Explicitly out of scope

• hover: / focus: / disabled: / group-hover:
• dark:
• 2xl: (no Core 2xl breakpoint)
• Arbitrary values (bg-[#…]/10, md:w-[…])
• cn() / dynamic className
• Palette → semantic role heuristics (opt-in CLI --heuristic palette-roles, map-only — not this CSS package)
• Any Core CSS for Tailwind parity

Slash-opacity (Tier-2)

Sheet: opacity-color-tier2.css (generated).

| Tailwind | Compat | Technique | |----------|--------|-----------| | from-emerald-500/10 | velin-from-emerald-500-10 | --tw-gradient-from + stops wiring | | via-blue-500/50 | velin-via-blue-500-50 | --tw-gradient-via + via-stops | | to-cyan-500/10 | velin-to-cyan-500-10 | --tw-gradient-to | | shadow-emerald-500/20 | velin-shadow-emerald-500-20 | --tw-shadow-color only | | ring-ring/50 | velin-ring-ring-50 | --tw-ring-color | | outline-ring/50 | velin-outline-ring-50 | outline-color | | divide-border/50 | velin-divide-border-50 | sibling border-color |

Gradients keep multi-stop semantics (no collapse to a single background). Shadow is a color modifier, not a full box-shadow utility.

Tier-2 out of scope

• State variants (hover:shadow-…, focus-visible:ring-…)
• Arbitrary colors
• Inventing full shadow stacks or fake 1:1 visual claims

Responsive (BP allowlist)

Sheet: responsive.css (generated).

Wraps existing Compat bases (and a few Core extras) as:

md:px-4 → velin-md-px-4

Breakpoints match Core: sm 36rem · md 48rem · lg 62rem · xl 80rem. No 2xl.

Requires --compat tailwind so the Compat catalog is loaded. Without Compat, responsive Compat classes stay unresolved.

Anti-duplicate

Compat must not define a selector already present in the Core catalog (assertNoCatalogCollisions).

Docs

ADR 0020 · PILOT_COMPAT_ARCHITECTURE.md · PILOT_SLASH_OPACITY_ANALYSIS.md