Skip to content

refactor(user-interface): state floors once and report values below them #14317

Description

@kyle-sexton

Parent

Refs #14214
Source: PLAN Phase 8, topic literal-measurements-config

Depends on

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, 44px or 16px).
  • 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions