PrinciplesCore design principles and rules for building with XDS.
Design PhilosophyXDS is a design system that prioritizes consistency, adaptability, and developer experience. Every decision flows from a few core ideas:
•Components over primitives — use XDS components for everything they cover before reaching for raw HTML
•Semantic tokens over hardcoded values — colors, spacing, and radii are named by purpose, not appearance
•Theme-agnostic code — your app code never references specific colors or measurements, so themes and dark mode work automatically
•Open internals — every primitive is exported and composable, so you can build on top of XDS without fighting it
Rules
1.Use XDS components for everything they cover
2.StyleX or Tailwind for custom styling — both are first-class (see `npx xds docs styling`)
3.Semantic tokens, not hardcoded values (see `npx xds docs tokens`)
4.CSS custom properties for colors, not hex values
5.Form inputs are controlled (value + onChange)
6.Use useXDSLinkComponent() for navigation so consumers can plug in their framework router via XDSLinkProvider
Styling ApproachXDS 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.See `npx xds docs styling` for the complete guide with examples.
Anti-Patterns
| Guidance | Practices |
|---|---|
| Don't | Inline styles on raw elements. Use xstyle on XDS components |
| Don't | Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface) |
| Don't | Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities |
| Don't | Hardcoded <a> elements. Use useXDSLinkComponent() so consumers can swap in their framework router via XDSLinkProvider |
| Don't | Inventing props. Read component docs first |
Design TokensXDS provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run `npx xds docs tokens` for the full reference with all values.