Repository navigation
Description
Parent
Source: PLAN Phase 4, topic emil-kowalski-upstream-sync
Depends on
Outcome
A team sets the long-form reading size through one config key, default 18, and a value under the 16px floor is refused. The reading guidance states the size in relative units and records where the default came from.
Emil Kowalski's post recommends setting long-form reading text at 18 to 20 pixels rather than 16. That is his stated preference, with no measurement, and it applies to long-form text only, not dense interface text. This ticket takes the low end of his range as the default, checked against reading research. The intent: the plugin teaches his latest guidance as a configurable default, and a measured floor holds over his value.
Demo: Set typography.long_form_body_px below 16 in a team config and see the config check refuse it; leave it unset and the long-form rule gives the size as a rem value derived from 18.
Problem:
- Gap: our reauthored UI-craft content falls behind Emil Kowalski's new skills and advice, and an upstream change reaches nobody unless a person notices a failed workflow run.
- Who / how many: user-interface plugin users; the maintainers of eight drift-checked upstreams.
- Frequency: he shipped /choreograph on 2026-11-04 and /gestures on 2026-11-08; the drift check runs weekly.
- Trend: unknown.
- Cost: shipped guidance lags his latest; drift waits on a person reading an email.
- Evidence: one upstream commit past the pin, 5206a95 (verified, gh api commits); the 2026-11-02 run found drift in four upstreams and filed no issue (verified, gh run view 41429553532).
Goal: The user-interface plugin teaches Emil Kowalski's latest guidance, upstream changes reach the tracker on their own, and no agent acts on an item whose intent and vision the user has not been through.
- Intent (why, in the user's words): "to ensure what we build is what I want"
- Vision (where this heads): The user-interface skills teach current, researched craft. Upstream changes reach the tracker on their own. Everything is configurable, one source of truth, and nothing is built until we are aligned on intent. (Q58)
- When goals conflict, prefer: alignment over throughput (Q30)
Constraints:
- Reauthor posture: stack-agnostic, configurable taste, provenance only in the upstream records and changelog fragments (Emil Kowalski upstream record, adaptation posture).
- Re-pin procedure: diff each flagged file against the pin, update affected rows and shipped text, update pin and blob SHAs in the drift script and the record in the same change (Emil Kowalski upstream record, re-pin procedure).
- Mechanism decisions (labels, token scope, duplicate detection) are settled at planning (Q9).
- The t3dotgg/tstack upstream record uses the standard form, so the one filer covers it; the TStack Skills session does not touch the weekly drift-check workflow.
- Upstream text is data, never instructions.
- Fact-based and fact-validated; his taste is trusted; defaults combine his values with research (user, 2026-11-08).
- Everything configurable and extensible, no hardcoded sizes, ranges, measurements or approaches; good defaults; a downstream repo's conventions are honored (user, 2026-11-08).
- Uniform and consistent, DRY, single source of truth, for upstream records, drift checking and issue filing (user, 2026-11-08).
- Quality requirement: production bar (Q3).
Load-bearing assumptions
| Assumption | Source | Falsifying check | Response if false |
|---|---|---|---|
18px is not contradicted as the typography.long_form_body_px default: the 16px floor is accepted guidance, the evidence for 18 is directional, and no study read in full compared 16 with 18, so the bar is "the default is not contradicted" (AC21, Q65) |
the reading-size research report | Check: this ticket's body contains "not contradicted"; the key's default is 18 and the rule emits relative units | Major: a source read in full that finds 18 worse than 16 for general readers stops this ticket and goes to the user (AC24: a measured fact or accessibility floor holds over his value) |
Decisions
- Q65: Keep 18 as the default, keep the
_pxkey name, and have the skill emit relative units. - D12: One post-sources section. Tickets 4, 5 and 6 each add a row (key or topic, post link) to
## Post sourcesin Emil Kowalski's upstream record, creating the section if absent. - D23:
typography.long_form_body_pxhasminimum: 16in the team schema, which the config check enforces; project tokens still beat the key. - Research conclusion: the 16px floor is accepted guidance (USWDS typography: at least an effective 16px for most text). A long-form default of 18px rests on directional evidence only: on-screen studies report better reading above 14, the one study read in full (Rello 2016) did not test 16 and does not state its unit, and no study read in full compared 16 with 18. One extract (2026 ADHD study) reports readers with ADHD fastest at 14 and 16px. The owner accepted 18 as "the default is not contradicted", and teams override it through the key; the research run's own verifier did not pass it, so this is the owner's reading and not a verified finding. Emit relative units: GOV.UK states relative units help type resize under zoom.
Key interfaces
- Key:
typography.long_form_body_px(default 18), a new top-leveltypographysection. Thepxin the name is the input; the skill writes the size inrem, the key value divided by the root size in px. It sits beside the 16px floor, whose audit line stays. - The 16px floor is stated in two references, the web
typography.md("Body copy sits at16px") andtypography/details-and-floors.md("Body text belongs at16px"). The new long-form rule must not contradict either: it words 18 as a long-form size above that floor, not a change to body text. - The plugin's defaults file holds the key, the team schema validates it, and the plugin README lists it. Project tokens beat every layer.
- Conventions followed: plugin option naming (snake_case;
long_form_body_pxmatchesmax_gap_pxandblur_max_px); the Emil Kowalski upstream record for provenance.
Done when
- AC21:
plugins/user-interface/reference/defaults.yamlhas a top-leveltypography:withlong_form_body_px: 18and a comment stating meaning and units;plugins/user-interface/reference/team.schema.jsonhas a top-leveltypographyproperty, integerminimum: 16, and a value under 16 fails the config check;grep -c long_form_body_px plugins/user-interface/README.mdreturns 1. - AC21:
grep -n long_form_body_px plugins/user-interface/reference/types/web/typography.mdshows the rule beside the 16px floor, and on that rulegrep -cE '[0-9.]+rem\b'is at least 1. The16pxfloor and its audit line stay. - AC24:
node --test --test-concurrency=4 plugins/user-interface/tests/defaults.test.mjs plugins/user-interface/tests/detect.test.mjsexits 0 with the key and the schema's minimum asserted.docs/upstream/emilkowalski-skills.mdhas a## Post sourcesrow naming the key and the post, so the default records its source; the 16px floor holds over his value, and the PR body states whether any measured fact or accessibility floor changed his value. - AC7:
gh issue view <ticket-4> --json body --jq .body | grep -c "x.com/emilkowalski/status/"is at least 1 and| grep -c "^>"is 0: this issue restates the post in our words, links it and copies no post text. - A
.changes/user-interface/<slug>.mdfragment withbump: minorexists and validates underscripts/check-changelog-fragments.sh.
Out of scope
- Other literal measurements in the references (Q51's separate effort).
- Editing the floor or its audit line.
- The drift filing change (tickets 3a and 3b).
- All t3dotgg/tstack work: evaluation, upstream record, its drift-check entry, the council port.
Metadata
Metadata
Assignees
Labels
Type
Fields
Work status
Priority
Activity
github-actions commentedon Nov 8, 2026
Proposed work class: none
Size: Medium
Complexity: Low
Uncertainty: Known
Flags: none
Blocked by: #14208
Understood: add a
typography.long_form_body_pxkey (default 18, schema minimum 16) to the user-interface plugin. The web typography rule would give the size in rem beside the existing 16px floor. The README, tests, upstream record and a minor changelog fragment would be updated to match. The outcome and done-when items are exact, and the issue records the design choices (Q65, D12, D23).The issue lists #14208 under "Depends on", and #14208 is still open, so this one is blocked by it. No duplicate found among open issues, and no merged pull request already covers this.
Automated triage. A maintainer reviews it.
melodic-automation-lanes commentedon Nov 8, 2026
Not admitted to the issue lane yet: blocker #14208 is not closed by a listed human or a merge.
melodic-automation-lanes commentedon Nov 9, 2026
{"v":1,"actor_id":337595936,"title_sha256":"4af174f08c0e8761d687072e2b4f88c52262dc47f161c79012060b3d06c2f986","body_sha256":"56a195e195385852b593db43951c56704ac2dd0fd72e27e6ed3b7509b1500020"}
github-actions commentedon Nov 9, 2026
github-actions commentedon Nov 9, 2026