Repository navigation
Conversation
docs/ui/site/ is the design source for the docs site: README.md is the spec, site.css the stylesheet, and reference/ the pages rendered from the repository's Markdown at c754bcb, whose markup and classes are the contract eng/site is held to. Added unchanged from the design session's archive; the generator does not read it yet. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
eng/site writes the design in docs/ui/site/ and embeds no stylesheet of its own. At build it writes site-tokens.css from docs/ui/tokens.json (light on :root, dark under prefers-color-scheme: dark, since the site has no script to set data-theme) and copies docs/ui/bundle.css, docs/ui/site/site.css and the mark verbatim. - The frame: the skip link, the bar with the sections the site map puts in it (so a new section needs no change to the frame), the article first in the document, then the page list, then "On this page"; the pager; the foot with the commit and the licence the build states. - Page order is a section README's links, then the rest by name. - Heads: an ADR's number, badge and decision set; a problem type's HTTP status, mono name and Title as lede; a section's summary as lede. The H1 moves into the head. - The ADR badge is read from the ledger, never from the status line (ruling 4, as the maintainer corrected it on #368): Superseded from the ADR index row, else Accepted or "Not yet accepted · n" from the ADR's own set; an unaccepted amendment by another ADR is a dated note. - Tables in div.vd-table (vd-table--kv when the header is empty), an anchor on each h2 and h3, figure.vd-diagram with an alt from the node labels, ul.vd-api on the API reference. - Markdig writes a column's alignment as a style attribute, which the page's policy blocks; it becomes align, and the output check now fails on any inline style, and on any resource loaded from another origin. The script fixture gets the smallest design source, so its one finding is the script. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
A dated amendment of ADR 0247 (ADR 0068), filed unaccepted (ADR 0066): the site embeds no stylesheet, writes site-tokens.css from tokens.json and copies bundle.css and docs/ui/site/site.css, and loads three stylesheets of its own origin where point 6 said one; the policy is unchanged. It records the maintainer's answers on #368: the ADR badge read from the ledger, the licence read from the build, the bar from the site map. Ruling SiteStyledFromDesignSource joins the docs-site set without accepted-by. Deque.AxeCore.Playwright and Microsoft.Playwright widen their scope to tests/Varve.Site.Tests/; no package is added. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
- A table whose header cells are all empty was never a key-value table: the header-cell pattern also matched <thead>. It matches th alone. - A code block and a table scroll sideways, and a keyboard could not reach either to scroll it (axe-core, scrollable-region-focusable, WCAG 2.1.1, at 390 wide and on long code at 1440). With no script to tell which overflow, each pre and each div.vd-table is in the tab order. - A section's index has no "On this page", as the design's reference pages show (the ADR index has many h2s, and its reference has none). - The page lists are internal, for the tests of their order. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
dotnet run --project eng/site -- screenshots --site <dir> --out <dir> --chrome <path> writes a page of each kind (home, an accepted ADR, ADR 0247 with its diagram, the ADR index, a problem type, an operator page with tables, an API page) in light and dark, at 1440 and 390 wide, at twice the density, under each page's own policy, served from the built files with every other request refused. It is the generator's rather than the tests', because the tests cite SiteStyledFromDesignSource and do not compile until it is accepted (ADR 0066), and the review comes before the acceptance. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
tests/Varve.Site.Tests, run by ci.yml's docs site job on the runner's Chrome: - the ADR badge for every case on a fixture ledger (tests/fixtures/site/ledger), main having no "Not yet accepted" ADR: accepted, unaccepted with its count, superseded in the index whatever the status line says, superseded in a later clause, superseded in part, an accepted ADR with an unaccepted amendment by another (a dated note, not its badge), a revoked ruling, and no set at all; - site-tokens.css read back and held to tokens.json in both schemes, citing SiteStyledFromDesignSource, so the build is red on CS0618 until it is accepted (ADR 0066); - the diagram alt, page order (tests/fixtures/site/order), the bar from the site map, the table wrappers and the ADR index's Notes; - a page of each kind against docs/ui/site/reference/, structure only; - two builds of one commit byte for byte; - each page under its own policy, unbypassed: nothing refused, nothing from another origin, the tokens applied; - axe-core at WCAG 2.2 AA on the home page, ADR 0247 and an operator page, in both schemes at 1440 and 390 wide; only the context that runs axe bypasses the policy. The job also takes the review's screenshots and uploads them with the site and the audit's report, as docs-site-review. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
The foot of each page under docs/ui/site/reference/, and the frame drawn in docs/ui/site/README.md, said Apache-2.0. The repository is MPL-2.0 (ADR 0031, superseding 0002), and the generator reads the foot's licence from Directory.Build.targets (the maintainer's answer 4 on #368). Only the licence changes. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
The maintainer's answers 1 and 2 on #368 (2026-11-19). The ADR badge has three states from the ADR's own set, still in one place (Ledger.StateOf): every ruling in force accepted is "Accepted" (ok); some accepted and some not is "Accepted · N pending" (warn), N the unaccepted ones; none accepted is "Not yet accepted" (warn). Superseded is unchanged. A ruling's amendment is the date its statement ends with ("amended YYYY-MM-DD", ADR 0068 point 4), and the head names the amendment the pending rulings belong to, linking its section when the page has one. The fixture ledger gains ADR 0010, with two rulings of a dated amendment and one undated rule pending. Every code block and table is in the tab order as a named region: a table by its header cells, a code block by its language, "Table" or "Code" when there is neither. The audit passes with them. The contract compares an ADR head's meta by the kinds of item, not their number, which is the ledger's answer. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
The maintainer's answer 3 on #368. A value written {name} in tokens.json is resolved to that token's value in the same scheme, through any chain, so site-tokens.css holds values only; a reference to no token, or a cycle, fails the build. The test fails when the output holds an unresolved {…} or a var(), checks the values against tokens.json followed independently, and proves the chain, the unknown name and the cycle on fixtures. The design's own preview of the file wrote {accent} unresolved, which a browser drops, focus ring and all. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
The maintainer's answer 4 on #368: site.css set tabular figures on the whole body, which in some system faces spaces out hyphens and dates in prose. They are set on tables and on an ADR's number in the page list. The design side had not answered otherwise on #368. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
The amendment of 2026-11-19, still unaccepted, now states the token references resolved, the badge's three accepted states and the pending amendment in the head, the named scrolling regions, and tabular figures in tables and numbers only. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
The built site's check fails on an inline style or a style element, which the policy drops without a word, on a resource loaded from another origin (img src, link href, protocol-relative included), and on a stylesheet that imports or references a file. Each is a page or a stylesheet of its own, beside a page that passes: a link to another origin, alignment by attribute, and url(#…) to its own fragment. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
The traceability record (the prompts verbatim, the tool and the model) and the session's close-out for #368 and pull request #379: the ruling SiteStyledFromDesignSource as a dated amendment of ADR 0247, the stylesheets a page loads (3,186 bytes before, 43,156 after), the audit per page, scheme and width, what the maintainer changed after the screenshots, and the deferred work as #369, #372 and #373. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Closes #368 Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
IDE0005 in OutputCheckTests.cs, reported by CI on #379's head as an error beside the expected CS0618. A local run with warnings-as-errors off on the command line had hidden it; the solution build, with them on, now fails on CS0618 alone. Refs #368 Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx Signed-off-by: Emil Okkels Klein <emil@okkels-klein.dk>
|
"Test the site" failed to compile on two errors:
Every step before it passed:
The fix is head Generated by Claude Code |
|
Hosted result at head The six that failed each fail on one error,
The skipped job is Everything else passed, the macOS
So the only failure is the expected one. It clears when the ruling is accepted. The accessibility audit then runs in CI for the first time, and I will post its result per page, scheme and width here, with Generated by Claude Code |
Completes: #368
Refs #129. This is part of its docs-site deliverable. The work log, the plan and the maintainer's answers are on #368.
What this changes, and why
The docs site took its look from a stylesheet embedded in
eng/site, unrelated to the design system. It now takes its design fromdocs/ui/site/, built from the same design source as the Web UI (ADR 0206).Styles.
eng/siteembeds no stylesheet.site-tokens.cssfromdocs/ui/tokens.json: light values on:root, dark underprefers-color-scheme: dark(the site has no script to setdata-theme). Every token reference is resolved to its value in each scheme, and a reference to no token, or a cycle, fails the build.docs/ui/bundle.css,docs/ui/site/site.cssand the mark verbatim.The frame, as the design writes it:
Directory.Build.targets, never typed.A section's page order is its README's links, then the rest by name.
Heads.
HTTP 422, its name in mono, and its Title as the lede.The ADR badge is read from the ledger, never from the status line. It is one mapping (
Ledger.StateOf), with a fixture ledger case for each state:The ADR index splits each Status cell into the badge and a Notes cell that keeps the README's words.
Markup.
div.vd-table, withvd-table--kvwhen the header cells are empty.a.vd-anchor.figure.vd-diagram, itsaltbuilt from the node labels: all 12 for ADR 0247's.ul.vd-api.tabindex="0",role="region", labelled by its language or its header cells).site.csssets tabular figures on tables and ADR numbers only, not on the whole body (the maintainer's answer 4; the design side did not answer otherwise on #368 before the push).docs/ui/site/reference/: "Apache-2.0" in the foot of its 8 pages is corrected to MPL-2.0, as the maintainer asked. So is the frame drawing indocs/ui/site/README.md, which the maintainer let stand.Decision.
SiteStyledFromDesignSourceis in thedocs-siteset withoutaccepted-by, and is cited by type fromtests/Varve.Site.Tests.Deque.AxeCore.PlaywrightandMicrosoft.Playwrightwiden their register scope to that project. No package is added.This pull request is red on
CS0618until the ruling is accepted, and that is its only failure (see "What was measured").For review:
eng/site … screenshotswrites a page of each kind in both schemes at 1440 and 390. ci.yml'sdocs sitejob uploads them with the built site as thedocs-site-reviewartifact, on every build. They are the generator's, not the tests', so the review never waits on an acceptance.What was measured
The dispatched run on head
117820fc(CI run 883). I read every failed job's log:CS0618attests/Varve.Site.Tests/SiteTokensTests.cs, and nothing else:build(ubuntu, windows),api freeze,decision report,pipeline (devcontainer), anddocs site's step "Test the site".docs siteup to that step: green. The site built twice, byte-identical, 594 files each; 28 screenshots were taken and uploaded.auth (providers)ismain-only.The run on this pull request's head,
6edd2664, is reported here when it ends.Locally, at head
8d07c6a8f54d330dba16d4f1732a54154e0ddd1a, against Chrome from Playwright, the build's warnings-as-errors turned off on the command line only. The one commit since adds the records, and no code.tests/Varve.Site.Tests: 67 of 67 pass. They cover the badge, the head, page order, the tokens, thealt, the structural contract, two byte-identical builds, each page under its own unbypassed policy, the audit, and the output check's failure paths.CS0618alone.eng/ci.cs -- --only:site-links,site-links-fixtures,site-svg-fixtures,site-script-fixture,register,test-projects,model-names,issue-refsanddcoall pass. So doesevery_stylesheet_balances_its_braces, which now walksdocs/ui/site/site.csstoo.axe-core, WCAG 2.2 AA, locally (only the context that runs axe bypasses the policy; the other checks read the built files): no violation on any page, scheme or width.
index.htmladr/0247-the-docs-site.htmloperator/configure.htmlIn CI the audit runs for the first time once the ruling is accepted. Its result per page, scheme and width, with
axe.md, will be reported here.What a page loads, in bytes:
site-tokens.cssbundle.csssite.cssThe site uses about 1.3 KB of
bundle.css, about 5%:vw-stateand its tones. Extracting it is #373.Badges on this branch: 213 Accepted, 7 Superseded, and 1 "Accepted · 1 pending" (ADR 0247, from this amendment).
What was found
style="text-align: …", which the policy blocks, silently, on 37 pages. It is nowalign. The built site's check also fails on any inline style, on any resource from another origin, and on a stylesheet that loads anything; each failure is proven inOutputCheckTests.scrollable-region-focusable, WCAG 2.1.1). The design's markup lacks this.site-tokens.cssleft references unresolved (--focus-ring: {accent}), which a browser drops, focus ring and all. This is noted on Docs site: styled from the design source (docs/ui/site), with the frame, page heads and ledger-read ADR badges #368 for the design side.<thead>. The tests found it.What is left
docs/learn/in its own first pull request.bundle.css.SiteStyledFromDesignSource. After it, the session reports the CI audit here, withaxe.md, and adds the CI result to the close-out record.Checklist
Refs #368; the completing commit carriesCloses #368docs/ui/site/README.mdchanges only in its licence lineeng/and tests onlyOutputCheckTests, the badge's fixture ledger, and the tokens' unknown-name and cycle fixturesdocs/traceability/2026-11-19-issue-368-docs-site-design.md, with the session's close-out indocs/sessions/2026-11-docs-site-design.mddotnet run eng/ci.cspasses locally — no: it stops atbuildonCS0618, as ADR 0066 expects; the site gates pass one at a timeDeveloped with AI assistance under human review.
🤖 Generated with Claude Code
https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx