Skip to content

Docs site: styled from the design source, with ledger-read ADR badges (#368, ADR 0247 amended, filed unaccepted) - #379

Open
Hafeok wants to merge 14 commits into
mainfrom
claude/docs-site-design-129
Open

Hafeok wants to merge 14 commits into
mainfrom
claude/docs-site-design-129

Conversation

@Hafeok

@Hafeok Hafeok commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

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 from docs/ui/site/, built from the same design source as the Web UI (ADR 0206).

Styles. eng/site embeds no stylesheet.

  • It writes site-tokens.css from docs/ui/tokens.json: light values on :root, dark under prefers-color-scheme: dark (the site has no script to set data-theme). Every token reference is resolved to its value in each scheme, and a reference to no token, or a cycle, fails the build.
  • It copies docs/ui/bundle.css, docs/ui/site/site.css and the mark verbatim.

The frame, as the design writes it:

  • the skip link, then the bar, whose sections come from the site map, so a section added there (Docs site: carry docs/learn/ when the learning track's first chapter lands #369, the learning track's) needs no change to the frame;
  • the article first in the document, then the page list, then "On this page";
  • previous and next;
  • the foot, with the commit and the licence. The licence is read from Directory.Build.targets, never typed.

A section's page order is its README's links, then the rest by name.

Heads.

  • An ADR shows its number, its badge and its decision set.
  • A problem type shows HTTP 422, its name in mono, and its Title as the lede.
  • A section index shows its summary as the lede.
  • The H1 moves into the head.

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:

  • Superseded (neutral), from the ADR index row. That covers the seven ADRs with no set, 0002 included.
  • Accepted (ok), when every ruling in force in the ADR's own set is accepted.
  • Accepted · N pending (warn), when some are and N are not. The head names the amendment those rulings belong to when their statements date one, and links its section.
  • Not yet accepted (warn), when none is.
  • An unaccepted ruling of another ADR that amends this one is a dated note, not its badge.

The ADR index splits each Status cell into the badge and a Notes cell that keeps the README's words.

Markup.

  • Tables are wrapped in div.vd-table, with vd-table--kv when the header cells are empty.
  • Every h2 and h3 carries an a.vd-anchor.
  • A diagram is a figure.vd-diagram, its alt built from the node labels: all 12 for ADR 0247's.
  • The API reference uses the same frame and ul.vd-api.
  • Every code block and table is a named region in the tab order (tabindex="0", role="region", labelled by its language or its header cells).

site.css sets 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 in docs/ui/site/README.md, which the maintainer let stand.

Decision.

  • ADR 0247 gets a dated amendment, 2026-11-19, filed unaccepted.
  • Its ruling SiteStyledFromDesignSource is in the docs-site set without accepted-by, and is cited by type from tests/Varve.Site.Tests.
  • Deque.AxeCore.Playwright and Microsoft.Playwright widen their register scope to that project. No package is added.

This pull request is red on CS0618 until the ruling is accepted, and that is its only failure (see "What was measured").

For review: eng/site … screenshots writes a page of each kind in both schemes at 1440 and 390. ci.yml's docs site job uploads them with the built site as the docs-site-review artifact, 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:

  • Failed on CS0618 at tests/Varve.Site.Tests/SiteTokensTests.cs, and nothing else: build (ubuntu, windows), api freeze, decision report, pipeline (devcontainer), and docs site's step "Test the site".
  • docs site up to that step: green. The site built twice, byte-identical, 594 files each; 28 screenshots were taken and uploaded.
  • Not a result: two macOS jobs got no runner and were cancelled; auth (providers) is main-only.
  • Every other job passed.

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, the alt, the structural contract, two byte-identical builds, each page under its own unbypassed policy, the audit, and the output check's failure paths.
  • The solution build fails on CS0618 alone.
  • Gates run one at a time with eng/ci.cs -- --only: site-links, site-links-fixtures, site-svg-fixtures, site-script-fixture, register, test-projects, model-names, issue-refs and dco all pass. So does every_stylesheet_balances_its_braces, which now walks docs/ui/site/site.css too.

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.

Page Light, 1440 Dark, 1440 Light, 390 Dark, 390
index.html none (21 rules passed) none (21) none (21) none (21)
adr/0247-the-docs-site.html none (27) none (27) none (28) none (28)
operator/configure.html none (25) none (25) none (25) none (25)

In 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.css bundle.css site.css Total
Before — — 3,186 (embedded) 3,186
After 2,039 24,541 16,576 43,156

The site uses about 1.3 KB of bundle.css, about 5%: vw-state and 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

  • Inline styles were blocked on the live site. Markdig writes a column's alignment as style="text-align: …", which the policy blocks, silently, on 37 pages. It is now align. 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 in OutputCheckTests.
  • Code blocks and tables were not reachable by keyboard. They scroll sideways, and a keyboard could not reach them to scroll (axe scrollable-region-focusable, WCAG 2.1.1). The design's markup lacks this.
  • The design's preview site-tokens.css left 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.
  • Key-value tables were never detected: a header-cell pattern also matched <thead>. The tests found it.
  • ADR 0002's status line says Accepted, but it is superseded by 0031. That is why Superseded is read from the index row.

What is left


Checklist

  • Issue referenced — every commit carries Refs #368; the completing commit carries Closes #368
  • ADR cited — ADR 0247 amended 2026-11-19, filed unaccepted; no accepted text edited
  • Specification updated, or n/a — n/a; the design's spec in docs/ui/site/README.md changes only in its licence line
  • API baseline updated, or n/a — n/a; eng/ and tests only
  • Conformance baseline updated, or n/a — n/a
  • Tests — the generator through its own entry points, the real repository and a real browser; fixtures for the ledger, the page order and the output check
  • A new gate's failure path was proven by running it — OutputCheckTests, the badge's fixture ledger, and the tokens' unknown-name and cycle fixtures
  • Signed and signed off — every commit signed, with the DCO sign-off from the hook
  • A traceability record exists — docs/traceability/2026-11-19-issue-368-docs-site-design.md, with the session's close-out in docs/sessions/2026-11-docs-site-design.md
  • dotnet run eng/ci.cs passes locally — no: it stops at build on CS0618, as ADR 0066 expects; the site gates pass one at a time

Developed with AI assistance under human review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NbWSYRkCLYi9UL4eh3NMHx

Hafeok and others added 12 commits November 19, 2026 13:00
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>

Hafeok commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

docs site at head 6edd2664: a second error beside the expected one, now fixed.

"Test the site" failed to compile on two errors:

  • CS0618 on the unaccepted SiteStyledFromDesignSource: expected (ADR 0066).
  • IDE0005, an unused using System.Collections.Generic; in tests/Varve.Site.Tests/OutputCheckTests.cs. Mine: my local runs turned warnings-as-errors off on the command line, which hid it.

Every step before it passed:

  • the site built twice, byte-identical, 594 files each;
  • 28 screenshots were taken;
  • docs-site-review was uploaded.

The fix is head 999454cdcb03a19860b628f3b63f22ca51a6332c, which drops the using. Built locally with warnings-as-errors on, the solution now fails on CS0618 alone. The hosted result on this head follows when its run ends.


Generated by Claude Code

Hafeok commented Nov 19, 2026

Copy link
Copy Markdown
Owner Author

Hosted result at head 999454cdcb03a19860b628f3b63f22ca51a6332c (CI run 44592941888): 39 jobs. 32 passed, one was skipped, and six failed.

The six that failed each fail on one error, CS0618 on the unaccepted DocsSite.SiteStyledFromDesignSource at tests/Varve.Site.Tests/SiteTokensTests.cs(26,18). I read every log:

  • build (ubuntu-latest)
  • build (windows-latest)
  • api freeze
  • decision report (never gates)
  • pipeline (devcontainer): its "exec failed" is that build inside the container
  • docs site: only its step "Test the site" failed

docs site, before that step: the site built twice, byte-identical, and the 28 screenshots and the docs-site-review artifact were uploaded.

The skipped job is auth (providers), which runs on main only.

Everything else passed, the macOS native aot and durability jobs included.

agent review is red because the head has no approval.

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 axe.md.


Generated by Claude Code

This branch was successfully deployed

1 active deployment
gates — 999454cd Deployed Nov 19, 2026 by Hafeok via agent review (judge) #1620
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.

1 participant