Styling Components

There are several ways to style things. Here is when to use each:

All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run npx astryx docs styling-libraries; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and useTheme() for non-CSS processing.

Every component accepts an xstyle prop for style customization. It accepts StyleX styles created via stylex.create(), not inline objects or class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination.

tsx
import * as stylex from '@stylexjs/stylex';
​
const overrides = stylex.create({
  card: { maxWidth: 400, marginBlock: 16 },
  saveButton: { alignSelf: 'flex-end' },
});
​
<Card xstyle={overrides.card} />
<Button label="Save" xstyle={overrides.saveButton} />

tsx
import * as stylex from '@stylexjs/stylex';
​
const overrides = stylex.create({
  card: {
    boxShadow: {
      default: 'none',
      ':hover': { '@media (hover: hover)': '0 4px 12px rgba(0,0,0,0.1)' },
    },
  },
});
​
<Card xstyle={overrides.card}>...</Card>

• 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

The package ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by design tokens: colors, spacing, radius, shadows, and typography all resolve to the active theme.

css
@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;
​
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "@astryxdesign/core/reset.css";
@import "@astryxdesign/core/astryx.css";
@import "@astryxdesign/theme-neutral/theme.css";
@import "@astryxdesign/core/tailwind-theme.css";
@import "tailwindcss/utilities.css" layer(utilities);

tsx
<div className="text-primary bg-surface rounded-container p-4 flex gap-3">
  <Button label="Save" variant="primary" />
  <Button label="Cancel" variant="secondary" />
</div>

The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run npx astryx docs styling-libraries.

Every component also accepts standard className and style props. className is appended after the component's own classes. style is merged after StyleX inline styles, so consumer values win on conflict.

tsx
<Card className="shadow-lg hover:shadow-xl transition-shadow">
  ...
</Card>
<Button label="Save" className="my-app-save-btn" />

For layout and wrapper styling, Tailwind utilities on className work well. For component-specific overrides (padding, colors, borders), prefer xstyle; it integrates with StyleX deduplication and the component's internal style pipeline.

Components extend HTML attributes and spread rest props onto their root DOM element. This means data-* attributes, aria-* attributes, event handlers, and other HTML props pass through automatically.

tsx
<Card
  data-testid="user-card"
  data-user-id={user.id}
  onMouseEnter={handleHover}
  aria-label="User profile card"
>
  ...
</Card>

tsx
const cardRef = useRef<HTMLDivElement>(null);
<Card ref={cardRef}>...</Card>

A few HTML attributes are intentionally omitted from the base type (contentEditable, dangerouslySetInnerHTML). children is not in the base type either; components that accept children declare it explicitly, so slot-based components don't silently drop JSX children.

Complex components are composed from smaller components. Each sub-component accepts its own xstyle, className, and rest props. You style the parts individually; there's no single "drill into sub-part" prop.

tsx
import * as stylex from '@stylexjs/stylex';
​
const overrides = stylex.create({
  dialog: { maxWidth: 500 },
  content: { gap: 'var(--spacing-4)' },
});
​
<Dialog isOpen={isOpen} onClose={close} xstyle={overrides.dialog}>
  <Layout
    header={
      <LayoutHeader hasDivider>
        <Heading level={2}>Edit Profile</Heading>
      </LayoutHeader>
    }
    content={
      <LayoutContent xstyle={overrides.content}>
        <TextInput label="Name" value={name} onChange={setName} />
      </LayoutContent>
    }
    footer={
      <LayoutFooter hasDivider>
        <Button label="Cancel" variant="secondary" onClick={close} />
        <Button label="Save" variant="primary" onClick={save} />
      </LayoutFooter>
    }
  />
</Dialog>

The pattern: the parent component (Dialog) controls structure and behavior, child components (Layout, Header, Button) control their own appearance. Style each piece where it lives.

When external CSS needs to target an XDS component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (.astryx-button, .astryx-card); data attributes identify the axis and value (data-variant, data-size, data-level, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.

css
.my-app .astryx-button[data-variant="primary"] {
  /* primary buttons in this app context */
}
​
.my-app .astryx-button[data-variant="primary"][data-size="sm"] {
  /* small primary buttons */
}
​
.my-app .astryx-heading[data-level="2"] {
  /* level 2 headings; numeric values stay literal in data attrs */
}

tsx
// <Button variant="primary" size="sm" />
// preferred selector attrs: data-variant="primary" data-size="sm"
​
// <Card variant="elevated" />
// preferred selector attrs: data-variant="elevated"
​
// <Heading level={2} />
// preferred selector attrs: data-level="2"

For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level prop:value API (variant:primary, size:sm) and handles selector generation for you. Run npx astryx docs theme for the full theming guide.

XDS still emits legacy bare prop/state classes such as .primary, .sm, .level-2, and .checked for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (.astryx-button, .astryx-card, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.

css
/* Deprecated compatibility selector — avoid in new CSS */
.my-app .astryx-button.primary {
  /* use .astryx-button[data-variant="primary"] instead */
}
​
/* Deprecated compatibility selector — avoid in new CSS */
.my-app .astryx-heading.level-2 {
  /* use .astryx-heading[data-level="2"] instead */
}

When writing custom styles, use design tokens instead of hardcoded values. Tokens are CSS custom properties that adapt to the active theme and color mode. The system provides tokens for spacing, color, radius, shadow, typography, and size.

tsx
import * as stylex from '@stylexjs/stylex';
​
const styles = stylex.create({
  surface: {
    padding: 'var(--spacing-4)',
    borderRadius: 'var(--radius-container)',
    backgroundColor: 'var(--color-background-surface)',
  },
});
​
<Card xstyle={styles.surface} />

tsx
import {colorVars, spacingVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';
​
const styles = stylex.create({
  highlight: {
    backgroundColor: colorVars['--color-accent-muted'],
    padding: spacingVars['--spacing-3'],
    borderRadius: radiusVars['--radius-element'],
  },
});

Both approaches work: var() strings or typed imports from tokens.stylex. The typed imports give autocomplete and catch typos at build time.

See npx astryx docs tokens for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See npx astryx docs theme for how to override tokens via defineTheme.