Skip to content

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

TypeScript

fix(theme-stone): raise secondary text contrast (#5509)

Jiun Shin78982073ec42
diff --git a/.changeset/stone-secondary-text-aa.md b/.changeset/stone-secondary-text-aa.md
new file mode 100644
index 0000000000..d8c7fd7515
--- /dev/null
+++ b/.changeset/stone-secondary-text-aa.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/theme-stone': patch
+---
+
+[fix] Stone theme: move `--color-text-secondary` to the canonical T40/T70 pair so normal secondary text meets WCAG AA across the theme's light and dark consumer surfaces (#5505)
+@jiunshinn
diff --git a/packages/cli/assets/templates/themes/stone/stoneTheme.ts b/packages/cli/assets/templates/themes/stone/stoneTheme.ts
index b1dfa63f9c..04a601dded 100644
--- a/packages/cli/assets/templates/themes/stone/stoneTheme.ts
+++ b/packages/cli/assets/templates/themes/stone/stoneTheme.ts
@@ -105,7 +105,9 @@ export const stoneTheme = defineTheme({
// Text — H=291
'--color-text-primary': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
- '--color-text-secondary': ['#83838a', '#9d9da3'], // T55 C=4 / T65 C=3
+ // T40/T70 keeps normal secondary text above AA on every stone surface,
+ // including the muted and tinted fills that components pair it with.
+ '--color-text-secondary': ['#5e5e63', '#ababb0'], // Stone Neutral T40 / T70
'--color-text-disabled': ['#d7d7da', '#5e5e61'], // T86 C=1.6 / T40 C=2
'--color-text-accent': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
'--color-on-dark': '#FFFFFF',
diff --git a/packages/themes/stone/src/stoneTheme.ts b/packages/themes/stone/src/stoneTheme.ts
index b1dfa63f9c..04a601dded 100644
--- a/packages/themes/stone/src/stoneTheme.ts
+++ b/packages/themes/stone/src/stoneTheme.ts
@@ -105,7 +105,9 @@ export const stoneTheme = defineTheme({
// Text — H=291
'--color-text-primary': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
- '--color-text-secondary': ['#83838a', '#9d9da3'], // T55 C=4 / T65 C=3
+ // T40/T70 keeps normal secondary text above AA on every stone surface,
+ // including the muted and tinted fills that components pair it with.
+ '--color-text-secondary': ['#5e5e63', '#ababb0'], // Stone Neutral T40 / T70
'--color-text-disabled': ['#d7d7da', '#5e5e61'], // T86 C=1.6 / T40 C=2
'--color-text-accent': ['#25252a', '#f3f3f5'], // light: Stone Neutral T15
'--color-on-dark': '#FFFFFF',
diff --git a/scripts/check-stone-secondary-text-contrast.test.mjs b/scripts/check-stone-secondary-text-contrast.test.mjs
new file mode 100644
index 0000000000..88cb8864b3
--- /dev/null
+++ b/scripts/check-stone-secondary-text-contrast.test.mjs
@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stone secondary-text contrast guard.
+ *
+ * `--color-text-secondary` is normal text in core components. Most consumers
+ * inherit the body, surface, card, or popover background; others explicitly
+ * pair it with muted (`Code`, `InputGroupText`), neutral (`Avatar`, `Kbd`),
+ * accent-muted, or interaction-overlay fills. Stone's old T55/T65 pair fell
+ * below WCAG AA on several of those resolved surfaces.
+ *
+ * @input The stone theme's secondary-text token and every stone surface that
+ * core consumers pair it with.
+ * @output Fails when a resolved foreground/background pair drops below 4.5:1.
+ * @position Repo-level theme contrast guard, sibling of the other scripts/check-*.
+ * @see https://github.com/facebook/astryx/issues/5505
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+ stonePalettes,
+ stoneTheme,
+} from '../packages/themes/stone/src/stoneTheme.ts';
+import {
+ compositeOver,
+ contrastRatio,
+} from '../packages/core/src/theme/contrast.ts';
+import {parseColor} from '../packages/core/src/utils/color.ts';
+
+const MODES = [
+ {name: 'light', index: 0, secondaryTone: 40},
+ {name: 'dark', index: 1, secondaryTone: 70},
+];
+
+/** WCAG 2.1 AA for normal-size text. */
+const AA_NORMAL = 4.5;
+
+const SURFACES = [
+ '--color-background-surface',
+ '--color-background-body',
+ '--color-background-card',
+ '--color-background-popover',
+ '--color-background-muted',
+ '--color-neutral',
+ '--color-accent-muted',
+ '--color-overlay-hover',
+ '--color-overlay-pressed',
+];
+
+/** Resolve one half of a theme token's `light-dark()` value. */
+function resolveToken(name, modeIndex) {
+ const value = stoneTheme.tokens?.[name];
+ if (typeof value !== 'string') {
+ throw new Error(`stone theme does not define ${name}`);
+ }
+ const match = value.match(/^light-dark\((.+?),\s*(.+)\)$/);
+ return match ? match[modeIndex + 1] : value;
+}
+
+/** Resolve an opaque rendered surface, flattening alpha fills over surface. */
+function resolveSurface(name, modeIndex) {
+ const value = parseColor(resolveToken(name, modeIndex));
+ const surface = parseColor(
+ resolveToken('--color-background-surface', modeIndex),
+ );
+ if (value === null || surface === null) {
+ throw new Error(`could not parse stone ${name} surface`);
+ }
+ return compositeOver(value, surface);
+}
+
+describe('Stone secondary text contrast', () => {
+ it.each(MODES)(
+ 'uses canonical stone contrast tones in $name mode',
+ ({index, secondaryTone}) => {
+ expect(resolveToken('--color-text-secondary', index)).toBe(
+ stonePalettes.neutral[secondaryTone],
+ );
+ },
+ );
+
+ it.each(MODES)('meets WCAG AA on every $name consumer surface', ({index}) => {
+ const foreground = resolveToken('--color-text-secondary', index);
+ const failures = SURFACES.map(name => ({
+ name,
+ ratio: contrastRatio(foreground, resolveSurface(name, index)),
+ }))
+ .filter(({ratio}) => ratio < AA_NORMAL)
+ .map(({name, ratio}) => `${name} = ${ratio.toFixed(2)}:1`);
+
+ expect(failures).toEqual([]);
+ });
+});