An open source design system that's fully customizable and agent ready
TypeScript
refactor(theme): private var naming, registry-driven container expansion, build validation (#1493)
Cindy Zhang67c24eee6d40
diff --git a/packages/cli/docs/theme.doc.dense.mjs b/packages/cli/docs/theme.doc.dense.mjsindex 84744d4b3d..52a1ecc027 100644--- a/packages/cli/docs/theme.doc.dense.mjs+++ b/packages/cli/docs/theme.doc.dense.mjs@@ -7,7 +7,9 @@ export const docsDense = {{ title: 'Themes', content: [null, { type: 'prose', text: '@xds/theme-{name} = source (runtime). @xds/theme-{name}/built = optimized (+ theme.css).' }] },{ title: 'Props', content: [null] },{ title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },- { title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (typography, radius, motion) + explicit token overrides + component overrides.' }, null, null] },+ { title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },+ { title: 'Component Overrides', content: [{ type: 'prose', text: 'components field targets .xds-* classes. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `npx xds component <Name>` for details.' }, null, null, null, null] },+ { title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. xds theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },{ title: 'Build for Production', content: [{ type: 'prose', text: 'npx xds theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },{ title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },{ title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },diff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjsindex 4675072a9c..5c2fef3977 100644--- a/packages/cli/docs/theme.doc.mjs+++ b/packages/cli/docs/theme.doc.mjs@@ -43,7 +43,7 @@ function App() {},{type: 'prose',- text: 'The default import uses runtime style injection \u2014 works everywhere, no build step. The `/built` import skips injection and relies on the pre-compiled CSS file for better performance and SSR support.',+ text: 'The default import uses runtime style injection — works everywhere, no build step. The `/built` import skips injection and relies on the pre-compiled CSS file for better performance and SSR support.',},],},@@ -73,7 +73,7 @@ function App() {},{type: 'prose',- text: 'All theme packages export from two subpaths:\n- `@xds/theme-{name}` \u2014 source theme (runtime injection)\n- `@xds/theme-{name}/built` \u2014 pre-built theme (pair with `theme.css`)',+ text: 'All theme packages export from two subpaths:\n- `@xds/theme-{name}` — source theme (runtime injection)\n- `@xds/theme-{name}/built` — pre-built theme (pair with `theme.css`)',},],},@@ -84,14 +84,14 @@ function App() {type: 'table',headers: ['Prop', 'Type', 'Default', 'Description'],rows: [- ['theme', 'XDSDefinedTheme', '\u2014', 'Theme object (required)'],+ ['theme', 'XDSDefinedTheme', '—', 'Theme object (required)'],['mode',"'system' | 'light' | 'dark'","'system'",'Color mode. system follows OS preference.',],- ['children', 'ReactNode', '\u2014', 'App content'],+ ['children', 'ReactNode', '—', 'App content'],],},],@@ -101,7 +101,7 @@ function App() {content: [{type: 'prose',- text: 'Use the CLI wizard (recommended) or create manually with defineTheme. Only override tokens that differ from defaults \u2014 omitted tokens use the XDS defaults.',+ text: 'Use the CLI wizard (recommended) or create manually with defineTheme. Only override tokens that differ from defaults — omitted tokens use the XDS defaults.',},{type: 'code',@@ -126,6 +126,7 @@ function App() {const myTheme = defineTheme({name: 'my-theme',+ color: { accent: '#7B61FF', neutralStyle: 'cool' },typography: {scale: { base: 14, ratio: 1.2 },body: { family: 'Inter', fallbacks: '-apple-system, sans-serif' },@@ -133,7 +134,8 @@ const myTheme = defineTheme({radius: { base: 4, multiplier: 1 },motion: { fast: 175, medium: 410, ratio: 0.75 },tokens: {- '--color-accent': ['#7B61FF', '#9B85FF'], // [light, dark]+ // Explicit overrides take precedence over scale-generated values+ '--color-accent': ['#7B61FF', '#9B85FF'],},components: {button: { 'variant:primary': { color: 'white' } },@@ -144,6 +146,11 @@ const myTheme = defineTheme({type: 'table',headers: ['Config', 'Generates', 'Parameters'],rows: [+ [+ 'color',+ '--color-accent, --color-background-*, --color-text-*, --color-border, etc.',+ 'accent (hex), neutralStyle? (warm|cool|neutral), contrast? (standard|high)',+ ],['typography.scale','--text-heading-*-size/weight/leading, --text-body-size/weight/leading',@@ -157,7 +164,7 @@ const myTheme = defineTheme({['radius','--radius-1 through --radius-4, --radius-container, --radius-page',- 'base (px), multiplier (0\u20132)',+ 'base (px), multiplier (0–2)',],['motion',@@ -168,6 +175,104 @@ const myTheme = defineTheme({},],},+ {+ title: 'Component Style Overrides',+ content: [+ {+ type: 'prose',+ text: 'The `components` field in defineTheme targets stable `.xds-*` CSS class names. Use `base` for all instances, `variant:value` or `stateName` for specific states.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Component overrides with standard CSS',+ code: `components: {+ // Standard CSS properties are expanded automatically.+ // borderRadius also sets the internal radius var for concentric math.+ // padding on container components (card, section, dialog) expands to layout tokens.+ card: {+ base: { borderRadius: '20px', padding: '24px' },+ },+ button: {+ base: { borderRadius: '9999px', textTransform: 'uppercase' },+ 'variant:ghost': { borderWidth: '2px', borderStyle: 'solid' },+ },+ // Some components have public CSS vars for properties that don't map+ // to standard CSS. Set these directly.+ button: {+ base: { '--button-press-scale': 'scale(0.95)' },+ },+}`,+ },+ {+ type: 'prose',+ text: 'Run `npx xds component <Name>` to see a component’s theming targets, public CSS variables, and which standard CSS properties are supported.',+ },+ {+ type: 'list',+ style: 'do',+ items: [+ 'Write standard CSS properties (borderRadius, padding) — the pipeline expands them into internal vars.',+ 'Set public CSS vars directly when no standard property equivalent exists.',+ ],+ },+ {+ type: 'list',+ style: 'dont',+ items: [+ 'Set private CSS vars (prefixed --_) directly — use standard CSS properties instead. `xds theme build` will error.',+ ],+ },+ ],+ },+ {+ title: 'Custom Variants',+ content: [+ {+ type: 'prose',+ text: 'Themes can add new prop values to any component. Any `prop:value` key where the value isn’t a built-in gets treated as a new variant. Use `xds theme build` to generate TypeScript augmentations for type safety.',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Adding custom variants',+ code: `components: {+ button: {+ // Override an existing variant+ 'variant:secondary': { backgroundColor: 'rgba(0,0,0,0.06)' },+ // Add a new variant — generates type augmentation on build+ 'variant:primary-muted': {+ backgroundColor: 'light-dark(#F2F4F6, #28292C)',+ color: 'var(--color-text-primary)',+ },+ },+ banner: {+ // Any extensible prop axis works — not just variant+ 'status:neutral': {+ backgroundColor: 'var(--color-muted)',+ color: 'var(--color-text-secondary)',+ },+ },+}`,+ },+ {+ type: 'prose',+ text: 'After building, the new values are type-safe in JSX:',+ },+ {+ type: 'code',+ lang: 'tsx',+ label: 'Using custom variants',+ code: `// TypeScript knows about 'primary-muted' after xds theme build+<XDSButton variant="primary-muted" label="Save draft" />+<XDSBanner status="neutral" title="Note" />`,+ },+ {+ type: 'prose',+ text: 'Custom variants only work when the theme that defines them is active. The component’s variant map is extended via module augmentation — no changes to the component source needed.',+ },+ ],+ },{title: 'Building Themes for Production',content: [@@ -203,13 +308,13 @@ const myTheme = defineTheme({],['ocean.variants.d.ts',- '(Optional) Module augmentations for custom component prop values found in the theme\u2019s component overrides',+ '(Optional) Module augmentations for custom component prop values found in the theme’s component overrides',],],},{type: 'prose',- text: 'The `__built: true` flag tells XDSTheme to skip runtime `<style>` injection \u2014 the CSS file handles it.',+ text: 'The `__built: true` flag tells XDSTheme to skip runtime `<style>` injection — the CSS file handles it.',},{type: 'code',@@ -253,12 +358,12 @@ import './themes/ocean.css';['Component overrides','Injected client-only',- 'In static CSS \u2014 present during SSR',+ 'In static CSS — present during SSR',],['SSR safe','Tokens yes, component overrides flash on hydration',- 'Fully SSR safe \u2014 no flash',+ 'Fully SSR safe — no flash',],['Best for',@@ -280,8 +385,8 @@ import './themes/ocean.css';type: 'list',style: 'dont',items: [- 'Use runtime themes in production SSR apps \u2014 component overrides will flash on hydration.',- 'Import /built without the CSS file \u2014 component overrides won\u2019t apply.',+ 'Use runtime themes in production SSR apps — component overrides will flash on hydration.',+ 'Import /built without the CSS file — component overrides won’t apply.',],},],@@ -350,8 +455,8 @@ import './themes/ocean.css';function MyComponent() {const ctx = useXDSTheme();- // ctx.theme \u2014 the XDSDefinedTheme object- // ctx.mode \u2014 'system' | 'light' | 'dark'+ // ctx.theme — the XDSDefinedTheme object+ // ctx.mode — 'system' | 'light' | 'dark'return null;}`,},diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjsindex c9366733a9..08e75f59d1 100644--- a/packages/cli/src/commands/build-theme.mjs+++ b/packages/cli/src/commands/build-theme.mjs@@ -917,6 +917,35 @@ function validateComponentOverrides(themeDef) {return warnings;}+/**+ * Validate that themes don't set private (--_*) CSS custom properties directly.+ * Private vars are internal implementation details managed by the derived var+ * expansion pipeline. Theme authors should write standard CSS properties+ * (e.g. borderRadius, padding) instead.+ *+ * Returns array of error strings.+ */+function validatePrivateVars(themeDef) {+ const errors = [];+ if (!themeDef.components) return errors;++ for (const [component, rules] of Object.entries(themeDef.components)) {+ for (const [key, styles] of Object.entries(rules)) {+ for (const [prop, value] of Object.entries(styles)) {+ if (typeof prop === 'string' && prop.startsWith('--_')) {+ errors.push(+ `Component "${component}" (${key}) sets private var "${prop}". ` ++ `Private vars (--_*) are internal — use standard CSS properties ` ++ `(e.g. borderRadius, padding) instead. The pipeline expands them automatically.`,+ );+ }+ }+ }+ }++ return errors;+}+export function registerTheme(program) {const theme = program.command('theme')@@ -963,6 +992,16 @@ export function registerTheme(program) {if (!json) console.warn(` ⚠ ${w}`);}+ // Validate no private vars are set directly+ const privateVarErrors = validatePrivateVars(themeDef);+ for (const e of privateVarErrors) {+ warningMessages.push(e);+ if (!json) console.error(` ✗ ${e}`);+ }+ if (privateVarErrors.length > 0 && !json) {+ console.error(`\n ${privateVarErrors.length} private var error(s). Use standard CSS properties instead.`);+ }+// Generate CSS using the shared generateThemeRules from core.// This ensures build and runtime produce identical rule sets.let css;diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjsindex 0f93f5c415..4c50adebe3 100644--- a/packages/cli/src/lib/component-format.mjs+++ b/packages/cli/src/lib/component-format.mjs@@ -212,37 +212,29 @@ export function formatFull(docs, options = {}) {sections.push(`Component key: \`${docs.theming.componentKey}\`\n`);}- // Component CSS vars — additional themeable properties+ // Component CSS vars — split into public (directly settable) and private (set via derived)if (docs.theming?.vars?.length) {- sections.push('**Themeable CSS variables** — additional properties that can be overridden in `defineTheme` component overrides.\n');-- // Build a set of vars that are derived from standard CSS properties- const derivedVarNames = new Set();- if (docs.theming?.derived?.length) {- for (const d of docs.theming.derived) {- if (d.vars) d.vars.forEach(v => derivedVarNames.add(v));+ // Private vars (--_*) are internal — set via standard CSS properties through derived expansion+ const publicVars = docs.theming.vars.filter(v => !v.private && !v.derived);+ const privateVars = docs.theming.vars.filter(v => v.private || v.derived);++ if (publicVars.length > 0) {+ sections.push('**Themeable CSS variables** — additional properties that can be overridden in `defineTheme` component overrides.\n');+ const varLines = [];+ varLines.push('| CSS Variable | Default | Description |');+ varLines.push('|-------------|---------|-------------|');+ for (const v of publicVars) {+ varLines.push(`| \`${v.name}\` | \`${v.default}\` | ${v.description} |`);}+ sections.push(varLines.join('\n') + '\n');}- const varLines = [];- varLines.push('| CSS Variable | Default | Description |');- varLines.push('|-------------|---------|-------------|');- for (const v of docs.theming.vars) {- if (v.derived) {- varLines.push(`| \`${v.name}\` | _(derived)_ | ${v.description} |`);- } else {- const derivedNote = derivedVarNames.has(v.name) ? ' _(set via standard CSS property)_' : '';- varLines.push(`| \`${v.name}\` | \`${v.default}\` | ${v.description}${derivedNote} |`);- }- }- sections.push(varLines.join('\n') + '\n');-- // Show derived property examples if available+ // Show derived property examples — the recommended way to themeif (docs.theming?.derived?.length) {const varsKey = docs.theming.targets?.length ? targetKey(docs.theming.targets[0]) : docs.theming.componentKey || '';const derivedExamples = docs.theming.derived.filter(d => d.vars?.length)- .map(d => ` ${d.property}: '...', // also sets ${d.vars.join(', ')}`)+ .map(d => ` ${d.property}: '...',`).join('\n');const expandExamples = docs.theming.derived.filter(d => d.expand === 'container')@@ -250,15 +242,7 @@ export function formatFull(docs, options = {}) {.join('\n');const allExamples = [derivedExamples, expandExamples].filter(Boolean).join('\n');if (allExamples) {- sections.push('Some vars can be set by writing standard CSS properties:\n```ts\ncomponents: {\n ' + varsKey + ': {\n base: {\n' + allExamples + '\n },\n },\n}\n```\n');- }- } else {- // Fallback: show raw var override example- const overridableVars = docs.theming.vars.filter(v => !v.derived);- if (overridableVars.length > 0) {- const exampleVar = overridableVars[0];- const varsKey = docs.theming.targets?.length ? targetKey(docs.theming.targets[0]) : docs.theming.componentKey || '';- sections.push('Override CSS vars in defineTheme:\n```ts\ncomponents: {\n ' + varsKey + ': {\n base: { \'' + exampleVar.name + '\': \'...\' },\n },\n}\n```\n');+ sections.push('Some properties are set via standard CSS in component overrides:\n```ts\ncomponents: {\n ' + varsKey + ': {\n base: {\n' + allExamples + '\n },\n },\n}\n```\n');}}}@@ -412,10 +396,10 @@ export function formatBrief(docs, componentName, importHint, options = {}) {output.push(` ${shortDesc}`);}- // Component vars (if any)+ // Component vars (if any — only show public vars)if (docs.theming?.vars?.length) {const varNames = docs.theming.vars- .filter(v => !v.derived)+ .filter(v => !v.derived && !v.private).map(v => `${v.name} (${v.default})`).join(', ');if (varNames) {diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjsindex 7bb27dfc7f..3d8e7eb9ad 100644--- a/packages/core/src/Banner/Banner.doc.mjs+++ b/packages/core/src/Banner/Banner.doc.mjs@@ -91,10 +91,10 @@ export const docs = {{className: 'xds-banner-icon', visualProps: ['status']},],vars: [- {name: '--banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)'},+ {name: '--_banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)', private: true},],derived: [- {property: 'borderRadius', vars: ['--banner-radius']},+ {property: 'borderRadius', vars: ['--_banner-radius']},],},};@@ -155,10 +155,10 @@ export const docsZh = {},],vars: [- {name: '--banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)'},+ {name: '--_banner-radius', description: 'Border radius (card container only)', default: 'var(--radius-container)', private: true},],derived: [- {property: 'borderRadius', vars: ['--banner-radius']},+ {property: 'borderRadius', vars: ['--_banner-radius']},],},};diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsxindex bb24bb8b86..4464331bee 100644--- a/packages/core/src/Banner/XDSBanner.tsx+++ b/packages/core/src/Banner/XDSBanner.tsx@@ -222,8 +222,8 @@ const styles = stylex.create({overflow: 'clip',},card: {- '--banner-radius': radiusVars['--radius-container'],- borderRadius: 'var(--banner-radius)',+ '--_banner-radius': radiusVars['--radius-container'],+ borderRadius: 'var(--_banner-radius)',},section: {borderRadius: '0',@@ -297,8 +297,8 @@ const styles = stylex.create({borderBottomColor: colorVars['--color-border'],},contentAreaCard: {- borderBottomLeftRadius: 'var(--banner-radius)',- borderBottomRightRadius: 'var(--banner-radius)',+ borderBottomLeftRadius: 'var(--_banner-radius)',+ borderBottomRightRadius: 'var(--_banner-radius)',},chevron: {display: 'inline-flex',diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjsindex fc98f9eb65..0dabd27cec 100644--- a/packages/core/src/Button/Button.doc.mjs+++ b/packages/core/src/Button/Button.doc.mjs@@ -123,14 +123,14 @@ export const docs = {{className: 'xds-button', visualProps: ['size', 'variant']},],vars: [- {name: '--button-radius', description: 'Border radius', default: 'var(--radius-element)'},+ {name: '--_button-radius', description: 'Border radius', default: 'var(--radius-element)', private: true},{name: '--button-press-scale', description: 'Active press transform', default: 'scale(0.98)'},{name: '--button-disabled-opacity', description: 'Opacity when disabled', default: '0.5'},{name: '--button-focus-offset', description: 'Focus ring outline offset', default: '3px'},{name: '--button-icon-only-aspect', description: 'Aspect ratio for icon-only buttons', default: '1 / 1'},],derived: [- {property: 'borderRadius', vars: ['--button-radius']},+ {property: 'borderRadius', vars: ['--_button-radius']},],},};@@ -201,14 +201,14 @@ export const docsZh = {},],vars: [- {name: '--button-radius', description: '圆角半径', default: 'var(--radius-element)'},+ {name: '--_button-radius', description: '圆角半径', default: 'var(--radius-element)', private: true},{name: '--button-press-scale', description: '按下时的变换', default: 'scale(0.98)'},{name: '--button-disabled-opacity', description: '禁用时的不透明度', default: '0.5'},{name: '--button-focus-offset', description: '焦点环轮廓偏移', default: '3px'},{name: '--button-icon-only-aspect', description: '纯图标按钮的宽高比', default: '1 / 1'},],derived: [- {property: 'borderRadius', vars: ['--button-radius']},+ {property: 'borderRadius', vars: ['--_button-radius']},],},};diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsxindex 127eab71b3..5de62e23b4 100644--- a/packages/core/src/Button/XDSButton.tsx+++ b/packages/core/src/Button/XDSButton.tsx@@ -54,7 +54,7 @@ const styles = stylex.create({borderWidth: 0,borderStyle: 'none',- borderRadius: `var(--button-radius, ${radiusVars['--radius-element']})`,+ borderRadius: `var(--_button-radius, ${radiusVars['--radius-element']})`,fontFamily: 'inherit',fontSize: typeScaleVars['--text-label-size'],lineHeight: typeScaleVars['--text-label-leading'],diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsindex e530f535ea..f652f6305c 100644--- a/packages/core/src/Card/Card.doc.mjs+++ b/packages/core/src/Card/Card.doc.mjs@@ -63,10 +63,10 @@ export const docs = {{className: 'xds-card'},],vars: [- {name: '--card-radius', description: 'Border radius of the card', default: 'var(--radius-container)'},+ {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},],derived: [- {property: 'borderRadius', vars: ['--card-radius']},+ {property: 'borderRadius', vars: ['--_card-radius']},{property: 'padding', expand: 'container'},],},@@ -103,10 +103,10 @@ export const docsZh = {{className: 'xds-card'},],vars: [- {name: '--card-radius', description: 'Border radius of the card', default: 'var(--radius-container)'},+ {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},],derived: [- {property: 'borderRadius', vars: ['--card-radius']},+ {property: 'borderRadius', vars: ['--_card-radius']},{property: 'padding', expand: 'container'},],},diff --git a/packages/core/src/Card/XDSCard.tsx b/packages/core/src/Card/XDSCard.tsxindex 767990321d..0bb50d540c 100644--- a/packages/core/src/Card/XDSCard.tsx+++ b/packages/core/src/Card/XDSCard.tsx@@ -61,8 +61,8 @@ export type XDSCardVariant =const styles = stylex.create({card: {- '--card-radius': radiusVars['--radius-container'],- borderRadius: 'var(--card-radius)',+ '--_card-radius': radiusVars['--radius-container'],+ borderRadius: 'var(--_card-radius)',overflow: 'clip',},withBorder: {diff --git a/packages/core/src/Carousel/XDSCarousel.tsx b/packages/core/src/Carousel/XDSCarousel.tsxindex 00b2c39fe3..d1b5760882 100644--- a/packages/core/src/Carousel/XDSCarousel.tsx+++ b/packages/core/src/Carousel/XDSCarousel.tsx@@ -159,7 +159,7 @@ const styles = stylex.create({pointerEvents: 'none' as const,},buttonRadiusOverride: {- '--button-radius': radiusVars['--radius-full'],+ '--_button-radius': radiusVars['--radius-full'],} as Record<string, string>,});diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjsindex 22556036f9..74cbd9b7cc 100644--- a/packages/core/src/Chat/Chat.doc.mjs+++ b/packages/core/src/Chat/Chat.doc.mjs@@ -20,13 +20,13 @@ export const docs = {{className: 'xds-trigger-menu'},],vars: [- {name: '--composer-radius', description: 'Border radius of the composer body. Inner elements derive their radius concentrically.', default: 'var(--radius-page)'},- {name: '--composer-padding', description: 'Padding of the composer body. Used in the concentric radius calculation.', default: 'var(--spacing-3)'},- {name: '--button-radius', description: 'Concentric button radius inside the composer.', default: 'max(var(--radius-element), calc(var(--composer-radius) - var(--composer-padding)))', derived: true, formula: 'max(var(--radius-element), calc(var(--composer-radius) - var(--composer-padding)))'},+ {name: '--_chat-composer-radius', description: 'Border radius of the composer body. Inner elements derive their radius concentrically.', default: 'var(--radius-page)', private: true},+ {name: '--_chat-composer-padding', description: 'Padding of the composer body. Used in the concentric radius calculation.', default: 'var(--spacing-3)', private: true},+ {name: '--_button-radius', description: 'Concentric button radius inside the composer.', default: 'max(var(--radius-element), calc(var(--_chat-composer-radius) - var(--_chat-composer-padding)))', private: true, derived: true, formula: 'max(var(--radius-element), calc(var(--_chat-composer-radius) - var(--_chat-composer-padding)))'},],derived: [- {property: 'borderRadius', vars: ['--composer-radius']},- {property: 'padding', vars: ['--composer-padding']},+ {property: 'borderRadius', vars: ['--_chat-composer-radius']},+ {property: 'padding', vars: ['--_chat-composer-padding']},],},components: [diff --git a/packages/core/src/Chat/XDSChatComposer.tsx b/packages/core/src/Chat/XDSChatComposer.tsxindex 5e77271d29..c04de343f3 100644--- a/packages/core/src/Chat/XDSChatComposer.tsx+++ b/packages/core/src/Chat/XDSChatComposer.tsx@@ -11,9 +11,9 @@* page-radius container, hover/focus shadows, and concentric inner radius.** Component CSS vars (themeable via defineTheme):- * - `--composer-radius` (default: --radius-page) — outer border radius- * - `--composer-padding` (default: --spacing-3) — body padding- * - Inner element radius = calc(--composer-radius - --composer-padding)+ * - `--_chat-composer-radius` (default: --radius-page) — outer border radius+ * - `--_chat-composer-padding` (default: --spacing-3) — body padding+ * - Inner element radius = calc(--_chat-composer-radius - --_chat-composer-padding)** SYNC: When modified, update:* - /packages/core/src/Chat/Chat.doc.mjs@@ -113,13 +113,13 @@ const styles = stylex.create({display: 'flex',flexDirection: 'column',// Component CSS vars — themeable via defineTheme({ components: { 'chat-composer': { base: {...} } } })- '--composer-radius': radiusVars['--radius-page'],- '--composer-padding': spacingVars['--spacing-3'],+ '--_chat-composer-radius': radiusVars['--radius-page'],+ '--_chat-composer-padding': spacingVars['--spacing-3'],// Concentric radius: buttons follow the outer shell's curvature.- // Sets --button-radius (not --radius-element) so only buttons are+ // Sets --_button-radius (not --radius-element) so only buttons are// affected — other components in slots keep their own radius.// Default: 28px - 12px = 16px (fully rounds a 32px button).- '--button-radius': `max(${radiusVars['--radius-element']}, calc(var(--composer-radius) - var(--composer-padding)))`,+ '--_button-radius': `max(${radiusVars['--radius-element']}, calc(var(--_chat-composer-radius) - var(--_chat-composer-padding)))`,},rootDisabled: {@@ -131,9 +131,9 @@ const styles = stylex.create({zIndex: 2,display: 'flex',flexDirection: 'column',- padding: 'var(--composer-padding)',+ padding: 'var(--_chat-composer-padding)',gap: spacingVars['--spacing-2'],- borderRadius: 'var(--composer-radius)',+ borderRadius: 'var(--_chat-composer-radius)',backgroundColor: colorVars['--color-background-popover'],cursor: 'text',boxShadow: {@@ -216,18 +216,18 @@ const styles = stylex.create({fontFamily: typographyVars['--font-family-body'],},statusTop: {- paddingBlockStart: 'var(--composer-padding)',- paddingBlockEnd: 'calc(var(--composer-padding) + var(--composer-radius))',- marginBlockEnd: 'calc(-1 * var(--composer-radius))',- borderTopLeftRadius: 'var(--composer-radius)',- borderTopRightRadius: 'var(--composer-radius)',+ paddingBlockStart: 'var(--_chat-composer-padding)',+ paddingBlockEnd: 'calc(var(--_chat-composer-padding) + var(--_chat-composer-radius))',+ marginBlockEnd: 'calc(-1 * var(--_chat-composer-radius))',+ borderTopLeftRadius: 'var(--_chat-composer-radius)',+ borderTopRightRadius: 'var(--_chat-composer-radius)',},statusBottom: {- paddingBlockStart: 'calc(var(--composer-padding) + var(--composer-radius))',- paddingBlockEnd: 'var(--composer-padding)',- marginBlockStart: 'calc(-1 * var(--composer-radius))',- borderBottomLeftRadius: 'var(--composer-radius)',- borderBottomRightRadius: 'var(--composer-radius)',+ paddingBlockStart: 'calc(var(--_chat-composer-padding) + var(--_chat-composer-radius))',+ paddingBlockEnd: 'var(--_chat-composer-padding)',+ marginBlockStart: 'calc(-1 * var(--_chat-composer-radius))',+ borderBottomLeftRadius: 'var(--_chat-composer-radius)',+ borderBottomRightRadius: 'var(--_chat-composer-radius)',},statusError: {backgroundColor: colorVars['--color-error-muted'],diff --git a/packages/core/src/Chat/XDSChatSendButton.tsx b/packages/core/src/Chat/XDSChatSendButton.tsxindex 028e4e91f5..247b4f14da 100644--- a/packages/core/src/Chat/XDSChatSendButton.tsx+++ b/packages/core/src/Chat/XDSChatSendButton.tsx@@ -52,7 +52,7 @@ export interface XDSChatSendButtonProps {const styles = stylex.create({root: {- borderRadius: 'var(--button-radius, var(--radius-full))',+ borderRadius: 'var(--_button-radius, var(--radius-full))',flexShrink: 0,},});diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex fb98fa92e8..f7bc6c763f 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -9,10 +9,10 @@ export const docs = {{className: 'xds-dialog', visualProps: ['variant']},],vars: [- {name: '--dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)'},+ {name: '--_dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)', private: true},],derived: [- {property: 'borderRadius', vars: ['--dialog-radius']},+ {property: 'borderRadius', vars: ['--_dialog-radius']},{property: 'padding', expand: 'container'},],},@@ -141,10 +141,10 @@ export const docsZh = {{className: 'xds-dialog', visualProps: ['variant']},],vars: [- {name: '--dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)'},+ {name: '--_dialog-radius', description: 'Border radius of the dialog', default: 'var(--radius-container)', private: true},],derived: [- {property: 'borderRadius', vars: ['--dialog-radius']},+ {property: 'borderRadius', vars: ['--_dialog-radius']},{property: 'padding', expand: 'container'},],},diff --git a/packages/core/src/Dialog/XDSDialog.tsx b/packages/core/src/Dialog/XDSDialog.tsxindex 3c15feaa54..5b614ea932 100644--- a/packages/core/src/Dialog/XDSDialog.tsx+++ b/packages/core/src/Dialog/XDSDialog.tsx@@ -120,8 +120,8 @@ const styles = stylex.create({padding: 0,border: 'none',backgroundColor: colorVars['--color-background-surface'],- '--dialog-radius': radiusVars['--radius-container'],- borderRadius: 'var(--dialog-radius)',+ '--_dialog-radius': radiusVars['--radius-container'],+ borderRadius: 'var(--_dialog-radius)',boxShadow: shadowVars['--shadow-high'],display: {default: 'none',diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjsindex 5360e06aef..9dac00e435 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs@@ -9,12 +9,12 @@ export const docs = {{className: 'xds-dropdown-menu-item'},],vars: [- {name: '--dropdown-radius', description: 'Border radius of the menu popup', default: 'var(--radius-element)'},- {name: '--dropdown-padding', description: 'Inner padding of the menu popup', default: 'var(--spacing-1)'},+ {name: '--_dropdown-menu-radius', description: 'Border radius of the menu popup', default: 'var(--radius-element)', private: true},+ {name: '--_dropdown-menu-padding', description: 'Inner padding of the menu popup', default: 'var(--spacing-1)', private: true},],derived: [- {property: 'borderRadius', vars: ['--dropdown-radius']},- {property: 'padding', vars: ['--dropdown-padding']},+ {property: 'borderRadius', vars: ['--_dropdown-menu-radius']},+ {property: 'padding', vars: ['--_dropdown-menu-padding']},],},components: [@@ -194,12 +194,12 @@ export const docsZh = {{className: 'xds-dropdown-menu-item'},],vars: [- {name: '--dropdown-radius', description: 'Border radius of the menu popup', default: 'var(--radius-element)'},- {name: '--dropdown-padding', description: 'Inner padding of the menu popup', default: 'var(--spacing-1)'},+ {name: '--_dropdown-menu-radius', description: 'Border radius of the menu popup', default: 'var(--radius-element)', private: true},+ {name: '--_dropdown-menu-padding', description: 'Inner padding of the menu popup', default: 'var(--spacing-1)', private: true},],derived: [- {property: 'borderRadius', vars: ['--dropdown-radius']},- {property: 'padding', vars: ['--dropdown-padding']},+ {property: 'borderRadius', vars: ['--_dropdown-menu-radius']},+ {property: 'padding', vars: ['--_dropdown-menu-padding']},],},components: [diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsxindex 905ff46ad0..9de58dd919 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx@@ -57,10 +57,10 @@ const styles = stylex.create({gap: spacingVars['--spacing-0-5'],maxHeight: '300px',overflowY: 'auto',- '--dropdown-radius': radiusVars['--radius-container'],- '--dropdown-padding': spacingVars['--spacing-1'],+ '--_dropdown-menu-radius': radiusVars['--radius-container'],+ '--_dropdown-menu-padding': spacingVars['--spacing-1'],padding: spacingVars['--spacing-1'],- borderRadius: 'var(--dropdown-radius)',+ borderRadius: 'var(--_dropdown-menu-radius)',opacity: 1,transitionProperty: 'opacity',transitionDuration: durationVars['--duration-fast'],diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsxindex c50759e787..bc1ec6597e 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx@@ -38,7 +38,7 @@ const styles = stylex.create({gap: spacingVars['--spacing-2'],width: '100%',padding: spacingVars['--spacing-2'],- borderRadius: `max(0px, calc(var(--dropdown-radius, ${spacingVars['--spacing-2']}) - var(--dropdown-padding, ${spacingVars['--spacing-1']})))`,+ borderRadius: `max(0px, calc(var(--_dropdown-menu-radius, ${spacingVars['--spacing-2']}) - var(--_dropdown-menu-padding, ${spacingVars['--spacing-1']})))`,fontFamily: typographyVars['--font-family-body'],fontSize: typeScaleVars['--text-label-size'],color: colorVars['--color-text-primary'],diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjsindex 816e2dce8b..aa29305ec8 100644--- a/packages/core/src/Field/Field.doc.mjs+++ b/packages/core/src/Field/Field.doc.mjs@@ -10,10 +10,10 @@ export const docs = {{className: 'xds-field-status', visualProps: ['type', 'variant']},],vars: [- {name: '--input-radius', description: 'Border radius of input fields', default: 'var(--radius-element)'},+ {name: '--_field-radius', description: 'Border radius of input fields', default: 'var(--radius-element)', private: true},],derived: [- {property: 'borderRadius', vars: ['--input-radius']},+ {property: 'borderRadius', vars: ['--_field-radius']},],},components: [@@ -236,10 +236,10 @@ export const docsZh = {{className: 'xds-field-status', visualProps: ['type', 'variant']},],vars: [- {name: '--input-radius', description: 'Border radius of input fields', default: 'var(--radius-element)'},+ {name: '--_field-radius', description: 'Border radius of input fields', default: 'var(--radius-element)', private: true},],derived: [- {property: 'borderRadius', vars: ['--input-radius']},+ {property: 'borderRadius', vars: ['--_field-radius']},],},components: [diff --git a/packages/core/src/Field/inputStyles.stylex.ts b/packages/core/src/Field/inputStyles.stylex.tsindex 5909816e1c..e26d929167 100644--- a/packages/core/src/Field/inputStyles.stylex.ts+++ b/packages/core/src/Field/inputStyles.stylex.ts@@ -45,8 +45,8 @@ export const inputWrapperStyles = stylex.create({'@media (hover: hover)': colorVars['--color-border-emphasized'],},},- '--input-radius': radiusVars['--radius-element'],- borderRadius: 'var(--input-radius)',+ '--_field-radius': radiusVars['--radius-element'],+ borderRadius: 'var(--_field-radius)',backgroundColor: colorVars['--color-background-surface'],transitionProperty: 'border-color, outline, box-shadow',transitionDuration: {diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjsindex a547521c70..50cd9cf3b4 100644--- a/packages/core/src/HoverCard/HoverCard.doc.mjs+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs@@ -8,10 +8,10 @@ export const docs = {{className: 'xds-hovercard'},],vars: [- {name: '--hovercard-radius', description: 'Border radius of the hover card', default: 'var(--radius-container)'},+ {name: '--_hovercard-radius', description: 'Border radius of the hover card', default: 'var(--radius-container)', private: true},],derived: [- {property: 'borderRadius', vars: ['--hovercard-radius']},+ {property: 'borderRadius', vars: ['--_hovercard-radius']},],},components: [@@ -158,10 +158,10 @@ export const docsZh = {{className: 'xds-hovercard'},],vars: [- {name: '--hovercard-radius', description: 'Border radius of the hover card', default: 'var(--radius-container)'},+ {name: '--_hovercard-radius', description: 'Border radius of the hover card', default: 'var(--radius-container)', private: true},],derived: [- {property: 'borderRadius', vars: ['--hovercard-radius']},+ {property: 'borderRadius', vars: ['--_hovercard-radius']},],},components: [diff --git a/packages/core/src/HoverCard/useXDSHoverCard.tsx b/packages/core/src/HoverCard/useXDSHoverCard.tsxindex a5d8ba356f..7ef58ddc59 100644--- a/packages/core/src/HoverCard/useXDSHoverCard.tsx+++ b/packages/core/src/HoverCard/useXDSHoverCard.tsx@@ -37,8 +37,8 @@ const styles = stylex.create({// Base container styles passed to useXDSLayercontainer: {backgroundColor: colorVars['--color-background-surface'],- '--hovercard-radius': radiusVars['--radius-container'],- borderRadius: 'var(--hovercard-radius)',+ '--_hovercard-radius': radiusVars['--radius-container'],+ borderRadius: 'var(--_hovercard-radius)',boxShadow: shadowVars['--shadow-med'],},// Position-based margin stylesdiff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjsindex cbc0ea3dd9..908d659809 100644--- a/packages/core/src/Popover/Popover.doc.mjs+++ b/packages/core/src/Popover/Popover.doc.mjs@@ -136,10 +136,10 @@ export const docs = {{className: 'xds-popover'},],vars: [- {name: '--popover-radius', description: 'Border radius of the popover', default: 'var(--radius-element)'},+ {name: '--_popover-radius', description: 'Border radius of the popover', default: 'var(--radius-element)', private: true},],derived: [- {property: 'borderRadius', vars: ['--popover-radius']},+ {property: 'borderRadius', vars: ['--_popover-radius']},],},usage: {@@ -291,10 +291,10 @@ export const docsZh = {{className: 'xds-popover'},],vars: [- {name: '--popover-radius', description: 'Border radius of the popover', default: 'var(--radius-element)'},+ {name: '--_popover-radius', description: 'Border radius of the popover', default: 'var(--radius-element)', private: true},],derived: [- {property: 'borderRadius', vars: ['--popover-radius']},+ {property: 'borderRadius', vars: ['--_popover-radius']},],},usage: {diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjsindex 8a1c3c9f19..9526fbd9f3 100644--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs@@ -9,12 +9,12 @@ export const docs = {{className: 'xds-segmented-control-item'},],vars: [- {name: '--segmented-radius', description: 'Border radius of the segmented control', default: 'var(--radius-element)'},- {name: '--segmented-padding', description: 'Inner padding of the segmented control', default: 'var(--spacing-0-5)'},+ {name: '--_segmented-control-radius', description: 'Border radius of the segmented control', default: 'var(--radius-element)', private: true},+ {name: '--_segmented-control-padding', description: 'Inner padding of the segmented control', default: 'var(--spacing-0-5)', private: true},],derived: [- {property: 'borderRadius', vars: ['--segmented-radius']},- {property: 'padding', vars: ['--segmented-padding']},+ {property: 'borderRadius', vars: ['--_segmented-control-radius']},+ {property: 'padding', vars: ['--_segmented-control-padding']},],},components: [diff --git a/packages/core/src/SegmentedControl/XDSSegmentedControl.tsx b/packages/core/src/SegmentedControl/XDSSegmentedControl.tsxindex 99a7ac5e7c..c7b4a3368d 100644--- a/packages/core/src/SegmentedControl/XDSSegmentedControl.tsx+++ b/packages/core/src/SegmentedControl/XDSSegmentedControl.tsx@@ -73,8 +73,8 @@ const styles = stylex.create({display: 'inline-flex',alignItems: 'center',gap: spacingVars['--spacing-0-5'],- '--segmented-padding': spacingVars['--spacing-0-5'],- padding: 'var(--segmented-padding)',+ '--_segmented-control-padding': spacingVars['--spacing-0-5'],+ padding: 'var(--_segmented-control-padding)',backgroundColor: colorVars['--color-neutral'],},disabled: {@@ -85,16 +85,16 @@ const styles = stylex.create({const sizeStyles = stylex.create({sm: {- '--segmented-radius': radiusVars['--radius-element'],- borderRadius: 'var(--segmented-radius)',+ '--_segmented-control-radius': radiusVars['--radius-element'],+ borderRadius: 'var(--_segmented-control-radius)',},md: {- '--segmented-radius': radiusVars['--radius-element'],- borderRadius: 'var(--segmented-radius)',+ '--_segmented-control-radius': radiusVars['--radius-element'],+ borderRadius: 'var(--_segmented-control-radius)',},lg: {- '--segmented-radius': radiusVars['--radius-element'],- borderRadius: 'var(--segmented-radius)',+ '--_segmented-control-radius': radiusVars['--radius-element'],+ borderRadius: 'var(--_segmented-control-radius)',},});diff --git a/packages/core/src/SegmentedControl/XDSSegmentedControlItem.tsx b/packages/core/src/SegmentedControl/XDSSegmentedControlItem.tsxindex 6b7d52db12..8a1c0ccb87 100644--- a/packages/core/src/SegmentedControl/XDSSegmentedControlItem.tsx+++ b/packages/core/src/SegmentedControl/XDSSegmentedControlItem.tsx@@ -115,7 +115,7 @@ const styles = stylex.create({});const CONCENTRIC_RADIUS =- 'max(0px, calc(var(--segmented-radius) - var(--segmented-padding)))';+ 'max(0px, calc(var(--_segmented-control-radius) - var(--_segmented-control-padding)))';const sizeStyles = stylex.create({sm: {diff --git a/packages/core/src/Thumbnail/XDSThumbnail.tsx b/packages/core/src/Thumbnail/XDSThumbnail.tsxindex c7f8ec817c..b813bd91e4 100644--- a/packages/core/src/Thumbnail/XDSThumbnail.tsx+++ b/packages/core/src/Thumbnail/XDSThumbnail.tsx@@ -173,7 +173,7 @@ const styles = stylex.create({top: spacingVars['--spacing-1'],right: spacingVars['--spacing-1'],zIndex: 1,- '--button-radius': `calc(${radiusVars['--radius-element']} - ${spacingVars['--spacing-1']})`,+ '--_button-radius': `calc(${radiusVars['--radius-element']} - ${spacingVars['--spacing-1']})`,height: 20,minWidth: 20,} as Record<string, string | number>,diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex 2925b74fac..3f76cdda96 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -99,7 +99,7 @@ export interface ThemingTarget {* { property: 'padding', expand: 'container' }** // Multiple vars from one property- * { property: 'padding', vars: ['--_composer-padding', '--_composer-button-offset'] }+ * { property: 'padding', vars: ['--_chat-composer-padding', '--_composer-button-offset'] }** // Multiple entries for the same property (both fire, in order)* { property: 'padding', expand: 'container' },@@ -125,16 +125,14 @@ export interface DerivedVar {** @example* ```- * {name: '--card-radius', description: 'Border radius', default: 'var(--radius-container)'}- * {name: '--card-concentric-radius', description: 'Inner radius', derived: true, formula: 'max(0px, calc(var(--card-radius) - var(--card-padding)))'}+ * {name: '--_card-radius', description: 'Border radius', default: 'var(--radius-container)'}+ * {name: '--card-concentric-radius', description: 'Inner radius', derived: true, formula: 'max(0px, calc(var(--_card-radius) - var(--card-padding)))'}* ```*/export interface ComponentVar {- /** CSS custom property name, e.g. '--card-radius' */+ /** CSS custom property name, e.g. '--_card-radius' or '--button-press-scale' */name: string;- /** What this var controls. For derived vars, describe what the CSS property- * expands into (e.g. "Border radius of the card. Theme authors write- * `borderRadius`; the pipeline also sets this var.") */+ /** What this var controls */description: string;/** Default value as a CSS expression, e.g. 'var(--radius-container)' */default: string;@@ -143,20 +141,13 @@ export interface ComponentVar {/** CSS expression showing how derived vars are computed */formula?: string;/**- * The standard CSS property (camelCase) that theme authors write to set- * this var. When present, the pipeline intercepts this property in- * component overrides and emits the internal var alongside the CSS.- *- * e.g. `'borderRadius'` — writing `borderRadius: '32px'` in defineTheme- * emits both `border-radius: 32px` and `--card-radius: 32px`.- */- property?: string;- /**- * Named expansion strategy instead of setting the var directly.- * `'container'` — the pipeline expands padding values into 7 container- * layout tokens (--xds-<component>-padding, -inline, -block-start, etc.).+ * Whether this var is private (internal implementation detail).+ * Private vars are set by the derived var expansion pipeline — theme+ * authors write standard CSS properties instead of setting them directly.+ * The CLI hides private vars from theming output.+ * `xds theme build` errors if a theme sets a private var directly.*/- expand?: 'container';+ private?: boolean;}/**diff --git a/packages/core/src/theme/defineTheme.test.ts b/packages/core/src/theme/defineTheme.test.tsindex 7b761e0539..f32f7437fb 100644--- a/packages/core/src/theme/defineTheme.test.ts+++ b/packages/core/src/theme/defineTheme.test.ts@@ -958,7 +958,7 @@ describe('container padding mapping', () => {card: {base: {padding: '20px',- '--card-radius': '16px',+ '--_card-radius': '16px',backgroundColor: 'white',},},@@ -966,7 +966,7 @@ describe('container padding mapping', () => {});const css = generateThemeCSSFlat(theme);// Non-padding props pass through- expect(css).toContain('--card-radius: 16px');+ expect(css).toContain('--_card-radius: 16px');expect(css).toContain('background-color: white');// Padding is mapped to component-scoped tokenexpect(css).toContain('--xds-card-padding: 20px');diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.tsindex 4335fad9dd..00cc0466c6 100644--- a/packages/core/src/theme/defineTheme.ts+++ b/packages/core/src/theme/defineTheme.ts@@ -613,13 +613,6 @@ export function defineTheme(input: XDSDefineThemeInput): XDSDefinedTheme {// Container padding mapping// =============================================================================-/**- * Components whose padding properties should be mapped to container tokens.- * When a theme sets `padding` on these components, the pipeline intercepts it- * and emits container token declarations instead.- */-const CONTAINER_COMPONENTS = new Set(['card', 'section', 'dialog']);-/** Padding properties that trigger container token mapping */const PADDING_PROPS = new Set(['padding',@@ -825,39 +818,46 @@ export function generateThemeRules(theme: XDSDefinedTheme): string[] {}}- // Container padding mapping: intercept padding on container- // components and emit container token declarations instead.- // Also expand derived vars: when a theme sets a standard CSS- // property (e.g. borderRadius), emit the internal vars too.- let finalProps = props;- if (CONTAINER_COMPONENTS.has(component)) {- const paddingProps = props.filter(([p]) => PADDING_PROPS.has(p));- if (paddingProps.length > 0) {- const nonPaddingProps = props.filter(- ([p]) => !PADDING_PROPS.has(p),- );- const parsed = parsePadding(paddingProps);- const containerTokens = expandContainerPadding(component, parsed);- finalProps = [...nonPaddingProps, ...containerTokens];- }- }-// Derived var expansion: for each CSS property, check if the// component has derived var entries and emit additional declarations.// Entries are processed in order (priority).+ // - `vars`: emit internal CSS custom property declarations+ // - `expand: 'container'`: expand padding to container layout tokens+ let finalProps = props;const derivedProps: [string, string][] = [];- for (const [prop, value] of finalProps) {+ let containerExpanded = false;++ for (const [prop, value] of props) {const derived = getDerivedVars(component, prop);- for (const entry of derived) {+ // Padding longhands (paddingBlock, paddingInline, etc.) also+ // match the 'padding' derived entry for container expansion.+ const paddingDerived = PADDING_PROPS.has(prop) && prop !== 'padding'+ ? getDerivedVars(component, 'padding')+ : [];+ for (const entry of [...derived, ...paddingDerived]) {+ if (entry.expand === 'container' && PADDING_PROPS.has(prop)) {+ containerExpanded = true;+ }if (entry.vars) {for (const varName of entry.vars) {derivedProps.push([varName, value]);}}- // 'container' expansion is already handled above via- // CONTAINER_COMPONENTS — no double-emit needed here}}++ // Container padding expansion: replace padding props with+ // component-scoped container tokens for layout integration.+ if (containerExpanded) {+ const paddingProps = props.filter(([p]) => PADDING_PROPS.has(p));+ const nonPaddingProps = props.filter(+ ([p]) => !PADDING_PROPS.has(p),+ );+ const parsed = parsePadding(paddingProps);+ const containerTokens = expandContainerPadding(component, parsed);+ finalProps = [...nonPaddingProps, ...containerTokens];+ }+if (derivedProps.length > 0) {finalProps = [...finalProps, ...derivedProps];}diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.tsindex 181faee42b..5215350f46 100644--- a/packages/core/src/theme/derivedVarRegistry.test.ts+++ b/packages/core/src/theme/derivedVarRegistry.test.ts@@ -53,7 +53,7 @@ const STRUCTURAL_VARS = new Set([/*** Extract component-specific CSS custom property names from a source file.- * Matches patterns like '--card-radius': or '--composer-padding':+ * Matches patterns like '--_card-radius': or '--_chat-composer-padding':* Excludes structural/runtime vars and standard token vars (--color-*, --spacing-*, etc.).*/function extractComponentVars(filePath: string): string[] {@@ -152,13 +152,13 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {* (cross-component vars). These are documented in the *consuming* component's* doc, not the *setting* component's doc.*- * e.g. Carousel and Thumbnail set --button-radius for their child Buttons,- * but --button-radius is documented in Button's doc.+ * e.g. Carousel and Thumbnail set --_button-radius for their child Buttons,+ * but --_button-radius is documented in Button's doc.*/const CROSS_COMPONENT_VARS: Record<string, string[]> = {- Carousel: ['--button-radius'],- Thumbnail: ['--button-radius'],- Chat: ['--button-radius'],+ Carousel: ['--_button-radius'],+ Thumbnail: ['--_button-radius'],+ Chat: ['--_button-radius'],};// ---------------------------------------------------------------------------@@ -267,7 +267,7 @@ describe('getDerivedVars', () => {it('returns matching entries for card borderRadius', () => {const result = getDerivedVars('card', 'borderRadius');expect(result).toHaveLength(1);- expect(result[0].vars).toEqual(['--card-radius']);+ expect(result[0].vars).toEqual(['--_card-radius']);});it('returns empty for unknown component', () => {diff --git a/packages/core/src/theme/derivedVarRegistry.ts b/packages/core/src/theme/derivedVarRegistry.tsindex 6c5640d8e2..302c15bd61 100644--- a/packages/core/src/theme/derivedVarRegistry.ts+++ b/packages/core/src/theme/derivedVarRegistry.ts@@ -34,42 +34,42 @@ export interface DerivedVarEntry {*/export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {banner: [- {property: 'borderRadius', vars: ['--banner-radius']},+ {property: 'borderRadius', vars: ['--_banner-radius']},],button: [- {property: 'borderRadius', vars: ['--button-radius']},+ {property: 'borderRadius', vars: ['--_button-radius']},],card: [- {property: 'borderRadius', vars: ['--card-radius']},+ {property: 'borderRadius', vars: ['--_card-radius']},{property: 'padding', expand: 'container'},],chat: [- {property: 'borderRadius', vars: ['--composer-radius']},- {property: 'padding', vars: ['--composer-padding']},+ {property: 'borderRadius', vars: ['--_chat-composer-radius']},+ {property: 'padding', vars: ['--_chat-composer-padding']},],dialog: [- {property: 'borderRadius', vars: ['--dialog-radius']},+ {property: 'borderRadius', vars: ['--_dialog-radius']},{property: 'padding', expand: 'container'},],'dropdown-menu': [- {property: 'borderRadius', vars: ['--dropdown-radius']},- {property: 'padding', vars: ['--dropdown-padding']},+ {property: 'borderRadius', vars: ['--_dropdown-menu-radius']},+ {property: 'padding', vars: ['--_dropdown-menu-padding']},],field: [- {property: 'borderRadius', vars: ['--input-radius']},+ {property: 'borderRadius', vars: ['--_field-radius']},],hovercard: [- {property: 'borderRadius', vars: ['--hovercard-radius']},+ {property: 'borderRadius', vars: ['--_hovercard-radius']},],popover: [- {property: 'borderRadius', vars: ['--popover-radius']},+ {property: 'borderRadius', vars: ['--_popover-radius']},],section: [{property: 'padding', expand: 'container'},],'segmented-control': [- {property: 'borderRadius', vars: ['--segmented-radius']},- {property: 'padding', vars: ['--segmented-padding']},+ {property: 'borderRadius', vars: ['--_segmented-control-radius']},+ {property: 'padding', vars: ['--_segmented-control-padding']},],};diff --git a/packages/core/src/theme/generateThemeRules.test.ts b/packages/core/src/theme/generateThemeRules.test.tsindex fb6ce8371d..8df86cac14 100644--- a/packages/core/src/theme/generateThemeRules.test.ts+++ b/packages/core/src/theme/generateThemeRules.test.ts@@ -224,7 +224,7 @@ describe('derived var expansion', () => {const cardRule = rules.find(r => r.includes('.xds-card'));expect(cardRule).toBeDefined();expect(cardRule).toContain('border-radius: 32px');- expect(cardRule).toContain('--card-radius: 32px');+ expect(cardRule).toContain('--_card-radius: 32px');});it('emits borderRadius AND internal var for dropdown-menu', () => {@@ -240,7 +240,7 @@ describe('derived var expansion', () => {const rule = rules.find(r => r.includes('.xds-dropdown-menu'));expect(rule).toBeDefined();expect(rule).toContain('border-radius: 16px');- expect(rule).toContain('--dropdown-radius: 16px');+ expect(rule).toContain('--_dropdown-menu-radius: 16px');});it('emits padding AND internal var for dropdown-menu', () => {@@ -255,7 +255,7 @@ describe('derived var expansion', () => {const rules = generateThemeRules(theme);const rule = rules.find(r => r.includes('.xds-dropdown-menu'));expect(rule).toBeDefined();- expect(rule).toContain('--dropdown-padding: 8px');+ expect(rule).toContain('--_dropdown-menu-padding: 8px');});it('emits internal vars for chat composer', () => {@@ -270,8 +270,8 @@ describe('derived var expansion', () => {const rules = generateThemeRules(theme);const rule = rules.find(r => r.includes('.xds-chat'));expect(rule).toBeDefined();- expect(rule).toContain('--composer-radius: 24px');- expect(rule).toContain('--composer-padding: 12px');+ expect(rule).toContain('--_chat-composer-radius: 24px');+ expect(rule).toContain('--_chat-composer-padding: 12px');});it('emits internal var for button borderRadius', () => {@@ -287,7 +287,7 @@ describe('derived var expansion', () => {const rule = rules.find(r => r.includes('.xds-button'));expect(rule).toBeDefined();expect(rule).toContain('border-radius: 8px');- expect(rule).toContain('--button-radius: 8px');+ expect(rule).toContain('--_button-radius: 8px');});it('does not emit derived vars for components without registry entries', () => {@@ -336,13 +336,13 @@ describe('derived var expansion', () => {const rule = rules.find(r => r.includes('.xds-card.muted'));expect(rule).toBeDefined();expect(rule).toContain('border-radius: 16px');- expect(rule).toContain('--card-radius: 16px');+ expect(rule).toContain('--_card-radius: 16px');});});describe('brutalist-style derived expansion', () => {- it('button borderRadius emits --button-radius for pill shape', () => {+ it('button borderRadius emits --_button-radius for pill shape', () => {const theme = defineTheme({name: 'test-brutalist',radius: {base: 4, multiplier: 0},@@ -355,7 +355,7 @@ describe('brutalist-style derived expansion', () => {const rules = generateThemeRules(theme);const rule = rules.find(r => r.includes('.xds-button'));expect(rule).toContain('border-radius: 9999px');- expect(rule).toContain('--button-radius: 9999px');+ expect(rule).toContain('--_button-radius: 9999px');});it('card padding emits container tokens via derived expansion', () => {@@ -386,7 +386,7 @@ describe('brutalist-style derived expansion', () => {const rule = rules.find(r => r.includes('.xds-dropdown-menu'));expect(rule).toBeDefined();expect(rule).toContain('border-radius: 0px');- expect(rule).toContain('--dropdown-radius: 0px');- expect(rule).toContain('--dropdown-padding: 4px');+ expect(rule).toContain('--_dropdown-menu-radius: 0px');+ expect(rule).toContain('--_dropdown-menu-padding: 4px');});});