Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat: CSS layer ordering for dist path theming (#806)

Cindy Zhangda283b3e1b03
diff --git a/apps/sandbox/next.config.mjs b/apps/sandbox/next.config.mjs
index f77eab8cb8..476006fcdb 100644
--- a/apps/sandbox/next.config.mjs
+++ b/apps/sandbox/next.config.mjs
@@ -3,7 +3,13 @@ const nextConfig = {
output: 'export',
trailingSlash: true,
basePath: process.env.SANDBOX_BASE_PATH || '',
- transpilePackages: ['@xds/core', '@xds/theme-default'],
+ // Theme packages still need transpilation for defineTheme() calls.
+ // @xds/core uses pre-built dist — no transpilation needed.
+ transpilePackages: [
+ '@xds/theme-default',
+ '@xds/theme-neutral',
+ '@xds/theme-brutalist',
+ ],
images: {
unoptimized: true,
},
diff --git a/apps/sandbox/package.json b/apps/sandbox/package.json
index 96e97dc47f..6abb694771 100644
--- a/apps/sandbox/package.json
+++ b/apps/sandbox/package.json
@@ -13,6 +13,8 @@
"@xds/cli": "*",
"@xds/core": "*",
"@xds/theme-default": "*",
+ "@xds/theme-neutral": "*",
+ "@xds/theme-brutalist": "*",
"next": "^15.5.14",
"react": "^19.2.4",
"react-dom": "^19.2.4"
diff --git a/apps/sandbox/postcss.config.js b/apps/sandbox/postcss.config.js
index af668d9eb3..a5f4dcd783 100644
--- a/apps/sandbox/postcss.config.js
+++ b/apps/sandbox/postcss.config.js
@@ -7,12 +7,10 @@ const rootDir = path.resolve(__dirname, '../..');
module.exports = {
plugins: {
'@stylexjs/postcss-plugin': {
- include: [
- 'src/**/*.{js,jsx,ts,tsx}',
- path.join(rootDir, 'packages/core/src/**/*.{ts,tsx}'),
- path.join(rootDir, 'packages/themes/default/src/**/*.{ts,tsx}'),
- path.join(rootDir, 'packages/themes/neutral/src/**/*.{ts,tsx}'),
- ],
+ // Only compile StyleX in sandbox page files.
+ // @xds/core and theme packages use pre-built dist CSS
+ // (imported in layout.tsx via @layer xds-base / xds-theme).
+ include: ['src/**/*.{js,jsx,ts,tsx}'],
babelConfig: {
babelrc: false,
parserOpts: {
@@ -20,13 +18,13 @@ module.exports = {
},
presets: [
['@babel/preset-react', {runtime: 'automatic'}],
- // Must come after preset-react (runs first due to reverse order)
- // to strip TypeScript type assertions before StyleX evaluates them.
'@babel/preset-typescript',
],
plugins: babelConfig.plugins,
},
- useCSSLayers: true,
+ // Don't use CSS layers for sandbox page styles — they should be
+ // unlayered (highest priority), same as consumer styles would be.
+ useCSSLayers: false,
},
},
};
diff --git a/apps/sandbox/src/app/(sandbox)/layout.tsx b/apps/sandbox/src/app/(sandbox)/layout.tsx
index 05eabe2dcf..648d8b6e29 100644
--- a/apps/sandbox/src/app/(sandbox)/layout.tsx
+++ b/apps/sandbox/src/app/(sandbox)/layout.tsx
@@ -1,14 +1,14 @@
-import {Sidebar} from '../Sidebar';
+import {XDSAppShell} from '@xds/core/AppShell';
+import {SandboxTopNav} from '../SandboxTopNav';
+import {SandboxNav} from '../SandboxNav';
-export default function SandboxLayout({
- children,
-}: {
- children: React.ReactNode;
-}) {
+export default function SandboxLayout({children}: {children: React.ReactNode}) {
return (
- <div style={{display: 'flex', minHeight: '100vh'}}>
- <Sidebar />
- <main style={{flex: 1, padding: '2rem'}}>{children}</main>
- </div>
+ <XDSAppShell
+ topNav={<SandboxTopNav />}
+ sideNav={<SandboxNav />}
+ contentPadding={4}>
+ {children}
+ </XDSAppShell>
);
}
diff --git a/apps/storybook/stories/ThemeEditor.stories.tsx b/apps/sandbox/src/app/(sandbox)/pages/theme-editor/page.tsx
similarity index 96%
rename from apps/storybook/stories/ThemeEditor.stories.tsx
rename to apps/sandbox/src/app/(sandbox)/pages/theme-editor/page.tsx
index 5bf1ada0a3..41ce4d3629 100644
--- a/apps/storybook/stories/ThemeEditor.stories.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/theme-editor/page.tsx
@@ -1,4 +1,5 @@
-import type {Meta, StoryObj} from '@storybook/react';
+'use client';
+
import * as React from 'react';
import {XDSButton} from '@xds/core/Button';
import {XDSTextInput} from '@xds/core/TextInput';
@@ -817,7 +818,7 @@ function ComponentPreview() {
<XDSText type="label" style={{marginBottom: '16px', display: 'block'}}>
Typography Scale
</XDSText>
- <XDSCard padding="lg">
+ <XDSCard padding={4}>
<article>
<XDSHeading level={1}>Building Design Systems</XDSHeading>
<XDSText
@@ -986,7 +987,6 @@ const styles = stylex.create({
<XDSTable
columns={spacingTableColumns}
data={spacingData}
- getRowKey={row => row.token}
density="compact"
dividers="rows"
/>
@@ -998,12 +998,11 @@ const styles = stylex.create({
Badges
</XDSText>
<div style={{display: 'flex', gap: '8px', flexWrap: 'wrap'}}>
- <XDSBadge label="Default" />
- <XDSBadge label="Primary" variant="primary" />
- <XDSBadge label="Ghost" variant="ghost" />
- <XDSBadge label="Positive" sentiment="positive" />
- <XDSBadge label="Negative" sentiment="negative" />
- <XDSBadge label="Warning" sentiment="warning" />
+ <XDSBadge label="Neutral" />
+ <XDSBadge label="Info" variant="info" />
+ <XDSBadge label="Success" variant="success" />
+ <XDSBadge label="Warning" variant="warning" />
+ <XDSBadge label="Error" variant="error" />
</div>
</div>
@@ -1034,23 +1033,23 @@ const styles = stylex.create({
gap: '12px',
maxWidth: '300px',
}}>
- <XDSTextInput label="Text Input" placeholder="Enter text..." />
+ <XDSTextInput label="Text Input" placeholder="Enter text..." value="" onChange={() => {}} />
<XDSSwitch
label="Toggle Switch"
- isSelected={switchValue}
+ value={switchValue}
onChange={setSwitchValue}
/>
<XDSCheckboxInput
label="Checkbox"
- isSelected={checkboxValue}
+ value={checkboxValue}
onChange={setCheckboxValue}
/>
<XDSSlider
label="Slider"
value={sliderValue}
onChange={setSliderValue}
- minValue={0}
- maxValue={100}
+ min={0}
+ max={100}
/>
</div>
</div>
@@ -1106,9 +1105,9 @@ const styles = stylex.create({
Avatars
</XDSText>
<div style={{display: 'flex', gap: '8px', alignItems: 'center'}}>
- <XDSAvatar name="John Doe" size="sm" />
- <XDSAvatar name="Jane Smith" size="md" />
- <XDSAvatar name="Bob Wilson" size="lg" />
+ <XDSAvatar name="John Doe" size="small" />
+ <XDSAvatar name="Jane Smith" size="medium" />
+ <XDSAvatar name="Bob Wilson" size="large" />
</div>
</div>
@@ -1146,8 +1145,8 @@ const styles = stylex.create({
<XDSText type="label" style={{marginBottom: '12px', display: 'block'}}>
Card
</XDSText>
- <XDSCard padding="md">
- <XDSStack gap="sm">
+ <XDSCard padding={3}>
+ <XDSStack direction="vertical" gap={2}>
<XDSHeading level={4}>Card Title</XDSHeading>
<XDSText type="body">
This is a sample card with some content to demonstrate how cards
@@ -1173,10 +1172,9 @@ const styles = stylex.create({
/>
<XDSDialog
isOpen={dialogOpen}
- onClose={() => setDialogOpen(false)}
- title="Sample Dialog">
+ onOpenChange={(open) => setDialogOpen(open)}>
<div style={{padding: '0 24px 24px 24px'}}>
- <XDSStack gap="md">
+ <XDSStack direction="vertical" gap={3}>
<XDSText type="body">
This is a sample dialog to preview how dialogs look with the
current theme settings.
@@ -1184,6 +1182,8 @@ const styles = stylex.create({
<XDSTextInput
label="Example Input"
placeholder="Type something..."
+ value=""
+ onChange={() => {}}
/>
<div
style={{
@@ -1219,7 +1219,7 @@ function LandingPagePreview() {
<div style={{display: 'flex', flexDirection: 'column', gap: '48px'}}>
{/* Hero */}
<div style={{textAlign: 'center', padding: '48px 24px'}}>
- <XDSBadge variant="accent" label="New Release" />
+ <XDSBadge variant="info" label="New Release" />
<XDSHeading level={1} style={{marginTop: 16, marginBottom: 12}}>
Ship faster with XDS
</XDSHeading>
@@ -1269,7 +1269,7 @@ function LandingPagePreview() {
desc: 'JSDoc annotations with composition hints for LLM-assisted development.',
},
].map(f => (
- <XDSCard key={f.title} padding="md">
+ <XDSCard key={f.title} padding={3}>
<XDSHeading level={3} style={{marginBottom: 8}}>
{f.title}
</XDSHeading>
@@ -1282,13 +1282,13 @@ function LandingPagePreview() {
</div>
{/* Testimonial */}
- <XDSCard padding="lg">
+ <XDSCard padding={4}>
<XDSText type="large" display="block" style={{marginBottom: 12}}>
&ldquo;XDS cut our dev time in half. The type scale system alone saved
us weeks of bikeshedding.&rdquo;
</XDSText>
<div style={{display: 'flex', alignItems: 'center', gap: '8px'}}>
- <XDSAvatar size="sm" name="Alex Chen" />
+ <XDSAvatar name="Alex Chen" size="small" />
<div>
<XDSText type="label">Alex Chen</XDSText>
<XDSText type="supporting" color="secondary">
@@ -1385,7 +1385,7 @@ function DashboardPreview() {
{label: 'Uptime', value: '99.97%', delta: '—'},
{label: 'NPS', value: '72', delta: '+3'},
].map(kpi => (
- <XDSCard key={kpi.label} padding="md">
+ <XDSCard key={kpi.label} padding={3}>
<XDSText type="supporting" color="secondary" display="block">
{kpi.label}
</XDSText>
@@ -1409,16 +1409,16 @@ function DashboardPreview() {
<XDSTab value="errors" label="Errors" />
</XDSTabList>
<div style={{marginTop: '16px'}}>
- <XDSTable columns={dashboardColumns} data={metrics} size="sm" />
+ <XDSTable columns={dashboardColumns} data={metrics} density="compact" />
</div>
</div>
{/* Activity Banner */}
<XDSBanner
- variant="educational"
+ status="info"
title="System Update"
description="A new version of the API is available. Review the changelog for breaking changes."
- action={
+ endContent={
<XDSButton label="View Changelog" variant="secondary" size="sm" />
}
/>
@@ -1426,7 +1426,7 @@ function DashboardPreview() {
{/* Bottom section */}
<div
style={{display: 'grid', gridTemplateColumns: '2fr 1fr', gap: '16px'}}>
- <XDSCard padding="md">
+ <XDSCard padding={3}>
<XDSHeading level={3} style={{marginBottom: 12}}>
Recent Activity
</XDSHeading>
@@ -1461,7 +1461,7 @@ function DashboardPreview() {
padding: '8px 0',
borderBottom: i < 3 ? '1px solid var(--color-divider)' : 'none',
}}>
- <XDSAvatar size="sm" name={item.user} />
+ <XDSAvatar name={item.user} size="small" />
<div style={{flex: 1}}>
<XDSText type="label">{item.user}</XDSText>
<XDSText type="body" color="secondary">
@@ -1475,7 +1475,7 @@ function DashboardPreview() {
</div>
))}
</XDSCard>
- <XDSCard padding="md">
+ <XDSCard padding={3}>
<XDSHeading level={3} style={{marginBottom: 12}}>
Quick Stats
</XDSHeading>
@@ -1492,7 +1492,7 @@ function DashboardPreview() {
43%
</XDSText>
</div>
- <XDSProgressBar value={43} />
+ <XDSProgressBar value={43} label="API Latency" isLabelHidden />
</div>
<div>
<div
@@ -1506,7 +1506,7 @@ function DashboardPreview() {
67%
</XDSText>
</div>
- <XDSProgressBar value={67} />
+ <XDSProgressBar value={67} label="Error Rate" isLabelHidden />
</div>
<div>
<div
@@ -1520,7 +1520,7 @@ function DashboardPreview() {
82%
</XDSText>
</div>
- <XDSProgressBar value={82} />
+ <XDSProgressBar value={82} label="Uptime" isLabelHidden />
</div>
</div>
</XDSCard>
@@ -1597,7 +1597,7 @@ export const ${themeName}Theme = defineTheme({
if (hasCustomTypeScale) {
parts.push(
- ` typeScale: { base: ${typeScaleBase}, ratio: ${typeScaleRatio} },`,
+ ` typography: { scale: { base: ${typeScaleBase}, ratio: ${typeScaleRatio} } },`,
);
}
@@ -1640,7 +1640,7 @@ function ThemeEditorComponent() {
const [showCode, setShowCode] = React.useState(false);
// Collect all defaults
- const allDefaults = React.useMemo(
+ const allDefaults: Record<string, string> = React.useMemo(
() => ({
...colorDefaults,
...spacingDefaults,
@@ -1703,7 +1703,7 @@ function ThemeEditorComponent() {
}
return defineTheme({
name: themeName,
- typeScale: {base: typeScaleBase, ratio: typeScaleRatio},
+ typography: {scale: {base: typeScaleBase, ratio: typeScaleRatio}},
tokens: tokenOverrides as Partial<Record<string, string>>,
icons: defaultIconRegistry,
});
@@ -1729,7 +1729,7 @@ function ThemeEditorComponent() {
label: category,
}))}
value={activeColorCategory}
- onChange={v => setActiveColorCategory(v)}
+ onChange={(v: string) => setActiveColorCategory(v)}
/>
{categoryTokens.map(tokenName => (
@@ -1818,8 +1818,8 @@ function ThemeEditorComponent() {
max={24}
step={1}
value={typeScaleBase}
- onChange={v => applyTypeScale(v, typeScaleRatio)}
- formatValue={v => `${v}px`}
+ onChange={(v: number) => applyTypeScale(v, typeScaleRatio)}
+ formatValue={(v: number) => `${v}px`}
valueDisplay="text"
/>
<XDSSelector
@@ -1837,7 +1837,7 @@ function ThemeEditorComponent() {
},
]}
value={isCustomRatio ? 'custom' : String(typeScaleRatio)}
- onChange={v => {
+ onChange={(v: string) => {
if (v === 'custom') return;
applyTypeScale(typeScaleBase, Number(v));
}}
@@ -1850,8 +1850,8 @@ function ThemeEditorComponent() {
max={1700}
step={1}
value={Math.round(typeScaleRatio * 1000)}
- onChange={v => applyTypeScale(typeScaleBase, v / 1000)}
- formatValue={v => (v / 1000).toFixed(3)}
+ onChange={(v: number) => applyTypeScale(typeScaleBase, v / 1000)}
+ formatValue={(v: number) => (v / 1000).toFixed(3)}
valueDisplay="text"
/>
)}
@@ -2014,7 +2014,7 @@ function ThemeEditorComponent() {
const categoryValue = TYPOGRAPHY_CATEGORIES[
activeTypographyCategory as keyof typeof TYPOGRAPHY_CATEGORIES
- ] as TypographyCategoryValue | undefined;
+ ] as unknown as TypographyCategoryValue | undefined;
// Get the list of tokens for this category
const categoryTokens: string[] = categoryValue
@@ -2069,7 +2069,7 @@ function ThemeEditorComponent() {
},
]}
value={activeTypographyCategory}
- onChange={v => setActiveTypographyCategory(v)}
+ onChange={(v: string) => setActiveTypographyCategory(v)}
/>
{/* Description for semantic styles */}
@@ -2343,29 +2343,6 @@ function ThemeEditorComponent() {
);
}
-// =============================================================================
-// Storybook Meta
-// =============================================================================
-
-const meta: Meta = {
- title: 'Theme Editor',
- parameters: {
- layout: 'fullscreen',
- docs: {
- page: null,
- },
- },
-};
-
-export default meta;
-
-type Story = StoryObj;
-
-export const ThemeEditor: Story = {
- render: () => <ThemeEditorComponent />,
- parameters: {
- // Use default theme for the editor chrome (left panel).
- // The preview panel wraps its own <XDSTheme theme={currentTheme}>.
- xdsTheme: 'default',
- },
-};
+export default function ThemeEditorPage() {
+ return <ThemeEditorComponent />;
+}
diff --git a/apps/sandbox/src/app/SandboxNav.tsx b/apps/sandbox/src/app/SandboxNav.tsx
new file mode 100644
index 0000000000..d663bf3344
--- /dev/null
+++ b/apps/sandbox/src/app/SandboxNav.tsx
@@ -0,0 +1,82 @@
+'use client';
+
+import {usePathname} from 'next/navigation';
+import Link from 'next/link';
+import {
+ XDSSideNav,
+ XDSSideNavHeading,
+ XDSSideNavItem,
+ XDSSideNavSection,
+} from '@xds/core/SideNav';
+import {XDSSelector} from '@xds/core/Selector';
+import {useThemeControls} from './providers';
+import type {ThemeMode} from '@xds/core/theme';
+
+const pages = [
+ {name: 'Home', href: '/'},
+ {name: 'Theme Editor', href: '/pages/theme-editor/'},
+ {name: 'Shell Lab', href: '/pages/shell-lab/'},
+ {name: 'Example', href: '/pages/example/'},
+ {name: 'Navigation', href: '/pages/navigation/'},
+ {name: 'TopNav Menu', href: '/pages/topnav-menu/'},
+ {name: 'Mega Menu', href: '/pages/mega-menu/'},
+ {name: 'Polymorphic Link', href: '/pages/polymorphic-link/'},
+ {name: 'Table Overview', href: '/pages/table-overview/'},
+];
+
+export function SandboxNav() {
+ const pathname = usePathname();
+ const {themeName, setThemeName, mode, setMode} = useThemeControls();
+
+ return (
+ <XDSSideNav header={<XDSSideNavHeading heading="Sandbox" />}>
+ <XDSSideNavSection title="Pages" isHeaderHidden>
+ {pages.map(page => {
+ const isActive =
+ pathname === page.href ||
+ (page.href !== '/' && pathname.startsWith(page.href));
+ return (
+ <XDSSideNavItem
+ key={page.href}
+ label={page.name}
+ href={page.href}
+ isSelected={isActive}
+ as={Link}
+ />
+ );
+ })}
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Theme">
+ <div style={{padding: '0 12px'}}>
+ <XDSSelector
+ label="Theme"
+ isLabelHidden
+ size="sm"
+ value={themeName}
+ onChange={setThemeName}
+ options={[
+ {value: 'default', label: 'Default'},
+ {value: 'neutral', label: 'Neutral'},
+ {value: 'brutalist', label: 'Brutalist'},
+ ]}
+ />
+ </div>
+ </XDSSideNavSection>
+ <XDSSideNavSection title="Mode">
+ <div style={{padding: '0 12px'}}>
+ <XDSSelector
+ label="Mode"
+ isLabelHidden
+ size="sm"
+ value={mode}
+ onChange={v => setMode(v as ThemeMode)}
+ options={[
+ {value: 'light', label: 'Light'},
+ {value: 'dark', label: 'Dark'},
+ ]}
+ />
+ </div>
+ </XDSSideNavSection>
+ </XDSSideNav>
+ );
+}
diff --git a/apps/sandbox/src/app/SandboxTopNav.tsx b/apps/sandbox/src/app/SandboxTopNav.tsx
new file mode 100644
index 0000000000..cee3cf8491
--- /dev/null
+++ b/apps/sandbox/src/app/SandboxTopNav.tsx
@@ -0,0 +1,12 @@
+'use client';
+
+import {XDSTopNav, XDSTopNavHeading} from '@xds/core/TopNav';
+
+export function SandboxTopNav() {
+ return (
+ <XDSTopNav
+ label="Main navigation"
+ heading={<XDSTopNavHeading heading="XDS Sandbox" />}
+ />
+ );
+}
diff --git a/apps/sandbox/src/app/Sidebar.tsx b/apps/sandbox/src/app/Sidebar.tsx
deleted file mode 100644
index 58856e2488..0000000000
--- a/apps/sandbox/src/app/Sidebar.tsx
+++ /dev/null
@@ -1,68 +0,0 @@
-'use client';
-
-import Link from 'next/link';
-import {usePathname} from 'next/navigation';
-
-const pages = [
- {name: 'Home', href: '/'},
- {name: '🔬 Shell Lab', href: '/pages/shell-lab/'},
- {name: 'Example', href: '/pages/example/'},
- {name: 'Navigation', href: '/pages/navigation/'},
- {name: 'TopNav Menu', href: '/pages/topnav-menu/'},
- {name: 'Mega Menu', href: '/pages/mega-menu/'},
- {name: 'Polymorphic Link', href: '/pages/polymorphic-link/'},
- {name: 'Table Overview', href: '/pages/table-overview/'},
-];
-
-export function Sidebar() {
- const pathname = usePathname();
-
- return (
- <nav
- style={{
- width: 220,
- borderRight: '1px solid var(--color-border, #e0e0e0)',
- padding: '1.5rem 1rem',
- display: 'flex',
- flexDirection: 'column',
- gap: '0.25rem',
- }}>
- <div
- style={{
- fontSize: '0.75rem',
- fontWeight: 700,
- textTransform: 'uppercase',
- letterSpacing: '0.05em',
- color: 'var(--color-text-secondary, #666)',
- marginBottom: '0.75rem',
- padding: '0 0.5rem',
- }}>
- Sandbox
- </div>
- {pages.map(page => {
- const isActive =
- pathname === page.href ||
- (page.href !== '/' && pathname.startsWith(page.href));
- return (
- <Link
- key={page.href}
- href={page.href}
- style={{
- display: 'block',
- padding: '0.5rem 0.75rem',
- borderRadius: 6,
- textDecoration: 'none',
- fontSize: '0.875rem',
- color: 'var(--color-text-primary, #333)',
- backgroundColor: isActive
- ? 'var(--color-overlay-hover, #f0f0f0)'
- : 'transparent',
- fontWeight: isActive ? 600 : 400,
- }}>
- {page.name}
- </Link>
- );
- })}
- </nav>
- );
-}
diff --git a/apps/sandbox/src/app/layout.tsx b/apps/sandbox/src/app/layout.tsx
index f324d4fde1..509a9549be 100644
--- a/apps/sandbox/src/app/layout.tsx
+++ b/apps/sandbox/src/app/layout.tsx
@@ -1,7 +1,26 @@
import type {Metadata} from 'next';
+
+/**
+ * XDS CSS Layer Model (dist path)
+ *
+ * Import order establishes CSS layer priority (lowest → highest):
+ * 1. @xds/core/reset.css → @layer xds-reset (reset styles)
+ * 2. @xds/core/xds.css → @layer xds-base (component base styles)
+ * 3. @xds/theme-default/theme.css → @layer xds-theme (default theme)
+ * 4. @xds/theme-neutral/theme.css → @layer xds-theme (neutral theme)
+ * 5. @xds/theme-brutalist/theme.css → @layer xds-theme (brutalist theme)
+ *
+ * All theme CSS files are in @layer xds-theme and scoped via
+ * @scope ([data-xds-theme="name"]), so only the active theme's rules apply.
+ *
+ * Product/consumer styles sit unlayered (outside layers) and naturally
+ * win over all XDS layers without needing !important.
+ */
import '@xds/core/reset.css';
import '@xds/core/xds.css';
import '@xds/theme-default/theme.css';
+import '@xds/theme-neutral/theme.css';
+import '@xds/theme-brutalist/theme.css';
import {Providers} from './providers';
export const metadata: Metadata = {
diff --git a/apps/sandbox/src/app/providers.tsx b/apps/sandbox/src/app/providers.tsx
index 41e4dfd709..d2d22a1e2a 100644
--- a/apps/sandbox/src/app/providers.tsx
+++ b/apps/sandbox/src/app/providers.tsx
@@ -1,8 +1,50 @@
'use client';
+import {useState, createContext, useContext, useEffect} from 'react';
import {XDSTheme} from '@xds/core/theme';
import {defaultTheme} from '@xds/theme-default';
+import {neutralTheme} from '@xds/theme-neutral';
+import {brutalistTheme} from '@xds/theme-brutalist';
+import type {XDSDefinedTheme, ThemeMode} from '@xds/core/theme';
+
+const themes: Record<string, XDSDefinedTheme> = {
+ default: defaultTheme,
+ neutral: neutralTheme,
+ brutalist: brutalistTheme,
+};
+
+type ThemeContextValue = {
+ themeName: string;
+ setThemeName: (name: string) => void;
+ mode: ThemeMode;
+ setMode: (mode: ThemeMode) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue>({
+ themeName: 'default',
+ setThemeName: () => {},
+ mode: 'light',
+ setMode: () => {},
+});
+
+export const useThemeControls = () => useContext(ThemeContext);
export function Providers({children}: {children: React.ReactNode}) {
- return <XDSTheme theme={defaultTheme}>{children}</XDSTheme>;
+ const [themeName, setThemeName] = useState('default');
+ const [mode, setMode] = useState<ThemeMode>('light');
+
+ // Sync color-scheme to document root
+ useEffect(() => {
+ document.documentElement.style.setProperty('color-scheme', mode);
+ }, [mode]);
+
+ const theme = themes[themeName] || defaultTheme;
+
+ return (
+ <ThemeContext.Provider value={{themeName, setThemeName, mode, setMode}}>
+ <XDSTheme theme={theme} mode={mode}>
+ {children}
+ </XDSTheme>
+ </ThemeContext.Provider>
+ );
}
diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjs
index 27c9789512..6cd3c3e5a0 100644
--- a/packages/cli/src/commands/build-theme.mjs
+++ b/packages/cli/src/commands/build-theme.mjs
@@ -793,7 +793,7 @@ export function registerTheme(program) {
const colorSchemeDecl = scopeBlock.includes('light-dark(')
? ' :root { color-scheme: light dark; }\n\n'
: '';
- css = `@layer xds.theme {\n${colorSchemeDecl}${scopeBlock}\n}\n`;
+ css = `@layer xds-theme {\n${colorSchemeDecl}${scopeBlock}\n}\n`;
} else {
// Legacy fallback when core isn't built yet
const scopeBlocks = [];
@@ -809,7 +809,7 @@ export function registerTheme(program) {
const colorSchemeDecl = joined.includes('light-dark(')
? ' :root { color-scheme: light dark; }\n\n'
: '';
- css = `@layer xds.theme {\n${colorSchemeDecl}${joined}\n}\n`;
+ css = `@layer xds-theme {\n${colorSchemeDecl}${joined}\n}\n`;
}
// Determine output path
diff --git a/packages/core/src/reset.css b/packages/core/src/reset.css
index 582cb1368f..ef3d8c586e 100644
--- a/packages/core/src/reset.css
+++ b/packages/core/src/reset.css
@@ -19,11 +19,11 @@
* import '@xds/core/reset.css';
*
* 2. Combine with theme and typography:
- * import '@xds/core/reset.css'; // @layer reset — clean slate
- * import '@xds/core/xds.css'; // @layer xds.core.base — component styles
- * import '@xds/theme-default/theme.css'; // @layer xds.theme — theme overrides
+ * import '@xds/core/reset.css'; // @layer xds-reset — clean slate
+ * import '@xds/core/xds.css'; // @layer xds-base — component styles
+ * import '@xds/theme-default/theme.css'; // @layer xds-theme — theme overrides
*
- * Layer order: reset → typography → xds → xds.theme
+ * Layer order: xds-reset → xds-base → xds-theme
* Consumer styles (unlayered) always override all XDS layers.
* The reset has the lowest priority and can be overridden by any other layer.
*
@@ -34,7 +34,7 @@
* - modern-normalize
*/
-@layer reset {
+@layer xds-reset {
/* ===========================================================================
Box Model
diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsx
index 99921da066..4e748693b5 100644
--- a/packages/core/src/theme/XDSTheme.tsx
+++ b/packages/core/src/theme/XDSTheme.tsx
@@ -88,7 +88,7 @@ function useThemeStyleInjection(theme: XDSDefinedTheme): void {
const style = document.createElement('style');
style.setAttribute('data-xds-theme', theme.name);
style.setAttribute('data-xds-id', id);
- style.textContent = `@layer xds.theme {\n${css}\n}`;
+ style.textContent = `@layer xds-theme {\n${css}\n}`;
document.head.appendChild(style);
injectedThemes.add(themeKey);
diff --git a/packages/themes/brutalist/src/index.ts b/packages/themes/brutalist/src/index.ts
index 6ed78ed7a6..03eb3a6022 100644
--- a/packages/themes/brutalist/src/index.ts
+++ b/packages/themes/brutalist/src/index.ts
@@ -54,9 +54,14 @@ export const brutalistTheme = defineTheme({
borderColor: 'var(--color-text-primary)',
},
},
- // Buttons are loud
+ // Buttons are loud — 9999px radius override tests layer ordering.
+ // Everything else in brutalist is 0px radius, but buttons are
+ // deliberately pill-shaped. If this override works without !important,
+ // CSS layers are doing their job.
+ // (same pattern that needed !important in Meta theme #692)
button: {
base: {
+ borderRadius: '9999px',
textTransform: 'uppercase',
letterSpacing: '0.1em',
fontWeight: '800',
diff --git a/scripts/build-css.mjs b/scripts/build-css.mjs
index 0cd92ff82f..aaa757cbb3 100644
--- a/scripts/build-css.mjs
+++ b/scripts/build-css.mjs
@@ -2,7 +2,7 @@
* @file build-css.mjs
* Post-build script that extracts StyleX CSS from compiled source files
* and outputs per-component CSS files, a shared common.css, and a combined xds.css,
- * all wrapped in @layer xds.
+ * all wrapped in @layer xds-base.
*
* Usage: node scripts/build-css.mjs
*
@@ -12,7 +12,7 @@
* 3. Identifies shared rules (used by 2+ components) → common.css
* 4. Outputs per-component CSS files with only unique rules
* 5. Outputs a combined xds.css with all rules
- * 6. All CSS is wrapped in @layer xds { ... }
+ * 6. All CSS is wrapped in @layer xds-base { ... }
*
* Per-component CSS enables tree-shaking for dist consumers:
* import { Button } from '@xds/core/Button';
@@ -145,7 +145,7 @@ function wrapInLayer(css, comment) {
return `/* ${comment} */
/* Auto-generated. Do not edit manually. */
-@layer xds {
+@layer xds-base {
${css
.split('\n')
.map(line => ' ' + line)