Repository navigation
Description
Parent
Refs #14214
Source: PLAN Phase 3, topic literal-measurements-config
Depends on
- feat(user-interface): default two-axis touch elements to tap-to-activate #14213
- refactor(user-interface): prove key placeholders end to end with press scale #14311
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, withminItemsandmaxItemsset 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.outcurve was read, and only one whose grader requires that curve was edited.
Out of scope
- Rewriting reference mentions; the sweep items do that.
- The keys added by feat(user-interface): absorb emil kowalski's gestures skill and re-pin the upstream record #14208, feat(user-interface): add a configurable long-form reading size #14210, feat(user-interface): add a motion cleanup sub-mode with a configurable pass order #14212 and feat(user-interface): default two-axis touch elements to tap-to-activate #14213.
- Editing other plugins.
- All t3dotgg/tstack work.
Activity
kyle-sexton commentedon Nov 9, 2026
Owner decision Q11 (2026-11-09): option (b). Add
animation.scale.press_min, default 0.95 (Emil's stated lower limit), whichauditreports 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).