Skip to content

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

TypeScript

fix(theme-gothic): accent text and icons stay readable on a light media surface (#10852)

Cindy Zhang971d57533ec7
diff --git a/.changeset/gothic-media-light-accent.md b/.changeset/gothic-media-light-accent.md
new file mode 100644
index 0000000000..ff09475c82
--- /dev/null
+++ b/.changeset/gothic-media-light-accent.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/theme-gothic': patch
+'@astryxdesign/cli': patch
+---
+
+[fix] Gothic: accent text and accent icons stay readable on a light media surface. They used Gothic's light accent there, near-white on a light band (1.14:1); now they follow the surface's dark accent (18.7:1 against a white surface). The CLI's Gothic theme template carries the same change.
+
+@cixzhang
diff --git a/.gitignore b/.gitignore
index 60ed15d571..4fbc103ff2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -60,6 +60,7 @@ internal/vibe-tests/.fixture-runs/
.tmp-theme-app-types-*/
tmp-swizzle-*-test/
packages/cli/.tmp-component-icons-*/
+packages/themes/*/.tmp-media-accent-*/
apps/sandbox/.next/
apps/sandbox/out/
apps/sandbox/next-env.d.ts
diff --git a/packages/cli/api/theme/build/build.media-accent-contrast.test.mjs b/packages/cli/api/theme/build/build.media-accent-contrast.test.mjs
new file mode 100644
index 0000000000..f22b02479f
--- /dev/null
+++ b/packages/cli/api/theme/build/build.media-accent-contrast.test.mjs
@@ -0,0 +1,204 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Accent text stays readable on media surfaces in every shipped theme.
+ * @input Real themeBuild calls on each published theme package's source, the
+ * same command its package build runs.
+ * @output The color accent text and accent icons resolve to inside each
+ * `[data-astryx-media]` surface of the built CSS, and its contrast against
+ * the surface (WCAG 2.2 SC 1.4.3, 4.5:1).
+ * @position Built-theme accessibility check for media surfaces. A media
+ * surface sets `color-scheme` and re-declares its surface tokens; a token it
+ * does not re-declare keeps the value the theme root computed. The node
+ * project's global setup supplies the compiled core package.
+ */
+
+import {afterAll, beforeAll, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {themeBuild} from './build.mjs';
+
+const THEMES_DIR = path.resolve(import.meta.dirname, '../../../../themes');
+
+/** Published theme packages and their source entry. */
+const THEMES = fs
+ .readdirSync(THEMES_DIR)
+ .filter(name => {
+ const manifest = path.join(THEMES_DIR, name, 'package.json');
+ return (
+ fs.existsSync(manifest) &&
+ JSON.parse(fs.readFileSync(manifest, 'utf8')).private !== true
+ );
+ })
+ .sort();
+
+const ACCENT_TOKENS = ['--color-text-accent', '--color-icon-accent'];
+
+/**
+ * The reference background of each surface: the on-color for the opposite
+ * surface, which the theme designs to read as that surface's backdrop.
+ */
+const SURFACE_BACKDROP = {
+ dark: '--color-on-light',
+ light: '--color-on-dark',
+};
+
+/** @type {string[]} */
+const tmpDirs = [];
+/** @type {Map<string, string>} */
+const builtCss = new Map();
+
+beforeAll(async () => {
+ for (const name of THEMES) {
+ const packageDir = path.join(THEMES_DIR, name);
+ const entry = fs
+ .readdirSync(path.join(packageDir, 'src'))
+ .find(file => /^[a-z0-9]+Theme\.ts$/.test(file));
+ // The build writes only inside its working directory.
+ const tmpDir = fs.mkdtempSync(path.join(packageDir, '.tmp-media-accent-'));
+ tmpDirs.push(tmpDir);
+ const out = path.join(tmpDir, 'theme.css');
+ await themeBuild(path.join('src', entry), {out}, {cwd: packageDir});
+ builtCss.set(name, fs.readFileSync(out, 'utf8'));
+ }
+}, 240_000);
+
+afterAll(() => {
+ for (const tmpDir of tmpDirs) {
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+ }
+});
+
+/** @param {string} body */
+function declarations(body) {
+ /** @type {Record<string, string>} */
+ const map = {};
+ for (const part of body.split(';')) {
+ const colon = part.indexOf(':');
+ if (colon > 0) {
+ map[part.slice(0, colon).trim()] = part.slice(colon + 1).trim();
+ }
+ }
+ return map;
+}
+
+/** The theme root's token declarations and each media surface's. */
+function blocks(css) {
+ const root = css.match(/:scope\s*\{([^}]*--color-text-primary[^}]*)\}/);
+ /** @type {Record<string, Record<string, string>>} */
+ const surfaces = {};
+ for (const match of css.matchAll(
+ /\[data-astryx-media="(dark|light)"\]\s*\{([^}]*)\}/g,
+ )) {
+ surfaces[match[1]] = declarations(match[2]);
+ }
+ return {root: declarations(root ? root[1] : ''), surfaces};
+}
+
+/**
+ * Substitutes `var()` references the way the browser does for a custom
+ * property: against the declarations of the element that declares it.
+ * @param {string} value @param {(name: string) => string | undefined} lookup
+ */
+function substitute(value, lookup) {
+ let result = value;
+ for (let depth = 0; depth < 10 && result.includes('var('); depth += 1) {
+ result = result.replace(
+ /var\((--[\w-]+)(?:,\s*([^()]*))?\)/g,
+ (_, name, fallback) => lookup(name) ?? fallback ?? '',
+ );
+ }
+ return result;
+}
+
+/** Resolves `light-dark()` for the surface's color scheme. */
+function pickScheme(value, surface) {
+ const match = value.match(/^light-dark\(\s*([^,]+?)\s*,\s*([^)]+?)\s*\)$/);
+ if (!match) {
+ return value;
+ }
+ return surface === 'dark' ? match[2] : match[1];
+}
+
+/**
+ * The color a token takes on the innermost of nested media surfaces, given
+ * outermost first. Each surface resolves what it declares and inherits the
+ * rest from the surface around it.
+ */
+function surfaceColor(css, surfaceChain, token) {
+ const chain = [].concat(surfaceChain);
+ const {root, surfaces} = blocks(css);
+ let inherited = name =>
+ root[name] === undefined ? undefined : substitute(root[name], inherited);
+ for (const surface of chain) {
+ const own = surfaces[surface] ?? {};
+ const outer = inherited;
+ const resolve = name =>
+ own[name] === undefined ? outer(name) : substitute(own[name], resolve);
+ inherited = resolve;
+ }
+ return pickScheme(inherited(token) ?? '', chain.at(-1));
+}
+
+/** @param {string} color A `#rgb`, `#rrggbb` or `rgb()` color. */
+function channels(color) {
+ const hex = color.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+ if (hex) {
+ const digits =
+ hex[1].length === 3
+ ? [...hex[1]].map(digit => digit + digit).join('')
+ : hex[1];
+ return [0, 2, 4].map(i => Number.parseInt(digits.slice(i, i + 2), 16));
+ }
+ const rgb = color.match(/^rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)/);
+ if (rgb) {
+ return rgb.slice(1, 4).map(Number);
+ }
+ throw new Error(`Unsupported color: ${color}`);
+}
+
+function luminance(color) {
+ const [r, g, b] = channels(color).map(value => {
+ const c = value / 255;
+ return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+ });
+ return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+function contrast(a, b) {
+ const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+ return (light + 0.05) / (dark + 0.05);
+}
+
+describe('accent on media surfaces in built themes', () => {
+ it('builds every published theme', () => {
+ expect(THEMES.length).toBeGreaterThan(0);
+ expect([...builtCss.keys()]).toEqual(THEMES);
+ });
+
+ for (const name of THEMES) {
+ for (const surface of /** @type {const} */ ([
+ 'dark',
+ 'light',
+ ['light', 'dark'],
+ ['dark', 'light'],
+ ])) {
+ for (const token of ACCENT_TOKENS) {
+ const where = [].concat(surface).reverse().join(' surface inside a ');
+ it(`${name}: ${token} reads on a ${where} media surface`, () => {
+ const css = builtCss.get(name);
+ const foreground = surfaceColor(css, surface, token);
+ const backdrop = surfaceColor(
+ css,
+ surface,
+ SURFACE_BACKDROP[[].concat(surface).at(-1)],
+ );
+ expect(
+ contrast(foreground, backdrop),
+ `${foreground} on ${backdrop}`,
+ ).toBeGreaterThanOrEqual(4.5);
+ });
+ }
+ }
+ }
+});
diff --git a/packages/cli/assets/templates/themes/gothic/gothicTheme.ts b/packages/cli/assets/templates/themes/gothic/gothicTheme.ts
index 5ae07cf979..468bf5f05b 100644
--- a/packages/cli/assets/templates/themes/gothic/gothicTheme.ts
+++ b/packages/cli/assets/templates/themes/gothic/gothicTheme.ts
@@ -395,6 +395,22 @@ export const gothicTheme = defineTheme({
},
},
+ // Gothic's accent text and icons are one light color. On a media surface
+ // they follow that surface's accent, so a dark surface inside a light one
+ // gets its light accent back.
+ onDark: {
+ tokens: {
+ '--color-text-accent': 'var(--color-accent)',
+ '--color-icon-accent': 'var(--color-accent)',
+ },
+ },
+ onLight: {
+ tokens: {
+ '--color-text-accent': 'var(--color-accent)',
+ '--color-icon-accent': 'var(--color-accent)',
+ },
+ },
+
icons: gothicIconRegistry,
});
diff --git a/packages/themes/gothic/gothic.spec.md b/packages/themes/gothic/gothic.spec.md
index f96896e97d..78e5d8f1ca 100644
--- a/packages/themes/gothic/gothic.spec.md
+++ b/packages/themes/gothic/gothic.spec.md
@@ -13,6 +13,7 @@ verified_by:
packages/themes/gothic/src/gothicTheme.test.ts,
packages/themes/gothic/src/gothicColorMapping.test.ts,
scripts/generate-gothic-palette-refs.test.mjs,
+ packages/cli/api/theme/build/build.media-accent-contrast.test.mjs,
]
package: '@astryxdesign/theme-gothic'
source_theme: packages/themes/gothic/src/gothicTheme.ts
@@ -93,6 +94,10 @@ clearing normal-text AA. Syntax comments use `neutral.dark[65]` (`#7e8791`) on
`neutral.dark[10]` (`#101314`) at 5.12:1, so the maintained syntax mapping also
clears normal-text AA without an off-palette value.
+On a light media surface, accent text and accent icons use the surface's
+accent, `--color-on-light` (`neutral.dark[10]`, `#101314`), at 18.7:1 against a
+white surface. On a dark media surface they keep `neutral.dark[95]`.
+
## Build and artifact contract
The package and CLI template carry identical palette requests, generated
@@ -112,6 +117,7 @@ values.
| Role mapping | Gothic mapping and theme tests | semantic, categorical, syntax, effects | A maintained role bypasses selected Gothic references. |
| Public compatibility | Flat-ramp compatibility test and package build | numeric stops; `hue`; `chroma` | A released member or shape changes. |
| Mode contract | Theme CSS and rendered evidence | dark only | Light-dependent output or divergent mode values appear. |
+| Media-surface accent | Built-theme media accent contrast test | dark and light media surfaces | Accent text or icons fall below 4.5:1 on a media surface. |
| Package/template parity | Byte comparison and build | package and CLI template | Copies diverge. |
## Decision log
diff --git a/packages/themes/gothic/src/gothicTheme.ts b/packages/themes/gothic/src/gothicTheme.ts
index 5ae07cf979..468bf5f05b 100644
--- a/packages/themes/gothic/src/gothicTheme.ts
+++ b/packages/themes/gothic/src/gothicTheme.ts
@@ -395,6 +395,22 @@ export const gothicTheme = defineTheme({
},
},
+ // Gothic's accent text and icons are one light color. On a media surface
+ // they follow that surface's accent, so a dark surface inside a light one
+ // gets its light accent back.
+ onDark: {
+ tokens: {
+ '--color-text-accent': 'var(--color-accent)',
+ '--color-icon-accent': 'var(--color-accent)',
+ },
+ },
+ onLight: {
+ tokens: {
+ '--color-text-accent': 'var(--color-accent)',
+ '--color-icon-accent': 'var(--color-accent)',
+ },
+ },
+
icons: gothicIconRegistry,
});