The validator sees the rule after an @import, and dark rules fail - #529
Merged
Conversation
Three faults in bin/tdoc-validate-template, in the order they matter.
A statement at-rule ends at its semicolon and leaves no block behind, so
the rule written after it shared one `[^{}]+` run with it. Two of the
three CSS loops judged that run by its first character, read the whole
thing as one `@`-prefixed selector and skipped it, carrying the following
rule out of every check. `@import url("x.css"); .wrap{padding:99px}`
passed silently where `.wrap{padding:99px}` alone is an error, so one
`@import` line was a general way to hide CSS from this file -- including
from whatever rules get added to it later. Keeping only what follows the
last `;` leaves an ordinary selector to judge. The third loop already
read `_unconditional_css`, which delimits at-rules properly, so it was
never affected.
The body check reported "body background does not match the house style"
for `body{background:#fff;margin:0}`, where #fff *is* the house ground
and `margin` is the fault. One message stood for both halves of
`allowed and white`, so it named the wrong property and read as a bug in
the validator rather than a fault in the document -- which is how an
author learns to work around the tool instead of the rule. It now names
the properties that broke it, and a body with no background at all is
left to the structural error below rather than called a mismatch twice.
Dark rules were only taste notes. tdoc has no per-document dark palette:
the frame paints dark with `filter: invert(1) hue-rotate(180deg)` over
whatever the document painted, so a hand-built dark rule is inverted with
everything else and renders *light* -- the failure technical.md records
against a page that shipped its own dark palette and came out white. A
reader sees it, so it is an error. All three spellings are caught: the
`prefers-color-scheme: dark` block, the `html[data-tdoc-theme="dark"]`
selector, and a body simply painted dark, which wears no dark marker at
all. A ground given as `var(--x)` is left alone -- only a renderer can
resolve it, and guessing would be worse than staying quiet.
Checked against every HTML document in the repo: the parsing fix changes
no verdict on any of them, and the only verdict it changes at all is
test/fixtures/tdocs/copy-doc/v1/index.html, which carries a real
`html[data-tdoc-theme="dark"] body{background:#111}` rule. That fixture
is left as it is -- it is not a validator fixture and its tests only read
the theme attribute -- but it is an instance of the mistake, not a false
positive.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
PreviewOpen this: https://pr-529-tdoc-preview.jyshi1107.workers.dev/ — the homepage, this PR's code This link is unique to this PR. New commits update the same URL. It is not tdoc.dev. Preview has no Durable Object — concurrent comments use the KV fallback. Data expires in 14 days. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three faults in
bin/tdoc-validate-template, ordered by how much they matter. The first one is why the other two are worth fixing now: until it is closed, any rule added to this file can be stepped around with a single line.1. One
@importhid the rule after it from every checkA statement at-rule ends at its semicolon and leaves no block behind, so the rule written after it lands in the same
[^{}]+run. Two of the three CSS loops judged that run by its first character, read the whole thing as one@-prefixed selector, and skipped it — taking the following rule with it.So one
@importline was a general-purpose way to hide CSS from this file, including from whatever checks get added to it later. The fix keeps only what follows the last;, which leaves an ordinary selector to judge. The third loop already read_unconditional_css, which delimits at-rules properly, and was never affected._unconditional_cssis deliberately left alone. It strips at-rule blocks on purpose — a size inside@mediais a different layout, not a second size in the same one — so making the parser recurse into at-rules generally would break responsive layouts that are entitled to differ.2. An error that named the wrong property
body{background:#fff;margin:0}reported "body background does not match the house style" — but#fffis the house ground, andmarginis the fault. One message stood for both halves ofallowed and white, so it named a property that was correct. That reads as a bug in the validator rather than a fault in the document, and it is how an author learns to work around the tool instead of the rule. It now names the properties that actually broke it.A body that sets no background at all is left to the structural error below it, rather than called a house-style mismatch as well.
3. Dark rules were only taste notes
tdoc has no per-document dark palette. The frame paints dark with
filter: invert(1) hue-rotate(180deg)over whatever the document painted, so a hand-built dark rule is inverted along with everything else and renders light — the failureauthoring/style/technical.mdrecords against a page that shipped its own dark palette and came out white. The reader sees it, so it is an error, not taste.All three spellings are caught:
@media (prefers-color-scheme: dark){…}html[data-tdoc-theme="dark"] …A ground given as
var(--x)is left alone — only a renderer can resolve it, and guessing would be worse than staying quiet. That case is what a render-time check would still be needed for.Checking
Ran old and new against every HTML document in the repo (59):
test/fixtures/tdocs/copy-doc/v1/index.htmlThat fixture carries a real
html[data-tdoc-theme="dark"] body{background:#111}rule, so it is an instance of the mistake rather than a false positive. I left it as it is — it is not a validator fixture, and its tests only read the theme attribute — but it should probably be fixed in its own change.New tests cover all of it; each new assertion was checked to fail on
mainand pass here.The full suite passes:
npm test— 80 suites green, locally and on CI. The 8 playwright/network suites are gated off in both, as usual.test/fixtures/tdocs/copy-doc/v1/index.htmlis used by two of those gated suites, and neither invokes the validator, so this change does not affect them either way. The dark rule in that fixture is vestigial: the test that cares about dark reads thedata-tdoc-default-theme="dark"attribute, not the CSS. Read, not run — playwright is not installed here.Found by @ops, who hit the dark-mode bug while authoring and then traced it.
🤖 Generated with Claude Code