Theme

Wraps a subtree with a specific Astryx theme. For static production themes, use astryx theme build and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime defineTheme() when themes are dynamic or for prototyping.

defineTheme accepts a tokens object whose keys are CSS custom property names (always prefixed with --). Common token names include --color-accent, --color-background-surface, --color-background-body, --color-text-primary, --color-text-secondary, --radius-container, --spacing-1 through --spacing-6. Values can be a string (same for light/dark) or a [light, dark] tuple.

Example:

import {defineTheme} from '@astryxdesign/core/theme';
const myTheme = defineTheme({
  name: 'ocean',
  tokens: {
    '--color-accent': ['#0077B6', '#48CAE4'],
    '--color-background-surface': ['#F0F8FF', '#0A1628'],
    '--color-text-primary': ['#0A1317', '#FFFFFF'],
    '--radius-container': '16px',
  },
});

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Media Theme

Provides token overrides for content rendered on inverted surfaces: media overlays, scrims, toasts, and tooltips. The base behavior flips color-scheme so all light-dark() tokens resolve to the correct side. Only a small set of tokens need explicit overrides beyond that. Themes can further customize component appearance on media surfaces via onDark/onLight in defineTheme(), with both token overrides (e.g. "--color-accent": "#90CAF9") and component overrides (e.g. ghost buttons get a border on dark surfaces).

Prop	Type	Default	Description
mode *	'dark' \| 'light' \| 'auto' \| 'off'		Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from the painted surface (no media context when the ambient text already reads on the surface at 3:1, otherwise the side that reads better), and off to turn it off explicitly. The element renders either way, so a surface can switch contexts without remounting children.
fallback	'dark' \| 'light'	'dark'	Which side auto uses when the surface cannot be measured: during SSR, on the first client frame, and whenever the backdrop is not knowable from CSS, most often a background-image, whose pixels need sampling (useImageMode) rather than a computed style. Ignored unless mode is auto.
children *	ReactNode		Content to render with inverted token context. Components inherit the correct colors automatically.

Usage guidance

Use for any content placed over a dark background (image overlays, video scrims, dark cards) or other inverted surfaces like toasts and tooltips.
Prefer mode="auto" when the surface color comes from a theme token. A token named "inverted" is not guaranteed to be inverted, and auto measures what was actually painted instead of trusting the name. It can even decide that a surface needs no media context at all.
Pair with a background color: MediaTheme flips the token context but does not add a background. Set backgroundColor on the parent element.
Themes can customize components on media surfaces via onDark.components and onLight.components in defineTheme(). For example, add a border to ghost buttons on dark surfaces.
Avoid: Use MediaTheme for app-level dark mode: use Theme with mode="dark" or mode="system" instead. MediaTheme is for local surface inversions, not page-wide color scheme.

Syntax Theme

Applies syntax highlighting colors to CodeBlock and any code component in the subtree. By default, code components use the theme-level syntax colors (set via defineTheme({ syntax: ... })), which derive from the palette (--color-text-accent for keywords, --color-text-green for strings, etc.). SyntaxTheme lets you override those per-region. The system uses 14 semantic tokens (keyword, string, comment, number, function, type, variable, operator, constant, tag, attribute, property, punctuation, background) validated against 11 community themes. Custom themes are created with defineSyntaxTheme() and can use [light, dark] tuples for automatic color-scheme adaptation. Built-in presets: oneDarkPro, dracula, monokai, nord, tokyoNight, catppuccinMocha, githubLight, githubDark, solarizedLight, oneLight (import from @astryxdesign/core/theme/syntax).

Prop	Type	Default	Description
theme *	SyntaxTheme		Syntax highlighting theme: a preset from @astryxdesign/core/theme/syntax or a custom theme created with defineSyntaxTheme().
children *	ReactNode		Content subtree. All CodeBlock components within will use this syntax theme.

Usage guidance

Use the syntax field in defineTheme() for app-wide code styling. Use SyntaxTheme only when a specific section needs a different look.
Pick from built-in presets or create a custom theme with defineSyntaxTheme() for brand-specific colors.
Syntax themes support light-dark() tuples: each token can have different values for light and dark mode, resolved automatically by the color scheme.
For a single CodeBlock, pass the syntaxTheme prop directly: it is shorthand for wrapping that block in SyntaxTheme. Use the SyntaxTheme wrapper when theming a whole region of code components.

Theme

Example:

import {defineTheme} from '@astryxdesign/core/theme';
const myTheme = defineTheme({
  name: 'ocean',
  tokens: {
    '--color-accent': ['#0077B6', '#48CAE4'],
    '--color-background-surface': ['#F0F8FF', '#0A1628'],
    '--color-text-primary': ['#0A1317', '#FFFFFF'],
    '--radius-container': '16px',
  },
});

Prop	Type	Default	Description
theme *	DefinedTheme		Theme object to apply. Prefer built theme objects for static production themes; use runtime `defineTheme()` for dynamic themes.
mode	'light' \| 'dark' \| 'system'	'system'	Color mode. System follows OS preference.
children *	ReactNode		Content to render with the theme.

Usage guidance

Build app themes that are known ahead of time with astryx theme build, then import the generated CSS and built theme object.
Use runtime themes when the theme is created or edited in the browser, such as theme editors, user branding, or prototypes.
Token names always start with -- (e.g. --color-accent, --color-background-surface). Do not omit the prefix.
Avoid: Default to runtime themes in SSR production apps. Component overrides inject after hydration instead of shipping as static CSS.

useTheme

Programmatic access to theme tokens for non-CSS consumers like SVG, canvas, Vega, D3, maps, or chart libraries that need values in JavaScript instead of CSS custom property references.

Returns

[
  {
    "name": "name",
    "type": "string",
    "description": "Name of the nearest theme, or default when no provider is present."
  },
  {
    "name": "mode",
    "type": "'light' | 'dark'",
    "description": "Resolved effective color mode. system mode is resolved to light or dark."
  },
  {
    "name": "token",
    "type": "(name: string) => string",
    "description": "Resolve a single design token to its current CSS value for the effective mode."
  },
  {
    "name": "tokens",
    "type": "Record<string, string>",
    "description": "All tokens resolved for the current mode, including defaults and theme overrides. Stable until the active theme or mode changes; uses the same resolution logic as resolveThemeTokens(theme, {mode})."
  }
]

Usage guidance

Use tokens or token(name) when integrating theme colors into SVG attributes, canvas drawing, chart options, or other non-CSS configuration objects inside React components.
Use resolveThemeTokens(theme, {mode}) for the same token resolution outside React hooks.
Prefer CSS variables or StyleX tokens for ordinary component styling; use this hook only when JavaScript needs token values.
Use data visualization tokens such as --color-data-categorical-blue for chart series instead of arbitrary UI colors.
Avoid: Hardcode light/dark colors in data visualizations: resolve them through the current theme instead.
Avoid: Assume the hook reflects every CSS cascade override. It resolves tokens for the current Theme mode; local media-surface overrides and arbitrary external CSS may not be represented.

Examples

MediaTheme — Media Overlay: A compact media overlay showing MediaTheme adapting text, icons, badges, and button variants over an image-backed dark surface.
SyntaxTheme — Compact Preset: A concise code block rendered with the One Dark Pro syntax preset to show how SyntaxTheme changes highlighting colors without making the page long.
Theme — Distinct Themes: Two visually distinct theme providers wrapping identical content to show how Theme changes the visual treatment of child components.
MediaTheme — Image Overlay: A common image card pattern: place text and actions over a dark gradient and wrap the overlay content in MediaTheme mode="dark".
MediaTheme — Light Scrim: A light scrim over an image. Use MediaTheme mode="light" so text and ghost buttons use dark-on-light tokens.
SyntaxTheme — Dark Preset: Wrap a code block in SyntaxTheme to apply a dark syntax preset such as Dracula.
SyntaxTheme — Light Preset: Use a light syntax preset for code examples that need to sit on light documentation surfaces.
Theme — Apply Theme: Wrap a subtree in Theme to apply a theme to every child component in that region.
Theme — Nested Theme: Nested Theme providers let a local region use a different theme without affecting the rest of the page.
Theme — Switch Themes: Use state to switch the theme object passed to Theme and preview a different visual treatment.
useTheme — Token Values: Read resolved theme token values with useTheme for non-CSS consumers like SVG charts.