feat(react-ui): adopt CSS cascade layers (@layer openui) via build-side post-process

[ankit-thesys]

Closes #588.

Summary

Adopts CSS cascade layers (@layer openui) for OpenUI's compiled component CSS so consumers can override component styles without !important, selector mirroring, or specificity stacking. Implementation is build-side post-process in cp-css.js — component SCSS sources are unchanged.

• Compiled component CSS (dist/components/**/*.css) is wrapped in @layer openui { ... } after Sass emits it.
• defaults.css (the :root { --openui-* } token export) stays unlayered — ThemeProvider runtime injection contract is unchanged.
• All 9 example apps include the recommended Tailwind v4 layer-order declaration in their globals.css.
• README + chat/installation + chat/theming + api-reference + standard-library docs document the contract.

What changes for consumers

OpenUI components now lose to:

• Unlayered consumer CSS — plain CSS, CSS Modules, CSS-in-JS, Tailwind v3 utilities. Zero configuration needed.
• Tailwind v4 utilities, with this one-line addition to globals.css:

  @layer theme, base, openui, components, utilities;
  @import "tailwindcss";

Without that declaration, the cascade order is bundler-determined and openui typically ends up declared after utilities — utility overrides silently fail (see #588 Scenario A).

ThemeProvider token customization, var(--openui-*) resolution, and the defaults.css token-only export are unchanged.

Browser support

CSS cascade layers require Chrome 99+, Firefox 97+, Safari 15.4+, Edge 99+ (March 2022 baseline). Declared via browserslist in packages/react-ui/package.json so consumer build tools see the floor explicitly.

Why post-process instead of source-side @layer wraps

• One change site (cp-css.js) enforces the contract — no per-file discipline.
• Source SCSS stays clean — no 105-file diff, no skill/rule template, no separate CI guard.
• Storybook needs no special handling — consumes source SCSS (unlayered → specificity-driven), behaves as before this change. No preview-head.html, no preflight layer wrap.

Trade-off: in Storybook, OpenUI components win on specificity vs consumer overrides; in prod, consumers win via layer order. For "does this component look right" Storybook use, identical. For "does my consumer override beat OpenUI" QA, test in a consumer app.

We prototyped the source-side approach in parallel (105 SCSS source wraps + skill template + path-scoped rule + CI guard + Storybook preflight fix). Both produce identical consumer contracts. Post-process ships ~50× smaller diff (+112/-1 vs +7434/-7150) and avoids the maintenance overhead.

Test plan

• Pull the branch and run pnpm install && pnpm -r build.
• Run pnpm --filter @openuidev/react-ui storybook — confirm components render correctly. (Storybook needs no changes for this approach.)
• cd examples/openui-chat && pnpm dev — confirm components look right in a real consumer app.
• In the example, write a quick CSS override (e.g. unlayered .openui-button-base-primary { background: hotpink }, or layered @layer utilities { .openui-button-base-primary { background: red } }) and confirm it wins without !important.
• Confirm pnpm --filter @openuidev/react-ui lint:check and format:check are clean.
• Spot-check compiled output:
  • head -c 50 packages/react-ui/dist/components/Button/button.css should start with @layer openui{.
  • head -c 50 packages/react-ui/dist/openui-defaults.css should start with :root{ (unlayered, intentional).

Commits

1. 0efae7b4 — declare browserslist floor for cascade-layers support
2. f14358e8 — document @layer openui contract in readme
3. 93707abd — note ThemeProvider runtime injection is intentionally unlayered
4. 71169060 — adopt cascade-layer recipe for tailwind v4 example apps
5. 4a25d7f8 — document @layer integration recipe in chat docs
6. b8e70bae — wrap compiled component CSS in @layer openui via cp-css.js

🤖 Generated with Claude Code