Upgrading VelinStyle 1.4.0

Current target is 1.4.0 (Tailwind migrate CLI + Migration Intelligence + optional Compatibility package + optional Core Features through Phase 6.1). Follow semver and the CHANGELOG when bumping. Deutsch: Aktualisieren

1.3.x → 1.4.0

1. Bump to @birdapi/velinstyle@1.4.0 (optional: @birdapi/velinstyle-tailwind@1.4.0).
2. On a copy of your site:

   npx velinstyle migrate tailwind ./my-project
   npx velinstyle migrate tailwind ./my-project --compat tailwind
   npx velinstyle migrate tailwind ./my-project --compat tailwind --heuristic palette-roles

3. Review unresolved/warnings; apply with --write only when ready.
4. Expect honest coverage — pilot reference 69.4% Mapped; 80% gate not reached. Catalog sizes: Compat 2736 · Core 1427 · Intelligence+migrate tests 94 (with release-sync 102).
5. Migration Intelligence ships Acceptance/Manifest/Apply-Gate infrastructure; residual SAFE_REWRITE = 0 until explicit Catalog mappings exist. Guide: Migration Intelligence.

No breaking CSS/JS contracts from 1.3.x. Motion Clips from 1.3.0 remain available.

Core Features on 1.4.0 (optional)

Same package line — not part of the Tailwind Compat upgrade path and not a second npm version. Status: Project 2 freeze after Phase 6.1.

• Exports: @birdapi/velinstyle/adapt, /inspector, /blocks, /blocks-registry, /runtime
• CLI: velinstyle blocks list|info|add (ownership copy, lockfile, integrity, conflict-fail, --force, --dry-run)
• Local AI Ranker: opt-in, default OFF; candidate-ID ranking only; no raw DOM; no cloud
• Inspector Core: consumer of Adapt — no Overlay-UI, Selection-UI, or Token-Probe

Core Features overview · Inspector Core

When to upgrade

• From 1.3.x — adopt Tailwind migrate / Compat without class renames in Core.
• From 1.1.0 — adopt overlay lifecycle fixes and optional DI commands without class renames.
• From <1.2 — pin @1.2.2, skim 1.2.2 and 1.2.1 foundations, then older sections as needed.

When not

• Migrating from Tailwind/Bootstrap is a different path — use the Migration Guide.
• Do not treat beta plan/review as required for a CSS-only upgrade.

Semver

Patch — bug fixes, safe to upgrade. Minor — new utilities or components, backward compatible. Major — breaking class or token renames; use the migration notes in GitHub releases.

Checklist

1. Read the release notes on GitHub Releases
2. Update npm: npm install @birdapi/velinstyle@latest or pin a version
3. Re-run visual tests and npx velinstyle scan on templates
4. Compare token changes in CSS Variables

Legacy notes (0.7.0)

0.7.0 added WCAG-oriented CSS modules (focus-not-obscured, target size, optional enhanced contrast).

• New CSS: focus-not-obscured.css, target-size.css, high-contrast-aaa.css; security.css is now a separate @layer security.
• Web Components: improved keyboard/ARIA for collapse, popover, tooltip, carousel, dropdown, drawer, accordion; modal/drawer use inert on background.
• CLI: four new a11y/* scanner rules; framework adds npm run test:contrast.

WCAG 2.2 AAA (0.9+)

• Tokens: AAA contrast is now the default in :root, dark, and 13 themes — use data-velin-contrast="aa" only if you need lighter muted text.
• Components: 43 Web Components in core/a11y/component-contracts.json (all pass); run npm run test:a11y:coverage in the framework repo.
• Runtime: import { initA11y } from '@birdapi/velinstyle/a11y' — announcer + scroll padding for fixed nav.
• Dialogs: empty <velin-dialog> / <velin-modal> need aria-label or a titled header.
• Docs: AAA matrix · Accessibility

Upgrading within 0.9.x

• Runtime: default export @birdapi/velinstyle — use register() + bootFromDOM() instead of loading the full IIFE when possible.
• Component tags: prefer velin-tooltip and velin-stepper; velin-tooltip-wc / velin-stepper-wc are deprecated aliases (source files renamed).
• Spacing: .velin-mb-* is margin-bottom; use .velin-my-* for block-axis spacing.
• Security: sanitizeSearchUrl, DOMPurify for SVG — see Security.
• WCAG: targets WCAG 2.2 Level AAA token defaults and component contracts — your app certification remains your responsibility — matrix.

Upgrading within 1.0.x

• Runtime: default export @birdapi/velinstyle — use register() + bootFromDOM() instead of loading the full IIFE when possible.
• Aliases: velin-tooltip-wc and velin-stepper-wc are deprecated aliases — use velin-tooltip / velin-stepper (source files renamed).
• Spacing: .velin-mb-* is margin-bottom; use .velin-my-* for block-axis spacing.
• Security: sanitizeSearchUrl, DOMPurify for SVG — see Security.
• WCAG: targets WCAG 2.2 Level AAA token defaults — AAA matrix.

Upgrading to 1.3.0

Patch release focused on the Production Builder and Showcase P0 primitives. CSS/WC APIs remain compatible.

• Publish path: velinstyle production . --explain → link dist/velin-production/ instead of the full CDN bundle. See Production Builder.
• New WCs: <velin-otp-input>, <velin-password-strength>, <velin-empty-state>.
• Overlays: reactive title + slot="title" on modal / drawer / sheet.
• Tables: row severity via velin-data-table__row--*, data-severity, and .velin-table--* aliases.
• Pin @birdapi/velinstyle@1.4.0. Package guide: UPGRADING.md.

Upgrading within 1.1 → 1.2.0 foundations

A minor release: no classes, tokens, or tags were removed, so an existing 1.0.x integration keeps working after the version bump. The deprecated velin-tooltip-wc and velin-stepper-wc aliases are still shipped.

• New components: <velin-data-table> and <velin-form-summary>. Both enhance existing markup, so nothing changes until you wrap a <table> or a <form>.
• Form summary takes over validation: unless you set native-validation, the element sets noValidate on its form and replaces the browser bubbles with a focusable summary. Remove your own submit-time validation handler for that form.
• React adapter: @velinstyle/react is now official and covers every canonical component. If you wrote your own wrappers, replace them — see Vite & React.
• Highlighting: Python, YAML, Go and Rust lexers load lazily like the existing languages; no change needed to <velin-code-block> usage.
• Release guard: npm run release:check in the framework repo verifies that versions and component counts match across framework and site. Add it to your own CI if you fork the docs.

Upgrading to 1.3.0

A minor foundation release: CSS, Web Components, and runtime remain stable. New Design Intelligence surfaces ship as beta / foundation — usable now, schemas and heuristics still expanding. Studio and the complete Utility Engine stay planned.

• Plan-first pages: velinstyle plan / scaffold use the page/section registry before HTML. Fragment recipes (navbar, modal, …) are unchanged. See Prompt scaffolding.
• Review gate (beta): velinstyle review scores design / a11y / SEO / performance / conversion heuristically — not perceptual QA.
• Agent metadata (beta): velin-agent.json embeds knowledge graph, pages, sections, and design constraints. See Velin-Meta.
• Overlay lifecycle: modal / drawer / sheet / lightbox use only focus-manager for inert + scroll lock; velin-dialog dispatches canonical velin-close.
• No breaking class renames in this minor — pin @birdapi/velinstyle@1.4.0 when ready.

Changelog

The canonical changelog lives in the CHANGELOG.md file in the framework repository.

Migrating from Tailwind or Bootstrap? See the Migration Guide (different from version upgrades).