Theme doctor: advice on imported themes, never a block
themeDoctor(theme) names the lighter mechanism for what a theme's CSS does (radius, bevel, hiding, literal colors, fonts), its performance costs (:has, universal selectors, blur, size) and accessibility costs (outline removed, unguarded motion, small post text, moved navigation), plus contrast fixes. Theme import adds the count and the first hint to its message. Tested.
This commit is contained in:
parent
f6df08e43d
commit
f4cb26f33e
5 changed files with 107 additions and 1 deletions
57
packages/runtime/src/themeDoctor.ts
Normal file
57
packages/runtime/src/themeDoctor.ts
Normal file
|
|
@ -0,0 +1,57 @@
|
||||||
|
// The theme doctor: advice, never a block. A theme may do anything its trust level allows; the doctor
|
||||||
|
// points at the lighter mechanism for what the theme does (a token before a component setting, a
|
||||||
|
// component setting before CSS, CSS before a script) and at performance, accessibility and contrast
|
||||||
|
// costs. Used by the import screen, the Theme Builder's report and `waybetter store check`. Pure.
|
||||||
|
|
||||||
|
import { contrastRatio } from './themeApi.ts';
|
||||||
|
import { ensureContrast, type ThemeSpec } from './themeSpec.ts';
|
||||||
|
|
||||||
|
export type DoctorAdvice = {
|
||||||
|
/** `lighter`: a lighter mechanism would do; `performance`, `accessibility`, `contrast`: a cost. */
|
||||||
|
kind: 'lighter' | 'performance' | 'accessibility' | 'contrast';
|
||||||
|
/** Stable id, for tests and translations (`wb.doctor.<id>`). */
|
||||||
|
id: string;
|
||||||
|
/** English text (the panel translates by id when it has the words). */
|
||||||
|
text: string;
|
||||||
|
};
|
||||||
|
|
||||||
|
type Rule = { id: string; kind: DoctorAdvice['kind']; test: RegExp; text: string };
|
||||||
|
/** What a theme's free-form CSS does that a v2 group does without CSS. */
|
||||||
|
const CSS_RULES: Rule[] = [
|
||||||
|
{ id: 'css-radius', kind: 'lighter', test: /border-radius\s*:/i, text: 'Corner radii: components.<part>.radius (or shape.radius) sets them without CSS and keeps working when the site renames its classes.' },
|
||||||
|
{ id: 'css-bevel', kind: 'lighter', test: /box-shadow\s*:[^;{}]*inset[^;{}]*inset[^;{}]*inset/i, text: 'Bevelled edges: components.<part>.borderStyle "bevel-out" / "bevel-in" draws them from the theme\'s colors.' },
|
||||||
|
{ id: 'css-hide', kind: 'lighter', test: /display\s*:\s*none/i, text: 'Hiding a part: components.<part>.visible (avatars, counts, names) or a layout variant (sidebar: hidden) does it, and the owner can switch it back.' },
|
||||||
|
{ id: 'css-color', kind: 'lighter', test: /(?:^|[;{\s])(?:color|background(?:-color)?)\s*:\s*#[0-9a-f]{3,8}/i, text: 'Literal colors: name a role (text, muted, accent, surface…) in colors or in a component, so the contrast pass covers it.' },
|
||||||
|
{ id: 'css-font', kind: 'lighter', test: /font-family\s*:/i, text: 'Fonts: font.roles sets the post, heading, numbers and mono faces without CSS.' },
|
||||||
|
{ id: 'css-has', kind: 'performance', test: /:has\(/i, text: ':has() is matched again on every change of the page; keep it off rules that repeat down a timeline.' },
|
||||||
|
{ id: 'css-universal', kind: 'performance', test: /(?:^|[\s,>+~])\*\s*(?:[,{>+~:\[]|$)/m, text: 'A universal selector (*) is matched against every element; anchor the rule on a part.' },
|
||||||
|
{ id: 'css-blur', kind: 'performance', test: /backdrop-filter\s*:/i, text: 'Blur (backdrop-filter) is costly on parts that repeat; the glass fill of bars and panels is the cheaper place for it.' },
|
||||||
|
{ id: 'css-outline-none', kind: 'accessibility', test: /outline\s*:\s*(?:none|0)\b/i, text: 'Removing the outline hides where keyboard focus is; decor.focusRing draws a visible one instead.' },
|
||||||
|
{ id: 'css-motion', kind: 'accessibility', test: /(?:animation|transition)\s*:/i, text: 'Motion should stay inside @media (prefers-reduced-motion: no-preference); decor.motion does that for you.' },
|
||||||
|
];
|
||||||
|
|
||||||
|
/** Advice for a theme document. Empty when there is nothing to say. */
|
||||||
|
export function themeDoctor(theme: ThemeSpec): DoctorAdvice[] {
|
||||||
|
const out: DoctorAdvice[] = [];
|
||||||
|
const css = theme.css ?? '';
|
||||||
|
if (css.trim()) {
|
||||||
|
for (const rule of CSS_RULES) if (rule.test.test(css)) out.push({ kind: rule.kind, id: rule.id, text: rule.text });
|
||||||
|
if (css.length > 20_000) out.push({ kind: 'performance', id: 'css-size', text: 'More than 20,000 characters of CSS: the site recalculates styles with every rule; tokens and component settings compile to fewer rules.' });
|
||||||
|
}
|
||||||
|
if (theme.colors) {
|
||||||
|
const fixed = ensureContrast(theme.colors);
|
||||||
|
for (const role of ['text', 'muted', 'accent'] as const) {
|
||||||
|
if (fixed[role] !== theme.colors[role]) out.push({ kind: 'contrast', id: `contrast-${role}`, text: `The ${role} color was adjusted to stay readable (${contrastRatio(theme.colors[role], theme.colors.bg).toFixed(2)}:1 on the background).` });
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (theme.components) {
|
||||||
|
const posts = theme.components.post;
|
||||||
|
if (posts?.fill === 'glass') out.push({ kind: 'performance', id: 'glass-post', text: 'Glass on posts is not drawn: blur on every post of a timeline is too costly.' });
|
||||||
|
const text = theme.components.postText?.fontSize;
|
||||||
|
if (text !== undefined && text < 14) out.push({ kind: 'accessibility', id: 'small-post-text', text: 'Post text under 14px is hard to read for many people.' });
|
||||||
|
}
|
||||||
|
if (theme.variants?.nav === 'top' || theme.variants?.nav === 'bottom') {
|
||||||
|
out.push({ kind: 'accessibility', id: 'nav-moved', text: 'Moving the navigation changes where people look for it; it only applies on wide panes, and the owner can turn layout changes off.' });
|
||||||
|
}
|
||||||
|
return out;
|
||||||
|
}
|
||||||
44
packages/runtime/tests/themeDoctor.test.ts
Normal file
44
packages/runtime/tests/themeDoctor.test.ts
Normal file
|
|
@ -0,0 +1,44 @@
|
||||||
|
import assert from 'node:assert/strict';
|
||||||
|
import test from 'node:test';
|
||||||
|
import { themeDoctor } from '../src/themeDoctor.ts';
|
||||||
|
import { sanitizeSpec } from '../src/themeSpec.ts';
|
||||||
|
|
||||||
|
const ids = (raw: unknown) => themeDoctor(sanitizeSpec(raw)).map(advice => advice.id);
|
||||||
|
|
||||||
|
test('a theme made of tokens and component settings gets no advice', () => {
|
||||||
|
assert.deepEqual(ids({ name: 'Clean', colors: { bg: '#000000', text: '#ffffff', accent: '#1d9bf0' }, components: { button: { radius: 4 } } }), []);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('free-form CSS is pointed at the lighter mechanism and its costs', () => {
|
||||||
|
const css = [
|
||||||
|
'a { border-radius: 0; }',
|
||||||
|
'.x { display: none; }',
|
||||||
|
'.y { color: #ff0000; }',
|
||||||
|
'.z { font-family: Comic Sans MS; }',
|
||||||
|
'div:has(img) { opacity: .9; }',
|
||||||
|
'* { box-sizing: border-box; }',
|
||||||
|
'.g { backdrop-filter: blur(8px); }',
|
||||||
|
'button:focus { outline: none; }',
|
||||||
|
'.m { transition: all .2s; }',
|
||||||
|
'.b { box-shadow: inset 1px 1px #fff, inset -1px -1px #000, inset 2px 2px #ddd; }',
|
||||||
|
].join('\n');
|
||||||
|
const found = ids({ name: 'Heavy', css });
|
||||||
|
for (const id of ['css-radius', 'css-hide', 'css-color', 'css-font', 'css-has', 'css-universal', 'css-blur', 'css-outline-none', 'css-motion', 'css-bevel']) {
|
||||||
|
assert.ok(found.includes(id), `${id} is reported`);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
test('advice is a hint, never a change: the theme is left as it was', () => {
|
||||||
|
const theme = sanitizeSpec({ name: 'Keep', css: '.x { display: none; }' });
|
||||||
|
const before = JSON.stringify(theme);
|
||||||
|
themeDoctor(theme);
|
||||||
|
assert.equal(JSON.stringify(theme), before);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('unreadable colors are named with their contrast', () => {
|
||||||
|
const advice = themeDoctor(sanitizeSpec({ name: 'Low', colors: { bg: '#000000', text: '#111111', accent: '#1d9bf0' } }));
|
||||||
|
const text = advice.find(item => item.id === 'contrast-text');
|
||||||
|
assert.ok(text, 'text contrast is reported');
|
||||||
|
assert.equal(text.kind, 'contrast');
|
||||||
|
assert.match(text.text, /\d\.\d\d:1/);
|
||||||
|
});
|
||||||
|
|
@ -19,6 +19,7 @@ import { tabProfile } from '../profileModel.ts';
|
||||||
import { Button, ColorField, Row, Section, Segmented, Select, Slider, Toggle, useSettingsQuery, type Option } from './controls.tsx';
|
import { Button, ColorField, Row, Section, Segmented, Select, Slider, Toggle, useSettingsQuery, type Option } from './controls.tsx';
|
||||||
import { IconPackImport, IconPackReview } from './IconPackInstall.tsx';
|
import { IconPackImport, IconPackReview } from './IconPackInstall.tsx';
|
||||||
import type { IconPack } from '../../../runtime/src/themeIcons.ts';
|
import type { IconPack } from '../../../runtime/src/themeIcons.ts';
|
||||||
|
import { themeDoctor } from '../../../runtime/src/themeDoctor.ts';
|
||||||
import { bytesLabel, defaultWeights, loadCatalog, weightsLabel } from './fonts/catalog.ts';
|
import { bytesLabel, defaultWeights, loadCatalog, weightsLabel } from './fonts/catalog.ts';
|
||||||
import { FontRoles } from './fonts/FontRoles.tsx';
|
import { FontRoles } from './fonts/FontRoles.tsx';
|
||||||
import { CustomCssEditor } from './Plugins.tsx';
|
import { CustomCssEditor } from './Plugins.tsx';
|
||||||
|
|
@ -405,7 +406,9 @@ function ImportPanel({ onImport, onCancel }: { onImport(theme: ThemeSpec, warnin
|
||||||
const run = (json: string) => {
|
const run = (json: string) => {
|
||||||
const parsed = parseThemeJson(json);
|
const parsed = parseThemeJson(json);
|
||||||
if ('error' in parsed) { setError(parsed.error); return; }
|
if ('error' in parsed) { setError(parsed.error); return; }
|
||||||
onImport(parsed.theme, parsed.warnings);
|
// The theme doctor: advice only (never a block); contrast is already in the warnings.
|
||||||
|
const hints = themeDoctor(parsed.theme).filter(advice => advice.kind !== 'contrast');
|
||||||
|
onImport(parsed.theme, hints.length ? [...parsed.warnings, t('wb.appearance.doctorHints', { count: hints.length, hint: hints[0]!.text })] : parsed.warnings);
|
||||||
};
|
};
|
||||||
return <div className="bt-import">
|
return <div className="bt-import">
|
||||||
<div className="bt-import-drop" onDragOver={event => event.preventDefault()}
|
<div className="bt-import-drop" onDragOver={event => event.preventDefault()}
|
||||||
|
|
|
||||||
|
|
@ -25,6 +25,7 @@ export const PANEL_MESSAGES = {
|
||||||
'wb.appearance.icons.remove': 'Remove {name}',
|
'wb.appearance.icons.remove': 'Remove {name}',
|
||||||
'wb.appearance.icons.removed': 'Removed the icon pack “{name}”.',
|
'wb.appearance.icons.removed': 'Removed the icon pack “{name}”.',
|
||||||
'wb.appearance.icons.imported': 'Imported icon packs',
|
'wb.appearance.icons.imported': 'Imported icon packs',
|
||||||
|
'wb.appearance.doctorHints': '{count, plural, one {The theme doctor has a hint:} other {The theme doctor has # hints, the first:}} {hint}',
|
||||||
'wb.appearance.icons.site': 'The site\'s own icons',
|
'wb.appearance.icons.site': 'The site\'s own icons',
|
||||||
'wb.appearance.accountTheme': 'Account theme · {name}',
|
'wb.appearance.accountTheme': 'Account theme · {name}',
|
||||||
'wb.appearance.accountsHint': 'Every pane of an account shows its theme unless the pane has its own.',
|
'wb.appearance.accountsHint': 'Every pane of an account shows its theme unless the pane has its own.',
|
||||||
|
|
|
||||||
|
|
@ -418,6 +418,7 @@
|
||||||
"wb.appearance.icons.remove": "Remove {name}",
|
"wb.appearance.icons.remove": "Remove {name}",
|
||||||
"wb.appearance.icons.removed": "Removed the icon pack “{name}”.",
|
"wb.appearance.icons.removed": "Removed the icon pack “{name}”.",
|
||||||
"wb.appearance.icons.imported": "Imported icon packs",
|
"wb.appearance.icons.imported": "Imported icon packs",
|
||||||
|
"wb.appearance.doctorHints": "{count, plural, one {The theme doctor has a hint:} other {The theme doctor has # hints, the first:}} {hint}",
|
||||||
"wb.appearance.icons.site": "The site's own icons",
|
"wb.appearance.icons.site": "The site's own icons",
|
||||||
"wb.appearance.accountTheme": "Account theme · {name}",
|
"wb.appearance.accountTheme": "Account theme · {name}",
|
||||||
"wb.appearance.accountsHint": "Every pane of an account shows its theme unless the pane has its own.",
|
"wb.appearance.accountsHint": "Every pane of an account shows its theme unless the pane has its own.",
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue