主题 · Theme

使用主题令牌统一颜色、字体与形状，并保持明暗模式。

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

主题 · 综合展示 / 主题 1：首先体验这个示例，再查看代码理解组件的组合方式。
主题 · 综合展示 / 主题 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
主题 · 综合展示 / 主题 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
主题 · 主题 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
主题 · 主题 / 浅色 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
主题 · 主题 / 深色 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
主题 · 主题 / 浅色 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
主题 · 主题 8：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
主题 · 主题 9：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
主题 · 主题 10：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
主题 · 主题 11：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

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).

属性	类型	默认值	说明
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.

使用建议

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.
避免：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).

属性	类型	默认值	说明
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.

使用建议

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

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',
  },
});

属性	类型	默认值	说明
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.

使用建议

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.
避免：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})."
  }
]

使用建议

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.
避免：Hardcode light/dark colors in data visualizations: resolve them through the current theme instead.
避免：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.