Migration Guide Tutorial

Switch from Bootstrap or Tailwind to VelinStyle — step by step. Beginners can follow the path top to bottom; pros can jump to the mapping tables and CLI. Deutsch: Migrationsleitfaden

What you get: clearer component classes (velin-btn), fewer utility stacks, and AAA color defaults. Version bumps inside VelinStyle → use Upgrading instead.

Who is this for?

BeginnerYou know HTML/CSS and want a safe checklist — start at Step 1.
In a hurrySee one button rewritten in three styles, then skim the tables.
Pro / bulk migrateJump to mapping tables + velinstyle prefix.

Pick your starting point

I use Bootstrap — replace .btn / .card with Velin components, then utilities.
I use Tailwind — shrink class salads into components; prefix remaining utilities with velin-.
Mixed / existing app — load VelinStyle side-by-side first (npm or CDN).
Already on VelinStyle — this page is not for version upgrades.

Beginner path (about 30–60 min)

Do these in order. Stop after each step and check the page still looks OK.

Add VelinStyle — install or CDN from Download. Keep Bootstrap/Tailwind for now.
Rewrite one control — change a primary button to velin-btn velin-btn--primary (see quick win).
Utilities — swap spacing/display classes using the tables below (or run the CLI dry-run).
Components — migrate navbar, cards, alerts, forms with the component table + linked docs.
Layout & theme — containers/grid + data-velin-theme (see layout section).
Remove the old stack — when coverage is good, drop Bootstrap/Tailwind CSS/JS from the bundle.

Stuck? Troubleshooting · FAQ · BirdAPI Tutorials.

Before you start (2 minutes)

Work on a branch or copy — class renames are mechanical but visual QA matters.
Open DevTools; after each batch, spot-check spacing and buttons.
Optional: skim Feature scope so you know what is stable vs beta.

Good to know: AAA color defaults

VelinStyle ships AAA contrast tokens (about 7:1 text on bright surfaces). If older muted/pastel colors look “too strong”, opt down:

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

Details: Accessibility.

Quick win: one button

Same intent — three ways to write it. VelinStyle packs look & focus into fewer classes.

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

<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>

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

Why migrate? Less class salad

Heavy Tailwind often means 10–15 classes per control. VelinStyle is component-first: semantic classes carry layout, color, hover, and focus — utilities stay for one-offs.

<!-- 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>

How VelinStyle classes work

Utilities use a velin- prefix (e.g. velin-flex) to avoid clashes. Components use BEM-style velin-* names (velin-btn, velin-card) — not Bootstrap’s unprefixed btn / card. Use the tables as find-and-replace starters, then open the linked docs for full markup.

Reference: Tailwind → utilities

Add velin- where an analogue exists. Spacing steps are not identical to Tailwind rem defaults — spot-check 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 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 index: Utilities API · Spacing.

Reference: Bootstrap → utilities

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`	Design tokens
`.text-muted`	`.velin-text-muted`	Semantic text
`.rounded`	`.velin-rounded`	Default radius
`.shadow`	`.velin-shadow`

Remember: Bootstrap component classes (.btn, .card) do not map 1:1 — use the next table.

Reference: Bootstrap → components

Bootstrap	VelinStyle	Doc
`.btn` / `.btn-primary`	`.velin-btn .velin-btn--primary`	Buttons
`.modal` / `.modal-dialog`	`.velin-modal-overlay` + `.velin-modal`	Modal · `<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`	Badge
`.form-control`	`.velin-input`	Form control
`.list-group`	`.velin-list-group` + `.velin-list-group__item`	List group

Layout & themes

Layout: .container / .row / .col-* → .velin-container, grid (.velin-grid, .velin-col-*), optional page shells.
Themes: Bootstrap data-bs-theme / Tailwind dark → data-velin-theme and CSS variables / dist/themes/*.css.

Extras you gain

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

Pro tip: CLI `velinstyle prefix`

Rewrites class / className in HTML, Vue, JSX, TSX. Dry-run is default; add --write to apply.

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

More: CLI docs · project wiring: Existing project.

Checklist

Add VelinStyle — CSS + optional JS
Side-by-side — keep the old stack until coverage is good
One component — button / card smoke test
Utilities — tables or prefix dry-run
Components — markup to velin-* patterns
Remove old CSS — drop Bootstrap/Tailwind when ready
Then upgrade notes — Upgrading for current release details

Need longer walkthroughs? BirdAPI Tutorials · snippets in the CodeGewölbe.