Skip to content

Mechanize UI color token enforcement check - #614

Open
ArthurArthurArthur0817 wants to merge 1 commit into
sysprog21:mainfrom
ArthurArthurArthur0817:check-css-tokens
Open

ArthurArthurArthur0817 wants to merge 1 commit into
sysprog21:mainfrom
ArthurArthurArthur0817:check-css-tokens

Conversation

@ArthurArthurArthur0817

@ArthurArthurArthur0817 ArthurArthurArthur0817 commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem and behavior

UI colors must be defined as design tokens to ensure consistency across light and dark themes. To prevent hardcoded color literals from slipping into the codebase, this PR mechanizes the enforcement.

Per the maintainer's review, rather than introducing a standalone Python checker, this PR drops the Python script and strictly extends the existing tests/browser/theme.test.js to enforce CSS token usage across the repository.

Notes

The extended test suite now enforces the following strict zero-tolerance rules:

  • No Stacked Declarations: Prevents stacked var() declarations within the same component rule (i.e., a declaration must not shadow a token read in the same rule) to avoid cascade overrides.
  • Strict recording.css Scoping: Confines color literals in web/recording/recording.css strictly to its own :root block. Existing out-of-scope literals have been converted into semantic variables.
  • No Orphaned Tokens: Scans web/theme.css to ensure every declared token is read by at least one component or derived token, preventing unused tokens from accumulating.

Testing

Coverage is now integrated directly into tests/browser/theme.test.js. The tests will fail if a component sheet shadows a token read, if recording.css leaks literals outside its :root, or if theme.css leaves tokens unused.

Close #578

cubic-dev-ai[bot]

This comment was marked as resolved.

@ArthurArthurArthur0817
ArthurArthurArthur0817 force-pushed the check-css-tokens branch 2 times, most recently from 5b0898d to 64cdc76 Compare November 7, 2026 11:00
jserv

This comment was marked as outdated.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

cubic-dev-ai[bot]

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

jserv

This comment was marked as resolved.

Comment thread web/styles.css Resolved
Comment thread web/styles.css Resolved
Comment thread web/styles.css Resolved
Comment thread web/theme.css Resolved

@jserv jserv left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes: the stacked declarations in styles.css (see the inline comments) alter existing UI, and the enforcement belongs in the existing test rather than a new checker.

tests/browser/theme.test.js already enforces most of this rule for styles.css, task.css and peer.css: no color literal outside theme.css, no redeclared theme role, no read of an undeclared token. Since literals may only live in theme.css, it needs no scope parsing. A separate Python checker would keep a second copy of the same rule, and the two can drift. I suggest extending theme.test.js instead:

  1. Duplicate properties in one rule block. The per-declaration loop can remember the properties it has seen and fail when a later var() value repeats an earlier var() one. That would have flagged the four stacked box-shadow, background and color declarations in this diff, which the current tests let through.
  2. web/recording/recording.css. It is not in components, so nothing checks it. It loads no theme.css, so give it its own block: color literals only in its own :root. A rule against name collisions with theme.css would fail existing code, since its :root already declares --ink and --muted.

Two more checks fit the same file and could be separate issues. One is a token declared in theme.css that nothing reads; main has none today, so the rule can be zero-tolerance from the start. The other is the theme.css header rule that a derived token is restated wherever its input is overridden.

A contrast check against the AA ratios in that header would be the most valuable addition. It needs a maintained list of text and surface pairs and a browser, so it belongs in its own change.

@ArthurArthurArthur0817

Copy link
Copy Markdown
Contributor Author

I have completely reverted the CSS workarounds, removed the Python checker, and extended tests/browser/theme.test.js as you suggested.
The JS test now catches stacked var() declarations, separately enforces recording.css literals only in its :root, and checks for unused tokens in theme.css.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 5 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

View guided diff | Re-trigger cubic

Comment thread scripts/test.sh Resolved
@jserv

jserv commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

I have completely reverted the CSS workarounds, removed the Python checker, and extended tests/browser/theme.test.js as you suggested.

As CodeTrial’s codebase grows beyond 400K lines of code, automating tests for its web functionality becomes crucial. That is why I requested consolidation of the web test suite, with a scope extending beyond UI color token tweaks.

Bringing software up to professional standards is also an opportunity to strengthen your software development skills.

Comment thread scripts/test.sh Resolved
Comment thread tests/browser/theme.test.js Resolved
Comment thread tests/browser/theme.test.js Resolved
Comment thread tests/browser/theme.test.js Resolved

@jserv jserv left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rebase the current branch onto the upstream default branch and rework the series into functionally minimal commits, folding similar ones and enforcing the project's commit message rules.

Comment thread web/recording/recording.css Resolved
Comment thread tests/browser/theme.test.js Resolved
}
});

test("recording.css confines color literals to its own :root", () => {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The diff deletes task dialogs keep their backdrop in both system themes, a test unrelated to this change, and the description does not mention it. Please restore it.

Comment thread tests/browser/theme.test.js Resolved

@Shih-Hsuan Shih-Hsuan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The diff removes token-reference validation and leaves peer-interview timers stopped when a back/forward restore encounters a transient refresh failure.

...themed,
...Object.values(sheets).flatMap((css) => [...declared(css)]),
]);
test("component stylesheets paint no color a theme cannot override", () => {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This replacement removes the existing checks for component-level theme-role redeclarations and undeclared token references. With the helper scope repaired, .card { color: var(--missing-role); } and .card { --ink: var(--muted); color: var(--ink); } both pass the remaining tests in this file, while the original test rejects them. Restore the original declaration/reference test alongside the new checks.

Comment thread web/peer-interview.js Resolved
block.replace(/--[\w-]+\s*:[^;]*;/g, ""),
);
assert.deepEqual(
paintedColors("recording.css", recordingRest),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

paintedColors is a const inside the callback of the first component stylesheets paint no color a theme cannot override test, so this test and the second test of that name throw ReferenceError: paintedColors is not defined, and the recording.css rule never checks anything. Move colorFunction, namedColor and paintedColors to module scope next to CSS_NAMED_COLORS, so every test that calls the helper can reach it.

Comment on lines +139 to 143
test("component stylesheets paint no color a theme cannot override", () => {
for (const [name, css] of Object.entries(sheets)) {
const redeclared = [...declared(css)].filter((token) => themed.has(token));
assert.deepEqual(redeclared, [], `${name} redeclares theme roles`);
// A read with a fallback, var(--x, value), is a value scripts set at
// runtime (a measured height, a progress fraction), not a theme role.
const missing = [...new Set(captures(css, /var\((--[\w-]+)\)/g))].filter(
(token) => !known.has(token),
);
assert.deepEqual(missing, [], `${name} reads undeclared tokens`);
assert.deepEqual(paintedColors(name, css), [], `${name} paints colors`);
}
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a second test with the same name as the one just above it, and it runs the same check on the same sheets: the first test walks every declaration with assert.doesNotMatch against colorFunction and namedColor, and paintedColors repeats that loop. Once the helper is at module scope, have the existing test assert paintedColors(name, css) is empty and delete this copy, so the rule lives in one place.

Comment thread src/accounts/peer/rounds.rs Resolved
Comment thread src/web/peer/observer.rs Resolved
@jserv

jserv commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

This commit is built on an older tree and, merged as it is, would revert work already on main that has nothing to do with #578: the named replay flow, the strict check on the peer ready value, the observer that keeps running when the audio writer cannot open, and their docs and tests. The detail is on src/accounts/peer/rounds.rs. Rebuild the branch on current main so it carries only the theme test and recording.css changes.

@@ -30,6 +30,7 @@ const sheets = Object.fromEntries(
components.map((name) => [name, stripCssComments(read(`web/${name}`))]),
);
const theme = stripCssComments(read("web/theme.css"));

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the redeclaration test removed, nothing in this file reads theme any more, so the eslint gate in scripts/test.sh fails here with no-unused-vars ('theme' is assigned a value but never used). Nothing at this head checks theme.css for unused tokens either, although the reply on this PR says the test now does. Restoring the test that compares each component sheet's declared(css) against declared(theme) reads it again; if that test stays out, delete this line.

@jserv

jserv commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Some review comments on this pull request are not settled yet. Please refine the change per the review comments listed below, reply on each thread with what you changed or why you did not, and mark each thread resolved yourself once it is settled (Resolve conversation, at the bottom of the thread). The pull request stays blocked while review threads are open.

Not addressed at the current head:

Addressed at the current head; reply with what changed and resolve:

Checked at a2bb693.

Comment on lines 102 to +106
test("component stylesheets paint no color a theme cannot override", () => {
const colorFunction =
/\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\(|#[0-9a-f]{3,8}\b/i;
const namedColor = new RegExp(`\\b(?:${CSS_NAMED_COLORS.join("|")})\\b`, "i");
// Declarations, not lines: a value wrapped onto the lines after its property
// is still read, and a selector such as `#face-check` is not a hex color.
for (const [name, css] of Object.entries(sheets)) {
assert.deepEqual(paintedColors(name, css), [], `${name} paints colors`);
}
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing at this head defines paintedColors, colorFunction or namedColor, so this test throws ReferenceError: paintedColors is not defined, and styles.css, task.css and peer.css lose the color check they pass on main; there is no helper left to move to module scope, so it has to be written back. The version below keeps the mask exemption, which the #000 stop in the -webkit-mask and mask declarations of styles.css needs, along with the two comments that explained the parsing. With it this test and the recording.css one pass, and the recording.css test still fails on main's four hex backgrounds.

Suggested change
test("component stylesheets paint no color a theme cannot override", () => {
const colorFunction =
/\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\(|#[0-9a-f]{3,8}\b/i;
const namedColor = new RegExp(`\\b(?:${CSS_NAMED_COLORS.join("|")})\\b`, "i");
// Declarations, not lines: a value wrapped onto the lines after its property
// is still read, and a selector such as `#face-check` is not a hex color.
for (const [name, css] of Object.entries(sheets)) {
assert.deepEqual(paintedColors(name, css), [], `${name} paints colors`);
}
});
const colorFunction =
/\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\(|#[0-9a-f]{3,8}\b/i;
const namedColor = new RegExp(`\\b(?:${CSS_NAMED_COLORS.join("|")})\\b`, "i");
/// The declarations in a sheet that paint a color literal. Declarations, not
/// lines: a value wrapped onto the lines after its property is still read, and
/// a selector such as `#face-check` is not a hex color.
const paintedColors = (name, css) =>
[...css.matchAll(/\{([^{}]*)\}/g)].flatMap(([, body]) =>
body.split(";").flatMap((declaration) => {
const [, property, value] =
declaration.match(/^\s*([\w-]+)\s*:([\s\S]*)$/) ?? [];
// A mask paints coverage, not color: its stops are alpha only.
if (!property || /^(?:-webkit-)?mask$/.test(property)) return [];
if (!colorFunction.test(value) && !namedColor.test(value)) return [];
return [`${name}: ${property}:${value.replace(/\s+/g, " ")}`];
}),
);
test("component stylesheets paint no color a theme cannot override", () => {
for (const [name, css] of Object.entries(sheets)) {
assert.deepEqual(paintedColors(name, css), [], `${name} paints colors`);
}
});

Comment on lines +116 to +120
if (properties.has(property) && (properties.get(property) || hasVar)) {
assert.fail(
`${name} shadows a token read for ${property}: ${value.trim()}`,
);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The condition also fires when the earlier declaration is a literal and the later one reads a token (color: #fff; color: var(--ink)), and then the message says the later declaration "shadows a token read", which is the reverse of what happened. Name what the rule actually enforces, so a failure points at the right declaration:

Suggested change
if (properties.has(property) && (properties.get(property) || hasVar)) {
assert.fail(
`${name} shadows a token read for ${property}: ${value.trim()}`,
);
}
if (properties.has(property) && (properties.get(property) || hasVar)) {
assert.fail(
`${name} declares ${property} twice in one rule, one of them a token read: ${value.trim()}`,
);
}

Comment thread web/recording/recording.css Outdated
--edge: #232b34;
--pass: #3fb950;
--fail: #f85149;
--page-bg: #0d1117;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

styles.css paints the page with --page (body { background: var(--page); }), so --page-bg is a second name for the same role in the only sheet the recording page loads. A rule carried over from styles.css that reads var(--page) finds nothing declared here and renders with no background, which is how this page lost its backgrounds at an earlier head. Name it --page, the way the board's token follows --paper, and read var(--page) in body.

Per review, extend theme.test.js to enforce CSS token usage. Prevent
stacked var() declarations and strictly scope recording.css color
literals to its own :root.

Change-Id: Ia15d0ca2fd81439f8fcad48a977b90f7506dcf2f
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Mechanize UI color token enforcement check

4 participants