Skip to content

feat(user-interface): add a configurable long-form reading size #14210

Description

@kyle-sexton

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 _px key 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 sources in Emil Kowalski's upstream record, creating the section if absent.
  • D23: typography.long_form_body_px has minimum: 16 in 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-level typography section. The px in the name is the input; the skill writes the size in rem, 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 at 16px") and typography/details-and-floors.md ("Body text belongs at 16px"). 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_px matches max_gap_px and blur_max_px); the Emil Kowalski upstream record for provenance.

Done when

  • AC21: plugins/user-interface/reference/defaults.yaml has a top-level typography: with long_form_body_px: 18 and a comment stating meaning and units; plugins/user-interface/reference/team.schema.json has a top-level typography property, integer minimum: 16, and a value under 16 fails the config check; grep -c long_form_body_px plugins/user-interface/README.md returns 1.
  • AC21: grep -n long_form_body_px plugins/user-interface/reference/types/web/typography.md shows the rule beside the 16px floor, and on that rule grep -cE '[0-9.]+rem\b' is at least 1. The 16px floor and its audit line stay.
  • AC24: node --test --test-concurrency=4 plugins/user-interface/tests/defaults.test.mjs plugins/user-interface/tests/detect.test.mjs exits 0 with the key and the schema's minimum asserted. docs/upstream/emilkowalski-skills.md has a ## Post sources row 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>.md fragment with bump: minor exists and validates under scripts/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.

Activity

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 8, 2026
  2. github-actions commented on Nov 8, 2026

    @github-actions
    Contributor

    Proposed work class: none

    Size: Medium
    Complexity: Low
    Uncertainty: Known
    Flags: none
    Blocked by: #14208

    Understood: add a typography.long_form_body_px key (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.

  3. added and removed
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Nov 8, 2026
  4. melodic-automation-lanes commented on Nov 8, 2026

    @melodic-automation-lanes
    Contributor

    Not admitted to the issue lane yet: blocker #14208 is not closed by a listed human or a merge.

  5. melodic-automation-lanes commented on Nov 9, 2026

    @melodic-automation-lanes
    Contributor

    {"v":1,"actor_id":337595936,"title_sha256":"4af174f08c0e8761d687072e2b4f88c52262dc47f161c79012060b3d06c2f986","body_sha256":"56a195e195385852b593db43951c56704ac2dd0fd72e27e6ed3b7509b1500020"}

  6. github-actions commented on Nov 9, 2026

    @github-actions
    Contributor
    No description provided.
  7. github-actions commented on Nov 9, 2026

    @github-actions
    Contributor
    No description provided.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Fields

    Work status

    needs-triage

    Priority

    medium

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions