Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(text): make text color theme-extensible via TextColorMap (#4577)

freddymeta531fb34955fb
diff --git a/.changeset/text-color-extensible.md b/.changeset/text-color-extensible.md
new file mode 100644
index 0000000000..d0149814fa
--- /dev/null
+++ b/.changeset/text-color-extensible.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Text & Heading: `color` is now theme-extensible. `TextColor` is derived from a new `TextColorMap` interface (same technique as `ButtonVariantMap` etc.), so a theme can add custom text colors — `astryx theme build` generates the module augmentation when it sees new `color:*` values on Text/Heading overrides, and consumers can augment `TextColorMap` manually for type safety. A custom color renders as a stable class (`astryx-text.<color>` / `astryx-heading.<color>`) that theme CSS paints, falling back to the `primary` StyleX baseline so it never renders unstyled. Built-in colors are unchanged.
+@freddymeta
diff --git a/packages/core/src/Heading/Heading.tsx b/packages/core/src/Heading/Heading.tsx
index 6fecd530c1..7df9ba8dd9 100644
--- a/packages/core/src/Heading/Heading.tsx
+++ b/packages/core/src/Heading/Heading.tsx
@@ -41,6 +41,7 @@ import {
truncationTooltipStyles,
} from '../Text/text.stylex';
import {useTruncation} from '../Text/useTruncation';
+import {resolveStyleColor} from '../Text/Text';
import type {LayerPlacement} from '../Layer';
import {mergeProps, mergeRefs} from '../utils';
import type {BaseProps} from '../BaseProps';
@@ -251,7 +252,7 @@ export function Heading({
{...mergeProps(
themeProps('heading', {level, color, ...(type && {type})}),
stylex.props(
- colorStyles[color],
+ colorStyles[resolveStyleColor(color)],
type ? sizeByTypeStyles[type] : sizeByLevelStyles[level],
type && defaultWeightByTypeStyles[type],
// Display: use truncation styles when maxLines > 0
diff --git a/packages/core/src/Text/Heading.doc.mjs b/packages/core/src/Text/Heading.doc.mjs
index da4923d5c2..45ab84fbe6 100644
--- a/packages/core/src/Text/Heading.doc.mjs
+++ b/packages/core/src/Text/Heading.doc.mjs
@@ -33,7 +33,7 @@ export const docs = {
{
name: 'color',
type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
- description: 'Text color.',
+ description: 'Text color. Themes may add custom colors.',
default: "'primary'",
},
{
@@ -120,7 +120,7 @@ export const docsZh = {
{
name: 'color',
type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
- description: '文本颜色。',
+ description: '文本颜色。主题可添加自定义颜色。',
default: "'primary'",
},
{
@@ -186,7 +186,7 @@ export const docsDense = {
type: 'Display variant (display-1/2/3); overrides visual styling from level with display-scale sizing.',
children: 'Heading content.',
accessibilityLevel: 'aria-level override when different from level for document outline.',
- color: 'Text color.',
+ color: 'Text color. Themes may add custom colors.',
display: "Display type; overridden to 'block' when maxLines>0 or hasCapsize.",
maxLines: 'Max lines before truncation; 0=none. Shows tooltip if truncated.',
hasTruncateTooltip: "Tooltip for truncated text; true=default position, false=disabled, or a placement ('above' | 'below' | 'start' | 'end').",
diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjs
index 91e356aec9..e083c10758 100644
--- a/packages/core/src/Text/Text.doc.mjs
+++ b/packages/core/src/Text/Text.doc.mjs
@@ -41,7 +41,7 @@ export const docs = {
{
name: 'color',
type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
- description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others.",
+ description: "Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others. Themes may add custom colors.",
},
{
name: 'weight',
diff --git a/packages/core/src/Text/Text.test.tsx b/packages/core/src/Text/Text.test.tsx
index d360ac31cd..043329718f 100644
--- a/packages/core/src/Text/Text.test.tsx
+++ b/packages/core/src/Text/Text.test.tsx
@@ -9,6 +9,7 @@ import {render, screen} from '@testing-library/react';
import {describe, it, expect} from 'vitest';
import {Text} from './Text';
import type {TextType} from './Text';
+import type {TextColor} from '../theme/types';
describe('Text', () => {
describe('rendering', () => {
@@ -233,3 +234,44 @@ describe('Text custom types', () => {
expect(screen.getByText('Muted').className).toContain('secondary');
});
});
+
+describe('Text custom colors', () => {
+ it('renders a custom color as a stable class for theme CSS to target', () => {
+ // A theme adds a custom color (e.g. via TextColorMap augmentation +
+ // defineTheme). The rendered element carries the color as a class
+ // (astryx-text.<color>) so `.astryx-text.brand { color: ... }` from the
+ // theme applies — mirroring how custom `type`s work.
+ render(<Text color={'brand' as TextColor}>Branded</Text>);
+ const el = screen.getByText('Branded');
+ expect(el.className).toContain('astryx-text');
+ expect(el.className).toContain('brand');
+ });
+
+ it('does not crash on a custom color (falls back to the primary StyleX baseline)', () => {
+ // colorStyles has no entry for a custom color; the component must resolve a
+ // built-in baseline instead of indexing undefined. Built-in `primary` is
+ // the baseline, so both share its StyleX color class.
+ render(
+ <>
+ <Text color={'brand' as TextColor}>Custom</Text>
+ <Text color="primary">Builtin</Text>
+ </>,
+ );
+ const custom = screen.getByText('Custom');
+ const builtin = screen.getByText('Builtin');
+ // Neither throws, and the custom color reuses primary's baseline StyleX
+ // class (the real color comes from theme CSS via the `brand` class).
+ const primaryAtomic = builtin.className
+ .split(/\s+/)
+ .filter(c => c.startsWith('x'));
+ expect(primaryAtomic.length).toBeGreaterThan(0);
+ for (const cls of primaryAtomic) {
+ expect(custom.className).toContain(cls);
+ }
+ });
+
+ it('still applies built-in colors directly', () => {
+ render(<Text color="accent">Accent</Text>);
+ expect(screen.getByText('Accent').className).toContain('accent');
+ });
+});
diff --git a/packages/core/src/Text/Text.tsx b/packages/core/src/Text/Text.tsx
index d6be12f894..18d983065b 100644
--- a/packages/core/src/Text/Text.tsx
+++ b/packages/core/src/Text/Text.tsx
@@ -23,6 +23,7 @@ import type {
BuiltinTextType,
TextSize,
TextColor,
+ BuiltinTextColor,
TextWeight,
TextDisplay,
TextJustify,
@@ -185,6 +186,24 @@ function resolveStyleType(type: TextType): BuiltinTextType {
return 'body';
}
+/**
+ * Resolve the StyleX baseline color. Built-in colors map to their own color
+ * style; custom (theme-defined) colors fall back to the `primary` baseline —
+ * their actual color comes from theme CSS (`.astryx-text.<color>` /
+ * `.astryx-heading.<color>`), which the rendered `color` class targets.
+ *
+ * Exported so Heading applies the same custom-color fallback as Text.
+ */
+export function resolveStyleColor(color: TextColor): BuiltinTextColor {
+ // The `in` guard is a runtime check for consumer-augmented custom colors
+ // (which widen `TextColor` beyond the built-ins via TextColorMap); within
+ // core the two types coincide, so no cast is needed.
+ if (color in colorStyles) {
+ return color;
+ }
+ return 'primary';
+}
+
/**
* Semantic text component. Renders text with type-based styling from the theme.
*
@@ -228,6 +247,11 @@ export function Text({
// Resolve style type — custom types fall back to 'body' for StyleX baseline
const styleType = resolveStyleType(type);
+ // Resolve style color — custom colors fall back to 'primary' for StyleX
+ // baseline; the real color comes from theme CSS via the rendered `color`
+ // class (see themeProps below).
+ const styleColor = resolveStyleColor(resolvedColor);
+
// Resolve wordBreak with smart default
const resolvedWordBreak =
wordBreak ?? (maxLines === 1 ? 'break-all' : 'break-word');
@@ -257,7 +281,7 @@ export function Text({
{...mergeProps(
themeProps('text', {type, size, color: resolvedColor}),
stylex.props(
- colorStyles[resolvedColor],
+ colorStyles[styleColor],
sizeByTypeStyles[styleType],
size && sizeStyles[size],
defaultWeightByTypeStyles[styleType],
diff --git a/packages/core/src/Text/index.ts b/packages/core/src/Text/index.ts
index 1d2d24b698..d30dffe935 100644
--- a/packages/core/src/Text/index.ts
+++ b/packages/core/src/Text/index.ts
@@ -7,12 +7,7 @@
* @position Entry point for Text components
*/
-export {
- Text,
- type TextProps,
- type TextType,
- type TextSize,
-} from './Text';
+export {Text, type TextProps, type TextType, type TextSize} from './Text';
export {
Heading,
type HeadingProps,
@@ -23,6 +18,7 @@ export {
// Re-export shared types from theme for convenience
export type {
TextColor,
+ TextColorMap,
TextWeight,
TextDisplay,
TextJustify,
diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.ts
index 00cf1a0ac3..e59df27d97 100644
--- a/packages/core/src/theme/index.ts
+++ b/packages/core/src/theme/index.ts
@@ -71,19 +71,13 @@ export {expandTypeScale, generateTypeScaleComponents} from './expandTypeScale';
export type {TypeScaleConfig, TypeScaleTokens} from './expandTypeScale';
export {expandRadiusScale} from './expandRadiusScale';
-export type {
- RadiusScaleConfig,
- RadiusScaleTokens,
-} from './expandRadiusScale';
+export type {RadiusScaleConfig, RadiusScaleTokens} from './expandRadiusScale';
export {expandColorScale} from './expandColorScale';
export type {ColorScaleConfig, ColorScaleTokens} from './expandColorScale';
export {expandMotionScale} from './expandMotionScale';
-export type {
- MotionScaleConfig,
- MotionScaleTokens,
-} from './expandMotionScale';
+export type {MotionScaleConfig, MotionScaleTokens} from './expandMotionScale';
// Export token defaults and vars for use in custom components and themes
export {
@@ -155,6 +149,8 @@ export type {
TextSize,
TextWeight,
TextColor,
+ BuiltinTextColor,
+ TextColorMap,
TypographyConfig,
TypographyRole,
FontWeight,
diff --git a/packages/core/src/theme/types.ts b/packages/core/src/theme/types.ts
index aa618cdabd..dd1f40fd11 100644
--- a/packages/core/src/theme/types.ts
+++ b/packages/core/src/theme/types.ts
@@ -15,11 +15,7 @@
* Raw CSS values (e.g. '800') are accepted as an escape hatch.
*/
export type FontWeight =
- | 'normal'
- | 'medium'
- | 'semibold'
- | 'bold'
- | (string & {});
+ 'normal' | 'medium' | 'semibold' | 'bold' | (string & {});
/**
* A typography role declaration (body, heading, or code).
@@ -155,15 +151,49 @@ export type TextSize =
export type TextWeight = 'normal' | 'medium' | 'semibold' | 'bold';
/**
- * Text color variants for Text/Heading
+ * Extensible map of text color variants for Text/Heading.
+ *
+ * Themes add custom colors via component overrides in defineTheme; a custom
+ * color renders with the `primary` baseline color from StyleX and receives its
+ * actual color from theme CSS (`.astryx-text.<color>` / `.astryx-heading.<color>`),
+ * exactly like custom text `type`s.
+ *
+ * To add type-safe custom colors, use module augmentation — the same technique
+ * as `ButtonVariantMap` etc.:
+ * ```ts
+ * declare module '@astryxdesign/core/Text' {
+ * interface TextColorMap {
+ * brand: true;
+ * danger: true;
+ * }
+ * }
+ * ```
+ *
+ * `astryx theme build` generates these augmentations automatically when it
+ * detects new `color:*` values in a theme's Text/Heading component overrides.
*/
-export type TextColor =
- | 'primary'
- | 'secondary'
- | 'disabled'
- | 'placeholder'
- | 'accent'
- | 'inherit';
+export interface TextColorMap {
+ primary: true;
+ secondary: true;
+ disabled: true;
+ placeholder: true;
+ accent: true;
+ inherit: true;
+}
+
+/**
+ * Built-in text color variants for Text/Heading. The concrete keys that ship
+ * with the design system, independent of theme augmentation — used where a
+ * value must be one of the real StyleX color styles (see `resolveStyleColor`).
+ */
+export type BuiltinTextColor =
+ 'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit';
+
+/**
+ * Text color variants for Text/Heading. Extensible via module augmentation of
+ * `TextColorMap`.
+ */
+export type TextColor = keyof TextColorMap;
/**
* Display mode for Text/Heading