Repository navigation
Description
Parent
Source: its own interview on 2026-11-08, split from the Emil Kowalski upstream-sync effort.
Depends on
- feat(user-interface): default two-axis touch elements to tap-to-activate #14213 for the build; the planning stages proceed now.
Outcome
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.
Demo: Open a reference that held a taste measurement and see it name a config key instead; set that key in a team config, and see a downstream repository's own token win over it.
Problem:
- Gap: 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).
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
This item goes through the full human-in-the-loop chain with the owner at each gate. The interview is done; explore, research, design, plan and spec remain.
Constraints:
- Production quality bar. Uniform and consistent, DRY, one source of truth, across the repository, plugins and skills. 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.
- Provenance only in upstream records and changelog fragments.
- Nothing is added to CI unless it is 100 percent needed; any CI addition comes to the owner first.
- Mechanism details are settled at planning.
Decisions
Terms:
- Example: a value shown only to illustrate a technique or a bug.
- Floor: a minimum or limit backed by a standard or measurement, accessibility or not.
- Taste: a value chosen because it looks or feels right, with no measured requirement.
- Constant: a value true by definition, with nothing to configure.
- Heuristic: an openly unmeasured value.
- Role key: a key named for what a value is used for. Scale: an ordered set of steps for one kind of value.
Scope:
- A measurement is any number a team could reasonably choose differently, in any unit or none. Numbers that only count things in prose stay out.
- Coverage is the plugin's references, skill references, SKILL.md bodies and scripts. Tests, fixtures and evals change only where the move breaks them.
- Non-numeric approaches stay out; an approach gets a key when a specific rule calls for it.
- Only this plugin's values move. Explore lists any plugin that repeats a value this plugin teaches, and that list becomes a follow-up ticket.
Keys and homes:
- One key per role or scale, shared by every mention. A real difference between mentions becomes separate roles.
- A reference names only the key. Existing key-plus-default text is rewritten; the README Default column stays.
- Default values live in
reference/defaults.yaml. Each floor has one stated home with its source, other prose points there, a code example keeps its number, and a schema minimum may repeat a floor. The defaults test and README are the only other copies.
Defaults:
- Order: the course record on a conflict, then Emil Kowalski's latest source (his skills repository, posts and AI for UI course), then today's number. Other sources count as today's number with their source kept.
- Where mentions differ and he is silent, research picks; with no research answer, use the most common number and label it heuristic.
- A floor holds over any of these. Research covers every key, existing keys included.
- The owner receives a list of every default whose shipped number changes and every heuristic.
- A value with no upstream records its source in one links-only record under
docs/upstream. - 16px stays a floor: body text is backed by USWDS typography, and inputs by the WebKit source constant. A stated minimum with nothing behind it is taste until research finds a source. A taste key bounded by a floor gets a schema minimum.
Which value applies, for every skill:
- A matching project token, then a key set by a team or person, then
css.token_fallbackwhen tokens of that kind exist, and the plugin default only with no tokens of that kind. - The key's plugin default is the number the fallback carries, and replaces "use your own values" wherever a key exists. An agent picks a number only where no key exists.
- Scripts use what the caller passes. A skill that cannot run the resolver reads the shipped defaults file. The glossary's common-usage numbers stay examples.
- A project value below a floor stands, and the audit reports it.
Settled later: how the audit reports each floor and what a re-pin does (design, returned to the owner if either changes scope); what the one-time check scans and how keys are shaped (planning).
Key interfaces
- The plugin's defaults file holds new keys, the team schema validates them, and the plugin README lists them, in snake_case, through the existing cascade.
- The cascade's layers are plugin defaults, userConfig, team and personal.
Done when
- The full chain has run for this item, with the owner at each gate: interview,
/discovery:explore,/discovery:research, design,/planning:plan, and spec. - The list classifying every measurement in scope as example, floor, taste or constant is published in this issue, borderline values went to the owner, and the owner reviewed it at the plan gate before any value moved.
- Every taste value resolves through one role or scale key, and a reference names the key without restating its default.
- Every default follows the Defaults order, records its source, and research covered every key; the owner received the list of changed defaults and heuristics.
- Every floor is stated with its source in one home, and the audit reports a project value below a floor.
- 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 in the pull request and nothing is committed for it. - No new test or CI check is added: each new key is in the existing defaults test, a review rule covers new inline taste values and key names, and a one-time build check stops the change if a named key is missing.
- The README's layer table matches the cascade source, and the setup skill no longer offers a write to the user-global file the cascade does not read.
- The follow-up ticket for plugins that repeat these values is filed.
-
gh issue view <n> --json labelsshowsneeds-humanuntil the owner has been through the chain for this item.
Out of scope
- 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: evaluation, upstream record, its drift-check entry, the council port.
Activity
kyle-sexton commentedon Nov 9, 2026
Classified measurements (issue 14214)
For the owner's review at the plan gate, before any value moves (AC1, AC2, AC8). Paths are under
plugins/user-interface/. Generated from the role map.Counts: 1,222 rows in 64 files before excluding prose counts: 313 taste, 585 example, 201 constant, 61 floor, 62 not a measurement (excluded). Of the 313 taste numbers, 105 sit in code blocks. The design record's 316 counted one show-and-hide line as four numbers; here it is one.
Legend for the list: T taste, E example, F floor, C constant; a trailing c means the number is in a code block;
→names the key.Key set
100 roles in 111 leaves.
minis a schema minimum. One shipped key value changes:animation.easing.out.animation.blur_max_pxanimation.blur_px.softenanimation.delay_ms.group_warmanimation.delay_ms.tooltipanimation.delay_ms.indicatoranimation.duration_ms.exit_factoranimation.duration_ms.hoveranimation.duration_ms.largeanimation.duration_ms.mediumanimation.duration_ms.pressanimation.duration_ms.smallanimation.easing.inanimation.easing.outanimation.easing.spring_stand_inanimation.gesture.deceleration_rateanimation.gesture.rubberband_constantanimation.gesture.slop_pxanimation.gesture.velocity_thresholdanimation.inspect_playback_rateanimation.scale.enteranimation.scale.enter_smallanimation.scale.hover_maxanimation.scale.pressanimation.scale.swap_startanimation.skip_frequencyanimation.spring.bounce.defaultanimation.spring.bounce.playful_maxanimation.spring.duration_s.defaultanimation.spring.duration_s.smallanimation.spring.response_sanimation.stagger_ms.intervalanimation.stagger_ms.max_totalanimation.stagger_ms.sectionanimation.stagger_ms.wordanimation.travel_px.largeanimation.travel_px.mediumanimation.travel_px.smallcolor.border.dark_solid_lcolor.border.light_alphacolor.dark_mode.brand_desaturation_percentcolor.hover_mix_percentcolor.illustration_max_colorscolor.overlay_alphacolor.ramp.chroma_percentcolor.ramp.endpoints_lcolor.ramp.hue_spread_max_degcolor.subtle_mix_percentcolor.triage.light_surface_min_lcolor.triage.near_black_lcolor.triage.near_white_lcss.border_px.hairlinecss.border_px.standardcss.border_px.strongcss.concentric_radius.max_gap_pxcss.edge_fade.length,.stops_percentcss.focus_ring.offset_pxcss.focus_ring.widthcss.image_outline.opacityicon.filled_below_pxicon.label_gap_pxicon.size_emicon.size_pxlayout.breakout_widthlayout.content_widthlayout.grid_track_min_widthlayout.media_aspect_ratiolayout.media_smalllayout.panel_max_heightlayout.sidebar_widthlayout.simple_page_columnslayout.terminal_min_columnslayout.z_index_stray_aboveperformance.image_max_kbperformance.search_debounce_msperformance.virtualize_min_itemsradius.lradius.sspacing.control_paddingspacing.flowspacing.lspacing.mspacing.optical_icon_pxspacing.sspacing.sectionspacing.xsstates.copy_confirm_msstates.toast_reading_wpmstates.wait_indicator_mstouch.check_width_pxtouch.fixed_width_hunt_pxtouch.target_desktop_pxtypography.fluid_body.min_rem(min 1),.preferred_rem,.preferred_vw,.max_remtypography.fluid_scale.narrow_rem,.wide_rem,.size_narrow_rem(min 1),.size_wide_rem,.ratio_narrow,.ratio_wide,.space_m_factor,.space_l_factortypography.fluid_max_ratiotypography.line_height.bodytypography.line_height.displaytypography.measure_chtypography.small_text_px.captiontypography.small_text_px.controltypography.small_text_px.minMentions that are not a direct swap
248 of the 313 taste numbers equal their key's default, directly or by unit. The other 65 are below: 30 changed, 18 listed, 4 negated, 6 scaled by key, 6 derived, 1 complement.
Owner answers, plan Q6 and Q7. A duration key is both the value a recipe writes and the role's ceiling, so recipes below a role's upper end move to it. The
deriveddamping rows stay examples and keep their numbers. Plan Q9: the 9:1 pair stays a floor at guidance standing; the 2.5 fluid ratio atskills/write-css/reference/foundations.mdlines 234, 235, 296 and 297 is taste undertypography.fluid_max_ratio; the 44 finger-pad sentence is removed and the 44 floor stays. Alistednumber is recorded on the key's row,negatedandscaled by keyare written as expressions, andcomplementis rewritten to hold the key's own quantity.animation.duration_ms.pressanimation.scale.pressanimation.duration_ms.mediumanimation.duration_ms.mediumanimation.duration_ms.smallanimation.scale.enteranimation.duration_ms.largeanimation.duration_ms.largeanimation.duration_ms.largeanimation.duration_ms.largeanimation.duration_ms.largeanimation.blur_px.softenanimation.blur_px.softenspacing.optical_icon_pxicon.label_gap_pxanimation.inspect_playback_rateanimation.duration_ms.mediumlayout.content_widthanimation.travel_px.smallanimation.duration_ms.mediumanimation.duration_ms.largeanimation.duration_ms.mediumanimation.duration_ms.largeanimation.duration_ms.mediumanimation.duration_ms.mediumanimation.duration_ms.smallanimation.duration_ms.smallanimation.duration_ms.smallicon.label_gap_pxicon.label_gap_pxcolor.hover_mix_percentanimation.spring.bounce.defaultanimation.spring.bounce.playful_maxanimation.spring.bounce.defaultanimation.spring.bounce.playful_maxanimation.spring.bounce.playful_maxanimation.spring.bounce.defaultanimation.scale.pressanimation.scale.pressanimation.scale.pressanimation.scale.enteranimation.spring.duration_s.smallanimation.scale.enteranimation.scale.enteranimation.stagger_ms.intervalanimation.stagger_ms.intervalanimation.stagger_ms.intervalanimation.spring.bounce.playful_maxanimation.gesture.deceleration_ratespacing.optical_icon_pxtypography.measure_chtypography.measure_chtypography.measure_chtypography.measure_chanimation.scale.enteranimation.travel_px.smallanimation.travel_px.mediumcss.border_px.standardanimation.travel_px.smallanimation.duration_ms.exit_factoranimation.duration_ms.exit_factoranimation.duration_ms.exit_factoranimation.duration_ms.exit_factoranimation.duration_ms.exit_factoranimation.duration_ms.exit_factorHeuristics
animation.easing.in: 0.3, 0, 1, 1color.subtle_mix_percent: 12icon.size_px: 12, 16, 20, 24, 48layout.breakout_width: 80remlayout.grid_track_min_width: 16remlayout.media_aspect_ratio: 16 / 9layout.media_small: 3.5remlayout.panel_max_height: 80dvhlayout.sidebar_width: 20rem, 50%radius.l: 1.25remspacing.control_padding: 0.75rem, 1.25remspacing.flow: 1lh, 2em, 0.5emspacing.section: clamp(3rem, 1rem + 6vw, 8rem), 6remtypography.fluid_body.min_rem(min 1),.preferred_rem,.preferred_vw,.max_rem: 1, 0.75, 1, 1.75typography.fluid_scale.narrow_rem,.wide_rem,.size_narrow_rem(min 1),.size_wide_rem,.ratio_narrow,.ratio_wide,.space_m_factor,.space_l_factor: 20, 77.5, 1.125, 1.25, 1.2, 1.25, 1.5, 2typography.fluid_max_ratio: 2.5Class doubts and borderline values
Each line gives the class used and the doubt. Paths here are from the repository root.
No class was changed here. Each line gives the class used and the doubt.
Same kind of number, classed differently across drafts:
write-cssrecipe literals taste, because those files call them "this skill's defaults". The layout-type draft classes every code block underreference/types/web/example. So hover 150ms is taste atplugins/user-interface/reference/animation/catalog.md:200,266and example atplugins/user-interface/reference/types/web/shape-and-depth.md:153andplugins/user-interface/reference/types/web/typography/details-and-floors.md:28.plugins/user-interface/skills/write-css/reference/interaction.md:27,28, example atplugins/user-interface/reference/types/web/accessibility.md:79,80. WCAG 2.2 SC 2.4.13 (Level AAA) requires the indicator to be "at least as large as the area of a 2 CSS pixel thick perimeter" (Understanding 2.4.13), so 2px may be a floor at AAA. Neither research run covered it.plugins/user-interface/reference/types/web/color.md:29,215,218,221,226,234andplugins/user-interface/skills/write-css/reference/spacing-and-shape.md:154; taste atplugins/user-interface/reference/types/web/shape-and-depth.md:122,126,203,228.Other doubts, from the four drafts' Borderline sections:
plugins/user-interface/reference/animation/behaviors.md:42,43,126,176,192-195,222,223,242-245: example;plugins/user-interface/reference/animation/behaviors.md:13says "keep the values" andplugins/user-interface/reference/animation/catalog.md:16-18says "never a template to copy", and one needs rewording either way.plugins/user-interface/reference/animation/behaviors.md:253: taste; the line says "such as", which reads as example.plugins/user-interface/reference/animation/catalog.md:289(200ms): example; line gives a reason, which reads as taste.plugins/user-interface/reference/animation/catalog.md:34,plugins/user-interface/reference/types/web/states.md:135,137,154,plugins/user-interface/skills/audit/reference/launch-scope.md:385(400ms): taste; a floor if a responsiveness source backs it.plugins/user-interface/reference/animation/gestures.md:120,121,135: taste; constants if the WWDC source fixes them.plugins/user-interface/reference/animation/catalog.md:563,plugins/user-interface/skills/audit/reference/frame-capture.md:112: taste; review procedure, which reads as example.plugins/user-interface/skills/write-css/reference/interaction.md:135,plugins/user-interface/reference/types/touch-web.md:149,170,171(24px): example; the owner ruled 24 the AA floor.plugins/user-interface/reference/types/touch-web.md:149(44px finger pad): floor; X2 found no source stating it.plugins/user-interface/reference/types/web/shape-and-depth.md:131-144,170(elevation alphas): example; reads as taste.plugins/user-interface/reference/types/web/shape-and-depth.md:297(10% image outline): taste; the file says "not up for theming".plugins/user-interface/reference/types/web/typography/details-and-floors.md:24-26(underline),plugins/user-interface/reference/types/web/typography/scale-and-rhythm.md:96,102(tracking),plugins/user-interface/reference/types/web/icons.md:39-43(stroke),plugins/user-interface/reference/types/web/accessibility.md:205(200ms exit delay): example; reads as taste.plugins/user-interface/reference/types/web/layout-stability.md:149,150(font weights): constant; the sentence says "adjustable globally".plugins/user-interface/reference/types/web/layout.md:112(8),plugins/user-interface/reference/types/web/icons.md:216(about 3),plugins/user-interface/reference/types/web/component-api.md:87,320: counts in prose under one reading; the first two are classed taste, the last not-a-measurement.plugins/user-interface/reference/types/web/states.md:251(200-250 wpm): taste; measured if a source is cited.plugins/user-interface/reference/types/terminal.md:104(80): taste; a convention, which reads as constant.plugins/user-interface/reference/types/web/color.md:135,plugins/user-interface/skills/write-css/reference/foundations.md:157,158(mix amounts),plugins/user-interface/reference/types/web/color.md:215,218(border values),plugins/user-interface/reference/types/web/color/building-scales.md:18,19,25(ramp): taste; each could be example.plugins/user-interface/reference/types/web/color/building-scales.md:134(~10 degrees): taste; a floor if a perceptual measurement backs it.plugins/user-interface/reference/types/web/color.md:88-127,plugins/user-interface/reference/types/web/color/contrast.md:97-103(triage): taste;plugins/user-interface/reference/types/web/color/contrast.md:102-104says they do not replace the calculation, so no key is the other reading.plugins/user-interface/reference/types/web/color.md:177(9:1): floor; 3:1 times 3:1, a constant under the other reading. W3C technique C40 is sufficient guidance, not a success criterion.plugins/user-interface/reference/types/web/color/contrast.md:23(24px, 18.5px): constant conversions; the px form of a floor under the other reading.plugins/user-interface/reference/types/web/color.md:57,plugins/user-interface/reference/types/web/color/building-scales.md:54,plugins/user-interface/reference/types/web/color/gamut-and-p3.md:17-21,58: constant; sample lightnesses read as example.plugins/user-interface/reference/design-system-doc.md:220,230(16, 14, 12px): example; the line says not values to impose, against the owner's rulings on those numbers.plugins/user-interface/skills/audit/reference/launch-scope.md:118: example; the pattern encodes the 16px floor and an unstated z-index threshold.plugins/user-interface/skills/audit/reference/launch-scope.md:375(100+/day): taste; a count in prose under the other reading.plugins/user-interface/skills/write-css/reference/foundations.md:234,235,296,297(2.5): floor; taste until research backs the derivation (B5 does not).plugins/user-interface/skills/write-css/reference/layout.md:168,170,173,plugins/user-interface/skills/write-css/reference/scroll-and-viewport.md:210,220(4rem),plugins/user-interface/skills/write-css/reference/show-and-hide.md:299,304(-3rem),plugins/user-interface/skills/write-css/reference/spacing-and-shape.md:154,155: example; reads as taste.plugins/user-interface/skills/write-css/reference/text-and-media.md:80,87,88,152,153,161,162,210: taste; per-component literals or a constant under the other reading.Lines with a key-worthy number and no kept row, so they need rows:
plugins/user-interface/reference/animation/behaviors.md:116andplugins/user-interface/reference/animation/catalog.md:160.Classified list
Added after the merge check:
skills/write-css/vendor/check-css.mjs19: 300 T →animation.duration_ms.large; 20: 500 T, retired because no key holds it;reference/animation/behaviors.md116 andreference/animation/catalog.md160 also take keys.README.md
reference/animation/behaviors.md
reference/animation/catalog.md
reference/animation/gestures.md
reference/animation/performance.md
reference/concerns.json
reference/design-system-doc.md
reference/types/mods.md
reference/types/terminal.md
reference/types/touch-web.md
reference/types/web.md
reference/types/web/accessibility.md
reference/types/web/color.md
reference/types/web/color/building-scales.md
reference/types/web/color/contrast.md
reference/types/web/color/converting-colors.md
reference/types/web/color/gamut-and-p3.md
reference/types/web/color/tailwind.md
reference/types/web/component-api.md
reference/types/web/forms.md
reference/types/web/generic-defaults.md
reference/types/web/icons.md
reference/types/web/layout-stability.md
reference/types/web/layout.md
reference/types/web/marketing-pages.md
reference/types/web/performance.md
reference/types/web/shape-and-depth.md
reference/types/web/states.md
reference/types/web/theming.md
reference/types/web/typography.md
reference/types/web/typography/details-and-floors.md
reference/types/web/typography/font-capabilities.md
reference/types/web/typography/line-behavior.md
reference/types/web/typography/scale-and-rhythm.md
reference/types/web/typography/tailwind.md
reference/types/web/typography/typefaces-and-formats.md
scripts/focus-path.mjs
skills/audit/reference/frame-capture.md
skills/audit/reference/launch-scope.md
skills/audit/reference/motion.md
skills/audit/SKILL.md
skills/design/reference/order-of-work.md
skills/glossary/reference/analytics.md
skills/glossary/reference/color.md
skills/glossary/reference/copywriting.md
skills/glossary/reference/design-tools.md
skills/glossary/reference/easing-and-springs.md
skills/glossary/reference/icons.md
skills/glossary/reference/interaction.md
skills/glossary/reference/layout.md
skills/glossary/reference/motion.md
skills/glossary/reference/rendering-performance.md
skills/glossary/reference/typography.md
skills/glossary/SKILL.md
skills/write-css/reference/foundations.md
skills/write-css/reference/interaction.md
skills/write-css/reference/layout.md
skills/write-css/reference/motion.md
skills/write-css/reference/scroll-and-viewport.md
skills/write-css/reference/show-and-hide.md
skills/write-css/reference/spacing-and-shape.md
skills/write-css/reference/text-and-media.md
skills/write-css/scripts/review.mjs
skills/write-css/vendor/check-css.mjs
kyle-sexton commentedon Nov 9, 2026
Post-blocker rescan for #14311 (main at b0a0df2, against the design scan's base 8a00f58)
#14212 (#14383) and #14213 (#14524) are closed, so #14311 is unblocked. Since the design scan, PRs #14319, #14322, #14383 and #14524 changed 20 files under
plugins/user-interface.New or rewritten numbers: none outside config. Every number they added is already a key with a default in
reference/defaults.yaml:animation.gesture.distance_threshold0.4typography.long_form_body_px18(floor16, enforced by the config check)animation.cleanup_ordertouch.both_axes_activationtap-to-activate, no numberThe prose that mentions them (README,
behaviors.md,typography.mdsection 6,touch-web.mdsection 6,scroll-and-viewport.md) names the key beside the value. They are four of the 100 roles already counted (D5, D11), so the count does not change.Line drift: row positions in the classified list now differ for rows below the inserted text in
behaviors.md,catalog.md,gestures.md,touch-web.md,typography.mdandscroll-and-viewport.md. A rerun flipped the code/prose flag on 5 rows for that reason only, with no value change. The #14311 build finds each row by its value, not its line number.Basis:
git diff -U0 8a00f58a3c b0a0df2227 -- plugins/user-interface(added lines that contain a digit), and a rerun of the local classified-list scan.Plan Q10 still needs the owner's go-ahead on this delta before the build starts.
kyle-sexton commentedon Nov 10, 2026
All eight child issues (#14311-#14318) are closed with merged PRs. Closed by the owner's decision in session.