Skip to content

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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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 theme
if (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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.mjs
index 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.ts
index 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.mjs
index 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.tsx
index 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 useXDSLayer
container: {
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 styles
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index 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.mjs
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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 token
expect(css).toContain('--xds-card-padding: 20px');
diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.ts
index 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.ts
index 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.ts
index 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.ts
index 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');
});
});