Migrating 0.2 → 0.3

0.3.0 removed the entire pre-ui-* vocabulary. Everything shipped is now under the .ui-* contract and the check-classes drift gate. This page turns the CHANGELOG's BREAKING notes into a runnable recipe. The machine-readable source of truth is MIGRATIONS.json.

1. Mechanical renames (safe to automate)

These are whole-class-token renames with no semantic change. Run from your consuming app's repo root (adjust the glob to your templates — .astro, .svelte, .jsx, .tsx, .html):

# Preview first — list every file/line that will change:
rg -l --glob '*.{astro,svelte,jsx,tsx,vue,html}' \
  -e 'skip-link' -e 'site-nav' -e 'site-menu' -e 'theme-toggle' -e '\bapp-' .

# Apply (BSD/macOS sed shown; GNU sed: drop the '' after -i):
fd -e astro -e svelte -e jsx -e tsx -e vue -e html -x sed -i '' \
  -e 's/\bskip-link\b/ui-skiplink/g' \
  -e 's/\bsite-nav\b/ui-sitenav/g' \
  -e 's/\bsite-menu\b/ui-sitemenu/g' \
  -e 's/\btheme-toggle\b/ui-themetoggle/g' \
  -e 's/\bapp-\(shell\|rail\|topbar\|toolbar\|nav\|panel\|content\|main\|metrics\|metric\|empty-state\)/ui-app-\1/g' {}

The \b word boundaries keep app- from clobbering unrelated tokens, but review the diff — a codemod cannot know your markup.

If you import the typed class registry, switch to the new entries instead and let the compiler find the rest:

import { cls } from '@ponchia/ui/classes';
// cls.appShell, cls.appRail, …, cls.themetoggleTrack, cls.menuHost

2. Concept moves (manual — no 1:1 rename)

3. Import and token checks

The bundle collapsed in 0.3.0. Use the package root (@ponchia/ui) or @ponchia/ui/css; removed paths such as ./css/index.css, ./css/responsive.css, ./dist/bronto-core.css, and ./css/{layout,typography,cards}.css should be deleted.

Direct leaf imports changed meaning too: @ponchia/ui/css/<leaf>.css now resolves to the safe layered build. If you intentionally depended on a raw unlayered leaf overriding your app by specificity, switch that import to @ponchia/ui/css/unlayered/<leaf>.css.

If you re-brand with a pale --accent, set --accent-text as well; 0.3.0 routes small accent-coloured text through that AA-safe token. TypeScript users should also expect cls and token helpers to reject typos now that the declarations are literal unions.

4. Verify

• rg -n 'class(Name)?=.*"[^"]*\b(hero|callout|metric-tile|post-card|skip-link)\b' should return nothing after the pass.
• rg -n '@ponchia/ui/(css/(index|responsive|layout|typography|cards)\\.css|dist/bronto-core\\.css)' should return nothing.
• Visual-diff your app: token values can change in any release without a major bump, so eyeball the result, don't just diff classes.

Deprecation policy

From 0.3.1 onward, removals follow the policy in stability.md: a class is deprecated for one minor (kept working, marked in CHANGELOG + MIGRATIONS.json) before it is removed. 0.2 → 0.3 predates this policy, which is why it was a hard cut.