An open source design system that's fully customizable and agent ready
TypeScript
feat(theme): make color.accent optional in defineTheme (#2279) (#3916)
AK0fe271dc78a4
diff --git a/.changeset/define-theme-optional-accent.md b/.changeset/define-theme-optional-accent.mdnew file mode 100644index 0000000000..e20f32e1bc--- /dev/null+++ b/.changeset/define-theme-optional-accent.md@@ -0,0 +1,9 @@+---+'@astryxdesign/core': patch+'@astryxdesign/cli': patch+---++[feat] `defineTheme`: make `color.accent` optional (#2279)++A theme can now restyle the neutral ramp (`neutralStyle`, `contrast`) without adopting an accent. An accent-less config seeds the neutral palettes from the default accent's hue but leaves `--color-accent`, `--color-accent-muted` and `--color-on-accent` ungenerated, so they fall through to the token defaults — the same fall-through `expandColorScale` already applies to status, categorical and on-dark tokens. Configs that pass an accent are unchanged, token for token.+@AKnassadiff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjsindex 6ea12ede2f..a14dab4e4a 100644--- a/packages/cli/docs/theme.doc.mjs+++ b/packages/cli/docs/theme.doc.mjs@@ -191,7 +191,7 @@ const myTheme = defineTheme({['color','--color-accent, --color-background-*, --color-text-*, --color-border, etc.',- 'accent (hex), neutralStyle? (warm|cool|neutral), contrast? (standard|high)',+ 'accent? (hex — omit for neutral-only), neutralStyle? (warm|cool|neutral), contrast? (standard|high)',],['typography.scale',diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.tsindex 737178b137..e28c67cc18 100644--- a/packages/core/src/theme/defineTheme.ts+++ b/packages/core/src/theme/defineTheme.ts@@ -239,9 +239,15 @@ export interface DefineThemeInput {* categorical hues, and fixed tokens (on-dark/on-light) use defaults.* Explicit `tokens` entries always take precedence.*+ * `accent` is optional — omit it for a neutral-only theme, which keeps+ * the default accent tokens and only themes the neutrals.+ ** @example* ```tsx* color: { accent: '#0064E0', neutralStyle: 'cool', contrast: 'standard' }+ *+ * // Neutral-only — accent tokens stay at their defaults+ * color: { neutralStyle: 'warm' }* ```*/color?: ColorScaleConfig;diff --git a/packages/core/src/theme/expandColorScale.test.ts b/packages/core/src/theme/expandColorScale.test.tsindex f37ce37399..607ef81815 100644--- a/packages/core/src/theme/expandColorScale.test.ts+++ b/packages/core/src/theme/expandColorScale.test.ts@@ -4,6 +4,19 @@ import {describe, it, expect} from 'vitest';import {expandColorScale} from './expandColorScale';import {defineTheme} from './defineTheme';import {generateThemeRules} from './generateThemeRules';+import {resolveThemeTokens} from './tokens';+import {colorDefaults} from './tokens.stylex';++/** Light-mode half of colorDefaults['--color-accent'] — the hue an accent-less config seeds from. */+const DEFAULT_ACCENT = '#0064E0';+const DEFAULT_ACCENT_DARK = '#2694FE';++/** The three tokens that only exist when a seed accent is supplied. */+const ACCENT_TOKENS = [+ '--color-accent',+ '--color-accent-muted',+ '--color-on-accent',+] as const;describe('expandColorScale', () => {it('produces all expected token keys', () => {@@ -86,6 +99,82 @@ describe('expandColorScale', () => {});});+describe('expandColorScale — neutral-only themes (#2279)', () => {+ it('accent is optional — a config without one expands', () => {+ const tokens = expandColorScale({neutralStyle: 'warm'});+ expect(tokens['--color-background-surface']).toMatch(/^light-dark\(#/);+ });++ it('expands an empty config', () => {+ const tokens = expandColorScale({});+ expect(tokens['--color-background-surface']).toMatch(/^light-dark\(#/);+ expect(tokens).not.toHaveProperty('--color-accent');+ });++ it('omits the accent tokens so they fall through to colorDefaults', () => {+ const tokens = expandColorScale({neutralStyle: 'warm'});+ for (const key of ACCENT_TOKENS) {+ expect(tokens).not.toHaveProperty(key);+ }+ // ...and the reference tokens still point at whatever --color-accent resolves to.+ expect(tokens['--color-text-accent']).toBe('var(--color-accent)');+ expect(tokens['--color-icon-accent']).toBe('var(--color-accent)');+ });++ it('seeds the neutral palettes from the light half of the default accent', () => {+ // Drift guard: the module's DEFAULT_ACCENT_SEED is private, so pin the+ // colorDefaults value it is copied from. Re-coloring the default accent+ // without re-seeding would silently change every neutral-only theme.+ expect(colorDefaults['--color-accent']).toBe(+ `light-dark(${DEFAULT_ACCENT}, ${DEFAULT_ACCENT_DARK})`,+ );++ const neutralOnly = expandColorScale({neutralStyle: 'warm'});+ const seeded = expandColorScale({+ accent: DEFAULT_ACCENT,+ neutralStyle: 'warm',+ });+ for (const [key, value] of Object.entries(seeded)) {+ if ((ACCENT_TOKENS as ReadonlyArray<string>).includes(key)) {+ continue;+ }+ expect(neutralOnly[key], key).toBe(value);+ }+ });++ it('honours neutralStyle and contrast without an accent', () => {+ const warm = expandColorScale({neutralStyle: 'warm'});+ const cool = expandColorScale({neutralStyle: 'cool'});+ expect(warm['--color-neutral']).not.toBe(cool['--color-neutral']);++ const high = expandColorScale({contrast: 'high'});+ const standard = expandColorScale({contrast: 'standard'});+ expect(high['--color-text-primary']).not.toBe(+ standard['--color-text-primary'],+ );+ });++ it('does not re-color themes that do pass an accent', () => {+ // Seeding from the default hex derives a DIFFERENT accent than the default+ // token holds, so "just default the seed" is not behavior-preserving —+ // omitting the tokens is the only way a neutral-only theme keeps the+ // default accent.+ const tokens = expandColorScale({accent: DEFAULT_ACCENT});+ expect(tokens['--color-accent']).toMatch(/^light-dark\(#/);+ expect(tokens['--color-accent']).not.toBe(colorDefaults['--color-accent']);+ });++ it('treats an empty accent as supplied, not absent', () => {+ // '' is falsy but not nullish. Only an absent accent is neutral-only; a+ // supplied-but-malformed one keeps its pre-#2279 behavior (the hex parser+ // falls back to black) rather than silently dropping the accent tokens.+ const tokens = expandColorScale({accent: ''});+ for (const key of ACCENT_TOKENS) {+ expect(tokens).toHaveProperty(key);+ }+ });+});+describe('expandColorScale + defineTheme integration', () => {it('explicit token overrides win over generated values', () => {const theme = defineTheme({@@ -110,4 +199,59 @@ describe('expandColorScale + defineTheme integration', () => {// The base token itself stays a resolved color pair.expect(css).toMatch(/--color-accent: light-dark\(#/);});++ it('a neutral-only theme leaves the accent tokens at their defaults (#2279)', () => {+ const theme = defineTheme({+ name: 'test-neutral-only',+ color: {neutralStyle: 'warm'},+ });+ for (const key of ACCENT_TOKENS) {+ expect(theme.tokens).not.toHaveProperty(key);+ }+ // Neutrals are still themed.+ expect(theme.tokens['--color-background-surface']).toMatch(+ /^light-dark\(#/,+ );++ const css = generateThemeRules(theme).join('\n');+ expect(css).not.toContain('--color-accent:');+ expect(css).not.toContain('--color-on-accent:');+ expect(css).toContain('--color-background-surface:');+ });++ it('a neutral-only theme resolves accent tokens to the defaults at runtime (#2279)', () => {+ // The CSS side falls through by simply not emitting the tokens. The JS side+ // (useTheme/resolveThemeTokens) has to agree: the omitted tokens come back+ // from tokenDefaults, and the var() references the theme DOES emit resolve+ // against them instead of leaking a literal 'var(--color-accent)'.+ const theme = defineTheme({+ name: 'test-neutral-only-runtime',+ color: {neutralStyle: 'warm'},+ });++ const light = resolveThemeTokens(theme, {mode: 'light'});+ expect(light['--color-accent']).toBe(DEFAULT_ACCENT);+ expect(light['--color-text-accent']).toBe(DEFAULT_ACCENT);+ expect(light['--color-icon-accent']).toBe(DEFAULT_ACCENT);++ const dark = resolveThemeTokens(theme, {mode: 'dark'});+ expect(dark['--color-accent']).toBe(DEFAULT_ACCENT_DARK);+ expect(dark['--color-text-accent']).toBe(DEFAULT_ACCENT_DARK);+ });++ it('an explicit accent token still wins on a neutral-only theme (#2279)', () => {+ // Neutral scale from HCT + a hand-picked accent: the tokens map is the only+ // source of --color-accent, so the reference tokens follow it.+ const theme = defineTheme({+ name: 'test-neutral-only-explicit-accent',+ color: {neutralStyle: 'warm'},+ tokens: {'--color-accent': ['#AA0000', '#FF5555']},+ });+ expect(+ resolveThemeTokens(theme, {mode: 'light'})['--color-text-accent'],+ ).toBe('#AA0000');++ const css = generateThemeRules(theme).join('\n');+ expect(css).toContain('--color-text-accent: var(--color-accent);');+ });});diff --git a/packages/core/src/theme/expandColorScale.ts b/packages/core/src/theme/expandColorScale.tsindex 0c9effafd6..2795786bd6 100644--- a/packages/core/src/theme/expandColorScale.ts+++ b/packages/core/src/theme/expandColorScale.ts@@ -2,7 +2,7 @@/*** @file expandColorScale.ts- * @input Color scale configuration { accent, neutralStyle?, contrast? }+ * @input Color scale configuration { accent?, neutralStyle?, contrast? }* @output Token overrides for derivable color tokens* @position Theme utility; consumed by defineTheme.ts*@@ -11,6 +11,10 @@* derive from the accent — status colors, categorical hues, and fixed* tokens (on-dark/on-light) fall through to colorDefaults.*+ * `accent` is optional: a neutral-only config still gets the full neutral+ * ramp (seeded from the default accent's hue) while the accent tokens+ * themselves fall through to colorDefaults, same as the tokens above.+ ** SYNC: When modified, update:* - /packages/core/src/theme/defineTheme.ts*/@@ -31,11 +35,21 @@ import {hexToHct, tonalPalette, hexWithAlpha} from './hct';** // With customization* { accent: '#B7410E', neutralStyle: 'warm', contrast: 'high' }+ *+ * // Neutral-only — keeps the default accent, themes the neutrals+ * { neutralStyle: 'warm' }* ```*/export interface ColorScaleConfig {- /** Seed accent color as hex (#RRGGBB). Everything derives from this. */- accent: string;+ /**+ * Seed accent color as hex (#RRGGBB). Everything derives from this.+ *+ * Optional. When omitted, the neutral palettes are seeded from the+ * default accent's hue and the accent tokens (--color-accent,+ * --color-accent-muted, --color-on-accent) are not generated — they+ * fall through to colorDefaults.+ */+ accent?: string;/*** Neutral tone warmth. Controls how much of the seed's hue bleeds@@ -69,6 +83,14 @@ const NEUTRAL_VARIANT_CHROMA: Record<string, number> = {neutral: 6,};+/**+ * Hue source for accent-less configs — the light half of+ * colorDefaults['--color-accent'] (a test guards the two against drift).+ * Only its hue reaches the output: the accent tokens stay ungenerated, so+ * they keep their colorDefaults values rather than this seed's derivation.+ */+const DEFAULT_ACCENT_SEED = '#0064E0';+// =============================================================================// Computation// =============================================================================@@ -89,18 +111,23 @@ function accentWithAlpha(alpha: number): string {* --color-on-dark/on-light) are NOT generated — they fall through* to colorDefaults.*+ * Without an `accent`, the accent tokens join that fall-through set: the+ * neutrals are seeded from the default accent's hue, and --color-accent,+ * --color-accent-muted and --color-on-accent keep their colorDefaults values.+ ** @example* ```* const tokens = expandColorScale({ accent: '#0064E0' });* // tokens['--color-accent'] === 'light-dark(#..., #...)'+ *+ * const neutralOnly = expandColorScale({ neutralStyle: 'warm' });+ * // neutralOnly['--color-accent'] === undefined* ```*/-export function expandColorScale(- config: ColorScaleConfig,-): ColorScaleTokens {+export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {const {accent, neutralStyle = 'cool', contrast = 'standard'} = config;- const seed = hexToHct(accent);+ const seed = hexToHct(accent ?? DEFAULT_ACCENT_SEED);const seedHue = seed.hue;const primaryChroma = Math.max(seed.chroma, 48);@@ -119,14 +146,25 @@ export function expandColorScale(const textSecondaryDarkTone = isHigh ? 80 : 70;return {- // Core semantic- '--color-accent': ld(P[40], P[80]),- // Derived accent tokens reference --color-accent instead of baking its- // resolved hex, so a scoped override of the base token re-accents the- // whole subtree at runtime. --color-on-accent stays baked: it is a- // contrast computation against the accent, which CSS cannot express.- '--color-accent-muted': ld(accentWithAlpha(0.2), accentWithAlpha(0.25)),- '--color-on-accent': ld(P[100], P[20]),+ // Core semantic — only with a seed accent. Without one these fall through+ // to colorDefaults, whose --color-accent is NOT what the default seed+ // derives: defaulting the seed instead of omitting the tokens would+ // recolor every neutral-only theme. Nullish and not truthy, matching the+ // seed above, so a supplied-but-malformed accent keeps its old behavior.+ ...(accent != null+ ? {+ '--color-accent': ld(P[40], P[80]),+ // Derived accent tokens reference --color-accent instead of baking its+ // resolved hex, so a scoped override of the base token re-accents the+ // whole subtree at runtime. --color-on-accent stays baked: it is a+ // contrast computation against the accent, which CSS cannot express.+ '--color-accent-muted': ld(+ accentWithAlpha(0.2),+ accentWithAlpha(0.25),+ ),+ '--color-on-accent': ld(P[100], P[20]),+ }+ : null),'--color-neutral': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[90], 0.2)),'--color-background-surface': ld(N[99], N[10]),'--color-background-body': ld(N[95], N[5]),