🏷️ a11y: Give Prompt Category Icons Their Own Color Role (#16933)

* feat: Give Prompt Category Icons a Purpose Color Role

* fix: Keep Token Formatting and Skip Hover on Touch in the Category Icon Scenario

* test: Refresh the Theme Resolver Pin After Rebasing on the Avatar Ink Change
This commit is contained in:
Marco Beretta 2026-10-09 19:40:39 +02:00 • committed by GitHub
parent 6c8f659d54
commit 908ff5162a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 275 additions and 11 deletions

View file

@ -182,7 +182,7 @@ describe('theme cache storage', () => {
* - definitions with one or both mode blocks absent.
* A new role, or a new fallback, joins by construction.
*/
const PIN = { fingerprint: '1.3.leqd1k', digest: '1js4qi' };
const PIN = { fingerprint: '1.3.q7j6x4', digest: '1c7345r' };
const digestOf = (text: string): string => {
let hash = 5381;

View file

@ -6,9 +6,9 @@ const categoryColors = {
code: 'text-series-5',
misc: 'text-series-1',
shop: 'text-series-6',
idea: 'text-series-4',
idea: 'text-category-icon',
write: 'text-series-6',
travel: 'text-series-4',
travel: 'text-category-icon',
finance: 'text-series-2',
roleplay: 'text-series-2',
teach_or_explain: 'text-series-1',
@ -17,12 +17,12 @@ const categoryColors = {
rd: 'text-series-6',
it: 'text-series-5',
sales: 'text-series-2',
aftersales: 'text-series-4',
aftersales: 'text-category-icon',
};
describe('CategoryIcon', () => {
it.each(Object.entries(categoryColors))(
'uses the semantic series color for %s',
'uses the semantic color role for %s',
(category, color) => {
const { container } = render(<CategoryIcon category={category} />);
const icon = container.querySelector('svg');

View file

@ -38,9 +38,9 @@ const categoryColorMap: Record<string, string> = {
code: 'text-series-5',
misc: 'text-series-1',
shop: 'text-series-6',
idea: 'text-series-4',
idea: 'text-category-icon',
write: 'text-series-6',
travel: 'text-series-4',
travel: 'text-category-icon',
finance: 'text-series-2',
roleplay: 'text-series-2',
teach_or_explain: 'text-series-1',
@ -49,7 +49,7 @@ const categoryColorMap: Record<string, string> = {
rd: 'text-series-6',
it: 'text-series-5',
sales: 'text-series-2',
aftersales: 'text-series-4',
aftersales: 'text-category-icon',
};
export default function CategoryIcon({

View file

@ -0,0 +1,182 @@
import { randomUUID } from 'crypto';
import { expect, test } from '@playwright/test';
import type { Page } from '@playwright/test';
import type { ThemeDefinition } from '../../../../packages/client/src/theme/types';
import { clickHouseTheme } from '../../../../packages/client/src/theme/themes/clickhouse';
import { getAccessToken, requestJson } from '../helpers';
import { openPanel } from './panels';
/**
* The prompt category icons that drew in the `series-4` chart slot (idea, travel, aftersales) read
* the `category-icon` role. The stock palettes keep it on `series-4`; ClickHouse quiets it to its
* muted text, which clears the 3:1 WCAG 1.4.11 (Non-text Contrast) floor on the panel and on a
* hovered row, where Click UI's fuchsia did not.
*/
test.describe.configure({ timeout: 90_000 });
type Mode = 'light' | 'dark';
type CreatedGroup = { group?: { _id: string } };
const WCAG_NON_TEXT_MIN = 3;
const STOCK_SERIES_4: Record<Mode, string> = {
light: 'rgb(182, 123, 5)',
dark: 'rgb(200, 133, 12)',
};
const CLICKHOUSE_MUTED: Record<Mode, string> = {
light: 'rgb(105, 110, 121)',
dark: 'rgb(179, 182, 189)',
};
async function installTheme(page: Page, mode: Mode, definition: ThemeDefinition | null) {
await page.addInitScript(
([storedMode, stored]) => {
localStorage.setItem('color-theme', storedMode);
localStorage.removeItem('theme-colors');
localStorage.removeItem('theme-name');
if (stored === null) {
localStorage.removeItem('theme-definition');
localStorage.removeItem('theme-source');
return;
}
localStorage.setItem('theme-definition', JSON.stringify(stored));
localStorage.setItem('theme-source', 'definition');
},
[mode, definition] as const,
);
}
async function createIdeaGroup(page: Page, name: string): Promise<string> {
const token = await getAccessToken(page);
const body = await requestJson<CreatedGroup>(page, {
path: '/api/prompts',
token,
method: 'POST',
body: {
prompt: { prompt: `Text for ${name}`, type: 'text' },
group: { name, category: 'idea' },
},
});
const id = body.group?._id ?? '';
expect(id).not.toBe('');
return id;
}
async function deleteGroup(page: Page, id: string) {
const token = await getAccessToken(page);
await requestJson<{ message?: string }>(page, {
path: `/api/prompts/groups/${encodeURIComponent(id)}`,
token,
method: 'DELETE',
});
}
const channels = (color: string): number[] =>
(color.match(/\d+(\.\d+)?/g) ?? []).slice(0, 3).map(Number);
/** WCAG 2 relative luminance of an sRGB colour. */
function luminance(color: string): number {
const [r, g, b] = channels(color).map((value) => {
const unit = value / 255;
return unit <= 0.04045 ? unit / 12.92 : ((unit + 0.055) / 1.055) ** 2.4;
});
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
function contrast(foreground: string, background: string): number {
const [lighter, darker] = [luminance(foreground), luminance(background)].sort((a, b) => b - a);
return (lighter + 0.05) / (darker + 0.05);
}
/** Opens the prompts panel on a fresh idea prompt and reads its icon over the row at rest and, with
* a pointer, on hover; the row's own fill is transparent at rest, so the first opaque ancestor is
* the panel. */
async function categoryIconPaint(page: Page, mode: Mode, definition: ThemeDefinition | null) {
await installTheme(page, mode, definition);
await page.goto('/c/new', { timeout: 15000 });
const name = `Category icon ${randomUUID().slice(0, 8)}`;
const id = await createIdeaGroup(page, name);
try {
await page.goto('/c/new', { timeout: 15000 });
await openPanel(page, 'prompts', 'Prompts');
await page.locator('#prompts-panel').getByRole('search').getByRole('textbox').fill(name);
const row = page
.locator('#prompts-panel')
.getByRole('button', { name: new RegExp(`^${name} prompt`) })
.locator('..');
await expect(row).toBeVisible({ timeout: 20000 });
const icon = row.locator('svg').first();
const read = () =>
icon.evaluate((node) => {
let element: Element | null = node.parentElement;
let background = 'rgba(0, 0, 0, 0)';
while (element) {
const fill = getComputedStyle(element).backgroundColor;
if (!/rgba\(.*,\s*0\)$/.test(fill) && fill !== 'transparent') {
background = fill;
break;
}
element = element.parentElement;
}
return { color: getComputedStyle(node).color, background };
});
const rest = await read();
/** A touch screen has no hover state to paint, so only a pointer reads the hovered row. */
const canHover = await page.evaluate(() => matchMedia('(hover: hover)').matches);
let hover: typeof rest | null = null;
if (canHover) {
await page.mouse.move(0, 0);
await row.hover();
await expect.poll(async () => (await read()).background).not.toBe(rest.background);
hover = await read();
}
await test.info().attach(`category-icon-${definition?.name ?? 'stock'}-${mode}`, {
body: await row.screenshot(),
contentType: 'image/png',
});
return { rest, hover };
} finally {
await deleteGroup(page, id);
}
}
async function expectStock(page: Page, mode: Mode) {
const { rest } = await categoryIconPaint(page, mode, null);
expect(rest.color).toBe(STOCK_SERIES_4[mode]);
}
async function expectClickHouse(page: Page, mode: Mode) {
const { rest, hover } = await categoryIconPaint(page, mode, clickHouseTheme);
expect(rest.color).toBe(CLICKHOUSE_MUTED[mode]);
expect(contrast(rest.color, rest.background)).toBeGreaterThanOrEqual(WCAG_NON_TEXT_MIN);
if (hover) {
expect(contrast(hover.color, hover.background)).toBeGreaterThanOrEqual(WCAG_NON_TEXT_MIN);
}
}
test.describe('prompt category icon role', () => {
test('stock light keeps the idea icon on series-4 @scenario:prompt-category-icon-stock-light', async ({
page,
}) => {
await expectStock(page, 'light');
});
test('stock dark keeps the idea icon on series-4 @scenario:prompt-category-icon-stock-dark', async ({
page,
}) => {
await expectStock(page, 'dark');
});
test('ClickHouse light quiets the idea icon to 3:1 or more @scenario:prompt-category-icon-clickhouse-light', async ({
page,
}) => {
await expectClickHouse(page, 'light');
});
test('ClickHouse dark quiets the idea icon to 3:1 or more @scenario:prompt-category-icon-clickhouse-dark', async ({
page,
}) => {
await expectClickHouse(page, 'dark');
});
});

View file

@ -398,6 +398,9 @@ Each status family has a foreground, a `-subtle` background, a `-border`, and a
(0.5rem, 0.25rem and 1rem by default).
- `bg-alert-error-fill` / `border-alert-error-border` - The error `Alert`'s fill and edge. They
follow `status-error-subtle` and `status-error-border`, which the badges, tags and diffs keep.
- `text-category-icon` - The prompt category icons that were drawn in `series-4` (idea, travel
and aftersales). It follows `series-4`, so a theme can quiet those icons without moving the
chart slot; ClickHouse draws them in its muted text, as Click UI draws its icons.
- Layering roles - `bg-surface-canvas` (the chat canvas and its header fade),
`bg-surface-user-message` (the user turn's bubble), `bg-surface-card` and
`bg-surface-card-hover` (marketplace cards), `bg-surface-nav-hover` and

View file

@ -225,6 +225,7 @@ html {
--series-6: 126 35 205;
--series-7: 1 131 1;
--series-8: 63 81 181;
--category-icon: var(--series-4);
/* Code syntax highlighting */
--syntax-text: var(--gray-800);
@ -517,6 +518,7 @@ html {
--series-6: 171 104 254;
--series-7: 80 167 49;
--series-8: 120 130 190;
--category-icon: var(--series-4);
/* Code syntax highlighting. Comment and meta are the flattened equivalents of
the 50% and 60% alpha whites this palette used before it was tokenized. */

View file

@ -68,7 +68,7 @@ describe.each([
const tokens = Object.keys(theme) as Array<keyof IThemeRGB>;
it('covers every registry color', () => {
expect(tokens).toHaveLength(162);
expect(tokens).toHaveLength(163);
});
it('resolves every registry color to the runtime theme value', () => {

View file

@ -644,6 +644,29 @@ describe('theme registry', () => {
expect(resolved.colors['rgb-alert-error-border']).toBe('7 8 9');
});
it('keeps the category icons on the series slot a theme repainted, unless it names them', () => {
const inherited = resolveTheme(
{
version: 1,
name: 'legacy-series',
modes: { light: { colors: { 'rgb-series-4': '4 5 6' } } },
},
'light',
);
const explicit = resolveTheme(
{
version: 1,
name: 'explicit-category-icon',
modes: { light: { colors: { 'rgb-series-4': '4 5 6', 'rgb-category-icon': '7 8 9' } } },
},
'light',
);
expect(inherited.colors['rgb-category-icon']).toBe('4 5 6');
expect(explicit.colors['rgb-category-icon']).toBe('7 8 9');
expect(explicit.colors['rgb-series-4']).toBe('4 5 6');
});
it('preserves an explicit tooltip surface and falls back to the bundled one otherwise', () => {
const explicit = resolveTheme(
{

View file

@ -177,10 +177,11 @@ export const overlayFallbackSources: ReadonlyArray<readonly [keyof IThemeRGB, ke
['rgb-text-tooltip', 'rgb-text-primary'],
['rgb-alert-error-fill', 'rgb-status-error-subtle'],
['rgb-alert-error-border', 'rgb-status-error-border'],
['rgb-category-icon', 'rgb-series-4'],
];
/** A theme that repaints a source role keeps the tooltip and the error alert on it, unless it
* names them. */
/** A theme that repaints a source role keeps the tooltip, the error alert and the category icons on
* it, unless it names them. */
export function overlayFallbacks(colors: IThemeRGB): IThemeRGB {
return Object.fromEntries(
overlayFallbackSources.flatMap(([role, source]) => {

View file

@ -920,3 +920,40 @@ describe('scrim defaults', () => {
expect(scrimRoles.map((role) => defaultAppearance[role])).toEqual(['0.8', '0.9', '0.65']);
});
});
/** The stock and high contrast palettes keep the category icons on the series slot they drew in. */
describe.each([
['default', defaultTheme],
['dark', darkTheme],
['high contrast light', highContrastLightTheme],
['high contrast dark', highContrastDarkTheme],
])('%s category icons', (_name, theme: IThemeRGB) => {
it('paint in series-4', () => {
expect(theme['rgb-category-icon']).toBe(theme['rgb-series-4']);
});
});
/** ClickHouse quiets the category icons apart from its chart slot, and each one is a graphical
* object under WCAG 1.4.11, so it owes 3:1 on the panel and on a hovered or selected row. */
describe.each([
['clickhouse light', clickHouseLightTheme],
['clickhouse dark', clickHouseDarkTheme],
])('%s category icons', (_name, theme: IThemeRGB) => {
it('clear the 3:1 mark floor on every row surface without moving series-4', () => {
const icon = toRgb(theme, 'rgb-category-icon');
const surfaces: Array<keyof IThemeRGB> = [
'rgb-surface-primary',
'rgb-surface-primary-alt',
'rgb-surface-nav-hover',
'rgb-surface-nav-selected',
];
const failures = surfaces.flatMap((surface) => {
const ratio = contrast(icon, toRgb(theme, surface));
return ratio < WCAG_MARK_MIN ? [`${surface}: ${ratio.toFixed(2)}:1`] : [];
});
expect(failures).toEqual([]);
expect(theme['rgb-category-icon']).not.toBe(theme['rgb-series-4']);
});
});

View file

@ -208,6 +208,7 @@ export const clickHouseLightTheme: IThemeRGB = {
'rgb-series-6': '187 51 255', // #bb33ff (chart.default.violet)
'rgb-series-7': '0 203 235', // #00cbeb (chart.default.babyblue)
'rgb-series-8': '8 155 131', // #089b83 (chart.default.teal)
'rgb-category-icon': '105 110 121', // #696e79 (text.muted; Click UI draws its icons neutral)
// Switch
'rgb-switch-unchecked': '204 207 211', // #cccfd3 (switch.color.background.default)
@ -399,6 +400,7 @@ export const clickHouseDarkTheme: IThemeRGB = {
'rgb-series-6': '187 51 255', // #bb33ff (chart.default.violet)
'rgb-series-7': '0 203 235', // #00cbeb (chart.default.babyblue)
'rgb-series-8': '109 248 225', // #6df8e1 (chart.default.teal)
'rgb-category-icon': '179 182 189', // #b3b6bd (text.muted; Click UI draws its icons neutral)
// Switch
'rgb-switch-unchecked': '96 96 96', // #606060 (switch.color.background.default)

View file

@ -206,6 +206,7 @@ const colorSources: Record<ThemeMode, Partial<Record<keyof IThemeRGB, string>>>
'rgb-series-6': 'global.color.chart.default.violet',
'rgb-series-7': 'global.color.chart.default.babyblue',
'rgb-series-8': 'global.color.chart.default.teal',
'rgb-category-icon': 'global.color.text.muted',
'rgb-switch-unchecked': 'click.switch.color.background.default',
'rgb-switch-thumb': 'click.switch.color.indicator.default',
'rgb-table-header-text': 'click.table.header.color.title.default',
@ -365,6 +366,7 @@ const colorSources: Record<ThemeMode, Partial<Record<keyof IThemeRGB, string>>>
'rgb-series-6': 'global.color.chart.default.violet',
'rgb-series-7': 'global.color.chart.default.babyblue',
'rgb-series-8': 'global.color.chart.default.teal',
'rgb-category-icon': 'global.color.text.muted',
'rgb-switch-unchecked': 'click.switch.color.background.default',
'rgb-switch-thumb': 'click.switch.color.indicator.default',
'rgb-table-header-text': 'click.table.header.color.title.default',

View file

@ -204,6 +204,7 @@ export const darkTheme: IThemeRGB = {
'rgb-series-6': '171 104 254', // #ab68fe (violet)
'rgb-series-7': '80 167 49', // #50a731 (green)
'rgb-series-8': '120 130 190', // #8082be (indigo)
'rgb-category-icon': '200 133 12', // #c8850c (matching series-4)
/** Unchecked switch track. 3.38:1 against the page and the `surface-primary`
* thumb, 5.74:1 against the checked `surface-inverted` track. */

View file

@ -188,6 +188,7 @@ export const defaultTheme: IThemeRGB = {
'rgb-series-6': '126 35 205', // #7e23cd (violet)
'rgb-series-7': '1 131 1', // #018301 (green)
'rgb-series-8': '63 81 181', // #3f51b5 (indigo)
'rgb-category-icon': '182 123 5', // #b67b05 (matching series-4)
/** Unchecked switch track. 3.03:1 against the white page and the
* `surface-primary` thumb, 5.91:1 against the checked `surface-inverted`

View file

@ -226,6 +226,7 @@ export const highContrastLightTheme: IThemeRGB = {
'rgb-series-6': '77 26 153', // #4d1a99
'rgb-series-7': '15 92 15', // #0f5c0f
'rgb-series-8': '0 0 0', // #000000 (neutral text stop)
'rgb-category-icon': '92 74 0', // #5c4a00 (matching series-4)
/** Unchecked switch track. The stock 58%/40% greys land at 2.9:1 and 2.2:1
* against these canvases. This clears 3:1 three ways at once: 5.74:1 against
@ -436,6 +437,7 @@ export const highContrastDarkTheme: IThemeRGB = {
'rgb-series-6': '200 163 255', // #c8a3ff
'rgb-series-7': '140 230 140', // #8ce68c
'rgb-series-8': '255 255 255', // #ffffff (neutral text stop)
'rgb-category-icon': '255 224 102', // #ffe066 (matching series-4)
/** Unchecked switch track: 5.32:1 against the page and the `surface-primary`
* thumb, 3.95:1 against the checked `surface-inverted` track. */

View file

@ -202,6 +202,8 @@
--color-series-6: rgb(var(--series-6));
--color-series-7: rgb(var(--series-7));
--color-series-8: rgb(var(--series-8));
/* Follows the slot it was painted in before its role, for a stylesheet that predates it. */
--color-category-icon: rgb(var(--category-icon, var(--series-4)));
/* charts and controls */
--color-chart-widget-surface: rgb(var(--chart-widget-surface));

View file

@ -246,6 +246,9 @@ export interface IThemeRGB {
'rgb-series-6'?: string;
'rgb-series-7'?: string;
'rgb-series-8'?: string;
/** The prompt category icons drawn in `rgb-series-4` (idea, travel, aftersales); it follows
* `rgb-series-4` when a theme omits it, so a theme can quiet them without moving the chart slot. */
'rgb-category-icon'?: string;
/**
* Unchecked track of the shared `Switch`. A control state rather than a
@ -432,6 +435,7 @@ export interface IThemeVariables {
'--series-6': string;
'--series-7': string;
'--series-8': string;
'--category-icon': string;
'--switch-unchecked': string;
'--switch-thumb': string;
@ -597,6 +601,7 @@ export interface IThemeColors {
'table-header-text'?: string;
'table-header-fill'?: string;
'series-8'?: string;
'category-icon'?: string;
presentation?: string;
// Retained for excluded SidePanel/Agents + SidePanel/Builder (pending migration)

View file

@ -171,6 +171,7 @@ export const themeColorTokens = Object.freeze([
'rgb-series-6',
'rgb-series-7',
'rgb-series-8',
'rgb-category-icon',
'rgb-switch-unchecked',
'rgb-switch-thumb',
'rgb-table-header-text',