Skip to content

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

TypeScript

docs: add cssProperties to doc infrastructure, move container padding docs to component docs (#850)

Cindy Zhangaf5498144458
diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjs
index b6dc425e14..9c7ef3a451 100644
--- a/packages/cli/src/lib/component-format.mjs
+++ b/packages/cli/src/lib/component-format.mjs
@@ -192,6 +192,17 @@ export function formatFull(docs, options = {}) {
sections.push(`Component key: \`${docs.theming.componentKey}\`\n`);
}
+ // Public CSS custom properties
+ if (docs.theming?.cssProperties?.length) {
+ const propLines = [];
+ propLines.push('| CSS Property | Description | Default |');
+ propLines.push('|-------------|-------------|---------|');
+ for (const p of docs.theming.cssProperties) {
+ propLines.push(`| \`${p.name}\` | ${p.description} | ${p.default || '—'} |`);
+ }
+ sections.push(propLines.join('\n') + '\n');
+ }
+
// Component CSS vars
if (docs.theming?.vars?.length) {
const varLines = [];
@@ -292,6 +303,18 @@ export function formatCompact(docs, componentName, importHint) {
sections.push(docs.notes.map(n => `- ${n}`).join('\n') + '\n');
}
+ // CSS custom properties (compact includes these for theme consumers)
+ if (docs.theming?.cssProperties?.length) {
+ sections.push('## CSS Properties\n');
+ const propLines = [];
+ propLines.push('| CSS Property | Description | Default |');
+ propLines.push('|-------------|-------------|---------|');
+ for (const p of docs.theming.cssProperties) {
+ propLines.push(`| \`${p.name}\` | ${p.description} | ${p.default || '—'} |`);
+ }
+ sections.push(propLines.join('\n') + '\n');
+ }
+
return sections.join('\n');
}
@@ -373,6 +396,14 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
}
}
+ // CSS custom properties (if any)
+ if (docs.theming?.cssProperties?.length) {
+ const cssPropNames = docs.theming.cssProperties
+ .map(p => `${p.name} (${p.default || '—'})`)
+ .join(', ');
+ output.push(` CSS Props: ${cssPropNames}`);
+ }
+
// Theme targets (class names, variants, states) with theme variant merging
if (docs.theming?.targets?.length) {
const { themeData = null } = options;
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index 29cea7af2d..c3ac33a1c2 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -93,6 +93,14 @@ export const docs = {
vars: [
{name: '--card-radius', description: 'Border radius of the card', default: 'var(--radius-3)'},
],
+ cssProperties: [
+ {
+ name: '--xds-container-padding',
+ description:
+ "Controls Card container padding. Set in theme component overrides via `card: { base: { '--xds-container-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",
+ default: 'var(--spacing-4)',
+ },
+ ],
},
};
@@ -190,6 +198,14 @@ export const docsZh = {
vars: [
{name: '--card-radius', description: 'Border radius of the card', default: 'var(--radius-3)'},
],
+ cssProperties: [
+ {
+ name: '--xds-container-padding',
+ description:
+ "Controls Card container padding. Set in theme component overrides via `card: { base: { '--xds-container-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",
+ default: 'var(--spacing-4)',
+ },
+ ],
},
};
diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjs
index 19762c3d24..1b41777512 100644
--- a/packages/core/src/Section/Section.doc.mjs
+++ b/packages/core/src/Section/Section.doc.mjs
@@ -100,6 +100,14 @@ export const docs = {
targets: [
{className: 'xds-section', visualProps: ['variant']},
],
+ cssProperties: [
+ {
+ name: '--xds-container-padding',
+ description:
+ "Controls Section container padding. Set in theme component overrides via `section: { base: { '--xds-container-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",
+ default: 'var(--spacing-4)',
+ },
+ ],
},
};
@@ -204,6 +212,14 @@ export const docsZh = {
targets: [
{className: 'xds-section', visualProps: ['variant']},
],
+ cssProperties: [
+ {
+ name: '--xds-container-padding',
+ description:
+ "Controls Section container padding. Set in theme component overrides via `section: { base: { '--xds-container-padding': 'var(--spacing-3)' } }`. Cascades to all internal layout padding variables. Do not use `--layout-padding-*` vars directly.",
+ default: 'var(--spacing-4)',
+ },
+ ],
},
};
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index da927b9820..d57d166fa4 100644
--- a/packages/core/src/docs-types.ts
+++ b/packages/core/src/docs-types.ts
@@ -99,6 +99,24 @@ export interface ThemingTarget {
states?: string[];
}
+/**
+ * Documents a public CSS custom property that themes can set on a component
+ * via component style overrides in `defineTheme`.
+ *
+ * @example
+ * ```
+ * {name: '--xds-container-padding', description: 'Controls container padding. Cascades to internal layout vars.', default: 'var(--spacing-4)'}
+ * ```
+ */
+export interface CSSPropertyDoc {
+ /** The CSS custom property name. Always starts with `--xds-`. */
+ name: string;
+ /** What this property controls, in 1-2 sentences. */
+ description: string;
+ /** Default value if not set by theme. e.g. `"var(--spacing-4)"` */
+ default?: string;
+}
+
/**
* Documents a CSS custom property exposed by a component for theming.
* These vars are set on the component's root element and can be overridden
@@ -177,6 +195,10 @@ interface BaseDoc {
targets: ThemingTarget[];
/** CSS custom properties exposed for theming. */
vars?: ComponentVar[];
+ /** Public CSS custom properties that themes can set on this component
+ * via component overrides. Only document supported public properties —
+ * internal variables must not be listed here. */
+ cssProperties?: CSSPropertyDoc[];
};
/** Accessibility notes — ARIA patterns, screen reader behavior.
* Each string is one self-contained, declarative note.