Align button styles across all eight variants

plan.md

@@ -0,0 +1,111 @@
+# 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.