Migration Guide

Mechanical mappings from Tailwind and Bootstrap to VelinStyle — utilities, components, layout, and themes — so you can switch without guesswork.

Overview

VelinStyle uses a velin- prefix on utilities to avoid collisions. Components use velin-* BEM-style classes (e.g. velin-btn, velin-card) — not the unprefixed Bootstrap names. Use the tables below as find-and-replace starters; then open the linked docs for markup structure.

Migration in 5 minutes

Same primary button — three styles. VelinStyle bundles intent into fewer, semantic classes (especially for buttons).

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

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

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

Tailwind → VelinStyle utilities

Prefix Tailwind-style utilities with velin- where a direct analogue exists. Spacing scales are not identical to Tailwind’s default rem steps — spot-check in the browser after bulk replace.

Tailwind	VelinStyle	Notes
`p-4`	`.velin-p-4`	Padding scale
`text-center`	`.velin-text-center`	Same intent
`bg-blue-500`	`.velin-bg-primary`	Semantic token vs. arbitrary color
`rounded-lg`	`.velin-rounded-lg`	Radius tokens
`flex`	`.velin-flex`	Or layout helpers `.velin-flex--*`
`hidden`	`.velin-hidden`
`mt-4`	`.velin-mbs-4` or `.velin-m-4`	Logical `mbs` = margin-block-start; see Spacing
`shadow-md`	`.velin-shadow`	See Shadows
`max-w-md`	`.velin-max-w-md`	Width caps
`opacity-50`	`.velin-opacity-50`

Full utility index: Utilities API · spacing detail: Spacing.

Bootstrap → VelinStyle utilities

Display, spacing, typography, and color utilities map predictably once you add the prefix.

Bootstrap	VelinStyle	Notes
`.d-flex`	`.velin-flex`	Display utility
`.d-none`	`.velin-hidden`	Same behavior
`.mt-3`	`.velin-mbs-4` or `.velin-m-3`	Check spacing scale
`.p-4`	`.velin-p-4`
`.text-center`	`.velin-text-center`
`.bg-primary`	`.velin-bg-primary`	Uses design tokens
`.text-muted`	`.velin-text-muted`	Semantic text color
`.rounded`	`.velin-rounded`	Default radius
`.shadow`	`.velin-shadow`

Remember: Bootstrap component classes (.btn, .card) do not carry over one-to-one — use the component table below.

Bootstrap → VelinStyle components

VelinStyle is a full UI kit: CSS components plus optional Web Components. Start from the doc page for each pattern.

Bootstrap	VelinStyle	Doc
`.btn` / `.btn-primary`	`.velin-btn .velin-btn--primary`	Buttons
`.modal` / `.modal-dialog`	`.velin-modal-overlay` + `.velin-modal` (+ BEM parts)	Modal · imperative `<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` (+ modifiers)	Form control
`.list-group`	`.velin-list-group` + `.velin-list-group__item`	List group

Layout & theme migration

Layout: replace .container / .row / .col-* with .velin-container, grid utilities (.velin-grid, .velin-col-*), and optional page shells (.velin-layout-*).
Themes: map Bootstrap data-bs-theme / Tailwind dark mode to data-velin-theme and optional CSS variables / dist/themes/*.css presets.

VelinStyle unique features

Extras you get beyond Bootstrap/Tailwind parity:

color-mix() utilities — dynamic tints without a preprocessor
Scroll-driven animations — pure CSS
View Transitions API helpers
CSS @layer — predictable cascade
Web Components — optional, framework-agnostic
Zero build step — one CSS file + optional JS

CLI: mechanical class migration (`velinstyle prefix`)

The CLI can rewrite class and className in HTML, Vue, JSX, and TSX: it adds velin- where a matching utility exists, optionally maps Bootstrap d-* display classes with --bootstrap-display, and loads an explicit JSON map for everything else.

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

If velinstyle-prefix-map.json sits in the directory you pass, it is loaded automatically. Use --map to merge a custom file. Dry-run is the default; add --write to apply changes.

Migration checklist

Add VelinStyle — CSS + optional components JS
Run side-by-side — layers + prefixed utilities reduce collisions
Utilities first — replace display/spacing/type using the tables above
Then components — swap markup to velin-* patterns (see doc links)
Integrate — Existing project guide · CLI (scan, blueprints)
Remove old CSS — when coverage is complete, drop Bootstrap/Tailwind from the bundle