Migration

This guide is for apps inside the Hub monorepo moving off MUI and @hub/shared/ui. If you are starting fresh outside the Hub, you do not need it; see Get started instead.

DOIS and the other Hub apps migrate onto the Design System screen by screen. Not big-bang, not component-by-component. Each screen is migrated as a unit, validated with design, and merged independently.

What migrating a screen means

1. Replace UI imports: @mui/material and @hub/shared/ui become @hub/ds-components.
2. Replace hardcoded values (hex colors, px or rem spacings, font references) with @hub/ds-tokens.
3. Audit local components used in the screen (replace, promote, or keep).
4. Validate visually with design against the Figma reference.
5. Make sure tests pass and the Chromatic baseline is updated.

Phases

Phase 1. Screens whose components are 100% Wave 1 (Typography, Icon, Button, Link, Container, Stack, Grid, TextField, Select, Checkbox). Start now.

Phase 2. Screens that need Modal, Tabs, Card, Alert, or Tooltip. These wait for Wave 2.

Phase 3. Screens with app-specific custom components.

Conventions

• Import from @hub/ds-components, never @mui/material directly. @hub/shared/ui is legacy, so migrate off it.
• The DS Typography color is a semantic enum (inherit, primary, secondary, muted, danger, warning, success). It does not map one to one to the MUI palette. Map headings to primary, captions to secondary, and caution text to warning.
• Run validate_usage from the DS MCP on a file before committing to catch MUI or legacy imports and hardcoded values.

The full strategy and the per-screen playbook live in the repo at libs/design-system/docs/migration-strategy.md (section 6 playbook, section 6.5 lessons).