Repository navigation
Description
Parent
Refs #14214
Source: PLAN Phase 8, topic literal-measurements-config
Depends on
- feat(user-interface): default two-axis touch elements to tap-to-activate #14213
- refactor(user-interface): move motion references to keys #14313
- refactor(user-interface): move color references to keys #14314
- refactor(user-interface): move layout, type and touch references to keys #14315
- refactor(user-interface): move write-css layout and audit scope to keys #14316
Outcome
Each floor is stated once with its source, other prose points there, and the audit reports a project value below a floor.
Demo: An audit on a scratch copy of with-ds with a 12px body-text token reports Should fix, names the floor and its source, and leaves the value in place; a text pair below 4.5:1 reports Blocking.
Problem: Most user-interface measurements are stated inline, so a team cannot change them through config and agents treat them as fixed unless the project has its own token.
- Who / how many: teams and repositories using the user-interface plugin; count unknown.
- Frequency, trend, cost: unknown.
- Evidence: 32 reference and skill files hold about 198 lines with px values, and about 252 more lines hold other units, from rough greps (observed); agents treating inline values as fixed (inferred); the owner's no-hardcoding rule (reported).
Goal: A team changes any user-interface taste measurement through one config key, every floor and constant stays stated, and a downstream repository's conventions win.
- Intent (why, in the user's words): "Everything should be configurable and extensible. We should never be hardcoding specific font sizes or ranges or any specific measurements and approaches."
- Vision (where this heads): Everything is configurable, one source of truth.
- When goals conflict, prefer: alignment over throughput
Constraints:
- Production quality bar.
- Everything configurable and extensible, with good defaults; approaches are met per rule.
- Uniform and consistent, DRY, one source of truth, across the repository, plugins and skills; SOLID; highest accuracy and coverage.
- Fact-based and fact-validated.
- A downstream repository's conventions win over every layer: its design system, conventions, lint config and layer system.
- Mechanism details are settled at planning.
- Nothing is added to CI unless it is 100 percent needed; any CI addition comes to the owner first.
- Provenance only in upstream records and changelog fragments.
- Quality requirement: Maintainability: each value has one home and a named key, with the named copies in AC6.
- Quality requirement: Reliability: an invalid setting follows the cascade rule: a valid higher layer still wins, an invalid personal value leaves the team value, otherwise the default applies.
- Quality requirement: Usability: a reference stays readable once it names a key, and accessibility floors stay stated.
- Quality requirement: Observability: the resolver shows each value and its layer.
- Quality requirement: Scalability: new values join an existing role key where one fits.
- Quality requirement: Performance: not applicable.
- Quality requirement: Security: not applicable; scripts receive schema-validated numbers.
- Run location: this work runs from the owner's local checkout. The classification scan, one-time named-key check and any proof runner stay uncommitted there, so an autonomous lane cannot run its checks.
Decisions
- Handoff D9: Audit severity follows a floor's standing; floors stay in their topic files.
- Handoff D10: 16px body names USWDS as its backing; 16px input names the WebKit source constant.
- Plan Q9: The 9:1 focus ring pair stays a floor at guidance standing and cites W3C technique C40; the unsourced finger-pad sentence is removed while the 44 floor stays.
- Interview Q8: A project value below a floor stands, and the audit reports it.
- Interview Q42: One home states each floor and its source; other prose names the floor and points there; a code example keeps its number.
Key interfaces
| Floor | Home (source stated here) | Other prose that points to the home |
|---|---|---|
| Text 4.5:1, large 3:1, non-text 3:1 (AA); 7:1, large 4.5:1 (AAA) | color contrast reference | web color reference, audit launch-scope reference |
| Pointer 44 (AAA, on touch or for a project claiming AAA), 24 (AA) | touch-web reference | write-css interaction reference |
| Body text 16px (USWDS) | web typography reference | details-and-floors, forms, accessibility, write-css foundations, audit launch-scope references |
| Input text 16px (WebKit constant) | touch-web reference | web typography reference, write-css foundations reference |
Audit severity: below a WCAG AA floor is Blocking; below AAA or guidance is Should fix, naming the floor and its source; the value stands. A measurement floor is not an entry in the cascade's floors argument, which is a policy floor on personal overrides.
The touch-web reference also gains the 320 reflow requirement in links-only form, with pointer, as-of date and recheck trigger.
Done when
- AC9: Each floor is backed by a standard or measurement and stated with its source in one home; other prose points there; code examples keep their number. 16px body names USWDS; the 16px input floor names the WebKit source constant. A stated minimum with nothing behind it is taste until research finds a source.
- AC13: The audit reports any project value below a floor.
- AC15: No new test or CI check is added.
- AC19: The build starts only after feat(user-interface): default two-axis touch elements to tap-to-activate #14213 closes.
- The audit skill body restates no floor number (no
4.5:1,44pxor16px). - Both audit demo runs hold their expected severity, within a budget of 2 runs.
- The pull request adds a changelog fragment.
Out of scope
- Taste-number sweeps, done by the four sweep items.
- Editing other plugins.
- All t3dotgg/tstack work.
Activity