The Open Standard for Generative UI
fix(css): re-adopt `@layer openui` (#589) and make the docs honor cascade layers (#621)
Ankit Das1b790840a48e
diff --git a/docs/app/components/globals.css b/docs/app/components/globals.cssindex 7399cae27..393dfec6d 100644--- a/docs/app/components/globals.css+++ b/docs/app/components/globals.css@@ -1,5 +1,12 @@+/* 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");-@import "../../../packages/react-ui/dist/styles/index.css";+/* 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). */html,body {diff --git a/docs/app/demo/github/layout.css b/docs/app/demo/github/layout.cssindex 96252db3f..f8b74062b 100644--- a/docs/app/demo/github/layout.css+++ b/docs/app/demo/github/layout.css@@ -1,9 +1,16 @@/* 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. */-: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.++ 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;+ }}/* ─── Global ────────────────────────────────────────────────────────────────── */diff --git a/docs/app/global.css b/docs/app/global.cssindex 347cdca1d..14b7b4f9b 100644--- a/docs/app/global.css+++ b/docs/app/global.css@@ -1,3 +1,10 @@+/* 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.cssindex 21927ee20..f40735361 100644--- a/docs/app/playground/layout.css+++ b/docs/app/playground/layout.css@@ -1,9 +1,18 @@/* 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. */-: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.++ 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;+ }}/* ─── Scrollbar ─────────────────────────────────────────────────────────────── */diff --git a/docs/components/overview-components/chat-modal.tsx b/docs/components/overview-components/chat-modal.tsxindex 99003eab9..29934194f 100644--- a/docs/components/overview-components/chat-modal.tsx+++ b/docs/components/overview-components/chat-modal.tsx@@ -1,6 +1,9 @@"use client";-import "@openuidev/react-ui/components.css";+// NOTE: do not import react-ui CSS here. It is loaded once, app-wide, via+// docs/app/global.css. A second react-ui CSS import makes the bundler hoist a+// statement-less `@layer openui` chunk that loads BEFORE global.css's `@layer`+// order declaration, which breaks the cascade order (Tailwind preflight wins).import "./chat-modal.css";import { DemoCreditsDialog } from "@/components/DemoCreditsDialog";diff --git a/docs/content/docs/api-reference/react-ui.mdx b/docs/content/docs/api-reference/react-ui.mdxindex 86a960d7f..629c89f5d 100644--- a/docs/content/docs/api-reference/react-ui.mdx+++ b/docs/content/docs/api-reference/react-ui.mdx@@ -11,6 +11,12 @@ 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 componentsThese 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.mdxindex 0b49eaa82..1f52d2ee2 100644--- a/docs/content/docs/chat/installation.mdx+++ b/docs/content/docs/chat/installation.mdx@@ -57,7 +57,23 @@ export default function RootLayout({ children }: { children: React.ReactNode })These imports give you the default chat layout styling and theme tokens.-## 3. Render a layout to verify setup+## 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 setupRender 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.mdxindex 945c060e1..81218c053 100644--- a/docs/content/docs/chat/theming.mdx+++ b/docs/content/docs/chat/theming.mdx@@ -54,6 +54,20 @@ 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.mdxindex f8eeeaeef..3bebcde91 100644--- a/docs/content/docs/openui-lang/standard-library.mdx+++ b/docs/content/docs/openui-lang/standard-library.mdx@@ -21,6 +21,8 @@ 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 promptUse the CLI to generate the system prompt at build time:diff --git a/examples/hands-on-table-chat/src/app/globals.css b/examples/hands-on-table-chat/src/app/globals.cssindex cec7e6528..e5922b2c3 100644--- a/examples/hands-on-table-chat/src/app/globals.css+++ b/examples/hands-on-table-chat/src/app/globals.css@@ -1,3 +1,4 @@+@layer theme, base, openui, components, utilities;@import "tailwindcss";:root {diff --git a/examples/mastra-chat/src/app/globals.css b/examples/mastra-chat/src/app/globals.cssindex f1d8c73cd..4a090eef4 100644--- a/examples/mastra-chat/src/app/globals.css+++ b/examples/mastra-chat/src/app/globals.css@@ -1 +1,2 @@+@layer theme, base, openui, components, utilities;@import "tailwindcss";diff --git a/examples/multi-agent-chat/src/app/globals.css b/examples/multi-agent-chat/src/app/globals.cssindex e4ac5af9b..c45470e58 100644--- a/examples/multi-agent-chat/src/app/globals.css+++ b/examples/multi-agent-chat/src/app/globals.css@@ -1,2 +1,3 @@+@layer theme, base, openui, components, utilities;@import "tailwindcss";@import "@openuidev/react-ui/components.css";diff --git a/examples/openui-artifact-demo/src/app/globals.css b/examples/openui-artifact-demo/src/app/globals.cssindex 3d552a61f..0ffe00eb2 100644--- a/examples/openui-artifact-demo/src/app/globals.css+++ b/examples/openui-artifact-demo/src/app/globals.css@@ -1,2 +1,3 @@+@layer theme, base, openui, components, utilities;@import "tailwindcss";diff --git a/examples/openui-chat/src/app/globals.css b/examples/openui-chat/src/app/globals.cssindex 3d552a61f..0ffe00eb2 100644--- a/examples/openui-chat/src/app/globals.css+++ b/examples/openui-chat/src/app/globals.css@@ -1,2 +1,3 @@+@layer theme, base, openui, components, utilities;@import "tailwindcss";diff --git a/examples/openui-dashboard/src/app/globals.css b/examples/openui-dashboard/src/app/globals.cssindex 975bcec94..00eb02317 100644--- a/examples/openui-dashboard/src/app/globals.css+++ b/examples/openui-dashboard/src/app/globals.css@@ -1,3 +1,4 @@+@layer theme, base, openui, components, utilities;@import "tailwindcss";@keyframes openui-loading-bar {diff --git a/examples/shadcn-chat/src/app/globals.css b/examples/shadcn-chat/src/app/globals.cssindex d63189515..39a6d2c91 100644--- a/examples/shadcn-chat/src/app/globals.css+++ b/examples/shadcn-chat/src/app/globals.css@@ -1,3 +1,4 @@+@layer theme, base, openui, components, utilities;@import "tailwindcss";@custom-variant dark (&:is([data-theme="dark"] *));diff --git a/examples/supabase-chat/src/app/globals.css b/examples/supabase-chat/src/app/globals.cssindex f1d8c73cd..4a090eef4 100644--- a/examples/supabase-chat/src/app/globals.css+++ b/examples/supabase-chat/src/app/globals.css@@ -1 +1,2 @@+@layer theme, base, openui, components, utilities;@import "tailwindcss";diff --git a/examples/vercel-ai-chat/src/app/globals.css b/examples/vercel-ai-chat/src/app/globals.cssindex e4ac5af9b..c45470e58 100644--- a/examples/vercel-ai-chat/src/app/globals.css+++ b/examples/vercel-ai-chat/src/app/globals.css@@ -1,2 +1,3 @@+@layer theme, base, openui, components, utilities;@import "tailwindcss";@import "@openuidev/react-ui/components.css";diff --git a/packages/react-ui/README.md b/packages/react-ui/README.mdindex 460cfef42..2f3044661 100644--- a/packages/react-ui/README.md+++ b/packages/react-ui/README.md@@ -139,6 +139,37 @@ function App() {| `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:++```css+@import "@openuidev/react-ui/components.css";++/* Wins, no specificity tricks needed */+.openui-button-base-primary { background: hotpink; }+```++### With Tailwind v4++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";+```++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++No configuration needed — these all emit unlayered CSS, which automatically beats anything in `@layer openui`.++### 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`.+## ComponentsAll components are available as individual imports:diff --git a/packages/react-ui/cp-css.js b/packages/react-ui/cp-css.jsindex c805b4941..dc8f9b78a 100644--- a/packages/react-ui/cp-css.js+++ b/packages/react-ui/cp-css.js@@ -1,7 +1,7 @@import fs from "fs";import { camelCase } from "lodash-es";import path from "path";-import {fileURLToPath} from "url"+import { fileURLToPath } from "url";const dirname = path.dirname(fileURLToPath(import.meta.url));@@ -12,6 +12,29 @@ 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 filesfunction fixScssImportsInJs(dir) {const entries = fs.readdirSync(dir);@@ -37,6 +60,12 @@ 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 existsensureDirectoryExists(distDir);diff --git a/packages/react-ui/package.json b/packages/react-ui/package.jsonindex f138ce6ed..89769d655 100644--- a/packages/react-ui/package.json+++ b/packages/react-ui/package.json@@ -194,6 +194,7 @@"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.tsxindex 1949046ce..424fab01a 100644--- a/packages/react-ui/src/components/ThemeProvider/ThemeProvider.tsx+++ b/packages/react-ui/src/components/ThemeProvider/ThemeProvider.tsx@@ -236,6 +236,8 @@ 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.useInsertionEffect(() => {const style = document.createElement("style");style.setAttribute("data-openui-theme", id);