Mastering Design Tokens in Astryx: Color, Typography, Spacing, and More

Astryx uses a comprehensive semantic token system — CSS custom properties named by purpose rather than appearance. Every design value in your UI should come from these tokens, which adapt automatically when you switch themes or color modes. There are 10 token categories in total.

Token Categories Overview

Category	Prefix	Example
Color	--color-*	--color-accent
Spacing	--spacing-*	--spacing-4
Radius	--radius-*	--radius-container
Shadow	--shadow-*	--shadow-med
Typography	--text-*	--text-body-size
Font	--font-*	--font-family-body
Size	--size-*	--size-element-md
Duration	--duration-*	--duration-fast
Easing	--ease-*	--ease-standard
Border	--border-*	--border-width

Using Tokens in CSS and StyleX

Plain CSS

.my-component {
  color: var(--color-text-primary);
  background: var(--color-background-surface);
  padding: var(--spacing-4);
  border-radius: var(--radius-container);
  box-shadow: var(--shadow-low);
  font-family: var(--font-family-sans);
}

StyleX with Typed Token Imports

import * as stylex from '@stylexjs/stylex';
import { colorVars, spacingVars } from '@astryxdesign/core';

const styles = stylex.create({
  card: {
    padding: spacingVars['--spacing-4'],
    backgroundColor: colorVars['--color-background-surface'],
    borderRadius: radiusVars['--radius-container'],
  },
});

1. Color System

The color system uses semantic tokens where names describe purpose, not appearance. All colors use CSS light-dark() for automatic light/dark mode switching — no manual prefers-color-scheme media query needed.

Surface Hierarchy (4 Levels)

Token	Light	Dark	Usage
--color-background-body	#F1F4F7	#111112	Page background
--color-background-surface	#FFFFFF	#1F1F22	Sidebar, Dialog
--color-background-card	#FFFFFF	#1F1F22	Card
--color-background-popover	#FFFFFF	#28292C	Dropdown, Tooltip, Modal

Text Colors (4 Levels)

Token	Light	Dark
--color-text-primary	#0A1317	#DFE2E5
--color-text-secondary	#4E606F	#AAAFB5
--color-text-disabled	#A4B0BC	#6F747C
--color-text-accent	#0064E0	#3E9EFB

Best Practices

• Use semantic tokens instead of hex values
• Follow the surface hierarchy: body → surface → card → popover
• Use status colors only for their semantic meaning
• Don’t mix accent and status colors in the same context

2. Typography

The type system uses a geometric scale: round(14 × 1.2^step). Base = 14px, ratio = 1.2.

Semantic Type Scale

Level	Size	Weight	Usage
display-1	42px	400	Hero banners
heading-1	24px	600	Main heading
body	14px	400	Main body text
supporting	12px	400	Captions, metadata
label	14px	500	Form labels
code	14px	400	Code, numbers

<Heading level={1} type="display-1">Hero Title</Heading>
<Text type="body">Body text at base scale.</Text>
<Text type="label">Form Label</Text>
<Text type="supporting">Helper text, timestamps, metadata.</Text>
<Text type="code">const x = 1;</Text>

3. Spacing

A 4px-base-unit scale. All spacing values are multiples of 4px.

Value	Usage
--spacing-1 (4px)	Very tight: icon next to text
--spacing-2 (8px)	Close: label to input
--spacing-4 (16px)	Standard: elements in same group
--spacing-6 (24px)	Between sections/subgroups
--spacing-8 (32px)	Between major groups or page edges

<VStack gap={4}>   {/* 16px gap */}
<HStack gap={3}>   {/* 12px gap */}

4. Shape / Radius

A 7-level radius scale:

Token	Value	Usage
--radius-inner	4px	Input fields, small buttons
--radius-element	8px	Buttons, Badge
--radius-container	12px	Card, Dialog, Sheet
--radius-page	28px	Special containers, Drawer
--radius-full	9999px	Circle, Pill

5. Elevation / Shadows

3 elevation levels + 5 inset shadow tokens:

Token	Usage
--shadow-low	Tooltips, subtle cards
--shadow-med	Dropdowns, popovers
--shadow-high	Dialogs, modals

6. Motion

Duration and easing tokens organized in 3 bands:

Duration	Value	Usage
--duration-fast	150ms	Hover, button press
--duration-normal	200ms	State change, standard
--duration-slow	300ms	Menu/dialog open

Always honor prefers-reduced-motion:

@media (prefers-reduced-motion: reduce) {
  .animated-element {
    transition-duration: 0.01ms !important;
  }
}

7. Icons

Astryx separates icon identity from SVG files using semantic names. Register your own icon set once at the entry point:

import { registerIcons } from '@astryxdesign/core/Icon';
import { XMarkIcon, ChevronDownIcon } from '@heroicons/react/24/outline';

registerIcons({
  close: <XMarkIcon />,
  chevronDown: <ChevronDownIcon />,
});

8. Illustrations

Illustrations are reserved for emotional/status communication — not decoration. Use them in empty states, onboarding, error states, and celebration screens:

<EmptyState
  illustration={<MyIllustration />}
  title="No results found"
  description="Try adjusting your search or filters"
  action={<Button label="Create new item" />}
/>

CLI Reference

View all tokens at any time:

npx astryx docs tokens
npx astryx docs tokens --dense   # compact for AI context
npx astryx docs color
npx astryx docs typography
npx astryx docs spacing
npx astryx docs shape
npx astryx docs elevation
npx astryx docs motion
npx astryx docs icons