The design system as a page

[iderex]

Depends on the landing page issue.

The design system moves here from where it is served today and becomes a page
rather than a specification. It shows colour, type, tiles and focus by rendering
them, and it states the speed budget the clients are held to as numbers.

Two budgets exist and the page must not blur them. The client budget is about
what a native client has to achieve. The site budget in #6 is about this page.
The page names both and says which is which.

Where the client budget numbers come from is #89 rather than this issue. They
are the same class of fact as a token, so they arrive here the same way and are
not typed on this page.

The tokens are the interesting part. They live in exactly one place and both the
page and the stylesheet come from it, which is the invariant the greppable gate
checks. A page that demonstrates a colour that is not the colour the stylesheet
uses is worse than no page.

Which place that is, and why it is not this one, is #65. This page renders the
pinned copy #66 keeps current and defines no value of its own, so the gate here
catches a value typed into this tree and the freshness run catches this tree
falling behind the file the clients are held to.

The accent and the colour vision presets are demonstrated rather than described,
because which hue works depends on which cone type is missing and a paragraph
cannot show that.

Done when

The page renders every token from the single token source, the greppable gate
refuses a second definition of any token, and the page states both budgets and
labels which is which.

[iderex]

The middle condition here says the greppable gate refuses a second definition of any
token. The row on main that looks like that one refuses colours, and only colours, so
ticking the condition off against it would be wrong.

The row declares what it reaches:

gh api repos/Flowfin/site/contents/internal/invariant/invariant.go --jq '.content' \
  | base64 -d | sed -n '281,285p'
			ID:      "design-tokens-live-in-exactly-one-file",
			Subject: BuildInputs,
			Reason:  "a colour typed into a template is a second definition of a value published somewhere else, and the day the published one moves the page goes on rendering the old one perfectly, so nobody sees it",
			Refuses: "a colour written into what the build reads, in any of the hex forms the published file uses, outside a fragment reference",
			decide:  decideTypedColour,

and the operator behind it matches hex colours and nothing else:

gh api repos/Flowfin/site/contents/internal/invariant/invariant.go --jq '.content' \
  | base64 -d | sed -n '624,628p'
		text := fragmentReference.ReplaceAllString(line, "")
		for _, m := range hexColour.FindAllString(text, -1) {
			details = append(details, fmt.Sprintf(
				"line %d writes the colour %s, and %s is the one file a colour is read from",
				i+1, m, tokens.File))

Both run 2026-08-12. The name of the row is about tokens and what it decides is about
colour, which is why the gap is easy to miss.

The token file carries seven groups of values, and the colours sit inside three of them:

gh api repos/Flowfin/site/contents/data/design-tokens.json --jq '.content' \
  | base64 -d | grep -oE '^  "[a-z-]+"'
  "what"
  "not-here"
  "how-to-read-this"
  "surface"
  "lift"
  "focus"
  "type"
  "shape"
  "font"
  "budget"

Run 2026-08-12. The first three keys are prose about the file. Of the seven that carry
values, surface, lift and focus hold the colours the row reads, and type,
shape, font and budget hold values it does not. A type size, a radius, a ring
width or a budget number typed into a template is the same failure this row exists for,
in a form it does not read. That
matters most for this page in particular, because the page demonstrates every one of
those groups rather than the colours alone, and it is the page where a value gets typed
next to the thing it is describing.

So the condition as written asks for more than one more row. It is a row per value shape
the file carries, or one operator that reads the shapes out of the file rather than
carrying a pattern per shape. #89 asks for one of those shapes on its own, for the
budget numbers, and it is a different row from this one rather than the same row
widened.

[iderex]

The middle condition is met on main now, and the first one turns out not to fit
beside the budget this milestone already holds.

The row reads a shape per group of values the file carries rather than the
colours alone:

go run . invariants | grep 'design-tokens-live'
  design-tokens-live-in-exactly-one-file: ok, 5 file(s) of every tracked file the build reads to render a page

and with four token values put into the frame, in the shape somebody writes them
while looking at the published file:

go run . invariants
  design-tokens-live-in-exactly-one-file: REFUSED, 4 violation(s)
    it refuses a colour, a length, a font family or a font weight written into what the build reads, outside a fragment reference
    templates/page.html.tmpl: line 9 writes the length 1080px, and data/design-tokens.json is the one file a length is read from
    templates/page.html.tmpl: line 9 declares a font family, and data/design-tokens.json is the one file a font stack is read from
    templates/page.html.tmpl: line 10 writes the length 56px, and data/design-tokens.json is the one file a length is read from
    templates/page.html.tmpl: line 10 declares a font weight, and data/design-tokens.json is the one file a weight is read from

Both run 2026-08-13 at 269d93e. The three new shapes carry their own pair
rather than resting on the fixture map, which holds one violation per row and
cannot tell one branch of an operator from another, so three of the four would
have been unproven under it while the row went on printing ok.

Now the first condition, which is the one I cannot build as written.

The file carries 206 values:

jq '[paths(scalars)]|length' data/design-tokens.json
206

The leanest rendering of all of them, one row per value with two cells and no end
tags, is:

jq -r '[paths(scalars) as $p | "<tr><td>" + ($p|map(tostring)|join(".")) + "<td>" + (getpath($p)|tostring)] | join("\n")' data/design-tokens.json | wc -c
15798

against a document line of

grep -n 'HTMLBytes = ' internal/budget/budget.go
27:	HTMLBytes = 20 * 1024

All run 2026-08-13. That leaves 4682 bytes for the frame, the title, the page's
own prose, the two budget tables and anything demonstrated. For scale, the
smallest page the build writes is the frame and four short paragraphs together:

go run . build | grep 'wrote dist/index.html'
wrote dist/index.html (1977 bytes)

So all 206 values fit on one page only if the page is a table of paths and
values with nothing else on it, and that is the opposite of what this issue asks
for. Colour, type, tiles and focus are to be shown by rendering them, and the
accent and the colour vision presets demonstrated rather than described, because
which hue works depends on which cone type is missing. That demonstration is
where the remaining bytes would go, and the presets are also where most of the
values are:

jq -r '[paths(scalars)|select(.[0]=="focus")]|length' data/design-tokens.json
66

Run 2026-08-13. Ten accents across five presets and two schemes, each with a
colour and an alpha.

Three ways out and I am taking none of them here, because each one moves
something that was decided somewhere else.

The page renders the values and not the file's own sentences about them. This is
the cheapest and it needs a written rule for which leaf is which, because the key
name does not decide it:

jq -r '.type.weight' data/design-tokens.json
The CSS numeric weight, 100 to 900. A platform whose font exposes fewer weights rounds to the nearest it has and says so.
jq -r '.type.distances.telephone.roles.tile.weight' data/design-tokens.json
540

Run 2026-08-13. One weight is a sentence and the other is a number, so a rule
by last segment gets both wrong.

The design system becomes more than one address. That reopens
decisions/0008-the-url-shape.md, which gives it exactly one and keeps the
address it already answers at.

The document line moves for this page. That is
decisions/0005-the-speed-budget.md rather than this issue, and #34 reads the
same constant, so the page and the check would move together.

What is left here is that choice, the page itself, and the last condition, which
is that the page states both budgets and labels which is which. The client
budget numbers have a file behind them and the site budget has internal/budget,
so that condition costs nothing once there is a page to put them on.

[iderex]

This issue was closed by the merge of #160 and none of its conditions was met by
that change. The cause is a sentence in that pull request's body, which said the
change does not close this issue and matched the pattern the tracker reads for a
closing reference, so the merge acted on the reference and not on the sentence
around it. The commit message carried no such reference:

git log -1 --format=%B 269d93e | grep -c -i 'close'
0

Run 2026-08-13. I have reopened it and taken the wording out of that body, so a
reader of the history is not left with a completed condition that was never met.
What is open here is what the comment above says: the page, the rule for what it
renders, and the two budgets on it.

[iderex]

The reading above puts the leanest rendering of all 206 values at 15798 bytes and
leaves 4682 for everything else. That count is over the whole file, and 52 of the
206 leaves are the file's own sentences about itself rather than values a client
reads. The first of the three ways out is the one that drops those, and measured
rather than supposed, it fits with room.

A leaf is a sentence if it is a string that ends in a full stop or carries one
followed by a space:

jq '[paths(scalars) as $p | select((getpath($p)|type)=="string"
    and (getpath($p)|test("[.]$|[.] ")))]|length' data/design-tokens.json
52

Every one of the 52 is prose about the file. Their last segments:

jq -r '[paths(scalars) as $p | select((getpath($p)|type)=="string"
    and (getpath($p)|test("[.]$|[.] "))) | ($p|map(tostring)|join("."))]|.[]' \
  data/design-tokens.json | sed 's/.*\.//' | sort | uniq -c | sort -rn
     15 role
     12 what
      5 why-this-hue
      5 why
      1 weight
      1 tile
      1 shelf
      1 scheme
      1 ring-width-applies-to
      1 not-here
      1 note
      1 method
      1 meta
      1 length
      1 duration
      1 display
      1 css-var
      1 combinations
      1 colour

That list carries the weight the reading above names as the pair a rule by key
name gets wrong. type.weight is a sentence and
type.distances.telephone.roles.tile.weight is 540, and this rule puts each on
the right side without reading either key.

It also keeps the nine values that a rule asking whether a string has a space in
it would have thrown away:

jq -r '[paths(scalars) as $p | select((getpath($p)|type)=="string"
    and (getpath($p)|test(" ")) and ((getpath($p)|test("[.]$|[.] "))|not))
    | ($p|map(tostring)|join(".")) + " = " + getpath($p)]|.[]' \
  data/design-tokens.json
focus.presets.protan.missing = L cones, red
focus.presets.deutan.missing = M cones, green
focus.presets.tritan.missing = S cones, blue
focus.presets.achroma.missing = all colour
type.distances.television.read-from = 3 m
type.distances.telephone.read-from = 35 cm
font.sans.stack.2 = Segoe UI
font.mono.stack.1 = Cascadia Mono
font.mono.stack.3 = SF Mono

The longest string it keeps is 14 characters, so nothing sentence-shaped survives
on the value side either.

What is left to render is 154 leaves, and the bare table over them, one row per
value with two cells and no end tags, is:

jq -r '[paths(scalars) as $p
    | select(((getpath($p)|type)=="string" and (getpath($p)|test("[.]$|[.] ")))|not)
    | "<tr><td>" + ($p|map(tostring)|join(".")) + "<td>" + (getpath($p)|tostring)]
    |join("\n")' data/design-tokens.json | wc -c
7861

against

grep -n 'HTMLBytes = ' internal/budget/budget.go
27:	HTMLBytes = 20 * 1024

so 12619 bytes are left for the frame, the title, the page's own prose, the two
budget tables and anything demonstrated. For scale, the build writes four pages
today and the largest of them is:

go run . build | grep '^wrote dist/privacy'
wrote dist/privacy/index.html (4945 bytes, 4 checked, 3 promised, 2 residual)

All run 2026-08-16 at 9fcaa0d.

So the document line is not what rules that answer out, and the reading above
left it looking as though it did. What the answer costs is the rule above written
down and given a test, and because the rule is this tree's reading of a file it
does not author, the test has to be one that survives the published file gaining
a value or a sentence. That is the argument left on this condition and it is
smaller than the byte count made it look.

Nothing here takes it, and the other two ways out are untouched: the design
system becoming more than one address is still
decisions/0008-the-url-shape.md, and moving the document line is still
decisions/0005-the-speed-budget.md.