An open source design system that's fully customizable and agent ready
TypeScript
fix(docs): correct xstyle prop documentation and remove XDS from titles (#1935)
Cindy Zhang6c6c9c287239
diff --git a/packages/cli/docs/getting-started.doc.mjs b/packages/cli/docs/getting-started.doc.mjsindex fa0af97f05..31298ab8ec 100644--- a/packages/cli/docs/getting-started.doc.mjs+++ b/packages/cli/docs/getting-started.doc.mjs@@ -71,13 +71,19 @@ export default function Page() {content: [{type: 'prose',- text: 'Every XDS component accepts an `xstyle` prop. Use an inline object for one-off tweaks, or `stylex.create` for reusable styles and pseudo-classes.',+ text: 'Every XDS component accepts an `xstyle` prop for StyleX style overrides created via `stylex.create()`.',},{type: 'code',lang: 'tsx',- label: 'Inline overrides',- code: `<XDSButton label="Save" xstyle={{alignSelf: 'flex-end', marginTop: 16}} />`,+ label: 'Style overrides',+ code: `import * as stylex from '@stylexjs/stylex';++const overrides = stylex.create({+ save: { alignSelf: 'flex-end', marginTop: 16 },+});++<XDSButton label="Save" xstyle={overrides.save} />`,},],},diff --git a/packages/cli/docs/icons.doc.mjs b/packages/cli/docs/icons.doc.mjsindex 931b6cc348..19f8fe342f 100644--- a/packages/cli/docs/icons.doc.mjs+++ b/packages/cli/docs/icons.doc.mjs@@ -5,7 +5,7 @@/** @type {import('../../core/src/docs-types').ReferenceDoc} */export const docs = {name: 'icons',- title: 'XDS Icons',+ title: 'Icons',description:"Semantic icon names available in XDS. These adapt to the active theme's icon registry.",diff --git a/packages/cli/docs/principles.doc.mjs b/packages/cli/docs/principles.doc.mjsindex 11f4500aa2..72d7b7f7f3 100644--- a/packages/cli/docs/principles.doc.mjs+++ b/packages/cli/docs/principles.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'principles',- title: 'XDS Principles',+ title: 'Principles',description:'Core design principles and rules for building with XDS.',@@ -48,7 +48,7 @@ export const docs = {content: [{type: 'prose',- text: 'XDS supports multiple styling approaches. Every component accepts an \`xstyle\` prop for overrides (inline objects, StyleX styles, or CSS class names). For layout and wrapper styling outside of components, use StyleX or Tailwind utilities — both resolve to the same XDS design tokens.',+ text: 'XDS supports multiple styling approaches. Every component accepts an \`xstyle\` prop for StyleX style overrides via \`stylex.create()\`. For layout and wrapper styling outside of components, use StyleX or Tailwind utilities — both resolve to the same XDS design tokens.',},{type: 'prose',diff --git a/packages/cli/docs/styling.doc.mjs b/packages/cli/docs/styling.doc.mjsindex 65d90b0675..2abaa10f39 100644--- a/packages/cli/docs/styling.doc.mjs+++ b/packages/cli/docs/styling.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'styling',- title: 'Styling XDS Components',+ title: 'Styling Components',description:'How to customize component appearance: xstyle prop, Tailwind, StyleX, className, rest props, compound component patterns, and theming hooks.',@@ -18,7 +18,7 @@ export const docs = {type: 'table',headers: ['Approach', 'Use for', 'Example'],rows: [- ['xstyle prop', 'Overriding a specific XDS component', 'xstyle={{ maxWidth: 400 }}'],+ ['xstyle prop', 'Overriding a specific XDS component', 'xstyle={styles.override}'],['Tailwind utilities', 'Layout, wrappers, and utility styling', 'className="flex gap-3 p-4"'],['stylex.create', 'Reusable styles, pseudo-classes, typed tokens', 'stylex.create({ card: { ... } })'],['className', 'Integrating with external CSS or Tailwind on components', 'className="my-card shadow-lg"'],@@ -35,19 +35,26 @@ export const docs = {content: [{type: 'prose',- text: 'Every XDS component accepts an xstyle prop for style customization. It accepts three formats: inline style objects, StyleX styles from stylex.create(), or CSS class name strings.',+ text: 'Every XDS component accepts an xstyle prop for style customization. It accepts StyleX styles created via stylex.create() — not inline objects, not class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination.',},{type: 'code',lang: 'tsx',- label: 'Inline object — quick overrides',- code: `<XDSCard xstyle={{ maxWidth: 400, marginBlock: 16 }} />-<XDSButton label="Save" xstyle={{ alignSelf: 'flex-end' }} />`,+ label: 'Simple overrides',+ code: `import * as stylex from '@stylexjs/stylex';++const overrides = stylex.create({+ card: { maxWidth: 400, marginBlock: 16 },+ saveButton: { alignSelf: 'flex-end' },+});++<XDSCard xstyle={overrides.card} />+<XDSButton label="Save" xstyle={overrides.saveButton} />`,},{type: 'code',lang: 'tsx',- label: 'StyleX — reusable, supports pseudo-classes',+ label: 'Pseudo-classes and conditional styles',code: `import * as stylex from '@stylexjs/stylex';const overrides = stylex.create({@@ -60,22 +67,15 @@ const overrides = stylex.create({});<XDSCard xstyle={overrides.card}>...</XDSCard>`,- },- {- type: 'code',- lang: 'tsx',- label: 'CSS class name — works with CSS Modules or plain CSS',- code: `<XDSCard xstyle="my-custom-card" />-<XDSCard xstyle={styles.customCard} /> // CSS Module`,},{type: 'list',style: 'unordered',items: [- '1-2 simple properties (margin, maxWidth): inline object is fine',- '3+ properties or reusable: use stylex.create',- 'Pseudo-classes (:hover, :focus-visible): requires stylex.create',+ 'All xstyle values must come from stylex.create()',+ 'Pseudo-classes (:hover, :focus-visible) are supported inside stylex.create','All :hover styles MUST use @media (hover: hover) guard',+ 'For non-StyleX styling (Tailwind, external CSS), use className instead',],},],@@ -175,7 +175,14 @@ const overrides = stylex.create({type: 'code',lang: 'tsx',label: 'Dialog with individually styled parts',- code: `<XDSDialog isOpen={isOpen} onClose={close} xstyle={{ maxWidth: 500 }}>+ code: `import * as stylex from '@stylexjs/stylex';++const overrides = stylex.create({+ dialog: { maxWidth: 500 },+ content: { gap: 'var(--spacing-4)' },+});++<XDSDialog isOpen={isOpen} onClose={close} xstyle={overrides.dialog}><XDSLayoutheader={<XDSLayoutHeader hasDivider>@@ -183,7 +190,7 @@ const overrides = stylex.create({</XDSLayoutHeader>}content={- <XDSLayoutContent xstyle={{ gap: 'var(--spacing-4)' }}>+ <XDSLayoutContent xstyle={overrides.content}><XDSTextInput label="Name" value={name} onChange={setName} /></XDSLayoutContent>}@@ -246,17 +253,23 @@ const overrides = stylex.create({{type: 'code',lang: 'tsx',- label: 'Using tokens in xstyle (inline)',- code: `<XDSCard xstyle={{- padding: 'var(--spacing-4)',- borderRadius: 'var(--radius-container)',- backgroundColor: 'var(--color-background-surface)',-}} />`,+ label: 'Using tokens in stylex.create',+ code: `import * as stylex from '@stylexjs/stylex';++const styles = stylex.create({+ surface: {+ padding: 'var(--spacing-4)',+ borderRadius: 'var(--radius-container)',+ backgroundColor: 'var(--color-background-surface)',+ },+});++<XDSCard xstyle={styles.surface} />`,},{type: 'code',lang: 'tsx',- label: 'Using tokens in stylex.create (type-safe imports)',+ label: 'Using typed token imports in stylex.create',code: `import {colorVars, spacingVars, radiusVars} from '@xds/core/theme/tokens.stylex';const styles = stylex.create({@@ -269,7 +282,7 @@ const styles = stylex.create({},{type: 'prose',- text: 'Both approaches work — var() strings in inline xstyle, or typed imports from tokens.stylex in stylex.create(). The typed imports give autocomplete and catch typos at build time.',+ text: 'Both approaches work — var() strings or typed imports from tokens.stylex. The typed imports give autocomplete and catch typos at build time.',},{type: 'prose',@@ -287,7 +300,7 @@ const styles = stylex.create({'style={{}} on raw <div> wrappers. Use xstyle on the XDS component directly.','Hardcoded colors (#fff, rgb(...)). Use var(--color-*) tokens or Tailwind semantic classes (text-primary, bg-surface).','Hardcoded spacing (16px, 1rem). Use var(--spacing-*) tokens or Tailwind spacing utilities (p-4, gap-3).',- 'Wrapping an XDS component in a <div> just to add margin. Use xstyle={{ margin: ... }} on the component.',+ 'Wrapping an XDS component in a <div> just to add margin. Use xstyle with stylex.create on the component.','Using !important. If styles aren\'t applying, check specificity — xstyle is merged last.',],},diff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjsindex 8d5135d6e0..88761e50e7 100644--- a/packages/cli/docs/theme.doc.mjs+++ b/packages/cli/docs/theme.doc.mjs@@ -2,7 +2,7 @@export const docs = {name: 'theme',- title: 'XDS Theme System',+ title: 'Theme System',description:'XDSTheme provider, custom themes, theme build for production/SSR, light/dark mode, and component style overrides.',