basecoat/plan.md

Basecoat Multi-Style + Theme Refactor Plan

Goals

• Support the current shadcn/ui visual packs: vega, nova, maia, lyra, mira, luma, sera, rhea.
• Keep current CDN and Tailwind/NPM usage working.
• Keep Basecoat's own class API (btn, dialog, popover, etc.).
• Split CSS into base tokens/utilities, component structure, style-pack visuals, and aggregate outputs.
• Make custom token themes, including TweakCN-style themes, predictable by loading them after Basecoat CSS.

Current Upstream Reference

• Local repo: ../_sandbox/shadcn-ui
• Style registry: ../_sandbox/shadcn-ui/apps/v4/registry/styles.tsx
• Style files: ../_sandbox/shadcn-ui/apps/v4/registry/styles/style-{vega,nova,maia,lyra,mira,luma,sera,rhea}.css
• Base components: ../_sandbox/shadcn-ui/apps/v4/registry/bases/base/ui/<component>.tsx

Target CSS Architecture

1. src/css/base/base.css
   • base layer, default token fallbacks, and semantic utilities needed by CDN users
2. src/css/components/*.css
   • Basecoat component selectors and shared structural behavior
3. src/css/styles/style-*.css
   • one file per style pack: vega, nova, maia, lyra, mira, luma, sera, rhea
   • component visuals: size, spacing, radius, typography, shadows, focus rings, variant colors when style-owned
4. Aggregates
   • src/css/basecoat.css: backward-compatible default aggregate, includes Vega
   • src/css/basecoat.all.css: explicit all-in-one Tailwind source
   • src/css/basecoat.cdn.css: CDN build entry

No .style-* wrapper is part of the Basecoat public contract for style selection. Users choose a style by importing a style file or using a style-specific generated asset. Docs may switch by swapping stylesheet URLs.

Per-Component File Checklist

For every component, check these files before editing:

• Basecoat component CSS: src/css/components/<component>.css
• Basecoat templates/macros if relevant: src/nunjucks/*.njk, src/jinja/*.html.jinja
• Basecoat docs examples: docs/src/components/<component>.njk
• Upstream base component: ../_sandbox/shadcn-ui/apps/v4/registry/bases/base/ui/<component>.tsx
• Upstream style packs: ../_sandbox/shadcn-ui/apps/v4/registry/styles/style-{vega,nova,maia,lyra,mira,luma,sera,rhea}.css
• Basecoat style packs: src/css/styles/style-{vega,nova,maia,lyra,mira,luma,sera,rhea}.css

Component Migration Workflow

1. Review current Basecoat CSS, markup, templates, and docs for the component.
2. Review the upstream base component and all eight upstream style files.
3. Decide what is shared structure versus style-pack-owned visual rules.
4. Remove outdated visual rules from shared component CSS when they are now style-owned.
5. Map upstream style intent onto Basecoat selectors. Do not port cn-* selectors.
6. Update the component section in all eight Basecoat style files.
7. Document non-trivial deltas as intentional, drift fixed, or deferred.
8. Update migration-tracker.md.
9. Run npm run build.
10. Run npm run docs:build when docs or docs style assets change.
11. Manually verify the docs page in light/dark and all eight styles.

Do not mark a component done because CSS compiles. It needs a visual/state check.

Packaging Contract

• Keep @import "basecoat-css"; as the default Vega-compatible import.
• Keep existing CDN files and JS bundle paths.
• Export split style files from packages/css as basecoat-css/styles/<style>.
• Keep the default CDN output equivalent to Vega unless a separate style-specific CDN asset is explicitly added.
• Custom themes should load after Basecoat styles so their :root and .dark tokens override defaults.

Component Migration Order

1. button
2. button-group
3. input
4. textarea
5. native-select
6. select
7. checkbox
8. radio
9. switch
10. range
11. label
12. field
13. card
14. alert
15. badge
16. table
17. tabs
18. popover
19. dropdown-menu
20. dialog
21. command
22. sidebar
23. toast
24. tooltip
25. collapsible
26. kbd

Current Status

• CSS split exists.
• Docs style switcher exists.
• Button is started and style sections exist for all eight styles.
• Button still needs a strict browser audit across all eight styles and light/dark.
• No other component should be considered migrated.

Risks

• Selector drift between Basecoat markup and upstream shadcn/ui assumptions.
• Incorrectly leaving visual rules in shared component CSS.
• Bundle growth from style-specific assets.
• Docs style assets need base semantic utilities available during Tailwind compilation.