brand-ui-migrate
Bring an app that already exists onto brand-ui (@elabs-ai/components-*). Use when someone wants to migrate, port, adopt or "move to" the design system in a codebase they already have ("migrate this project to brand-ui", "we use MUI, can we switch", "adopt your design system in our admin app", "replace our components with yours"). Profiles the repo, maps every component it finds to a brand-ui verdict, writes a phased migration plan, and then walks the phases with the user approving each one. Read-only until the plan is approved. For a brand-new app use `brand-ui-new-app`; for using components in an app already on brand-ui use `brand-ui`.
- License 许可
- MIT
- 最近更新
- 2026-10-07
- Stars
- ★ 1
- Forks
- 1
01 前言 Front Matter
- name
- brand-ui-migrate
- description
- Bring an app that already exists onto brand-ui (@elabs-ai/components-*). Use when someone wants to migrate, port, adopt or "move to" the design system in a codebase they already have ("migrate this project to brand-ui", "we use MUI, can we switch", "adopt your design system in our admin app", "replace our components with yours"). Profiles the repo, maps every component it finds to a brand-ui verdict, writes a phased migration plan, and then walks the phases with the user approving each one. Read-only until the plan is approved. For a brand-new app use `brand-ui-new-app`; for using components in an app already on brand-ui use `brand-ui`.
- allowed-tools
- [ "Bash(npx @elabs-ai/components-cli *)", "Bash(pnpm brand-ui *)", "Bash(npx brand-ui *)", "Bash(pnpm exec brand-ui *)" ]
- argument-hint
- [path to the project, defaults to the current directory]
- user-invocable
- true
03 SKILL.md 正文
brand-ui-migrate (brownfield adoption)
Move an existing UI onto brand-ui in reviewable steps, never in one sweep. The CLI does the deterministic analysis; you do the edits; the user approves every phase. The order matters: understand → map → plan → migrate → verify.
0 · Preconditions (check, don't assume)
The analysis commands come from the brand-ui CLI, a public package —
pnpm add -D @elabs-ai/components-cli installs anonymously, nothing to
configure (see docs/CONSUMING.md §1 and §7a). If brand-ui is not already
runnable in the project, say so and point the user at that one install command
before running anything. Do not paper over a missing CLI by guessing at the
codebase.
Inside the brand-ui repository itself, use pnpm brand-ui <cmd>; in a consuming
project, pnpm exec brand-ui <cmd> once the CLI is installed.
1 · Understand — change nothing
brand-ui scan . --json > brand-ui-scan.json
brand-ui map brand-ui-scan.json --json > brand-ui-map.json
brand-ui scan . --out migration/
brand-ui map brand-ui-scan.json --out migration/
brand-ui audit src/ --json
--out is the only thing these commands write, and it only creates
migration/repo-profile.md, migration/analysis.md and migration/plan.md.
No source file is touched at this stage — say that out loud, so the user knows
it is safe to run.
Then read the three documents and report back, in the user's terms:
- what the project is built on (framework, UI library, styling approach);
- the coverage number — the share of component usages a direct match or a prop remap already covers;
- the verdict split, and specifically what falls into
gap; - the token debt — how many raw colour, spacing and font values need replacing.
2 · Read the verdicts honestly
| Verdict | What you do with it |
|---|---|
| direct | Rename plus an import change. The safe bulk of the work. |
| props | Same idea, different API. Apply the prop remap the analysis lists. |
| compose | No single equivalent — rebuild it from primitives. Show the composition first. |
| gap | Nothing matched. Search before you conclude — then keep theirs and record why. |
| drop | Not UI (routing, document head, language constructs). Leave it alone. |
Two limits to state plainly rather than discover later:
- the inventory is a heuristic source scan, not an AST parse — good enough to rank work by blast radius, not a refactoring index;
gapmeans "the map has no entry", not "no equivalent exists". Runbrand-ui search <name>before telling the user something is missing.- a verdict is made per (name, library) — the
libcolumn. A brand-ui export that merely shares the name (Gridin charts is gridlines,Listin editor is a markdown block) is reported as agapwith a "name coincidence" note, never as a direct match. Do not "fix" that by importing the namesake.
3 · Plan — the strangler-fig phases
migration/plan.md already lays these out with the actual components per phase.
Walk them in order and stop for approval between each:
- Coexistence — install, wire the tokens stylesheet and one Tailwind
@sourceline per installed package, wrap the root inThemeProvider. The app must still build and render before anything else happens. A missing@sourcerenders components unstyled — verify each one. Decide the theme here: an app that had a brand (the old library's palette, a corporate typeface) gets it back as a brand-ui theme — a family fromthemes/<family>/in the brand-ui repository, or one built withbrand-ui-create-theme— registered onThemeProviderand added to the@custom-variant dark (…)line. The brand never re-enters as per-component colours in a later phase. - Leaf components — the
directmatches, lowest blast radius first. - Composite surfaces — the
propsremaps and thecomposerebuilds. - App shell — the frame itself: navigation, header, page scaffold. Ask
which of the library's shells the app moves into — flagship (recommended)
· dashboard · mail · double-sided, the entries under Storybook's
Layout/App Shell — with the question, the story ids to render and the
block each maps to in
../brand-ui-new-app/reference/app-shells.md. Show the rendered shells before the person picks, then copy the chosen block in (npx shadcn add <registry>/<block>.json→src/components/<block>/) and make the app's screens itschildren(the flagshipWorkspaceShelltakes the nav, the signed-in user and the trail as props; the other three carry their nav innav-items.ts— rewrite it from the app's routes). Never hand-roll the frame fromSidebarProvider+Sidebar+SidebarInset: that bare composition is the stand-in the archetype stories use, not a finished shell, and it is how a migrated app ends up looking like a plain rail with a one-word header. Charts and KPI tiles move intoChartFrame/MetricCardin the same pass, not into bareCards. Any custom grid cell holding a table or chart keepsmin-w-0, or one wide child pushes the page past the viewport. Record the chosen shell inmigration/plan.md. - Theming cutover — raw values become semantic tokens.
- Remove the old library — or document what stays and why.
Keep every phase to a diff a person can actually read. Run the project's build and tests after each batch, not at the end.
4 · Migrate — the rules that do not bend
- Never guess a prop. Run
brand-ui docs <Name>and use the real API. If it lists anti-patterns for that component, follow them. - Semantic tokens only —
bg-background,text-foreground,border-border. Never a raw hex. - Prefer composing what exists over writing a new component.
- Do not force a bad fit. A
gapstays the user's component until they say otherwise. - Visual decisions run the loop. Any choice the user can see — which shell,
which theme, which layout — goes through propose → preview → pick → refine, on
a render rather than on prose. The shell is the first of these and is never
skipped (
../brand-ui-new-app/reference/app-shells.md). The loop and its fidelity ladder are in../brand-ui-new-app/reference/visual-loop.md; there is one copy, and both flows use it.
5 · Verify — per screen, per theme
brand-ui audit src/and fix what it reports.- Check every migrated screen in every registered theme — light, dark and the brand family. A screen that only works in one theme is not migrated.
- Report honestly: what moved, what was skipped and why, and what the user should look at closely. Lead with what you did not verify.
What this skill does not do
It does not run an automated codemod. The transform engine is not implemented —
brand-ui codemod <map.json> emits a plan and a dry-run contract and edits no
files. The edits are yours to make and the user's to review. Say that up front
rather than implying a one-command migration.
04 同仓库更多 Skills
brand-ui
Build UI with the brand-ui component system (@elabs-ai/components-* packages — ui, data, ai, flow, maps, charts, marketing, editor, viewer, terminal, tokens, icons). Use when working in a project that depends on @elabs-ai/components-ui or any @elabs-ai/components-* package, when adding/composing components, building dashboards, data tables, AI/chat surfaces, React Flow canvases, MapLibre maps, code editors, file/document viewers, app shells, forms, or marketing sections, when theming with the token system, or when the user mentions brand-ui, @brand, light/dark themes, or "our design system". Provides live project context, the real component API, composition patterns, and the rules that keep components token-driven, accessible, and theme-safe.
brand-ui-update-theme
Use when an existing brand-ui theme family should be improved from new material — updated brand guidelines, a new logo, product screenshots, a live site, feedback like "the green is off" or "match their new design system" — e.g. "update the qlik theme with these links", "refresh our theme from the new brand book", "/update-theme". For a brand with no theme yet, use brand-ui-create-theme.
brand-ui-theme
Create or retune a brand-ui theme (token work). Use when adding a new theme, re-branding the system to a customer's palette, adjusting global radius/spacing/surfaces, or fixing token-level contrast across themes. Use when the user says "new theme", "brand it for <customer>", "make corners less rounded", "dark theme", "adjust the tokens", or "our colors". Every change is a token in a theme stylesheet — never a hardcoded value in a component.
brand-ui-start
The front door for building UI with brand-ui — a router/concierge that asks what you want to do and hands you to the right flow. Use when someone is starting out and unsure where to begin ("help me with brand-ui", "where do I start", "I want to build something", "what can brand-ui do", "get me going"), or types /brand-ui-start. Routes to three flows — build a NEW app (brand-ui-new-app), improve/migrate an EXISTING app (brand-ui-migrate), or just help me USE brand-ui in an app that already has it (brand-ui). If the intent is already obvious (the person said "build me a dashboard" or "audit this screen"), skip the question and go straight to that flow.
brand-ui-registry
Curate the brand-ui shadcn-compatible registry (maintainer workflow). Use when deciding whether something belongs as an imported @elabs-ai/components-* primitive vs a copy-own registry block/template, when adding or editing a registry item, or when validating/building the registry for distribution. Use when the user says "add a registry item", "make this a block", "publish to the registry", or "package vs registry". For consuming registry items in an app, use the `brand-ui` skill (npx shadcn add).
brand-ui-new-app
Define-to-build — scaffold a new brand-ui app from a plain-language description (VP-02). Use when the user wants to START an app, page, or demo ("build me a sales dashboard", "I need an admin console for X", "new app", "scaffold a chat assistant", "create a landing page for a pitch") rather than add to an existing one. Runs a staged interview (quick 3-question mode or full 7-stage spec mode), writes an app-spec.md, then scaffolds from the matching template + playbook with every wiring point annotated and a starter CLAUDE.md so later agent sessions stay on-brand. For adding components to an existing app use `brand-ui`; for authoring library components use `brand-ui-component`.