Skip to content

refactor(user-interface): add the full key set with recorded sources #14312

Description

@kyle-sexton

Parent

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

Depends on

Outcome

Every approved taste key exists with one default, a recorded source and schema validation, so references can name them.

Demo: A team touch.target_desktop_px: 20 is refused and the resolver shows 40, listing the key in the team layer's errors.

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 course files stay uncommitted there, so an autonomous lane cannot run its checks.

Load-bearing assumptions

Assumption Source Falsifying check Response if false
The #14208, #14210, #14212 and #14213 keys do not overlap this key set role-map animation.gesture.distance_threshold and typography.long_form_body_px are absent from the key set and present in the defaults file Moderate: flag and continue

Decisions

  • Plan D3: The fragment for this item is a minor bump because defaults change.
  • Plan Q4: A range or a value with parts is a fixed-length list.
  • Plan Q5: A size whose unit the team may choose is a CSS length string; a key whose name fixes the unit is a number.
  • Plan Q6: A duration key is both the value a recipe writes and the role's ceiling.
  • Plan Q7: The gesture damping column stays an example.
  • Plan Q9: The 9:1 pair stays a floor at guidance standing; the 2.5 ratio becomes taste as typography.fluid_max_ratio.
  • Handoff Q2: Press scale is 0.97.
  • Handoff D7: Course numbers are what the course's own skill files print for that use; the course wins a conflict, then Emil Kowalski's public source, then independent research, then the shipped number labeled heuristic.
  • Handoff D11: 100 roles in 111 leaves.
  • Interview Q26: Values with no upstream record their source in one links-only record under docs/upstream; a heuristic label stays in the defaults comment.
  • No shipped key is renamed, and no new userConfig entry is added (interview Q35, settled at plan).

Key interfaces

The key set, each default and its source are in the published classified list.

From the plan's Key shape:

A scale with named steps is one leaf per step. A ladder with no step names is one list (icon.size_px). A list's order is stated in the key's schema description, with minItems and maxItems set to its length. A short team list is refused, so a positional placeholder always has a value. A numeric value bounded by a floor is a separate numeric leaf, so the schema can hold its minimum (AC10).

Schema minimums: typography.fluid_body.min_rem and typography.fluid_scale.size_narrow_rem are at least 1; touch.target_desktop_px is at least 24. A list holding commas (spacing.section) is written in block style.

Conventions followed: ADR 0075; config-cascade contract; upstream-drift contract.

Done when

  • AC3: Each taste role or scale has one key in the defaults file and schema.
  • AC5: Every default follows this order: the course record on a conflict, then Emil Kowalski's latest source, then today's number; where mentions differ and he is silent, research picks, then the most common number labeled heuristic. A floor holds over any of these.
  • AC6: Default values live only in reference/defaults.yaml; the defaults test and README are the only other copies.
  • AC7: Each default records its source; a value with no upstream records it in one links-only record under docs/upstream; a value with none is labeled heuristic in the defaults comment.
  • AC8: The owner received a list of every default whose shipped number changed and every heuristic. (passes at base; kept: the post-blocker delta can change that list)
  • AC10: A taste key bounded by a floor has a schema minimum.
  • AC15: No new test or CI check is added; each new key joins the existing defaults test, written first.
  • AC19: The build starts only after feat(user-interface): default two-axis touch elements to tap-to-activate #14213 closes.
  • The defaults and detect tests pass; the detect command's output is under 28,000 characters, or the size goes to the owner.
  • The diff holds no course text, and the defaults file holds no path into the course files.
  • Each of the fifteen eval files holding the old animation.easing.out curve was read, and only one whose grader requires that curve was edited.

Out of scope

Activity

  1. added
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    on Nov 9, 2026
  2. added theissue type on Nov 9, 2026
  3. kyle-sexton commented on Nov 9, 2026

    @kyle-sexton
    MemberAuthor

    Owner decision Q11 (2026-11-09): option (b). Add animation.scale.press_min, default 0.95 (Emil's stated lower limit), which audit reports a project press scale below and never rewrites. Folded into this phase; the key count moves from 100 to 101 roles. Basis: PR #14789 removed the limit, so the audit lost a check it had (R3: his stated value is the default).

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

    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