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.

Theme packages may expose approved tonal palettes as authoring metadata. Agents and application code should still choose semantic tokens first. Numbered palette stops are a controlled fallback for theme definitions, custom visualizations, and gaps where no semantic role fits—not permission to choose arbitrary colors.

Surface Colors

Layered surface hierarchy: body → surface → card → popover. Each level sits visually above the previous one.

TokenValue
--color-accent
#262626 / #e7e7e7
--color-accent-muted
#f1f1f1 / #262626
--color-on-accent
#ffffff / #1b1b1b
--color-neutral
#0000000F / #ffffff1A
--color-background-surface
#ffffff / #262626
--color-background-body
#f1f1f1 / #1b1b1b
--color-overlay
#00000080 / #000000CC
--color-overlay-hover
#0000000D / #ffffff0D
--color-overlay-pressed
#0000001A / #ffffff1A
--color-background-muted
#f1f1f1 / #1b1b1b
--color-text-primary
#1b1b1b / #f1f1f1
--color-text-secondary
#525252 / #9e9e9e
--color-text-disabled
#9e9e9e / #525252
--color-text-accent
#262626 / #e7e7e7
--color-on-dark
#ffffff
--color-on-light
#1b1b1b
--color-icon-accent
#262626 / #e7e7e7
--color-icon-primary
#1b1b1b / #f1f1f1
--color-icon-secondary
#777777 / #9e9e9e
--color-icon-disabled
#9e9e9e / #525252
--color-background-card
#ffffff / #1b1b1b
--color-background-popover
#ffffff / #1b1b1b
--color-background-inverted
#0A1317 / #FFFFFF
--color-background-error-inverted
#AA071E / #E3193B
--color-success
#005711 / #bedfbe
--color-success-muted
#bbe1bb / #8ecb8f3D
--color-on-success
#ffffff / #1b1b1b
--color-error
#76000c / #fbd3cf
--color-error-muted
#ffd8d3 / #f99c943D
--color-on-error
#ffffff / #1b1b1b
--color-warning
#584400 / #f4d170
--color-warning-muted
#f9e19e / #e1b3003D
--color-on-warning
#1b1b1b
--color-border
#00000014 / #ffffff1A
--color-border-emphasized
#d4d4d4 / #525252
--color-skeleton
#e2e2e2 / #525252
--color-track
#CCD3DB / #5A5E66
--color-shadow
#0000001A / #0000004D
--color-tint-hover
black / white
--color-background-blue
#d0e5ff / #87bcff3D
--color-border-blue
#a0caff / #529fff
--color-icon-blue
#00458c / #87bcff
--color-text-blue
#00458c / #b8d7ff
--color-background-cyan
#c2eaf5 / #50cbe73D
--color-border-cyan
#71d7ef / #00b1ce
--color-icon-cyan
#00505f / #50cbe7
--color-text-cyan
#00505f / #a7dfed
--color-background-gray
#e2e2e2 / var(--color-neutral)
--color-border-gray
#d4d4d4 / #262626
--color-icon-gray
#525252 / #9e9e9e
--color-text-gray
#262626 / #e7e7e7
--color-background-green
#d2ead2 / #8ecb8f3D
--color-border-green
#a1d7a1 / #53b75a
--color-icon-green
#005711 / #8ecb8f
--color-text-green
#005711 / #bedfbe
--color-background-orange
#faddc2 / #eea75f3D
--color-border-orange
#f7b87a / #df8600
--color-icon-orange
#673a00 / #eea75f
--color-text-orange
#673a00 / #f4cca7
--color-background-pink
#fad7e4 / #ee9cbd3D
--color-border-pink
#f7adc9 / #e86ea3
--color-icon-pink
#82004b / #ee9cbd
--color-text-pink
#82004b / #f4c6d6
--color-background-purple
#f0dbf4 / #d7a3e33D
--color-border-purple
#e1b3ed / #c979dc
--color-icon-purple
#6f0782 / #d7a3e3
--color-text-purple
#6f0782 / #e6c9ec
--color-background-red
#ffd8d3 / #f99c943D
--color-border-red
#ffaea7 / #f76a65
--color-icon-red
#8a0011 / #f99c94
--color-text-red
#76000c / #fbd3cf
--color-background-teal
#c3ede3 / #55d1bb3D
--color-border-teal
#76dcc9 / #00b7a1
--color-icon-teal
#005348 / #55d1bb
--color-text-teal
#005348 / #a8e2d6
--color-background-yellow
#f9e19e / #e1b3003D
--color-border-yellow
#f1c000 / #c09800
--color-icon-yellow
#584400 / #e1b300
--color-text-yellow
#584400 / #f4d170
--color-syntax-keyword
#6f0782 / #e6c9ec
--color-syntax-string
#005711 / #bedfbe
--color-syntax-comment
#777777 / #9e9e9e
--color-syntax-number
#673a00 / #f4cca7
--color-syntax-function
#00458c / #b8d7ff
--color-syntax-type
#6f0782 / #e6c9ec
--color-syntax-variable
#1b1b1b / #e2e2e2
--color-syntax-operator
#777777 / #9e9e9e
--color-syntax-constant
#673a00 / #f4cca7
--color-syntax-tag
#8a0011 / #fac5c0
--color-syntax-attribute
#584400 / #f4d170
--color-syntax-property
#005348 / #a8e2d6
--color-syntax-punctuation
#6e6e6e / #a0a0a0
--color-syntax-background
#f1f1f1 / #111111
--color-data-categorical-blue
#0171E3
--color-data-categorical-orange
#EB6E00
--color-data-categorical-purple
#6B1EFD
--color-data-categorical-green
#0B991F
--color-data-categorical-pink
#F351C0
--color-data-categorical-cyan
#0171A4
--color-data-categorical-red
#F5394F
--color-data-categorical-teal
#08A3A3
--color-data-categorical-brown
#965E03
--color-data-categorical-indigo
#6F8AFF
--color-data-neutral
#8494A3 / #8C939B
--color-data-blue-5
#02165E
--color-data-blue-4
#004CBC
--color-data-blue-3
#2694FE
--color-data-blue-2
#78BEFF
--color-data-blue-1
#DBECFF
--color-data-shamrock-5
#0B603D
--color-data-shamrock-4
#138546
--color-data-shamrock-3
#24BB5E
--color-data-shamrock-2
#8EF7AA
--color-data-shamrock-1
#D6FEE4
--color-data-orange-5
#A13F04
--color-data-orange-4
#D66100
--color-data-orange-3
#FD9537
--color-data-orange-2
#FDB876
--color-data-orange-1
#FFE6CF
--color-data-pink-5
#8E1073
--color-data-pink-4
#D123A1
--color-data-pink-3
#F989D3
--color-data-pink-2
#FEADE3
--color-data-pink-1
#FCE3F4
--color-data-purple-5
#3E0697
--color-data-purple-4
#6B1EFD
--color-data-purple-3
#9081FF
--color-data-purple-2
#B3B0FE
--color-data-purple-1
#E8E8FB
--color-data-red-5
#9D0519
--color-data-red-4
#D31130
--color-data-red-3
#FB7D87
--color-data-red-2
#FFB2B8
--color-data-red-1
#FEE4E6
--color-data-teal-5
#08767D
--color-data-teal-4
#0C9293
--color-data-teal-3
#0DB7AF
--color-data-teal-2
#6CE6D8
--color-data-teal-1
#D7FCF8
--color-data-yellow-5
#8A5001
--color-data-yellow-4
#D69804
--color-data-yellow-3
#FBCE03
--color-data-yellow-2
#FCEC85
--color-data-yellow-1
#FDF6BA
--color-data-gray-5
#25363F / #333338
--color-data-gray-4
#5D6C7B / #666A72
--color-data-gray-3
#AFB9C4 / #B2B8BE
--color-data-gray-2
#CCD3DB / #D0D3D6
--color-data-gray-1
#F1F4F7 / #F2F4F6
--color-brand

Usage

Applying color tokens
tsx
import * as stylex from '@stylexjs/stylex';
import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';
​
const styles = stylex.create({
  container: {
    backgroundColor: colorVars['--color-background-surface'],
    color: colorVars['--color-text-primary'],
    borderColor: colorVars['--color-border'],
  },
  accent: {
    color: colorVars['--color-text-accent'],
  },
});

Best Practices

GuidancePractices
Do

Use semantic tokens (--color-text-primary) instead of raw hex values.

Do

When authoring a theme and no semantic token fits, use an exact numbered stop from its approved palette and record the family, mode, stop, and contrast relationship (for example, blue light-mode stop 45 via palette.blue.light[45]).

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

Invent or approximate a color when the active theme exposes an approved numbered stop for that role.

Don't

Mix accent colors with status colors in the same context.

Don't

Use --color-on-accent on non-accent backgrounds.