basecoat/handoff.md

Basecoat Multi-Style Migration Handoff

This handoff is for resuming the release/1.0.0 work on Basecoat's split CSS architecture and shadcn/ui v4 style-pack support.

Ground Truth

• Local Basecoat repo: /Users/hunvreus/Workspace/basecoat
• Local shadcn/ui upstream repo: /Users/hunvreus/Workspace/_sandbox/shadcn-ui
• Upstream branch/commit verified during this pass: main at 460ad60d8
• Upstream style registry: ../_sandbox/shadcn-ui/apps/v4/registry/styles.tsx
• Current upstream styles: vega, nova, maia, lyra, mira, luma, sera, rhea

The earlier five-style assumption was wrong. Luma, Sera, and Rhea are current upstream styles and must be included in every component migration.

Core Rules

• Keep Basecoat's own class API (btn, btn-outline, dialog, popover, etc.).
• Do not introduce shadcn/ui cn-* classes.
• Use upstream shadcn/ui as a style reference, not as selectors to copy directly.
• Translate upstream style intent to Basecoat selectors and markup.
• Component CSS should stay structural/shared when possible.
• Style-pack CSS owns visual differences: radius, density, spacing, typography, focus rings, shadows, and style-specific variant details.
• Default aggregate behavior remains Vega.
• Non-default styles are selected by importing or loading the relevant style file, not by requiring .style-* wrapper classes.

Files To Check For Every Component

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

Required Process

1. Review current Basecoat CSS and markup/templates/docs.
2. Review upstream base component source.
3. Review the component section in all eight upstream style files.
4. Decide what belongs in shared component CSS versus each style file.
5. Remove outdated shared visual rules if those rules are now style-owned.
6. Implement the component section in all eight Basecoat style files.
7. Keep Basecoat selectors only.
8. Classify non-trivial differences as intentional, drift fixed, or deferred.
9. Update migration-tracker.md.
10. Run npm run build.
11. Run npm run docs:build when docs or docs style assets are touched.
12. Browser-check light/dark and all eight styles.

Do not mark a component done just because CSS compiles.

What Has Been Done

• Split CSS source into:
  • src/css/base/base.css
  • src/css/components/*.css
  • src/css/styles/*.css
• Kept src/css/basecoat.css as the backward-compatible default aggregate.
• Added src/css/basecoat.all.css as an explicit all-in-one Tailwind source.
• Updated scripts/build.js to copy split CSS folders into packages/css/dist.
• Split select and native-select.
• Kept src/css/components/form.css as a convenience aggregate rather than nesting under components/form/*.
• Added docs style switcher in docs/src/_includes/partials/header.njk.
• Added docs stylesheet swapping in docs/src/_includes/layouts/base.njk.
• Added docs style entrypoints for all non-default styles:
  • docs/css/style-nova.css
  • docs/css/style-maia.css
  • docs/css/style-lyra.css
  • docs/css/style-mira.css
  • docs/css/style-luma.css
  • docs/css/style-sera.css
  • docs/css/style-rhea.css
• Added Basecoat style files for all eight upstream styles:
  • src/css/styles/vega.css
  • src/css/styles/nova.css
  • src/css/styles/maia.css
  • src/css/styles/lyra.css
  • src/css/styles/mira.css
  • src/css/styles/luma.css
  • src/css/styles/sera.css
  • src/css/styles/rhea.css

Button Status

Button is the only component with style-pack sections currently present.

Files involved:

• src/css/components/button.css
• src/css/styles/vega.css
• src/css/styles/nova.css
• src/css/styles/maia.css
• src/css/styles/lyra.css
• src/css/styles/mira.css
• src/css/styles/luma.css
• src/css/styles/sera.css
• src/css/styles/rhea.css
• docs/src/components/button.md

Current button work includes:

• Shared button CSS moved toward structural rules.
• Visual rules moved into style files.
• xs button and icon size classes added.
• Icon-aware padding mapped with Basecoat selectors using :has(> svg:first-child) and :has(> svg:last-child).
• All eight style files have Button sections.
• Docs include btn-xs-outline and btn-xs-icon-outline examples.

Button should remain in-progress until browser-audited across light/dark and all eight styles. Button-group adjacency is separate and should be handled during button-group.

Current Component Status

• button: in progress / pending visual audit
• Everything else: pending

No component besides Button should be considered migrated.

Issues Encountered

• The original migration plan assumed only five styles. Upstream now has eight.
• The first button attempt mixed old Basecoat visual rules with new style-pack rules, causing broken rendering.
• Some docs style entrypoints need src/css/base/base.css imported first so Tailwind can resolve semantic utilities like focus-visible:border-ring.
• Style switching should remove the override stylesheet href for Vega instead of setting href="".
• Sidebar dropdown width was a tangent. The user explicitly said not to modify generic CSS for that; handle width with a Tailwind class only when that task is active.

Things Learned

• Shadcn/ui icon-aware button padding is CSS-owned, not React-owned.
• Upstream uses data hooks like has-data-[icon=inline-start]:pl-*.
• Basecoat should map that to its own markup, currently :has(> svg:first-child) and :has(> svg:last-child).
• Blind copy is not viable because upstream uses cn-* class composition while Basecoat uses explicit classes like btn-xs-icon-outline.

Build And Validation Commands

npm run build
npm run docs:build
npm run docs:dev

Use npm run docs:dev for manual browser review.

Remaining Work

1. Run build validation after the latest Luma/Sera/Rhea wiring.
2. Browser-check /components/button for all eight styles in light and dark mode.
3. Update Button tracker status only after visual audit.
4. Migrate button-group next because it interacts with button radius and adjacency.
5. Continue component-by-component using migration-tracker.md.

Current Risks

• Button may still have visual deltas from upstream until audited.
• Docs style override assets may duplicate base CSS because they import base utilities for Tailwind compilation.
• The package does not currently generate separate style-specific CDN bundles beyond split style exports.
• The worktree includes unrelated sidebar template changes; do not revert or fold them into style migration unless explicitly requested.