Theme engine v3: component inks solved on the grounds they sit on

A part's text role is still swapped for a readable one on its own fill, and its ink is
then solved with inkOn: on its fill, or with no fill of its own on every surface it can
sit on, the page canvas included (Solarized Light's outline Post button in the rail:
accent on the page read 4.45:1). Roles made for a parent's fill (onAccent, onInverse,
bg) stand. Invariant suite: Solarized Light I1 107 -> 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
CRTkafa 2026-10-02 06:14:15 +07:00
parent e3fe5820df
commit 4eaaa31fb1
2 changed files with 19 additions and 3 deletions

View file

@ -15,6 +15,7 @@
// The bevel borders (`bevel-out`, `bevel-in`) follow 98.css's raised and sunken edges (MIT, Jordan // The bevel borders (`bevel-out`, `bevel-in`) follow 98.css's raised and sunken edges (MIT, Jordan
// Scales, https://github.com/jdan/98.css): four inset shadows, here computed from the theme's roles. // Scales, https://github.com/jdan/98.css): four inset shadows, here computed from the theme's roles.
import { inkOnEvery } from './themeInk.ts';
import { contrastRatio, hexToRgb, mix, relativeLuminance, type FontRoleName } from './themeApi.ts'; import { contrastRatio, hexToRgb, mix, relativeLuminance, type FontRoleName } from './themeApi.ts';
// --------------------------------------------------------------------------------------------- // ---------------------------------------------------------------------------------------------
@ -390,15 +391,27 @@ export function compileComponents(components: ThemeComponents, parts: PartMap, c
decl.forEach(([property, value], index) => put(part.fill ? fillRule : box, `fill${index ? `-${index}` : ''}`, property, value)); decl.forEach(([property, value], index) => put(part.fill ? fillRule : box, `fill${index ? `-${index}` : ''}`, property, value));
} }
let textRole = has('text') ? tokens.text! : undefined; let textRole = has('text') ? tokens.text! : undefined;
const need = def.contrast ?? 4.5;
if (face && (def.text || textRole)) { if (face && (def.text || textRole)) {
const need = def.contrast ?? 4.5; // A role that cannot read on this fill gives way to the best role (white label on an accent fill)...
if (!textRole || contrastRatio(ctx.colors[textRole], face) < need) { if (!textRole || contrastRatio(ctx.colors[textRole], face) < need) {
const readable = readableRole(face, ctx.colors, textRole); const readable = readableRole(face, ctx.colors, textRole);
if (textRole && readable !== textRole) notes.push(`${id}: text "${textRole}" on its fill is under ${need}:1, using "${readable}"`); if (textRole && readable !== textRole) notes.push(`${id}: text "${textRole}" on its fill is under ${need}:1, using "${readable}"`);
textRole = readable; textRole = readable;
} }
} }
if (textRole) put(type, 'text', 'color', ctx.colors[textRole]); if (textRole) {
// ...and the ink is then solved on the grounds it really sits on (theme engine v3 3.3): its fill, or with
// no fill of its own every surface it can sit on, the page canvas included (an outline button in the
// rail sits on the page: Solarized's accent read 4.45:1 there).
// A role made for another ground (onAccent, onInverse, bg: a label on a fill some parent paints, the
// Classic bar) is the theme's statement about that parent and stands.
const surfaceInk = textRole === 'text' || textRole === 'muted' || textRole === 'accent';
const grounds = face ? [face] : surfaceInk ? [ctx.colors.bg, ctx.colors.surface, ctx.colors.elevated, ctx.colors.page] : [];
const solved = grounds.length ? inkOnEvery(grounds, ctx.colors[textRole], need) : { ink: ctx.colors[textRole], adjusted: false };
if (solved.adjusted) notes.push(`${id}: text "${textRole}" moved to ${solved.ink} to read ${need}:1 on ${grounds.join('/')}`);
put(type, 'text', 'color', solved.ink);
}
if (has('radius')) put(box, 'radius', 'border-radius', tokens.radius === 'pill' ? '9999px' : `${tokens.radius}px`); if (has('radius')) put(box, 'radius', 'border-radius', tokens.radius === 'pill' ? '9999px' : `${tokens.radius}px`);
const style = has('borderStyle') ? tokens.borderStyle! : undefined; const style = has('borderStyle') ? tokens.borderStyle! : undefined;

View file

@ -92,7 +92,10 @@ test('text on a fill the theme chose keeps its contrast: the role is swapped for
const out = css({ buttonPrimary: { fill: 'accent', text: 'accent' }, post: { fill: 'text' }, postText: { text: 'muted' }, avatar: { fill: 'surface' } }); const out = css({ buttonPrimary: { fill: 'accent', text: 'accent' }, post: { fill: 'text' }, postText: { text: 'muted' }, avatar: { fill: 'surface' } });
assert.ok(out.values.includes(`--wb-part-buttonPrimary-text:${COLORS.onAccent}`)); assert.ok(out.values.includes(`--wb-part-buttonPrimary-text:${COLORS.onAccent}`));
assert.ok(out.notes.some(note => note.startsWith('buttonPrimary:'))); assert.ok(out.notes.some(note => note.startsWith('buttonPrimary:')));
assert.ok(out.values.includes(`--wb-part-postText-text:${COLORS.muted}`), 'no fill of its own: the theme\'s role stands (the palette guarantees it on the theme\'s surfaces)'); // No fill of its own: the role's ink is solved on every surface it can sit on, the page canvas included
// (theme engine v3: this raw palette's muted reads 3.9:1 on its page; ensureContrast fixes it upstream too).
const postInk = out.values.find(v => v.startsWith('--wb-part-postText-text:'))!.split(':')[1]!;
for (const ground of [COLORS.bg, COLORS.surface, COLORS.elevated, COLORS.page]) assert.ok(contrastRatio(postInk, ground) >= 4.5, `${postInk} on ${ground}`);
assert.ok(!out.text.includes('--wb-part-avatar-text'), 'a fill alone colors no text on a part that is not a text part'); assert.ok(!out.text.includes('--wb-part-avatar-text'), 'a fill alone colors no text on a part that is not a text part');
assert.equal(readableRole('#000000', COLORS), 'onAccent'); assert.equal(readableRole('#000000', COLORS), 'onAccent');
for (const role of ['accent', 'text', 'surface', 'inverse'] as const) { for (const role of ['accent', 'text', 'surface', 'inverse'] as const) {