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.mjsindex 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 varsif (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 mergingif (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.mjsindex 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.mjsindex 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.tsindex 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.