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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/.gitignore b/.gitignoreindex 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.tsdiff --git a/packages/cli/api/theme/build/build.media-accent-contrast.test.mjs b/packages/cli/api/theme/build/build.media-accent-contrast.test.mjsnew file mode 100644index 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.tsindex 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.mdindex 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 alsoclears 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 contractThe 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 logdiff --git a/packages/themes/gothic/src/gothicTheme.ts b/packages/themes/gothic/src/gothicTheme.tsindex 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,});