refactor to xzero
Refactor to Xzero
Use the public xzero-ui MCP server at https://mcp.xzero.co.uk/mcp. The complete Free and Pro library is available through this service. No account, sign-in, token, or upstream fallback is required. If the service is unavailable, retry later; do not use upstream services.
Migrate one pattern at a time and prove parity after each. Copy this checklist:
Refactor progress:
- [ ] 1. Inventory written
- [ ] 2. Mapping table agreed
- [ ] 3. Tokens and foundation in place
- [ ] 4. Pattern migrated: <name> (repeat per pattern)
- [ ] 5. Parity verified for that pattern
- [ ] 6. Cleanup done
- [ ] 7. Checklist passes on changed screens
1. Inventory
Scan the target files. For each UI element record: current implementation, props in use, behavior (controlled or not, async, validation, analytics), and usage count. Group duplicates: five hand-rolled modals are one pattern. Order patterns by usage count times visibility; start with the one that appears most.
2. Map
| Existing | Xzero | Watch for |
|---|---|---|
| Button, IconButton, LoadingButton | button (variant, size, loading), action-button | Icon-only buttons need aria-label |
| Link styled as button | Keep a link; style it in your module | Xzero button is for actions |
| Modal, Dialog, AlertDialog | dialog (DialogContent title, description) | Long forms go to drawer |
| Sheet, side panel | drawer; mobile sheets to bottom-sheet | |
| DropdownMenu, Menu | dropdown-menu; right click to context-menu | |
| Select, Autocomplete, Combobox | select, combobox, multi-select | Xzero select takes label, options, value, onValueChange |
| Switch, Checkbox, Radio | switch, checkbox, radio-group, radio-cards | Switch applies immediately; checkbox submits |
| ToggleGroup, ButtonGroup | segmented-control (default export; options, value, onValueChange) | 2 to 5 options |
| Tabs | tabs (Tabs, TabsList, TabsTrigger, TabsContent) | Tabs only for peer panels |
| Toast, Snackbar | In-place confirmation first; toast only for background work | |
| Table, DataGrid, TreeView | sortable-data-table, tree-view for hierarchies; Pro data-grid | Wrap in a scroll container inside the card |
| Tooltip, Popover, HoverCard | tooltip, popover, hover-card | |
| Skeleton, Spinner | skeleton, button loading | No page spinners |
| Card with header and actions | card or plain markup with a border | Do not nest cards |
| Alert, Banner | alert with tone | |
| Badge, Chip | badge, chip-group for filters |
Check each target's "When not to use" before committing to the mapping. Record anything with no Xzero equivalent; keep it and restyle it with tokens.
3. Tokens and foundation
The first install adds xzero-foundation (foundation.css and motion tokens); import @/components/xzero/foundation.css once in the root layout. Map the old theme onto Xzero tokens, not the other way around:
| Old | Xzero |
|---|---|
| Brand or primary color | --accent (or a brand accent, see design-system-generation.md) |
| Grays for text | --foreground, --text-secondary, --text-muted |
| Grays for backgrounds | --background, --surface, --surface-muted |
| Borders and dividers | --border, --border-subtle, --border-strong |
| Success, warning, error | --success, --warning, --danger |
| Radii | --radius-control, --radius-panel, --radius-surface, --radius-pill |
| Font weights 600 and 700 | 500 |
| Uppercase labels and overlines | Sentence case text, or remove |
4. Migrate one pattern
- Install the Xzero item with
get_install_command. - Replace one usage. Translate props; keep the same controlled state, callbacks, and form names.
- Move styling to tokens. Remove wrapper styles that fought the old library.
- Replace the remaining usages of that pattern.
- Remove the old component once it has no usages.
5. Parity (feedback loop)
For each migrated pattern confirm, and fix before moving on:
- Same keyboard behavior (Tab order, arrows in composites, Escape on overlays, focus return).
- Same form submission values and validation messages.
- Same analytics and test ids (move
data-testidto the new root). - Same responsive behavior at 390 and 1440px.
- Type check, lint, and existing tests pass.
6. Cleanup
Delete unused CSS and utility classes, the old dependency when nothing imports it, hand-made focus ring styles (Xzero's foundation draws one shared keyboard-only ring), uppercase transforms, eyebrow labels, and decorative gradients.
Output
The inventory, the mapping table for this codebase, the patch per pattern, parity results, and the list of kept elements with no Xzero equivalent. Finish with the free skill's checklist.md on every changed screen.