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.mdnew file mode 100644index 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.+@freddymetadiff --git a/packages/core/src/Heading/Heading.tsx b/packages/core/src/Heading/Heading.tsxindex 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 > 0diff --git a/packages/core/src/Text/Heading.doc.mjs b/packages/core/src/Text/Heading.doc.mjsindex 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.mjsindex 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.tsxindex 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.tsxindex 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 baselineconst 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 defaultconst 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.tsindex 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 convenienceexport type {TextColor,+ TextColorMap,TextWeight,TextDisplay,TextJustify,diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.tsindex 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 themesexport {@@ -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.tsindex 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