← Back to the screen

Design system portfolio

Design record: Ledgerhawk

The four direction lines behind this page, the generator command that produced its tokens, and the pairs it was measured against.

Reviewing a database migration the way GitHub reviews code: a real diff of real SQL, a lock analysis of every statement attached as evidence, and one required approval standing between the change and 41.2 million rows.

Direction

Archetype. Shell. The rail is the release week, the top bar is persistent, and one migration fills the well. Someone returns to this tab every day of a release week.

Data stance. Prose-first. The review conversation is the spine. The diff, the lock table, and the checks sit under the sentences that cite them.

Density. Compact. 14px body, 12px metadata, 32px controls, and a 44px hit area on a coarse pointer through --control-minTarget-coarse rather than a taller button.

The one bold thing. State is never carried by hue. Open, merged, and closed each get an icon, a word, and a silhouette of their own: a full pill, a 3px rectangle, an outline with no fill. The rail repeats all three six times, which is what teaches the vocabulary before the reader needs it.

Generated

primer_tokens.py --both   > tokens.css
primer_tokens.py --scales > scales.css
primer_tokens.py --theme light-tritanopia

--both emits colour only, so the size, spacing, type, and motion scales come from a second run of the same generator rather than from a hand-written number. Nobody edits either file. The third command is the check behind the bold thing.

What the accessible themes settled

--bgColor-open-emphasis is green #1f883d in light, orange #bc4c00 in light-colorblind, and red #cf222e in light-tritanopia. --bgColor-closed-emphasis goes from red to neutral gray in both accessible themes. --bgColor-done-emphasis stays purple #8250df throughout.

Open against merged measures 1.12:1 in light, 1.00:1 in light-colorblind, and 1.06:1 in light-tritanopia. The two fills are one tone in greyscale in every theme Primer ships, so colour could not separate them under any remapping. The icon, the word, and the silhouette carry the state; the fill only confirms it.

Contrast measured

fgColor-muted on bgColor-muted at 12px reaches 5.74:1 light and 5.94:1 dark. fgColor-onEmphasis on bgColor-open-emphasis at 14px reaches 4.52:1 light and 4.63:1 dark. That second pair is Primer's own tightest required pairing, and it is why the pill label sits at 14px medium rather than 12px.

A diff row measures 19.5px at Primer's --text-codeBlock line height. Eight line-number links stacked at that pitch met neither SC 2.5.8's 24px minimum nor its spacing exemption, and moving the anchor to the whole row would not have helped: the row is the same 19.5px tall and the same 19.5px apart. Growing the pitch to 24px was the other way to pass, and it changes what the page is.

So the line number identifies the line and nothing more. The row keeps its id, so #L14 still resolves and tr:target still marks the line; the links that reach a line live in the sentences that cite it, where SC 2.5.8's inline exception applies and where a prose-first page should have put them anyway. Verified with node tools/a11y-probe.mjs github-primer: no findings, light and dark.

Copy-lint exceptions

copy-lint.ignore holds three rules with the reason for each: operator-copy, because this page is the operator's tool and "migration" is their own word; shouty-caps, because every caps run on the page is SQL; and jargon, because Request changes is the name of the control in every review tool this audience uses.

The rail

The rail carried five destinations and four of them resolved to this document. A shell whose rail does nothing is a frame around a smaller product, so the destinations are gone and the rail is the release week instead: six migrations, one of them this page.

The current one is the only link and carries aria-current="page". The other five are rows, not controls, and that is the honest treatment for a build that is one screen, and a control that does nothing is worse than a row that never claimed to. #476 and #479 in the rail are the same two the timeline cites, so the rail and the conversation agree about the week.

Below 1012px the queue is a horizontal snap strip above the page head. It reads as cards rather than as tabs, which keeps it distinct from the section nav underneath it; the previous collapse put two scrolling tab strips one above the other.

The greyscale check

.rail rendered with filter: grayscale(1) and read back: open, merged and closed stay apart with no colour at all. Open and merged are one tone, which is Primer's palette and it is measured above, so the separation is the pill against the 3px rectangle, the icon, and the word. Closed is the outline and separates on lightness as well.

The prose measure

The stance is prose-first and the spine had no measure: at 1920px a body paragraph ran 1310px, about 187 characters. .shell is capped at Primer's own --breakpoint-xxlarge (1400px) and centred, which puts the paragraph at 790px and leaves 1920 reading as 1440 does. The spec panel's own measure is capped at 34rem for the same reason.

The uplift

The page is now one pull request, #482, read as GitHub reads one: a verdict strip, a conversation with a connector line, a lock chart attached as evidence, a merge box that counts what blocks it, and a diff with syntax colour and tabular line numbers. Opened Fri 11 Sep 2026, 14:22 UTC. The page clock reads 16:05 UTC, and each reader action moves it on by one minute.

The interaction. Apply mo-adeyemi's suggestion on line 12 and the page answers everywhere at once: the diff renumbers (+9 -3 becomes +10 -3, hunk -4,7 +4,13 becomes +4,14), a commit event joins the timeline, the replay reruns and the chart collapses from 4 m 12 s to a 0.02 s hairline, the verdict figure goes red to green, and the merge box drops from three blockers to two. Resolve the thread and request a review again and it drops to one. Revert undoes the commit. The override dialog exists because a real team needs a way past a failing budget, and it makes the reader type the PR number first.

The numbers, reconciled. The earlier page contradicted itself in several places; every figure now comes from one set. Replay: CREATE INDEX CONCURRENTLY 2 m 50 s (170 s), SET NOT NULL 4 m 12 s (252 s), DROP 0.04 s; the sum, 422.04 s, is 7 m 02 s, and the chart's x positions are those seconds over 422.04. The budget is 30 s, so the ratio is 252 / 30 = 8.4. After the suggestion the longest hold is 0.04 s. Conversation count 6, checks 4 (one failing, one warning, two passing), release week 37 with 2 of 5 applied and six rows in the rail. Times: opened 14:22, replay 14:31, review 15:04, reply 15:31, reply 15:52.

Line numbers in prose. The comments cite lines by new-file number: line 5 is lock_timeout, line 7 is the CREATE INDEX, line 12 is the constraint. The links in the prose land on the row through its id.

Dark. There is no dimmed variant in the generated tokens, so dark is the one dark theme and is checked on its own ground: the diff tints, the three label pairs and the chart bars are each measured again there. The nested-theme selector cannot re-scope inside a dark root, so the two swatches in the notes panel show the current theme and both ratios are written out beside them.

Keyboard. ? lists them. J and K walk the conversation, R re-runs the checks, A applies the suggestion, / focuses the rail filter. The key hints on buttons are hidden on a coarse pointer.

Deliberately left. direction_check reports accent-spread on the page, as it did before the uplift. The colours it counts are Primer's open, merged, closed and label states, which are the product's vocabulary rather than competing accents. The primary button is the only green control.

Round two: the first screen

The verdict's first cell is now the replay drawn as one run, full width, 88px tall (64px on a phone). Three segments on one time axis, each on a functional role: the concurrent index build in success (2 m 50 s, 0 to 40.28%), the first 30 s of the exclusive lock in attention (the budget, 7.11%), the rest in danger (3 m 42 s over, to 99.99%), with the 0.04 s DROP as a tick at the end. The 4 m 12 s figure stands on a stem that drops onto the bar where the lock begins, so it is read off the thing it measures. Blocking apply and Apply window are a quiet strip beneath. Apply the suggestion and the segments collapse to a ghost of the old hold, the figure ticks to 0.04 s and the stem goes green; the chart below the conversation still carries the same numbers and the text equivalent.

Round four (2026-10-29)

The lock bar had three segments built three ways: a pale green fill, a yellow budget window, and a saturated red slab that read as an error banner in light and left the green and yellow as dark blanks in dark. All three are now one construction, a muted fill in the segment's own colour under a 4px cap in its emphasis colour, so the bar reads the same in both themes and the cap, not the fill, is the drawn mark. Every segment names itself: CREATE INDEX 2 m 50 s, BUDGET 30 s (inside the bar where the track is 760px or wider, and in the coloured note under it at every width) and SET NOT NULL ACCESS EXCLUSIVE, which now starts at its own segment's edge. The figures are unchanged: the lock is the 30 s budget plus 3 m 42 s over, 4 m 12 s, after a 2 m 50 s index build, inside a 7 m 02 s replay.

At 390 the release-week list and the section tabs scroll sideways by design, but the cut-off words read as a layout fault. Each row now fades at the edge it continues past (data-more, set from scroll position and size), so "Widen tracking_code to 64" and "Lock analysis" read as scrollable. The reflow was considered and left: Primer's own UnderlineNav scrolls or collapses to a menu, and four icon tabs do not fit in 358px.

Round eight (2026-10-29)

Round nine (2026-11-09)

Read below the fold, with the states driven, at 360 and 390 on a touch context, and in dark.

Left, severity 0 to 1: the sidebar sits after the diff on a phone (the verdict is the page's first screen, so the pane does not move above it); decimals in prose elsewhere ("41.2 million") keep Mona Sans's small point.

Round ten (2026-11-09)

A second reader, cold, held the merge box against GitHub's own. Round nine scored it 36/40; the fresh read scored it lower, on the one act the page exists for.

Inventions, each minimal: (1) the reviewer approves about a minute of page clock after a re-request, only once the suggestion is applied, because his own comment says he will approve the split version; before that the row says what he is waiting on. (2) Apply queues for the window instead of running now, because the page already shows an apply window and a freeze check; the page never simulates the window opening, so no state is merged. (3) Remove from queue exists until then.

Left, severity 1: the reviewer approves minutes after the request, not "tonight" as his comment says; the timeline events wrap their sentence on a 360 phone as the existing ones do.

Round eleven (2026-11-10)

Inventions: none beyond that one sentence of rail copy. Left, severity 1: the dialog is still a centred card on a phone, "production-eu" can still break at its hyphen, and the Open pill does not change to a Queued mark after queueing; this round was given the rail only.

Round thirteen (2026-11-10)

The reviewer would ship it "nearly": the Diff tab that is only a scroll anchor, with the five inert rail rows, is where the page claims navigation it does not have.

Decision: an in-page link row, not real tab panels. This is one document in which every act answers in every section: applying the suggestion rewrites the diff, the replay, the verdict and the merge box. Panels would put Apply suggestion and the diff it changes on different tabs, and the brief sets the diff, the lock table and the checks under the sentences that cite them. GitHub itself makes the diff a separate page and a design lead would only split here if the page were split. Primer's UnderlineNav is a nav of links, so the row stays one, and it now says what it is.

Inventions: none beyond two strings of chrome copy ("Jump to a section of this page", the reworded rail caption). Order of the rail changes (#482 first, then #484 down to #476) because the live row cannot be both in the middle of a list of context and apart from it. Left, severity 1: the section row still looks like Primer UnderlineNav, because it is one.

Round fifteen (2026-11-10)

The round fourteen reviewer would ship it "yes, with a note that the rail's inert rail rows and anchor tabs need captioning or removing". Round thirteen captioned both and they were still listed, so this round removes the look of each.

Inventions: the string "5 other migrations this week" (the reviewer's wording) and "On this page". No product facts. Left, severity 1: the phone has no sticky merge bar and the diff sits below the comment box (reviewer scores 3 on both, no defect named).

Round seventeen (2026-11-10)

The round sixteen reviewer scored 37/40 and held three things: focus drops to the page body after three acts, the diff is cut at 360 with only a fade as a cue, and the phone is the desktop restacked (8,343px at 390, 8,694px at 360) with the diff below the comment box.

Inventions: none. Left, severity 1: the release rail and top bar still sit above the title on a phone (about 370px before the verdict), and the phone has no sticky merge bar.