Skip to content

The Open Standard for Generative UI

feat(react-ui): opt-in layered CSS via ./layered-components.css and ./layered/styles/* (#631)

Ankit Das55dafd0fd4df
diff --git a/docs/app/components/globals.css b/docs/app/components/globals.css
index 393dfec6d..7399cae27 100644
--- a/docs/app/components/globals.css
+++ b/docs/app/components/globals.css
@@ -1,12 +1,5 @@
-/* Cascade layer order — must match app/global.css (theme < base < openui < components <
- utilities) so OpenUI component styles aren't clobbered by Tailwind preflight on /components. */
-@layer theme, base, openui, components, utilities;
-
@import url("https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400;500;700&display=swap");
-/* react-ui CSS is imported once, app-wide, in app/global.css. A second @import here
- makes the bundler hoist a statement-less `@layer openui` chunk ahead of global.css's
- `@layer` order declaration, breaking the cascade order. Components on this route still
- get react-ui styles from the global import (root layout wraps all routes). */
+@import "../../../packages/react-ui/dist/styles/index.css";
html,
body {
diff --git a/docs/app/demo/github/layout.css b/docs/app/demo/github/layout.css
index f8b74062b..96252db3f 100644
--- a/docs/app/demo/github/layout.css
+++ b/docs/app/demo/github/layout.css
@@ -1,16 +1,9 @@
/* Scope playground resets so they do not leak into other routes after navigation.
- Use `:where()` to keep specificity at zero and avoid overriding react-ui classes.
-
- IMPORTANT: wrap in `@layer base` so this reset sits BELOW `@layer openui`. Unlayered,
- it beats every layered OpenUI component style regardless of specificity, zeroing the
- padding/margin of rendered OpenUI components. In `@layer base`, OpenUI (higher layer)
- and the demo's own shell classes (unlayered) win over it. */
-@layer base {
- :where(.app, .app *, .app *::before, .app *::after) {
- box-sizing: border-box;
- margin: 0;
- padding: 0;
- }
+ Use `:where()` to keep specificity at zero and avoid overriding react-ui classes. */
+:where(.app, .app *, .app *::before, .app *::after) {
+ box-sizing: border-box;
+ margin: 0;
+ padding: 0;
}
/* ─── Global ────────────────────────────────────────────────────────────────── */
diff --git a/docs/app/global.css b/docs/app/global.css
index 14b7b4f9b..347cdca1d 100644
--- a/docs/app/global.css
+++ b/docs/app/global.css
@@ -1,10 +1,3 @@
-/* Cascade layer order — same recipe #589 applied to every example app's globals.css.
- theme < base < openui < components < utilities: Tailwind preflight (base) resets the
- baseline, OpenUI component styles (@layer openui from @openuidev/react-ui) apply on top,
- and Tailwind utilities / consumer overrides win above OpenUI. Declared before any import
- so the order is fixed regardless of bundler chunk ordering. */
-@layer theme, base, openui, components, utilities;
-
@import url("https://fonts.googleapis.com/css2?family=Playwrite+US+Trad&family=Geist:wght@400;500;600;700&display=swap");
@import "tailwindcss";
@import "fumadocs-ui/css/neutral.css";
diff --git a/docs/app/playground/layout.css b/docs/app/playground/layout.css
index f40735361..21927ee20 100644
--- a/docs/app/playground/layout.css
+++ b/docs/app/playground/layout.css
@@ -1,18 +1,9 @@
/* Scope playground resets so they do not leak into other routes after navigation.
- Use `:where()` to keep specificity at zero and avoid overriding shared docs styles.
-
- IMPORTANT: wrap in `@layer base` so this reset sits BELOW `@layer openui` in the
- cascade order. Unlayered, it would beat EVERY layered rule (incl. all OpenUI
- component styles in `@layer openui`) regardless of specificity — zeroing the
- padding/margin of OpenUI components rendered in the preview (cramped cards, buttons
- with overflowing text). In `@layer base` it still resets plain elements, but OpenUI
- (higher layer) and the playground's own shell classes (unlayered) win over it. */
-@layer base {
- :where(.app, .app *, .app *::before, .app *::after) {
- box-sizing: border-box;
- margin: 0;
- padding: 0;
- }
+ Use `:where()` to keep specificity at zero and avoid overriding shared docs styles. */
+:where(.app, .app *, .app *::before, .app *::after) {
+ box-sizing: border-box;
+ margin: 0;
+ padding: 0;
}
/* ─── Scrollbar ─────────────────────────────────────────────────────────────── */
diff --git a/docs/content/docs/api-reference/react-ui.mdx b/docs/content/docs/api-reference/react-ui.mdx
index 629c89f5d..86a960d7f 100644
--- a/docs/content/docs/api-reference/react-ui.mdx
+++ b/docs/content/docs/api-reference/react-ui.mdx
@@ -11,12 +11,6 @@ Use this package for prebuilt chat UIs and default component library primitives.
import { Copilot, FullScreen, BottomTray } from "@openuidev/react-ui";
```
-### Cascade-layer contract
-
-`@openuidev/react-ui/components.css` wraps every component rule in `@layer openui`. Unlayered consumer CSS overrides OpenUI components without specificity matching or `!important`. See [Chat → Theming](/docs/chat/theming#override-component-styles-with-css) for override patterns, and [Chat → Installation](/docs/chat/installation#3-for-tailwind-v4-set-the-cascade-layer-order) for the Tailwind v4 layer-order setup.
-
-Browser support: Chrome 99+, Firefox 97+, Safari 15.4+, Edge 99+ (all baseline from March 2022).
-
## Layout components
These layouts are documented in Chat UI guides and are all wrapped with `ChatProvider`.
diff --git a/docs/content/docs/chat/installation.mdx b/docs/content/docs/chat/installation.mdx
index 1f52d2ee2..0b49eaa82 100644
--- a/docs/content/docs/chat/installation.mdx
+++ b/docs/content/docs/chat/installation.mdx
@@ -57,23 +57,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
These imports give you the default chat layout styling and theme tokens.
-## 3. (For Tailwind v4) Set the cascade-layer order
-
-OpenUI's component styles live in `@layer openui`. If your app uses Tailwind v4, declare the layer order in your global stylesheet so `openui` sits above Tailwind's reset (`base`) but below `components` and `utilities`:
-
-```css
-/* app/globals.css */
-@layer theme, base, openui, components, utilities;
-@import "tailwindcss";
-```
-
-This places OpenUI above Tailwind's Preflight (so its element resets don't override component styles) while keeping Tailwind utilities like `bg-red-500` winning over OpenUI. Without this declaration, the cascade order is bundler-dependent and `openui` may end up declared *after* `utilities`, which prevents utility overrides from taking effect.
-
-Tailwind v3, plain CSS, CSS Modules, and CSS-in-JS need no configuration — their styles are unlayered and beat anything in `@layer openui` automatically.
-
-See [`@openuidev/react-ui`](/docs/api-reference/react-ui#cascade-layer-contract) for the full styling integration contract.
-
-## 4. Render a layout to verify setup
+## 3. Render a layout to verify setup
Render one of the built-in layouts on a page to confirm the package is installed correctly.
diff --git a/docs/content/docs/chat/theming.mdx b/docs/content/docs/chat/theming.mdx
index 81218c053..945c060e1 100644
--- a/docs/content/docs/chat/theming.mdx
+++ b/docs/content/docs/chat/theming.mdx
@@ -54,20 +54,6 @@ import { FullScreen } from "@openuidev/react-ui";
`disableThemeProvider` only skips the wrapper. It does not remove any chat functionality.
-## Override component styles with CSS
-
-OpenUI's component styles live in `@layer openui`. Any unlayered consumer CSS overrides them without `!important` or matching specificity:
-
-```css
-.openui-button-base-primary {
- background: hotpink;
-}
-```
-
-For Tailwind v4 apps, declare `@layer theme, base, openui, components, utilities;` ahead of `@import "tailwindcss";` in your global stylesheet (see [Installation](/docs/chat/installation#3-for-tailwind-v4-set-the-cascade-layer-order)) so utility classes also override OpenUI styles. CSS Modules, CSS-in-JS, and Tailwind v3 utilities emit unlayered CSS and override OpenUI automatically with no configuration.
-
-Browser support: Chrome 99+, Firefox 97+, Safari 15.4+, Edge 99+ (all baseline from March 2022).
-
<div className="grid md:grid-cols-2 gap-6 my-6">
<div>
<p className="text-sm text-center font-medium mb-2">Light (default)</p>
diff --git a/docs/content/docs/openui-lang/standard-library.mdx b/docs/content/docs/openui-lang/standard-library.mdx
index 3bebcde91..f8eeeaeef 100644
--- a/docs/content/docs/openui-lang/standard-library.mdx
+++ b/docs/content/docs/openui-lang/standard-library.mdx
@@ -21,8 +21,6 @@ import { openuiLibrary } from "@openuidev/react-ui";
<Renderer library={openuiLibrary} response={streamedText} isStreaming={isStreaming} />;
```
-The compiled stylesheet wraps component rules in `@layer openui` so your own CSS overrides them without specificity matching. See [Chat → Theming](/docs/chat/theming#override-component-styles-with-css) for the override contract, or [Chat → Installation](/docs/chat/installation#3-for-tailwind-v4-set-the-cascade-layer-order) for the Tailwind v4 setup.
-
## Generate prompt
Use the CLI to generate the system prompt at build time:
diff --git a/docs/generated/chat-system-prompt.txt b/docs/generated/chat-system-prompt.txt
index e98309971..cbd28d059 100644
--- a/docs/generated/chat-system-prompt.txt
+++ b/docs/generated/chat-system-prompt.txt
@@ -42,7 +42,7 @@ HorizontalBarChart(labels: string[], series: Series[], variant?: "grouped" | "st
Series(category: string, values: number[]) — One data series
### Charts (1D)
-PieChart(labels: string[], values: number[], variant?: "pie" | "donut") — Circular slices; use plucked arrays: PieChart(data.categories, data.values)
+PieChart(labels: string[], values: number[], variant?: "pie" | "donut", appearance?: "circular" | "semiCircular") — Circular slices; use plucked arrays: PieChart(data.categories, data.values)
RadialChart(labels: string[], values: number[]) — Radial bars; use plucked arrays: RadialChart(data.categories, data.values)
SingleStackedBarChart(labels: string[], values: number[]) — Single horizontal stacked bar; use plucked arrays: SingleStackedBarChart(data.categories, data.values)
Slice(category: string, value: number) — One slice with label and numeric value
@@ -58,7 +58,7 @@ FormControl(label: string, input: Input | TextArea | Select | DatePicker | Slide
Label(text: string) — Text label
Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
-Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>, size?: "small" | "medium" | "large")
SelectItem(value: string, label: string) — Option for Select
DatePicker(name: string, mode?: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<any>)
Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], label?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<number[]>) — Numeric slider input; supports continuous and discrete (stepped) variants
diff --git a/docs/generated/playground-component-spec.json b/docs/generated/playground-component-spec.json
index fb66938ca..8dc750f5f 100644
--- a/docs/generated/playground-component-spec.json
+++ b/docs/generated/playground-component-spec.json
@@ -74,7 +74,7 @@
"description": "One data series"
},
"PieChart": {
- "signature": "PieChart(labels: string[], values: number[], variant?: \"pie\" | \"donut\")",
+ "signature": "PieChart(labels: string[], values: number[], variant?: \"pie\" | \"donut\", appearance?: \"circular\" | \"semiCircular\")",
"description": "Circular slices; use plucked arrays: PieChart(data.categories, data.values)"
},
"RadialChart": {
@@ -122,7 +122,7 @@
"description": ""
},
"Select": {
- "signature": "Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)",
+ "signature": "Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>, size?: \"small\" | \"medium\" | \"large\")",
"description": ""
},
"SelectItem": {
@@ -265,7 +265,10 @@
},
{
"name": "Tables",
- "components": ["Table", "Col"],
+ "components": [
+ "Table",
+ "Col"
+ ],
"notes": [
"- Table is COLUMN-oriented: Table([Col(\"Label\", dataArray), Col(\"Count\", countArray, \"number\")]). Use array pluck for data: data.rows.fieldName",
"- Col data can be component arrays for styled cells: Col(\"Status\", @Each(data.rows, \"item\", Tag(item.status, null, \"sm\", item.status == \"open\" ? \"success\" : \"danger\")))",
@@ -295,7 +298,12 @@
},
{
"name": "Charts (1D)",
- "components": ["PieChart", "RadialChart", "SingleStackedBarChart", "Slice"],
+ "components": [
+ "PieChart",
+ "RadialChart",
+ "SingleStackedBarChart",
+ "Slice"
+ ],
"notes": [
"- PieChart and BarChart need NUMBERS, not objects. For list data, use @Count(@Filter(...)) to aggregate:",
"- PieChart from list: `PieChart([\"Low\", \"Med\", \"High\"], [@Count(@Filter(data.rows, \"priority\", \"==\", \"low\")), @Count(@Filter(data.rows, \"priority\", \"==\", \"medium\")), @Count(@Filter(data.rows, \"priority\", \"==\", \"high\"))], \"donut\")`",
@@ -304,7 +312,11 @@
},
{
"name": "Charts (Scatter)",
- "components": ["ScatterChart", "ScatterSeries", "Point"]
+ "components": [
+ "ScatterChart",
+ "ScatterSeries",
+ "Point"
+ ]
},
{
"name": "Forms",
@@ -338,14 +350,20 @@
},
{
"name": "Buttons",
- "components": ["Button", "Buttons"],
+ "components": [
+ "Button",
+ "Buttons"
+ ],
"notes": [
"- Toggle in @Each: @Each(rows, \"t\", Button(t.status == \"open\" ? \"Close\" : \"Reopen\", Action([...])))"
]
},
{
"name": "Data Display",
- "components": ["TagBlock", "Tag"],
+ "components": [
+ "TagBlock",
+ "Tag"
+ ],
"notes": [
"- Color-mapped Tag: Tag(value, null, \"sm\", value == \"high\" ? \"danger\" : value == \"medium\" ? \"warning\" : \"neutral\")"
]
diff --git a/docs/generated/playground-system-prompt.txt b/docs/generated/playground-system-prompt.txt
index 9124f44a6..e16a602fc 100644
--- a/docs/generated/playground-system-prompt.txt
+++ b/docs/generated/playground-system-prompt.txt
@@ -75,7 +75,7 @@ Series(category: string, values: number[]) — One data series
- Multiple chart views: use Tabs — Tabs([TabItem("line", "Line", [LineChart(...)]), TabItem("bar", "Bar", [BarChart(...)])])
### Charts (1D)
-PieChart(labels: string[], values: number[], variant?: "pie" | "donut") — Circular slices; use plucked arrays: PieChart(data.categories, data.values)
+PieChart(labels: string[], values: number[], variant?: "pie" | "donut", appearance?: "circular" | "semiCircular") — Circular slices; use plucked arrays: PieChart(data.categories, data.values)
RadialChart(labels: string[], values: number[]) — Radial bars; use plucked arrays: RadialChart(data.categories, data.values)
SingleStackedBarChart(labels: string[], values: number[]) — Single horizontal stacked bar; use plucked arrays: SingleStackedBarChart(data.categories, data.values)
Slice(category: string, value: number) — One slice with label and numeric value
@@ -94,7 +94,7 @@ FormControl(label: string, input: Input | TextArea | Select | DatePicker | Slide
Label(text: string) — Text label
Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
-Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>, size?: "small" | "medium" | "large")
SelectItem(value: string, label: string) — Option for Select
DatePicker(name: string, mode?: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<any>)
Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], label?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<number[]>) — Numeric slider input; supports continuous and discrete (stepped) variants
diff --git a/examples/hands-on-table-chat/src/app/globals.css b/examples/hands-on-table-chat/src/app/globals.css
index e5922b2c3..66f69ebe0 100644
--- a/examples/hands-on-table-chat/src/app/globals.css
+++ b/examples/hands-on-table-chat/src/app/globals.css
@@ -1,5 +1,5 @@
-@layer theme, base, openui, components, utilities;
@import "tailwindcss";
+@import "@openuidev/react-ui/styles/index.css";
:root {
--background: #0a0a0a;
diff --git a/examples/hands-on-table-chat/src/app/page.tsx b/examples/hands-on-table-chat/src/app/page.tsx
index c07c8cdb1..c6867597a 100644
--- a/examples/hands-on-table-chat/src/app/page.tsx
+++ b/examples/hands-on-table-chat/src/app/page.tsx
@@ -1,6 +1,5 @@
"use client";
-import "@openuidev/react-ui/components.css";
import { openAIMessageFormat, openAIAdapter } from "@openuidev/react-headless";
import { Copilot } from "@openuidev/react-ui";
import { spreadsheetLibrary } from "@/lib/spreadsheet-library";
diff --git a/examples/mastra-chat/src/app/globals.css b/examples/mastra-chat/src/app/globals.css
index 4a090eef4..3c1b5c75b 100644
--- a/examples/mastra-chat/src/app/globals.css
+++ b/examples/mastra-chat/src/app/globals.css
@@ -1,2 +1,2 @@
-@layer theme, base, openui, components, utilities;
@import "tailwindcss";
+@import "@openuidev/react-ui/styles/index.css";
diff --git a/examples/mastra-chat/src/app/page.tsx b/examples/mastra-chat/src/app/page.tsx
index 14e9ffc63..a64566126 100644
--- a/examples/mastra-chat/src/app/page.tsx
+++ b/examples/mastra-chat/src/app/page.tsx
@@ -1,5 +1,4 @@
"use client";
-import "@openuidev/react-ui/components.css";
import { useTheme } from "@/hooks/use-system-theme";
import { agUIAdapter } from "@openuidev/react-headless";
diff --git a/examples/material-ui-chat/src/app/globals.css b/examples/material-ui-chat/src/app/globals.css
index dfe06a90b..2a1f323bf 100644
--- a/examples/material-ui-chat/src/app/globals.css
+++ b/examples/material-ui-chat/src/app/globals.css
@@ -1,3 +1,5 @@
+@import "@openuidev/react-ui/styles/index.css";
+
html,
body {
height: 100%;
diff --git a/examples/material-ui-chat/src/app/page.tsx b/examples/material-ui-chat/src/app/page.tsx
index 27a218a7d..5c1e43730 100644
--- a/examples/material-ui-chat/src/app/page.tsx
+++ b/examples/material-ui-chat/src/app/page.tsx
@@ -1,5 +1,4 @@
"use client";
-import "@openuidev/react-ui/components.css";
import DarkModeIcon from "@mui/icons-material/DarkMode";
import LightModeIcon from "@mui/icons-material/LightMode";
diff --git a/examples/multi-agent-chat/src/app/globals.css b/examples/multi-agent-chat/src/app/globals.css
index c45470e58..436d6d8f2 100644
--- a/examples/multi-agent-chat/src/app/globals.css
+++ b/examples/multi-agent-chat/src/app/globals.css
@@ -1,3 +1,3 @@
@layer theme, base, openui, components, utilities;
@import "tailwindcss";
-@import "@openuidev/react-ui/components.css";
+@import "@openuidev/react-ui/layered/styles/index.css";
diff --git a/examples/multi-agent-chat/src/app/page.tsx b/examples/multi-agent-chat/src/app/page.tsx
index d60879ff6..6dbd033f7 100644
--- a/examples/multi-agent-chat/src/app/page.tsx
+++ b/examples/multi-agent-chat/src/app/page.tsx
@@ -1,6 +1,5 @@
"use client";
-import "@openuidev/react-ui/components.css";
import { useChat } from "@ai-sdk/react";
import { useRef, useEffect, useState } from "react";
diff --git a/examples/openui-artifact-demo/src/app/globals.css b/examples/openui-artifact-demo/src/app/globals.css
index 0ffe00eb2..d41e3795a 100644
--- a/examples/openui-artifact-demo/src/app/globals.css
+++ b/examples/openui-artifact-demo/src/app/globals.css
@@ -1,3 +1,3 @@
-@layer theme, base, openui, components, utilities;
@import "tailwindcss";
+@import "@openuidev/react-ui/styles/index.css";
diff --git a/examples/openui-artifact-demo/src/app/page.tsx b/examples/openui-artifact-demo/src/app/page.tsx
index a68e6c6f9..648b5cdd9 100644
--- a/examples/openui-artifact-demo/src/app/page.tsx
+++ b/examples/openui-artifact-demo/src/app/page.tsx
@@ -1,5 +1,4 @@
"use client";
-import "@openuidev/react-ui/components.css";
import { useTheme } from "@/hooks/use-system-theme";
import { openAIAdapter, openAIMessageFormat } from "@openuidev/react-headless";
diff --git a/examples/openui-chat/src/app/globals.css b/examples/openui-chat/src/app/globals.css
index 0ffe00eb2..d41e3795a 100644
--- a/examples/openui-chat/src/app/globals.css
+++ b/examples/openui-chat/src/app/globals.css
@@ -1,3 +1,3 @@
-@layer theme, base, openui, components, utilities;
@import "tailwindcss";
+@import "@openuidev/react-ui/styles/index.css";
diff --git a/examples/openui-chat/src/app/page.tsx b/examples/openui-chat/src/app/page.tsx
index 29cc3daf4..2886da632 100644
--- a/examples/openui-chat/src/app/page.tsx
+++ b/examples/openui-chat/src/app/page.tsx
@@ -1,5 +1,4 @@
"use client";
-import "@openuidev/react-ui/components.css";
import { useTheme } from "@/hooks/use-system-theme";
import { openAIAdapter, openAIMessageFormat } from "@openuidev/react-headless";
diff --git a/examples/openui-dashboard/src/app/globals.css b/examples/openui-dashboard/src/app/globals.css
index 00eb02317..0ea67bbe0 100644
--- a/examples/openui-dashboard/src/app/globals.css
+++ b/examples/openui-dashboard/src/app/globals.css
@@ -1,5 +1,5 @@
-@layer theme, base, openui, components, utilities;
@import "tailwindcss";
+@import "@openuidev/react-ui/styles/index.css";
@keyframes openui-loading-bar {
0% { background-position: 200% 0; }
diff --git a/examples/openui-dashboard/src/components/OpenUIDashboard/index.tsx b/examples/openui-dashboard/src/components/OpenUIDashboard/index.tsx
index 1fc4de287..4e925d848 100644
--- a/examples/openui-dashboard/src/components/OpenUIDashboard/index.tsx
+++ b/examples/openui-dashboard/src/components/OpenUIDashboard/index.tsx
@@ -2,7 +2,6 @@
import type { Starter } from "@/starters";
import type { Library } from "@openuidev/react-lang";
-import "@openuidev/react-ui/components.css";
import { useRef, useState } from "react";
import { DashboardProvider, useDashboard } from "./context";
import { ConversationPanel } from "./ConversationPanel";
diff --git a/examples/shadcn-chat/src/app/globals.css b/examples/shadcn-chat/src/app/globals.css
index 39a6d2c91..f04fd9b6b 100644
--- a/examples/shadcn-chat/src/app/globals.css
+++ b/examples/shadcn-chat/src/app/globals.css
@@ -1,5 +1,6 @@
@layer theme, base, openui, components, utilities;
@import "tailwindcss";
+@import "@openuidev/react-ui/layered/styles/index.css";
@custom-variant dark (&:is([data-theme="dark"] *));
diff --git a/examples/shadcn-chat/src/app/page.tsx b/examples/shadcn-chat/src/app/page.tsx
index a59a3d9ee..d068a639e 100644
--- a/examples/shadcn-chat/src/app/page.tsx
+++ b/examples/shadcn-chat/src/app/page.tsx
@@ -1,5 +1,4 @@
"use client";
-import "@openuidev/react-ui/components.css";
import { useTheme } from "@/hooks/use-system-theme";
import { shadcnChatLibrary } from "@/lib/shadcn-genui";
diff --git a/examples/supabase-chat/src/app/globals.css b/examples/supabase-chat/src/app/globals.css
index 4a090eef4..3c1b5c75b 100644
--- a/examples/supabase-chat/src/app/globals.css
+++ b/examples/supabase-chat/src/app/globals.css
@@ -1,2 +1,2 @@
-@layer theme, base, openui, components, utilities;
@import "tailwindcss";
+@import "@openuidev/react-ui/styles/index.css";
diff --git a/examples/supabase-chat/src/app/page.tsx b/examples/supabase-chat/src/app/page.tsx
index 7f503c18c..fd8332329 100644
--- a/examples/supabase-chat/src/app/page.tsx
+++ b/examples/supabase-chat/src/app/page.tsx
@@ -1,6 +1,5 @@
"use client";
-import "@openuidev/react-ui/components.css";
import { openAIAdapter, openAIMessageFormat } from "@openuidev/react-headless";
import { FullScreen } from "@openuidev/react-ui";
diff --git a/examples/vercel-ai-chat/src/app/globals.css b/examples/vercel-ai-chat/src/app/globals.css
index c45470e58..436d6d8f2 100644
--- a/examples/vercel-ai-chat/src/app/globals.css
+++ b/examples/vercel-ai-chat/src/app/globals.css
@@ -1,3 +1,3 @@
@layer theme, base, openui, components, utilities;
@import "tailwindcss";
-@import "@openuidev/react-ui/components.css";
+@import "@openuidev/react-ui/layered/styles/index.css";
diff --git a/examples/vercel-ai-chat/src/app/page.tsx b/examples/vercel-ai-chat/src/app/page.tsx
index b08b0a679..11ceb28cd 100644
--- a/examples/vercel-ai-chat/src/app/page.tsx
+++ b/examples/vercel-ai-chat/src/app/page.tsx
@@ -1,6 +1,5 @@
"use client";
-import "@openuidev/react-ui/components.css";
import { useChat } from "@ai-sdk/react";
import { useRef, useEffect, useState } from "react";
diff --git a/packages/react-ui/README.md b/packages/react-ui/README.md
index 2f3044661..0a52a29de 100644
--- a/packages/react-ui/README.md
+++ b/packages/react-ui/README.md
@@ -21,7 +21,7 @@ pnpm add @openuidev/react-ui @openuidev/react-lang @openuidev/react-headless
Don't forget to import the component styles:
```ts
-import "@openuidev/react-ui/components.css";
+import "@openuidev/react-ui/styles/index.css";
```
## Overview
@@ -38,25 +38,20 @@ The fastest way to get a working chat app:
```tsx
import { FullScreen } from "@openuidev/react-ui";
-import "@openuidev/react-ui/components.css";
+import "@openuidev/react-ui/styles/index.css";
function App() {
- return (
- <FullScreen
- apiUrl="/api/chat"
- threadApiUrl="/api/threads"
- />
- );
+ return <FullScreen apiUrl="/api/chat" threadApiUrl="/api/threads" />;
}
```
### Chat Layouts
-| Component | Description |
-| :--- | :--- |
+| Component | Description |
+| :----------- | :----------------------------------- |
| `FullScreen` | Full-page chat with a thread sidebar |
-| `Copilot` | Side-panel copilot overlay |
-| `BottomTray` | Collapsible bottom tray chat |
+| `Copilot` | Side-panel copilot overlay |
+| `BottomTray` | Collapsible bottom tray chat |
All chat layouts accept `apiUrl`, `threadApiUrl`, and theming props. See the [chat docs](https://openui.com/docs/chat) for full configuration.
@@ -79,10 +74,10 @@ function App() {
The package ships with two preconfigured OpenUI Lang libraries:
-| Export | Description |
-| :--- | :--- |
-| `openuiLibrary` | Full component library for charts, tables, forms, cards, images, and more |
-| `openuiChatLibrary` | Chat-optimized subset with follow-ups, steps, and callouts |
+| Export | Description |
+| :------------------ | :------------------------------------------------------------------------ |
+| `openuiLibrary` | Full component library for charts, tables, forms, cards, images, and more |
+| `openuiChatLibrary` | Chat-optimized subset with follow-ups, steps, and callouts |
Use them directly when building custom chat experiences:
@@ -91,13 +86,7 @@ import { Renderer } from "@openuidev/react-lang";
import { openuiLibrary } from "@openuidev/react-ui";
function AssistantMessage({ content, isStreaming }) {
- return (
- <Renderer
- response={content}
- library={openuiLibrary}
- isStreaming={isStreaming}
- />
- );
+ return <Renderer response={content} library={openuiLibrary} isStreaming={isStreaming} />;
}
```
@@ -131,58 +120,71 @@ function App() {
}
```
-| Export | Description |
-| :--- | :--- |
-| `ThemeProvider` | Context provider for theming |
+| Export | Description |
+| :----------------------- | :------------------------------------------ |
+| `ThemeProvider` | Context provider for theming |
| `createTheme(overrides)` | Create a theme with validation and defaults |
-| `defaultLightTheme` | Built-in light theme |
-| `defaultDarkTheme` | Built-in dark theme |
-| `swatchTokens` | Token palette for use in theme builders |
+| `defaultLightTheme` | Built-in light theme |
+| `defaultDarkTheme` | Built-in dark theme |
+| `swatchTokens` | Token palette for use in theme builders |
## Styling integration
-OpenUI's component styles live inside a CSS cascade layer named `openui`. Any unlayered consumer CSS overrides OpenUI without `!important` or specificity matching:
+OpenUI ships its component styles in two variants:
+
+| Import | Cascade behavior |
+| ------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `@openuidev/react-ui/styles/index.css` (default) | Unlayered — override via normal CSS specificity, as in 0.11.x and earlier |
+| `@openuidev/react-ui/layered/styles/index.css` (opt-in) | Wrapped in `@layer openui` — any unlayered consumer CSS wins |
+
+Need a single component's CSS? Import it per component: `./styles/<Component>.css` (unlayered) or `./layered/styles/<Component>.css` (layered).
+
+With the layered variant, plain CSS overrides OpenUI without `!important` or specificity matching:
```css
-@import "@openuidev/react-ui/components.css";
+@import "@openuidev/react-ui/layered/styles/index.css";
/* Wins, no specificity tricks needed */
-.openui-button-base-primary { background: hotpink; }
+.openui-button-base-primary {
+ background: hotpink;
+}
```
-### With Tailwind v4
+### With Tailwind v4 (layered variant)
Declare layer order at the top of your entry stylesheet so `openui` sits above Tailwind's reset but below `components` and `utilities`:
```css
@layer theme, base, openui, components, utilities;
-@import "@openuidev/react-ui/components.css";
@import "tailwindcss";
+@import "@openuidev/react-ui/layered/styles/index.css";
```
This places Tailwind's Preflight (in `base`) below OpenUI components so its element resets don't override them, while keeping utilities (`bg-red-500`, etc.) winning over OpenUI styles.
-### With Tailwind v3, CSS Modules, or CSS-in-JS
+### Rules for the layered variant
-No configuration needed — these all emit unlayered CSS, which automatically beats anything in `@layer openui`.
+- Import OpenUI CSS from **exactly one place** — multiple import sites under chunk-splitting bundlers (e.g. Turbopack) can register `openui` before your layer-order statement and lock the wrong order.
+- Wrap app-wide resets in a layer below `openui` (e.g. `@layer base { * { margin: 0; } }`) — unlayered resets beat all layered styles regardless of specificity.
+- `./defaults.css` and the `ThemeProvider` runtime style injection stay unlayered in both modes so runtime theming always overrides component defaults.
### Browser support
-CSS cascade layers require Chrome 99+, Firefox 97+, Safari 15.4+, or Edge 99+ (all baseline from March 2022). On older browsers, the `@layer { ... }` block is dropped entirely and components render unstyled. The package declares this floor via the `browserslist` field in its `package.json`.
+The layered variant requires CSS cascade layers: Chrome 99+, Firefox 97+, Safari 15.4+, Edge 99+ (all baseline from March 2022). On older browsers the `@layer { ... }` block is dropped entirely and components render unstyled. The default unlayered styles have no such floor.
## Components
All components are available as individual imports:
-| Category | Components |
-| :--- | :--- |
-| **Layout** | `Card`, `CardHeader`, `SectionBlock`, `Tabs`, `Accordion`, `Carousel`, `Separator`, `Steps` |
-| **Data Display** | `Table`, `Charts` (bar, line, area, pie, radar, scatter), `ListBlock`, `ListItem`, `Tag`, `TagBlock`, `CodeBlock`, `Image`, `ImageBlock`, `ImageGallery` |
-| **Forms** | `Input`, `TextArea`, `Select`, `CheckBoxGroup`, `CheckBoxItem`, `RadioGroup`, `RadioItem`, `SwitchGroup`, `SwitchItem`, `Slider`, `DatePicker`, `FormControl`, `Label` |
-| **Actions** | `Button`, `Buttons`, `IconButton`, `FollowUpBlock`, `FollowUpItem` |
-| **Feedback** | `Callout`, `TextCallout`, `MessageLoading` |
-| **Content** | `TextContent`, `MarkDownRenderer` |
-| **Chat** | `FullScreen`, `Copilot`, `BottomTray`, `Shell.*`, `CopilotShell.*`, `ToolCall`, `ToolResult` |
+| Category | Components |
+| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Layout** | `Card`, `CardHeader`, `SectionBlock`, `Tabs`, `Accordion`, `Carousel`, `Separator`, `Steps` |
+| **Data Display** | `Table`, `Charts` (bar, line, area, pie, radar, scatter), `ListBlock`, `ListItem`, `Tag`, `TagBlock`, `CodeBlock`, `Image`, `ImageBlock`, `ImageGallery` |
+| **Forms** | `Input`, `TextArea`, `Select`, `CheckBoxGroup`, `CheckBoxItem`, `RadioGroup`, `RadioItem`, `SwitchGroup`, `SwitchItem`, `Slider`, `DatePicker`, `FormControl`, `Label` |
+| **Actions** | `Button`, `Buttons`, `IconButton`, `FollowUpBlock`, `FollowUpItem` |
+| **Feedback** | `Callout`, `TextCallout`, `MessageLoading` |
+| **Content** | `TextContent`, `MarkDownRenderer` |
+| **Chat** | `FullScreen`, `Copilot`, `BottomTray`, `Shell.*`, `CopilotShell.*`, `ToolCall`, `ToolResult` |
### Per-component imports
@@ -196,15 +198,17 @@ import { Charts } from "@openuidev/react-ui/Charts";
## Subpath Exports
-| Import path | Description |
-| :--- | :--- |
-| `@openuidev/react-ui` | All components and libraries |
-| `@openuidev/react-ui/components.css` | Compiled component styles |
-| `@openuidev/react-ui/genui-lib` | OpenUI Lang libraries and prompt options |
-| `@openuidev/react-ui/tailwind` | Tailwind CSS plugin |
-| `@openuidev/react-ui/styles/*` | SCSS utilities |
-| `@openuidev/react-ui/scssUtils` | SCSS utility functions |
-| `@openuidev/react-ui/<Component>` | Per-component entry points |
+| Import path | Description |
+| :--------------------------------------------- | :--------------------------------------------------- |
+| `@openuidev/react-ui` | All components and libraries |
+| `@openuidev/react-ui/styles/index.css` | Full compiled stylesheet, unlayered (default import) |
+| `@openuidev/react-ui/layered/styles/index.css` | Full stylesheet wrapped in `@layer openui` (opt-in) |
+| `@openuidev/react-ui/defaults.css` | Theme tokens, always unlayered |
+| `@openuidev/react-ui/genui-lib` | OpenUI Lang libraries and prompt options |
+| `@openuidev/react-ui/styles/*` | Per-component compiled styles (unlayered) |
+| `@openuidev/react-ui/layered/styles/*` | Per-component styles wrapped in `@layer openui` |
+| `@openuidev/react-ui/scssUtils` | SCSS utility functions |
+| `@openuidev/react-ui/<Component>` | Per-component entry points |
## Documentation
@@ -212,7 +216,6 @@ import { Charts } from "@openuidev/react-ui/Charts";
- [Chat guides](https://openui.com/docs/chat)
- [Source on GitHub](https://github.com/thesysdev/openui/tree/main/packages/react-ui)
-
## License
[MIT](https://github.com/thesysdev/openui/blob/main/LICENSE)
diff --git a/packages/react-ui/check-css-artifacts.js b/packages/react-ui/check-css-artifacts.js
new file mode 100644
index 000000000..1f972fb88
--- /dev/null
+++ b/packages/react-ui/check-css-artifacts.js
@@ -0,0 +1,74 @@
+// Pre-publish guard for the CSS artifact contract:
+// - default exports stay UNLAYERED (./components.css, ./styles/*)
+// - the layered mirror is wrapped in @layer openui and BOM-free
+// - openui-defaults.css is unlayered in both trees (runtime theming contract)
+// Born out of the 2026-06 BOM incident: a U+FEFF pushed inside the layer
+// block silently killed the :root theme tokens in the packed tarball.
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const dist = path.join(dirname, "dist");
+const failures = [];
+
+const read = (rel) => fs.readFileSync(path.join(dist, rel), "utf8");
+const assert = (cond, msg) => {
+ if (!cond) failures.push(msg);
+};
+
+assert(
+ !/^\s*@layer/.test(read("components/index.css")),
+ "components/index.css must stay unlayered",
+);
+assert(!/^\s*@layer/.test(read("styles/index.css")), "styles/index.css must stay unlayered");
+assert(
+ read("layered/components/index.css").startsWith("@layer openui{"),
+ "layered/components/index.css must start with @layer openui{",
+);
+assert(
+ !/^\s*@layer/.test(read("styles/openui-defaults.css")),
+ "styles/openui-defaults.css must stay unlayered",
+);
+assert(
+ !/^\s*@layer/.test(read("layered/styles/openui-defaults.css")),
+ "layered/styles/openui-defaults.css must stay unlayered",
+);
+
+const unlayered = fs.readdirSync(path.join(dist, "styles")).filter((f) => f.endsWith(".css"));
+const layered = fs
+ .readdirSync(path.join(dist, "layered", "styles"))
+ .filter((f) => f.endsWith(".css"));
+assert(
+ unlayered.length === layered.length,
+ `layered mirror has ${layered.length} css files, unlayered has ${unlayered.length}`,
+);
+
+// Every per-component DEFAULT style must stay unlayered too — not just the
+// index files checked above. Guards against a regression that re-wraps
+// dist/styles/*.css in place (the `wrapComponentCssInPlace` behavior this
+// contract intentionally removed); since consumers can import individual
+// ./styles/<component>.css, an index-only check would miss it.
+// openui-defaults.css is asserted unlayered separately above.
+for (const name of unlayered) {
+ if (name === "openui-defaults.css") continue;
+ assert(!/^\s*@layer/.test(read(path.join("styles", name))), `styles/${name} must stay unlayered`);
+}
+
+for (const f of [
+ ...layered.map((n) => path.join("layered", "styles", n)),
+ "layered/components/index.css",
+]) {
+ const content = read(f);
+ assert(!content.includes("\uFEFF"), `${f} contains a BOM`);
+ const base = path.basename(f);
+ if (base !== "openui-defaults.css" && content.trim() !== "") {
+ assert(content.startsWith("@layer openui{"), `${f} is not wrapped in @layer openui`);
+ }
+}
+
+if (failures.length > 0) {
+ console.error("CSS artifact check FAILED:\n - " + failures.join("\n - "));
+ process.exit(1);
+}
+console.log(`CSS artifact check passed (${layered.length} layered files verified).`);
diff --git a/packages/react-ui/cp-css.js b/packages/react-ui/cp-css.js
index dc8f9b78a..2c645f860 100644
--- a/packages/react-ui/cp-css.js
+++ b/packages/react-ui/cp-css.js
@@ -2,6 +2,7 @@ import fs from "fs";
import { camelCase } from "lodash-es";
import path from "path";
import { fileURLToPath } from "url";
+import { mirrorStylesWithLayer, writeLayeredCopy } from "./css-layer-utils.mjs";
const dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -12,29 +13,6 @@ function ensureDirectoryExists(dirPath) {
}
}
-// Wrap a CSS file's contents in @layer openui { ... } if not already wrapped.
-// Idempotency check protects watch-mode and back-to-back builds.
-function wrapInLayer(content) {
- if (content.trim() === "") return content;
- if (/^\s*@layer\s+openui\b/.test(content)) return content;
- return `@layer openui{${content}}`;
-}
-
-// Walk dist/components and wrap every emitted .css file in @layer openui.
-// *.module.css are Storybook CSS Modules — locally scoped, not shipped, not wrapped.
-function wrapComponentCssInPlace(dir) {
- for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
- const full = path.join(dir, entry.name);
- if (entry.isDirectory()) {
- wrapComponentCssInPlace(full);
- } else if (entry.name.endsWith(".css") && !entry.name.endsWith(".module.css")) {
- const content = fs.readFileSync(full, "utf8");
- const wrapped = wrapInLayer(content);
- if (wrapped !== content) fs.writeFileSync(full, wrapped, "utf8");
- }
- }
-}
-
// Replace .scss imports with .css imports in compiled JS files
function fixScssImportsInJs(dir) {
const entries = fs.readdirSync(dir);
@@ -60,12 +38,6 @@ function copyCssFiles() {
const srcDir = path.join(dirname, "dist", "components");
const distDir = path.join(dirname, "dist", "styles");
- // Wrap every emitted component CSS in @layer openui before copying.
- // dist/openui-defaults.css lives outside dist/components and stays unwrapped
- // so the defaults.css export remains in the unlayered cascade — matching the
- // ThemeProvider runtime injection contract.
- wrapComponentCssInPlace(srcDir);
-
// Ensure the dist/styles directory exists
ensureDirectoryExists(distDir);
@@ -101,6 +73,15 @@ function copyCssFiles() {
fs.copyFileSync(defaultsCssPath, path.join(distDir, "openui-defaults.css"));
}
+ // Emit the opt-in layered mirror (./layered-components.css and
+ // ./layered/styles/*). The default exports above stay unlayered — see
+ // README "Styling integration".
+ writeLayeredCopy(
+ path.join(srcDir, "index.css"),
+ path.join(dirname, "dist", "layered", "components", "index.css"),
+ );
+ mirrorStylesWithLayer(distDir, path.join(dirname, "dist", "layered", "styles"));
+
// Fix .scss imports in compiled JS to point to .css files instead
fixScssImportsInJs(path.join(dirname, "dist"));
}
diff --git a/packages/react-ui/css-layer-utils.mjs b/packages/react-ui/css-layer-utils.mjs
new file mode 100644
index 000000000..a4799c68d
--- /dev/null
+++ b/packages/react-ui/css-layer-utils.mjs
@@ -0,0 +1,40 @@
+import fs from "fs";
+import path from "path";
+
+// Wrap a CSS file's contents in @layer openui { ... } if not already wrapped.
+// Idempotency check protects watch-mode and back-to-back builds.
+export function wrapInLayer(content) {
+ // Sass emits a UTF-8 BOM for files with non-ASCII output. At byte 0 the
+ // decoder strips it, but wrapping would push it inside the layer block,
+ // where U+FEFF parses as an identifier and kills the first rule
+ // (e.g. the :root theme tokens). Strip it before wrapping.
+ content = content.replace(/^\uFEFF/, "");
+ if (content.trim() === "") return content;
+ if (/^\s*@layer\s+openui\b/.test(content)) return content;
+ return `@layer openui{${content}}`;
+}
+
+// Write a layered copy of srcFile at destFile, creating parent directories.
+export function writeLayeredCopy(srcFile, destFile) {
+ const content = fs.readFileSync(srcFile, "utf8");
+ fs.mkdirSync(path.dirname(destFile), { recursive: true });
+ fs.writeFileSync(destFile, wrapInLayer(content), "utf8");
+}
+
+// Mirror every top-level *.css file in srcDir into destDir wrapped in
+// @layer openui. Files named in `unwrapped` are copied verbatim — they must
+// stay in the unlayered cascade (openui-defaults.css backs the runtime
+// theming override contract). Non-CSS files (e.g. cssUtils.scss) are skipped.
+export function mirrorStylesWithLayer(srcDir, destDir, unwrapped = ["openui-defaults.css"]) {
+ fs.mkdirSync(destDir, { recursive: true });
+ for (const name of fs.readdirSync(srcDir)) {
+ if (!name.endsWith(".css")) continue;
+ const src = path.join(srcDir, name);
+ if (!fs.statSync(src).isFile()) continue;
+ if (unwrapped.includes(name)) {
+ fs.copyFileSync(src, path.join(destDir, name));
+ } else {
+ writeLayeredCopy(src, path.join(destDir, name));
+ }
+ }
+}
diff --git a/packages/react-ui/css-layer-utils.test.mjs b/packages/react-ui/css-layer-utils.test.mjs
new file mode 100644
index 000000000..fa4e4be63
--- /dev/null
+++ b/packages/react-ui/css-layer-utils.test.mjs
@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { mirrorStylesWithLayer, wrapInLayer, writeLayeredCopy } from "./css-layer-utils.mjs";
+
+describe("wrapInLayer", () => {
+ it("wraps plain css in @layer openui", () => {
+ expect(wrapInLayer(".a{color:red}")).toBe("@layer openui{.a{color:red}}");
+ });
+
+ it("strips a leading BOM before wrapping so the first rule stays valid", () => {
+ // U+FEFF inside a layer block parses as an identifier and kills the
+ // first rule (e.g. the :root theme tokens) — the 2026-06 BOM incident.
+ expect(wrapInLayer("\uFEFF:root{--x:1}")).toBe("@layer openui{:root{--x:1}}");
+ });
+
+ it("is idempotent", () => {
+ const once = wrapInLayer(".a{color:red}");
+ expect(wrapInLayer(once)).toBe(once);
+ });
+
+ it("leaves empty/whitespace-only content untouched", () => {
+ expect(wrapInLayer("")).toBe("");
+ expect(wrapInLayer(" \n")).toBe(" \n");
+ });
+});
+
+describe("writeLayeredCopy", () => {
+ it("writes a wrapped copy, creating parent directories", () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "css-layer-"));
+ const src = path.join(dir, "in.css");
+ const dest = path.join(dir, "nested", "out.css");
+ fs.writeFileSync(src, ".a{color:red}");
+ writeLayeredCopy(src, dest);
+ expect(fs.readFileSync(dest, "utf8")).toBe("@layer openui{.a{color:red}}");
+ });
+});
+
+describe("mirrorStylesWithLayer", () => {
+ it("wraps css files, copies unwrapped names verbatim, skips non-css", () => {
+ const src = fs.mkdtempSync(path.join(os.tmpdir(), "css-layer-src-"));
+ const dest = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "css-layer-dest-")), "layered");
+ fs.writeFileSync(path.join(src, "button.css"), ".b{color:red}");
+ fs.writeFileSync(path.join(src, "openui-defaults.css"), ":root{--x:1}");
+ fs.writeFileSync(path.join(src, "cssUtils.scss"), "$x: 1;");
+ mirrorStylesWithLayer(src, dest);
+ expect(fs.readFileSync(path.join(dest, "button.css"), "utf8")).toBe("@layer openui{.b{color:red}}");
+ expect(fs.readFileSync(path.join(dest, "openui-defaults.css"), "utf8")).toBe(":root{--x:1}");
+ expect(fs.existsSync(path.join(dest, "cssUtils.scss"))).toBe(false);
+ });
+});
diff --git a/packages/react-ui/package.json b/packages/react-ui/package.json
index c81bc9518..f2a4156e8 100644
--- a/packages/react-ui/package.json
+++ b/packages/react-ui/package.json
@@ -18,15 +18,24 @@
"default": "./dist/index.cjs"
}
},
+ "./index.css": {
+ "default": "./dist/styles/index.css"
+ },
"./components.css": {
"default": "./dist/components/index.css"
},
+ "./layered/styles/index.css": {
+ "default": "./dist/layered/styles/index.css"
+ },
"./defaults.css": {
"default": "./dist/styles/openui-defaults.css"
},
"./styles/*": {
"default": "./dist/styles/*"
},
+ "./layered/styles/*": {
+ "default": "./dist/layered/styles/*"
+ },
"./genui-lib": {
"import": {
"types": "./dist/genui-lib/index.d.mts",
@@ -60,11 +69,11 @@
"README.md"
],
"scripts": {
- "test": "vitest run --passWithNoTests",
+ "test": "vitest run",
"copy-css": "node cp-css.js",
"generate-scss-index": "node src/scripts/scss-import.js",
"generate:css-utils": "tsx src/scripts/generate-css-utils.ts",
- "build": "rimraf dist && pnpm generate:css-utils && pnpm build:scss && pnpm build:tsc && pnpm build:cjs && pnpm run copy-css",
+ "build": "rimraf dist && pnpm generate:css-utils && pnpm build:scss && pnpm build:tsc && pnpm build:cjs && pnpm run copy-css && pnpm run check:css",
"typecheck": "tsc --noEmit",
"build:tsc": "tsc -p . || node -e \"process.exit(0)\"",
"build:cjs": "tsdown",
@@ -76,11 +85,12 @@
"lint:fix": "eslint ./src --fix",
"format:fix": "prettier --write ./src",
"format:check": "prettier --check ./src",
+ "check:css": "node check-css-artifacts.js",
"check:publint": "publint",
"check:attw": "attw --pack . --ignore-rules no-resolution",
"prepare": "pnpm run build",
- "prepublishOnly": "pnpm run check:publint && pnpm run check:attw",
- "ci": "pnpm run lint:check && pnpm run format:check"
+ "prepublishOnly": "pnpm run check:css && pnpm run check:publint && pnpm run check:attw",
+ "ci": "pnpm run lint:check && pnpm run format:check && pnpm run test"
},
"peerDependencies": {
"@openuidev/react-headless": "workspace:^",
@@ -196,7 +206,6 @@
"bugs": {
"url": "https://github.com/thesysdev/openui/issues"
},
- "browserslist": "defaults and supports css-cascade-layers",
"eslintConfig": {
"extends": [
"plugin:storybook/recommended"
diff --git a/packages/react-ui/src/components/ThemeProvider/ThemeProvider.tsx b/packages/react-ui/src/components/ThemeProvider/ThemeProvider.tsx
index 424fab01a..d9e54675d 100644
--- a/packages/react-ui/src/components/ThemeProvider/ThemeProvider.tsx
+++ b/packages/react-ui/src/components/ThemeProvider/ThemeProvider.tsx
@@ -236,8 +236,9 @@ export const ThemeProvider = ({
const useAutoScope = isNested && !hasExplicitSelector;
const styleSelector = useAutoScope ? `.${scopedClassName}` : effectiveCssSelector;
- // Intentionally unlayered — must override @layer openui so runtime theme
- // switching takes effect. See README "Styling integration" before changing.
+ // Intentionally unlayered — must override component styles in both modes,
+ // including when consumers opt into layered-components.css (@layer openui),
+ // so runtime theming always wins. See README "Styling integration" before changing.
useInsertionEffect(() => {
const style = document.createElement("style");
style.setAttribute("data-openui-theme", id);