Basecoat is a vanilla JavaScript/HTML/CSS port of shadcn/ui components. It reuses shadcn/ui's design patterns and Tailwind CSS classes while maintaining semantic HTML, native browser elements, and full accessibility (ARIA attributes, proper hierarchies, keyboard navigation). The goal is to provide shadcn-quality components without React dependencies.
- Basecoat keeps its own component class API (`btn`, `dialog`, `popover`, etc.). Do not introduce shadcn `cn-*` classes into Basecoat source.
- Shadcn/ui style packs are used as reference material, but must be mapped onto Basecoat markup and selectors.
- Style-pack architecture is one file per style:
-`src/css/styles/style-vega.css`
-`src/css/styles/style-nova.css`
-`src/css/styles/style-maia.css`
-`src/css/styles/style-lyra.css`
-`src/css/styles/style-mira.css`
-`src/css/styles/style-luma.css`
-`src/css/styles/style-sera.css`
-`src/css/styles/style-rhea.css`
- Default aggregate and CDN behavior should resolve to Vega unless explicitly changed.
- Non-default styles should be selected by importing the relevant style file or using a style-specific bundled asset, not by introducing shadcn internal selector conventions.
- During migration, each component must be reviewed in two layers:
- shared/base component CSS
- style-pack CSS overrides
- Do not assume existing Basecoat component CSS is still the right baseline. Reassess shared rules vs style-owned rules component by component.
- When Basecoat differs from upstream shadcn/ui, classify the difference as either intentional or drift, and prefer explicit decisions over silent divergence.
## Component migration workflow
For each component migration, follow this sequence:
1. Review the current Basecoat component CSS and markup/templates first.
2. Review the latest upstream shadcn/ui base component source for the equivalent component.
3. Review the relevant sections in all eight upstream style packs (`vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera`, `rhea`).
4. Decide what belongs in shared Basecoat component CSS versus what belongs in style-pack CSS.
5. Keep Basecoat selectors and markup. Do not port shadcn `cn-*` selectors directly.
6. Remove outdated Basecoat visual rules from the shared component CSS if those rules are now style-owned.
7. Implement or update the component section in:
-`src/css/components/<component>.css`
-`src/css/styles/style-vega.css`
-`src/css/styles/style-nova.css`
-`src/css/styles/style-maia.css`
-`src/css/styles/style-lyra.css`
-`src/css/styles/style-mira.css`
-`src/css/styles/style-luma.css`
-`src/css/styles/style-sera.css`
-`src/css/styles/style-rhea.css`
8. Document any non-trivial difference from upstream as either:
- intentional
- drift fixed
- deferred
9. Update the migration tracker entry for the component.
10. Run `npm run build` after each component migration.
11. Manually verify the component in docs for:
- light and dark mode
- all supported variants and sizes
- interaction states (`hover`, `focus`, `disabled`, `aria-invalid`, open/selected states when relevant)