Repository navigation
Mechanize UI color token enforcement check - #614
ArthurArthurArthur0817 wants to merge 1 commit into
Conversation
5b0898d to
64cdc76
Compare
64cdc76 to
218ebe2
Compare
218ebe2 to
f5ea34c
Compare
cc08714 to
f5ea34c
Compare
jserv
left a comment
There was a problem hiding this comment.
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:
- 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 earliervar()one. That would have flagged the four stackedbox-shadow,backgroundandcolordeclarations in this diff, which the current tests let through. web/recording/recording.css. It is not incomponents, so nothing checks it. It loads notheme.css, so give it its own block: color literals only in its own:root. A rule against name collisions withtheme.csswould fail existing code, since its:rootalready declares--inkand--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.
|
I have completely reverted the CSS workarounds, removed the Python checker, and extended tests/browser/theme.test.js as you suggested. |
There was a problem hiding this comment.
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
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. |
efb2009 to
a197749
Compare
jserv
left a comment
There was a problem hiding this comment.
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.
| } | ||
| }); | ||
|
|
||
| test("recording.css confines color literals to its own :root", () => { |
There was a problem hiding this comment.
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.
a197749 to
6bcce30
Compare
Shih-Hsuan
left a comment
There was a problem hiding this comment.
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", () => { |
There was a problem hiding this comment.
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.
| block.replace(/--[\w-]+\s*:[^;]*;/g, ""), | ||
| ); | ||
| assert.deepEqual( | ||
| paintedColors("recording.css", recordingRest), |
There was a problem hiding this comment.
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.
| 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`); | ||
| } | ||
| }); |
There was a problem hiding this comment.
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.
|
This commit is built on an older tree and, merged as it is, would revert work already on |
| @@ -30,6 +30,7 @@ const sheets = Object.fromEntries( | |||
| components.map((name) => [name, stripCssComments(read(`web/${name}`))]), | |||
| ); | |||
| const theme = stripCssComments(read("web/theme.css")); | |||
There was a problem hiding this comment.
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.
|
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. |
| 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`); | ||
| } | ||
| }); |
There was a problem hiding this comment.
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.
| 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`); | |
| } | |
| }); |
| if (properties.has(property) && (properties.get(property) || hasVar)) { | ||
| assert.fail( | ||
| `${name} shadows a token read for ${property}: ${value.trim()}`, | ||
| ); | ||
| } |
There was a problem hiding this comment.
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:
| 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()}`, | |
| ); | |
| } |
| --edge: #232b34; | ||
| --pass: #3fb950; | ||
| --fail: #f85149; | ||
| --page-bg: #0d1117; |
There was a problem hiding this comment.
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
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.jsto enforce CSS token usage across the repository.Notes
The extended test suite now enforces the following strict zero-tolerance rules:
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.recording.cssScoping: Confines color literals inweb/recording/recording.cssstrictly to its own:rootblock. Existing out-of-scope literals have been converted into semantic variables.web/theme.cssto 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, ifrecording.cssleaks literals outside its:root, or iftheme.cssleaves tokens unused.Close #578