Color
Semantic color tokens for surfaces, text, icons, borders, and status indicators.Overview #
Colors are semantic: tokens describe purpose, not appearance. Every color adapts automatically between light and dark modes via CSS light-dark(). Themes override the resolved values, so your code never references raw hex colors.
Surface Colors #
Layered surface hierarchy: body → surface → card → popover. Each level sits visually above the previous one.
Semantic colors for consistent theming. All colors use light-dark() for automatic mode switching.
| Token | Value |
|---|---|
| --color-accent | |
| --color-accent-muted | |
| --color-on-accent | |
| --color-neutral | |
| --color-background-surface | |
| --color-background-body | |
| --color-overlay | |
| --color-overlay-hover | |
| --color-overlay-pressed | |
| --color-background-muted | |
| --color-text-primary | |
| --color-text-secondary | |
| --color-text-disabled | |
| --color-text-accent | |
| --color-on-dark | |
| --color-on-light | |
| --color-icon-accent | |
| --color-icon-primary | |
| --color-icon-secondary | |
| --color-icon-disabled | |
| --color-background-card | |
| --color-background-popover | |
| --color-background-inverted | |
| --color-background-error-inverted | |
| --color-success | |
| --color-success-muted | |
| --color-on-success | |
| --color-error | |
| --color-error-muted | |
| --color-on-error | |
| --color-warning | |
| --color-warning-muted | |
| --color-on-warning | |
| --color-border | |
| --color-border-emphasized | |
| --color-skeleton | |
| --color-track | |
| --color-shadow | |
| --color-tint-hover | |
| --color-background-blue | |
| --color-border-blue | |
| --color-icon-blue | |
| --color-text-blue | |
| --color-background-cyan | |
| --color-border-cyan | |
| --color-icon-cyan | |
| --color-text-cyan | |
| --color-background-gray | |
| --color-border-gray | |
| --color-icon-gray | |
| --color-text-gray | |
| --color-background-green | |
| --color-border-green | |
| --color-icon-green | |
| --color-text-green | |
| --color-background-orange | |
| --color-border-orange | |
| --color-icon-orange | |
| --color-text-orange | |
| --color-background-pink | |
| --color-border-pink | |
| --color-icon-pink | |
| --color-text-pink | |
| --color-background-purple | |
| --color-border-purple | |
| --color-icon-purple | |
| --color-text-purple | |
| --color-background-red | |
| --color-border-red | |
| --color-icon-red | |
| --color-text-red | |
| --color-background-teal | |
| --color-border-teal | |
| --color-icon-teal | |
| --color-text-teal | |
| --color-background-yellow | |
| --color-border-yellow | |
| --color-icon-yellow | |
| --color-text-yellow |
Full reference: Color Tokens.
Usage #
Applying color tokens (page.stylex.ts)
tsimport * as stylex from '@stylexjs/stylex';export const styles = stylex.create({container: {backgroundColor: 'var(--color-background-surface)',color: 'var(--color-text-primary)',borderColor: 'var(--color-border)'},accent: {color: 'var(--color-text-accent)'}});
Outside StyleX the same tokens work anywhere CSS does — a scoped <style> block, a global stylesheet, or an SVG fill. tokenVar('--color-text-accent') from @astryx-svelte/core/theme returns the same var(...) reference when a styling-library config needs it as a value.
Best Practices #
| Guidance | Practices |
|---|---|
| Do | Use semantic tokens (--color-text-primary) instead of raw hex values. |
| Do | Rely on the surface hierarchy (body → surface → card → popover) for layering. |
| Do | Use status colors (success, error, warning) only for their semantic meaning. |
| Don't | Hardcode hex values, since they won't adapt to dark mode or custom themes. |
| Don't | Mix accent colors with status colors in the same context. |
| Don't | Use --color-on-accent on non-accent backgrounds. |