CSS Layers

[mfal]

Summary

This PR introduces CSS Cascade Layers for Flow styles and makes theme overrides more explicit and controllable.

Flow CSS is now emitted with a stable layer structure:

@layer flow.base, flow.theme, flow.components;

The theme-related CSS is isolated in flow.theme, while component styles live in flow.components. This allows applications to override Flow styles and theme tokens in a predictable later layer without fighting specificity.

Changes

• Wrap Flow CSS output in cascade layers
• Split Flow CSS into semantic sublayers:
  • flow.base
  • flow.theme
  • flow.components
• Move theme token and theme-selection rules into flow.theme
• Add scoped theme support via data-flow-theme="light" and data-flow-theme="dark"
• Add optional @mittwald/flow-react-components/scoped-theme.css
• Keep scoped theme tokens out of all.css by default
• Add docs example showing light and dark scoped theme areas
• Document layer usage and app override strategy
• Move scoped theme CSS generation into its own Vite plugin file

Why

Apps need a reliable way to override Flow CSS and theme decisions. CSS layers give us a cleaner override model than increasing selector specificity.

Scoped theme support also lets apps force a subtree into light or dark theme independently of data-theme, system, or prefers-color-scheme.

Usage

@layer flow.base, flow.theme, flow.components, app;

@import "@mittwald/flow-react-components/all.css";

@layer app {
  :root[data-theme="dark"] {
    --text--color--default: var(--color--gray--1100);
  }
}

For scoped light/dark areas:

@import "@mittwald/flow-react-components/all.css";
@import "@mittwald/flow-react-components/scoped-theme.css";

<section data-flow-theme="dark">
  {/* Flow components in this subtree use dark theme tokens. */}
</section>

Verification

• corepack pnpm --filter @mittwald/flow-react-components build
• corepack pnpm --filter @mittwald/flow-react-components test:compile
• corepack pnpm --filter @mittwald/flow-react-components test:unit -- dev/vite/cssLayerPlugin.test.ts
• corepack pnpm exec stylelint packages/components/src/styles/index.scss packages/components/src/styles/globals.scss packages/components/src/styles/theme-color-scheme.scss

Closes #2559

[github-actions]

Coverage Report for ./packages/components/

Status	Category	Percentage	Covered / Total
🔵	Lines	77.56%	370 / 477
🔵	Statements	77.93%	378 / 485
🔵	Functions	85.05%	74 / 87
🔵	Branches	65.56%	179 / 273

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/components/dev/vite/cssLayerPlugin.ts	62.18%	50%	50%	61.53%	31-35, 39-44, 48-50, 54-55, 72, 82, 106-110, 114-119, 123-125, 129-130, 150, 198-228

Generated in workflow #5518 for commit 37db7b0 by the Vitest Coverage Report Action

[github-actions]

🚀 Preview Deployment

Preview environments are ready:

Type	URL
docs	pr-2611.docs.review.flow-components.de
storybook	pr-2611.storybook.review.flow-components.de

Images:

• docs: ghcr.io/mittwald/flow/docs:pr-2611
• storybook: ghcr.io/mittwald/flow/storybook:pr-2611