Skip to content

refactor(user-interface): prove key placeholders end to end with press scale #14311

Description

@kyle-sexton

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_fallback when 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-ds fixture, 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.press and spacing.control_padding join 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-scale ran 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

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