Repository navigation
Description
Parent
Refs #14214
Source: PLAN Phase 2, topic literal-measurements-config
Depends on
Outcome
A team sets a taste key in its config and a skill writes that value, unless the project has a matching token. Press scale and control padding prove the form before any wider change.
Demo: On a scratch copy of the with-ds fixture, a team press scale of 0.9 writes 0.9, and a matching project token beats it.
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, proof runner and course files stay uncommitted there, so an autonomous lane cannot run its checks.
Load-bearing assumptions
| Assumption | Source | Falsifying check | Response if false |
|---|---|---|---|
| Durations and line counts from rough greps are replaced by the classified list; line numbers hold until the blockers land | Brief | Taste scan with its report-moved option lists the rows it re-keyed | Minor: re-key rows by content and proceed |
| An agent fills a placeholder with the resolved value instead of copying it | plan | The four placeholder proof runs report the expected values and hold no {{ |
Major: stop and replan the recipe form |
| A team token outranks a key through skill prose, since the detect script does not read token values | explore | The token proof run outputs the token's value | Major: stop and replan |
Decisions
- Plan D1: Placeholder form is
{{key}}, root-anchored; existing<animation.*>placeholders migrate to it. - Plan D2: One new file, the plugin's shared values reference, holds the placeholder rule and the AC11 order; each skill and each reference with a placeholder points there.
- Plan D3: Eight pull requests, each with a changelog fragment.
- Plan D5: Seven one-off proof runs and one existing eval case run against this slice.
- Plan D6: The detect test derives unset keys' expected values from the defaults file.
- Plan Q3: A recipe in a code block carries a placeholder naming the key.
- Plan Q10: A second owner review covers any delta from the blockers at this item's entry.
- Plan Q11: Skills name every rejected config key from
config.layers[].errors. - One-time named-key check (interview Q34, settled at plan): a scratch script scans the plugin's references, skills, scripts and README for placeholders and backticked names in the 11 namespaces. A placeholder must be a leaf, with
[n]inside its list length, in both the defaults file and the schema; a backticked name may also be a branch or.*wildcard. A failure stops the phase, and the result goes in the pull request body.
Key interfaces
From the plan's Key shape:
Placeholder:
{{animation.scale.press}}in a code block, with no spaces inside the braces and a first segment that is a config root. A list part is a zero-based{{spacing.control_padding[0]}}. A unit follows the closing braces ({{animation.duration_ms.press}}ms). A key naming a list expands to its items joined by,with no space. A sample that takes seconds writes the arithmetic ({{animation.duration_ms.medium}} / 1000). A placeholder never holds$, and the agent replaces the whole token and never leaves one in a written file. Prose names the key in backticks.
The values reference also states: the AC11 order and what "tokens of that kind" means; how a list part reads; the key-name shape rules; that a value below a floor stands and is reported; each written form (direct, negated, complement, scaled by key, derived stays an example); to name every dropped key; and that a team file nests keys.
Conventions followed: ADR 0075 (four-layer cascade and invalid-value rule); config-cascade contract; upstream-drift contract.
Done when
- AC1: Every number new or rewritten on the tree after feat(user-interface): default two-axis touch elements to tap-to-activate #14213 closes is classified as example, floor, taste or constant and posted to refactor(user-interface): move literal measurements in the references into config #14214.
- AC2: The owner reviewed that delta before any value moved.
- AC4: Press-scale and control-padding mentions name the key and restate no default number; a recipe carries a placeholder the agent fills in; the README Default column stays.
- AC11: A value resolves in this order for every skill: a matching project token, a key set by a team or person,
css.token_fallbackwhen tokens of that kind exist, and the plugin default only with no tokens of that kind. The key's plugin default replaces "use your own values" where a key exists. Scripts use what the caller passes. - AC12: A skill that cannot run the resolver reads the shipped defaults file; the glossary's common-usage numbers stay examples.
- AC14: A one-off run on a scratch copy of the
with-dsfixture, with a measurement token and a team key for the same role, outputs the token's value; the result is recorded in the pull request and nothing is committed for it. - AC15: No new test or CI check is added;
animation.scale.pressandspacing.control_paddingjoin the existing defaults test. - AC16: If a named key is missing during the build, the one-time named-key check stops the change; it exits 0 on this branch.
- AC19: The build starts only after feat(user-interface): default two-axis touch elements to tap-to-activate #14213 closes.
- All seven proof runs hold their expected values and no captured answer contains
{{;css-press-scaleran once; the total stays within a budget of 10 runs, raised only by the owner. - The defaults and detect tests pass, and the detect test adds no copy of the defaults.
- The pull request adds a changelog fragment.
Out of scope
- The other keys, added by the next item.
- Reference sweeps beyond the press-scale and control-padding mentions.
- 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