- Decision
- ADR-270
- Date
- 2026-11-19
- Status
- AcceptedAccepted (owner, 2026-11-19: six remarks on the build, among them the wrapped link of the header, the tabs that could be better, the contents column that did not show all thirteen entries and should show where the reader is, the threat model that was too long and the disclosure that still animated). The calls of the agent are the parts and their sizes, the colour of the tabs and the breakpoints of the header; the owner may overrule each.
- Mentions
- ADR-268, ADR-269, ADR-271
- Mentioned by
- ADR-271
1Decision
Split the long documents of the portal into parts and pages, and settle the header, the tabs, the contents column and the disclosures after the owner read the build; this amends ADR-269 (1) and (4) and the motion rule of ADR-268.
(1) The threat model is four parts with a tab each, /threat-model (scope, assets, trust boundaries, review rule), /threat-model/attackers, /threat-model/abuse-cases and /threat-model/supply-chain, and the capability boundaries stay at /boundaries; a part that lists cases is paged in pages of the same size (the 67 abuse cases are five pages of 14, 14, 14, 14 and 11, the 23 boundaries two pages of 12 and 11), with the numbers of the cases kept across pages and Previous, the page numbers and Next under the list.
A search hit lands on the page that holds its case. (2) The tabs of a page (the five of the bill of materials and the five of the security model) sit on the header band in its colour, so band and tabs read as one block; the current tab has the blue underline, a hover shows a grey one, and on a phone the tabs are one row that scrolls sideways.
(3) The links of the header never wrap: the gap is at most 28 px, the tag Developer portal goes below 1180 px and the button Project site below 1000 px, and the drawer starts at 860 px as before.
(4) The contents column of a page scrolls inside the height of the screen, a title takes at most two lines, a title shows no Markdown marks, and the section on screen has the blue edge: browse.js sets aria-current as the page scrolls, which is the one change to the script.
(5) A disclosure moves nothing while it opens: not the panel, not the plus and not the colour of its button; it takes 300 ms to close, with the height on the standard curve and a fade, and the plus turns back. (6) The sitemap lists every page that shows a document, which ADR-269 left out.
2Why and evidence
The page of the threat model held 67 abuse cases, 11 attackers and 6 supply-chain cases on one page, and the Duress Unlock notes have thirteen sections, so a page with a contents column that cannot be seen whole and that does not say where the reader is is not usable.
The rule of the owner that too much on a page is split into pages with a sub-navigation (ADR-268) is applied to the threat model, and the paging of the decision list is the model for the cases. The tabs were a separate bar under the band, and in the colour of the header; on the band they use less height and look designed.
Rejected: cutting the cases off, a tab per section for the engineering notes (they are read in order), a contents column that shows only the current section (the owner asked to see all), and a CSS-only marker of the current section (it needs :target-current, which not every browser has [assumption: not checked against browser data]).
3Consequences
npm run build -w dev builds 314 pages and checks 11,191 links [measured]; the 214 anchors of the search index all exist on the built pages [measured]; the links of the header stand in one row, without overlap, at 861, 900, 1000, 1001, 1100, 1181, 1280, 1440, 1630 and 1920 px [measured]; the marked section followed the scroll through sections 1, 4, 7, 10 and 13 of the Duress Unlock notes, and all thirteen titles are in the column at a height of 1013 px [measured].
The disclosures were driven with real clicks of the browser pane while each frame listed the running animations [measured]: opening Read the 13 advisories showed the full height in the first frame and no animation in any frame, opening the filter panel at 900 px gave 400 px in the first of 43 frames and no animation, and closing took about 370 ms in both.
Before the change the same click showed no height or icon animation either, and the only motion measured on opening was the 150 ms change of the background colour of the button, which is now removed; whether that was the motion the owner saw is not known. axe-core found no violation and no page is wider than the screen on the 35 pages of the sitemap that are not decisions, in the dark scheme at 320 px and the light scheme at 1024 px [measured].
Not done: the owner's confirmation of the disclosure, Firefox and Safari, the keyboard and a screen reader, the claim review, and the deployment.
4Review when
Point (5) is replaced by ADR-271; a part or a page of cases becomes too long or too short for its size; a published document gets a section whose id is not in a part of its entry (the part is then missing from the site and the check of the build does not say so, so the lists in documents.mjs are read again when a heading of the threat model changes).
Read from docs/governance/decision-log.md, entry ADR-270.