Adopt in an existing app
Bring an existing React app onto the shared theme and conventions, incrementally.
You do not need to rewrite anything. Adopt the foundation in the order that gives the most value for the least risk.
1. Theme first
Install and import @plainconceptsplatform/ui-theme (see the
Quickstart for the install steps). This is the single change
that makes an app look like the rest of the Platform, because every color, radius, and the type
scale now come from the shared tokens.
Replace hardcoded colors and spacing with the semantic tokens (bg-primary,
text-muted-foreground, border, rounded-lg) as you touch each screen.
2. Components as you go
When you next build or refactor a piece of UI, add the shadcn version instead of a bespoke one:
npx shadcn@latest add <component>They inherit the theme automatically. See the Components catalog.
3. Align structure over time
Move toward the Frontend architecture (Feature-Sliced Design) when you split or add features. You do not have to restructure the whole app at once; new features can follow the convention while old code migrates gradually.
4. Add the agent setup
Point your coding agent at the foundation and install the recommended skills so new work matches the conventions by default. See AI.
5. Migrate the full Platform stack
For a brownfield application that needs more than incremental adoption, use the
platform-onboard skill.
It runs a preflight scan, then migrates one domain at a time: agent setup, architecture docs,
OpenSpec, frontend tooling and structure, loop automation, and .NET guardrails when applicable.
The skill preserves behavior by requiring Playwright characterization tests before frontend changes. Treat every domain as a separate OpenSpec change so each migration step is reviewable and reversible.
What not to do
- Do not wrap the shadcn components in your own abstractions.
- Do not fork the theme. Bump the package version to pick up changes.
- Do not move app-specific components into the foundation. See Contributing.