Put the link to the content first in the frame, and refuse a page that drops it [#73] by iderex · Pull Request #155 · Flowfin/site

iderex · 2026-08-13T06:49:21Z

What was wrong

Five issues write into the frame #73 lands, and each of them says that
something has to be on every page. The frame carries the head, the affiliation
notice and the footer today, and it carries nothing above the text. So a
keyboard reader arrives at the top of a page and reaches what they came for
through everything the frame put in front of them. On the two pages the build
writes that is one link. Once a navigation lands it is one key press per entry
in it, on every page, and the only reader who can see that cost is the one
paying it.

Nothing refused it either. The row over the notice says the sentence is on the
page and says nothing about what a reader meets first, and no leg reads the
order of a page at all.

What this does

The frame opens with a link to the content, and the content carries the
identifier that link reaches:

git show HEAD:templates/page.html.tmpl | sed -n '9,11p'
  <body>
    <a href="#content">Skip to the content</a>
    <main id="content" tabindex="-1">

page-reaches-the-content-first refuses a produced page whose first focusable
element is not that link. It judges the address as well as the position,
because the way this rots is an identifier renamed on one side: both halves are
still there, the markup reads correctly, and the key press moves nobody.

What it reads as focusable is the set a browser puts in the tab order by
default, plus the attribute that overrides that answer in either direction.
That is a floor and the operator says so where the reader will meet it: an
element made focusable through something the row does not read is focusable to
a reader and invisible here, and a browser-backed leg is where that would be
seen.

The proof that it bites

The line deleted from the frame, which is the mistake somebody actually makes.
Both produced pages are refused and each says what a reader reaches instead:

go run . invariants
  page-reaches-the-content-first: REFUSED, 2 violation(s)
    it refuses a produced page whose first focusable element is not a link to that page's own content, including one pointing at an identifier no element on the page carries
    dist/index.html: line 22: the first thing a keyboard reader reaches is a link to https://github.com/Flowfin/site/blob/main/NOTICE.md, which leaves the content behind everything else this page carries
    dist/privacy/index.html: line 40: the first thing a keyboard reader reaches is a link to https://github.com/Flowfin/site/blob/main/NOTICE.md, which leaves the content behind everything else this page carries

The identifier renamed on the content and not in the link, which is the half
that looks correct:

go run . invariants
  page-reaches-the-content-first: REFUSED, 2 violation(s)
    dist/index.html: line 10: the link jumps to #content and no element on this page answers to that identifier, so the key press moves nobody
    dist/privacy/index.html: line 10: the link jumps to #content and no element on this page answers to that identifier, so the key press moves nobody

Both runs against a one-line edit to templates/page.html.tmpl at 4abd9f7,
reverted afterwards.

The row taken out of the table, which is the direction that says the guard is
not inert:

go test ./internal/invariant/ -count=1
--- FAIL: TestEveryRowRefusesItsOwnViolationAndPassesTheNeighbour (0.00s)
--- FAIL: TestRunRefusesAFrameThatDroppedTheContentLinkOnEveryPageItProduced (0.16s)
FAIL	github.com/Flowfin/site/internal/invariant	3.127s

Four near misses in the suite rather than one, because the position is lost in
four ways with four different repairs: a link written above it, a control
written above it, an address that leaves the page, and a fragment no element
answers to. A fifth case holds what must be left alone, which is what is in
front of the link and out of the tab order, because a row that refused a hidden
field or a region a script moves focus to is a row somebody switches off.

The run over the fixture tree asserts both produced pages rather than one. That
is what tells a property of the frame from a property of a page, and it is the
statement #153 added for the notice.

What else already reads this anchor

The links leg refuses a fragment pointing at an identifier no element carries,
from the other direction, so the two halves are held to each other by two legs
rather than one:

git show HEAD:internal/link/link.go | sed -n '130,133p'
			if !known[fragment] {
				dead = append(dead, fmt.Sprintf(
					"%s: line %d %s=%q points at #%s, and %s carries no element with that id",
					page(p.Name), r.line, r.attribute, r.value, fragment, page(file)))

The gate

go run . ci
gate: 6 legs, in order: format, vet, test, build, links, invariants
  format: ok, 37 file(s)
  vet: ok
  test: ok, 18 test file(s)
  build: ok, 3 file(s)
  links: every reference that stays inside this site resolves to a file the build wrote
  invariants: ok, 27 rule(s) decided, 1 owed and not decided
6 of 6 legs ran. None was skipped.

Run at 4abd9f7.

What it costs

74 bytes on each page, which is the element and the two attributes:

git checkout --detach origin/main && go run . build | grep '^wrote'
wrote dist/index.html (1194 bytes)
wrote dist/privacy/index.html (3404 bytes, 2 checked, 3 promised, 2 residual)
git checkout the-link-that-reaches-the-content && go run . build | grep '^wrote'
wrote dist/index.html (1268 bytes)
wrote dist/privacy/index.html (3478 bytes, 2 checked, 3 promised, 2 residual)

Run 2026-08-13, at 807975b and at 4abd9f7.

The means

The invariant table this tree already carries. The change adds no language, no
runtime and no dependency, the row is decided by reading bytes the build wrote,
and it is proved by the suite every other row is proved by.

What this does not do, and what it leaves open

It does not close #73. Two of that issue's conditions were already met, and
the third landed with #153. This is the static half of the fourth. The clause
asks that the link be shown to be the first focusable element by the headless
run, and there is no headless run: #63 is where the browser is pinned, and
until it lands the statement here is made by reading the produced bytes rather
than by a browser walking the tab order. The last condition, that the footer
links resolve from a page at every depth the site produces including the
not-found page, is untouched by this and waits on #30.

The link is visible rather than hidden until it is focused, because these pages
carry no stylesheet at all. That is a fact about today rather than a design
choice, and the day a stylesheet lands is the day it has to be decided.

The row says nothing about whether the link skips anything. On the pages the
build writes today it skips nothing, since there is no navigation between the
top of the page and the content. It is in the frame now so that the navigation
arrives behind it rather than in front of it.

Second reader

This change carries no second reader. What stands in place of one is the
evidence above: every claim in this body is a command with its output, run at
the commit being pushed rather than in a working tree, and the two directions
of the proof are here rather than the passing one alone.

…t drops it [#73] The frame carries the head, the notice and the footer, and nothing above the text. So a keyboard reader arrives at the top of a page and reaches what they came for through everything the frame put in front of them, which is one key press per link once a navigation lands, and the only reader who can see that cost is the one paying it. The frame now opens with a link to the content, and the content carries the identifier that link reaches. The row refuses a produced page whose first focusable element is not that link. It judges the address as well as the position, because the way this rots is an identifier renamed on one side: both halves are still there, the markup reads correctly, and the key press moves nobody. What the row reads is the first element a tab key stops on, which is the set a browser puts in the order by default and the attribute that overrides it in either direction. That is a floor and the operator says so at the function: an element made focusable through something it does not read is focusable to a reader and invisible here, and a browser-backed leg is where that would be seen. Four near misses rather than one, because the position is lost in four different ways with four different repairs: a link written above it, a control written above it, an address that leaves the page, and a fragment no element answers to. The one in the table is the line deleted from the frame, which is the mistake somebody actually makes. The run asserts both produced pages rather than one, which is what tells a property of the frame from a property of a page. The means is the invariant table this tree already carries, so the change adds no language, no runtime and no dependency, and the row is proved by the suite every other row is proved by. Signed-off-by: Nils Lehnen <[email protected]>

iderex added the enhancement New feature or request label Aug 13, 2026

iderex self-assigned this Aug 13, 2026

iderex added this to the The pages milestone Aug 13, 2026

iderex merged commit 0f5ec0a into main Aug 13, 2026
17 checks passed

iderex deleted the the-link-that-reaches-the-content branch August 13, 2026 06:50

Navigation Menu

Uh oh!

Put the link to the content first in the frame, and refuse a page that drops it [#73] - #155

Put the link to the content first in the frame, and refuse a page that drops it [#73]#155
iderex merged 1 commit into
mainfrom
the-link-that-reaches-the-content

iderex commented Aug 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

iderex commented Aug 13, 2026

What was wrong

What this does

The proof that it bites

What else already reads this anchor

The gate

What it costs

The means

What this does not do, and what it leaves open

Second reader

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant