Skip to content

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.md
new file mode 100644
index 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.
+@AKnassa
diff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjs
index 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.ts
index 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.ts
index 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.ts
index 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]),