Migration

This guide is for teams replacing or narrowing CCL and Material UI with @by/experience-system, @by/icons, Tailwind-first styling, and optionally @by-es.

What migration means here

You are not swapping imports while keeping the same theme JSON in memory. You are changing where visual truth lives: from JS theme objects in React context to DOM attributes (data-ds-theme, data-ds-color, data-ds-spacing, dir) plus theme.css and Tailwind variants.

Expect three kinds of churn together:

Principles

Strategy

Styling

Scope: mental models for appearance and layout—not every API name. The Button example below illustrates patterns that apply across typography, surfaces, inputs, and layout.

Note: Enabling Tailwind runs preflight — legacy markup may shift (heading margins, lists, controls). BY assumes preflight on. Disabling it to “fix” legacy pages usually breaks new surfaces—plan a visual pass the first time Tailwind loads.

Example: MUI styled components to BY Button

Before

import { styled } from '@mui/material/styles';
import Button from '@mui/material/Button';

const CustomButton = styled(Button)(({ theme }) => ({
  backgroundColor: theme.palette.primary.main,
  color: 'white',
  padding: '8px 16px',
  borderRadius: '4px',
  '&:hover': {
    backgroundColor: theme.palette.primary.dark,
  },
  margin: theme.spacing(1),
}));

export const MyComponent = () => {
  return <CustomButton variant="contained">Submit</CustomButton>;
};

After

import { Button } from '@by/experience-system';

export const MyComponent = () => {
  return (
    <div className="m-4">
      <Button type="button" variant="fill">
        Submit
      </Button>
    </div>
  );
};

Prefer semantic colors from Theming and Semantic colors over hard-coded palette utilities.

During transition: Passing className into MUI you still own is common—that differs from ad-hoc utilities on @by/experience-system atoms; stick to documented props and variants on BY primitives.

Migration CLI Tools

The by-es binary ships with @by/experience-system. Commands:

Usage

Pick one pattern depending on whether @by/experience-system is already in package.json.

From the project dependency

Use pnpm exec / npm exec / yarn exec so CI resolves the by-es binary from node_modules / your lockfile:

pnpm exec by-es migrate scan
npm exec -- by-es migrate scan
yarn exec by-es migrate scan

npx by-es may resolve locally when the package is installed; for CI, prefer exec for deterministic paths.

Using npx

One-off audit without adding the dependency:

npx @by/experience-system by-es migrate scan

Optional version pin:

npx @by/experience-system@latest by-es migrate scan --dir ./src --format json

Dependency scan

Purpose: Find .ts, .tsx, .js, .jsx imports from legacy stacks; print migration hints where maintainers defined them. Icons should move to @by/icons—empty hints still show where legacy code lives. By default, results go to docs/migration_scan.<ext>; --stdout prints only to the terminal.

Targets

v2 — CCL v2 / MUI v4

• @jda/lui-common-component-library
• @material-ui/core
• @material-ui/icons
• @material-ui/lab
• @material-ui/pickers
• @material-ui/styles
• @material-ui/system
• @material-ui/types
• @material-ui/utils

v3 — CCL v3 / MUI v5

• @jda/lui-common-component-library-mui5
• @jda/lui-common-icon-library-mui5 → replace with @by/icons
• @mui/icons-material
• @mui/lab
• @mui/material
• @mui/x-date-pickers
• @mui/styles
• @mui/system
• @mui/types
• @mui/utils

pnpm exec by-es migrate scan
pnpm exec by-es migrate scan --dir ./src --format json
pnpm exec by-es migrate scan --stdout
pnpm exec by-es migrate scan --format markdown --out ./migration_audit.md
npx @by/experience-system by-es migrate scan --target v3

Output

Scan JSON schema (version 2.0)

by-es migrate scan --format json writes a deterministic JSON tree with meta, rollup summary, and per-import findings (stable sort).

Meta object fields

Findings entries

Older tooling that expected legacy JSON keyed only by module should migrate to this shape (schemaVersion marks the cut).

Still on MUI v4 → v5? Follow Material UI migration and mui-replace codemod before assuming every hit maps to @by/experience-system.

Migration report

Purpose: Emit summary aggregates only (MigrateReportResult) — the same planning rollups as the summary object in migrate scan, without per-import findings. Runs a fresh scan (--dir, --gitignore, --target, --verbose same as scan) or --from-scan-json (reads meta + findings; any embedded summary is ignored and recomputed).

pnpm exec by-es migrate report --dir ./src
pnpm exec by-es migrate report --output json --stdout
pnpm exec by-es migrate report --from-scan-json ./docs/migration_scan.json --out ./migration-rollup.md

Codemod

Purpose: Apply conservative, component-level mechanical edits for the v4 migration target. It is a direct-replacement codemod, not a full migration engine: it changes imports, JSX tag identifiers, approved static prop names/values, and exact-match legacy LUI icon imports.

The command is dry-run by default. Add -w / --write to update files.

pnpm exec by-es migrate codemod --dir ./src --stdout
pnpm exec by-es migrate codemod --dir ./src --format json --out docs/migration_codemod.json
pnpm exec by-es migrate codemod --dir ./src -w
npx @by/experience-system by-es migrate codemod --dir ./src --stdout

Recommended workflow:

1. Run migrate scan --format json first so the team can see all work, including manual review.
2. Run migrate codemod --stdout and review changed, skipped, and prop-review items.
3. Run migrate codemod -w on a focused slice.
4. Type-check, lint, test, and visually inspect the slice.
5. Rerun migrate scan to confirm the expected findings were removed.

Operating tips

Resources

Related

• Installation
• Components