kwakseongjae/oh-my-design / skills/omd-feel
omd-feel
Verified디자인·프론트 업계가 '감'으로 쓰던 인터페이스 디테일을 수치화한 규칙으로 적용(APPLY)하거나 감사(AUDIT)한다. Jakub Krehel의 make-interfaces-feel-better 철학을 계승 + HIG/Material/WCAG/DS 토큰/실무자 리서치로 확장한 17축·113규칙(provenance 등급별). 모션 타이밍·이징·동심원 radius·tabular-nums·44px 타깃·focus ring·prefers-reduced-motion 등. 'feel 좋게 다듬어줘', '인터페이스 디테일 적용', 'feel 점검', '마이크로 인터랙션 손봐줘', 'make this feel better', 'polish the interactions', 「インターフェースの細部を詰めて」, 「介面細節打磨」 류에 트리거. 브랜드 토큰은 DESIGN.md(omd:apply)가 우선.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.1 KB |
| provenance.md | markdown | 51.6 KB |
| reference.md | markdown | 100.4 KB |
provenance.md
View on GitHub# omd:feel — Provenance & Methodology
**Date:** 2026-06-23
**What this is:** the evidence layer behind [`reference.md`](./reference.md). Every quantified rule traces to a source and a provenance tier, so an AI (or a reviewer) can tell a *spec gate* from a *taste heuristic*. The full rule bodies (default/range/anti-pattern/machine_check) live in `reference.md`; this file adds **where each number comes from**.
**Seed:** Jakub Krehel, *Details That Make Interfaces Feel Better* / `jakubkrehel/make-interfaces-feel-better` (https://jakub.kr/writing/details-that-make-interfaces-feel-better).
## Methodology
Multi-agent research workflow (44 agents): Seed → 14-category Extract → adversarial provenance Verify → dedup Synthesize → completeness Critic + Gap-fill.
**Result:** 113 synthesized rules across 17 dimensions, from 224 verified findings + 21 seed rules.
**Tier distribution:** SPEC 61, DS 24, CONV 19, OP 7, FOLK 2 — 85 of 113 spec/token-backed (enforceable).
## Extended philosophy
Jakub Krehel's thesis — "great interfaces are a collection of small things that compound" — is correct but, as stated, unfalsifiable: it tells you to care about details without telling you which numbers a detail should hit, or how to know when you've gotten one wrong. This corpus closes that gap. It converts the gut-feel of senior designers into a numbered, provenance-graded, machine-checkable system: every rule carries a default value, a defensible range, the curve or unit it lives in, an anti-pattern that names the failure mode, and a `machine_check` that an auditor (or an AI) can run against real DOM/CSS/native code. The compounding claim becomes operational — quality is the integral of dozens of small constraints each held inside its band, and a single out-of-band value (a 600ms checkbox tick, a 1px focus ring, body text at 2.85:1, a hover lift with no `@media (hover: hover)` gate) is a measurable subtraction from "feel," not a vibe.
The extension that makes this AI-applicable is honest provenance tiering. Not all numbers are equal: WCAG normative criteria, Apple HIG verbatim values, and committed design-system tokens (Carbon, Fluent, Polaris, Primer, M3) are load-bearing and can be enforced as gates; convergent multi-practitioner conventions (the ~150-300ms UI band, exit ≈ 0.8× enter, ease-out for enters) are strong defaults; and single-opinion craft tricks (Comeau's 2:1 shadow ratio, transient blur on crossfades) or outright folklore ("skeletons feel 30% faster," "1px @ 10% image hairline") are kept but *labeled* so downstream systems treat them as heuristics, never specs. An AI generating UI should therefore (1) hard-enforce spec-authoritative and ds-token rules, (2) apply industry-convention defaults unless overridden by a named design system, and (3) offer single-opinion/folklore items only as suggestions with their tier disclosed. The system also resolves conflicts by provenance: when M3 says state-layer focus is 10% and mdui/M2 say 12%, the M3 spec value wins and the alternative is noted — so the corpus converges on one answer per question while preserving the dissent. This is the quantified, checkable continuation of "small things compound": a machine can now audit the small things one by one.
---
## Per-rule provenance
### 1. Motion & Timing (durations)
- 🟢 SPEC · **Scale transition duration to the traversed area/distance: tiny state changes get short tokens, full-screen transitions get long tokens — never one global duration.** — material-components-android Motion.md ('duration should increase as the area/traversal of an animation increases'); m3.material.io/styles/motion/overview; vercel.com/design Geist (150/200/300ms tiering)
- 🟢 SPEC · **Quantize every duration to the M3 token scale (50ms steps 50-600, then 700/800/900/1000) — never hand-pick arbitrary ms.** — m3.material.io/styles/motion/easing-and-duration/tokens-specs; material-components-android Motion.md; mdui design-tokens
- 🟡 CONV · **Keep functional UI animations under ~300ms; aim ~150-200ms for most enter/exit transitions.** — Emil Kowalski 'Great Animations' / '7 Practical Tips' (animations.dev); Rauno Freiberg raunofreiberg/interfaces (≤200ms 'feel immediate'); nngroup.com/articles/animation-duration (100-500ms)
- 🟢 DS · **Use the Carbon duration ladder for productive/enterprise UI: 70ms button/toggle, 110ms fade, 150ms small expand, 240ms toast/expansion, 400ms large expansion, 700ms backdrop dim.** — @carbon/motion src/index.ts (committed tokens); carbondesignsystem.com/elements/motion/overview
- 🟢 DS · **Use the Fluent 2 duration ramp (50-500ms in 8 steps): hover ≤100ms, standard controls 150-200ms, dialogs/panels ≥300ms.** — fluentui packages/tokens/src/global/durations.ts (committed)
- 🟢 DS · **Quantize Polaris durations to a 50ms grid 0-500ms (plus a 5000ms loop slot); never use in-between values.** — Shopify/polaris polaris-tokens/src/themes/base/motion.ts (committed MotionDurationScale)
- 🟢 DS · **Quantize Primer durations to a 100ms grid (with a 50ms half-step) 0-1000ms; keep UI transitions 100-400ms. Primer skips 150/250/350.** — primer/primitives src/tokens/base/motion/timing.json5 (committed DTCG tokens)
- 🟢 DS · **Collapse Ant Design motion into fast/mid/slow ≈100/200/300ms (computed from motionBase=0 + motionUnit=0.1).** — ant-design seed.ts + genCommonMapToken.ts (computed tokens)
- 🟢 DS · **Use 300ms entering / 250ms returning for container-transform transitions; 150ms incoming / 75ms outgoing (linear) for cross-fades.** — material-components-android Motion.md (container transform 300/250; fade 150/75 linear)
- 🟢 DS · **Make exit/dismiss/collapse animations shorter than their enter — roughly 0.8× (75-85%).** — m2.material.io/design/motion/speed (nav drawer 250/200, card 300/250); MUI enteringScreen 225 / leavingScreen 195; NN/g (popup 300/200-250)
### 2. Easing & Springs
- 🟡 CONV · **Default to ease-out/decelerate for elements entering and any user-initiated transition; the fast start reads as instant responsiveness. Never use ease-in for enters.** — Emil Kowalski 'The Easing Blueprint' / 'Great Animations'; m1.material.io/motion/duration-easing (decelerate 0,0,0.2,1); Material decelerate token
- 🟢 SPEC · **Use the M3 standard easing cubic-bezier(0.2,0,0,1) for on-screen moves; standard-decelerate (0,0,0,1) for enters, standard-accelerate (0.3,0,1,1) for exits; emphasized variants for hero motion.** — material-components-android Motion.md; mdui design-tokens; m3.material.io/styles/motion/easing-and-duration/tokens-specs
- 🟢 SPEC · **Treat M3 'emphasized' as a 3-stop spring-like PATH curve, not a single cubic-bezier; cubic-bezier(0.2,0,0,1) is only its approximation (and is actually the 'standard' token). Use CSS linear() or an Android PathInterpolator for true emphasized motion.** — material-components-android Motion.md (emphasized = Path curve); developer.chrome.com/docs/css-ui/css-linear-easing-function
- 🟢 DS · **Use ease-in-out only for elements already on-screen that change position or shape (morphing) — not for enter/exit.** — Emil Kowalski 'The Easing Blueprint'; m1.material.io (standard 0.4,0,0.2,1); MUI easeInOut
- 🟢 DS · **Pick easing by intent and lifecycle from your DS token set — productive/practical for dense task UI, expressive/bold for hero moments; entrance curves start at (0,0), exit curves end at x=1.** — @carbon/motion src/index.ts; fluentui packages/tokens/src/global/curves.ts; Shopify/polaris base/motion.ts; primer/primitives easing.json5; uber/baseweb animation.ts; ant-design seed.ts; atlassian.design/foundations/motion
- 🟢 DS · **Reserve overshoot 'back' easings (control points outside 0-1) for playful emphasis only; never on dense/productive UI.** — ant-design seed.ts (motionEase* committed curves)
- 🟢 SPEC · **On Apple platforms, default UI motion to a spring (response 0.55, dampingFraction 0.825, blendDuration 0); think response+damping, not fixed duration. Pick smooth/snappy/bouncy by intent.** — Apple SwiftUI Animation.spring docs (defaults 0.55/0.825/0); WWDC23 'Animate with springs'
- 🟢 SPEC · **Default spring bounce to 0 (smooth); use up to ~0.15 for liveliness, ~0.3 for noticeable bounce, but stay under ~0.4 for functional UI. In Motion/Framer, set bounce + visualDuration, not raw stiffness/damping/mass.** — WWDC23 'Animate with springs' ('when not sure use bounce 0', caution above ~0.4); motion.dev/docs/spring (defaults bounce 0.25)
- ⚪ OP · **Use Apple-talk practitioner spring tuning by interaction context (single-source reconstruction, not Apple-official): light tap ~damping 0.4/response 0.2, momentum drawers ~0.8/0.3, draggable PiP ~1.0/0.4.** — Nathan Gitter 'Building Fluid Interfaces' (Medium reconstruction of WWDC18 803)
### 3. Spacing & Rhythm
- 🟢 SPEC · **Set every margin, padding, gap and dimension to a multiple of 8px (4px allowed as a half-step for icons/small text).** — designsystems.com/space-grids-and-layouts; m2.material.io ('components align to 8dp baseline grid; icons/type to 4dp')
- 🟢 SPEC · **Round every line-height (and text-block height) to a multiple of 4px so baselines land on a 4px vertical grid.** — designsystems.com/space-grids-and-layouts; Material (type aligns to 4dp baseline grid)
- 🟡 CONV · **Generate font sizes by multiplying a base by a fixed modular ratio rather than picking sizes ad hoc.** — A List Apart 'More Meaningful Typography' (Tim Brown / modularscale.com); Cieden type-scale guide
- 🟡 CONV · **Keep space INSIDE a component ≤ the space AROUND it, so grouping reads via Gestalt proximity.** — Cieden spacing best-practices; nngroup.com/articles/gestalt-proximity
- 🟢 SPEC · **Use responsive Material body margins (16dp phone → 32dp at small breakpoint, cap 200dp) and gutters (16dp ≥360dp / 24dp ≥600dp); align icon-leading content to the 72dp keyline (icon at 16dp).** — m2.material.io/design/layout/responsive-layout-grid; m1.material.io/layout/metrics-keylines (verbatim 16dp/72dp)
### 4. Radius & Shape
- 🟢 SPEC · **Set a nested element's radius to the parent's radius minus the gap between them: outer = inner + padding (e.g. 20 = 12 + 8).** — ondrejkonecny.com/blog/nested-rounded-corners; frontendmasters.com/blog (Lily Konings formula); SwiftUI ConcentricRectangle WWDC25 / iOS 26; jakub.kr 'Details That Make Interfaces Feel Better'
- ⚪ OP · **Optionally clip the parent's overflow at the padding box so children inherit a correct concentric corner automatically — but keep a calc()-based fallback (weak Safari support).** — frontendmasters.com/blog/the-classic-border-radius-advice-plus-an-unusual-trick
### 5. Shadow & Depth
- 🟡 CONV · **Stack 3-6 box-shadow layers (blur/offset roughly doubling 1/2/4/8/16px) instead of one shadow; lower each layer's alpha as you add layers so total darkness stays ~constant.** — Tobias Ahlin 'Layered smooth box-shadows' (5-layer @0.12, 6-layer @0.11); joshwcomeau.com/css/designing-shadows (doubling 1/2/4/8/16)
- ⚪ OP · **Keep vertical (Y) shadow offset ~2× the horizontal (X) offset and keep that ratio/direction identical site-wide to imply one fixed light source.** — joshwcomeau.com/css/designing-shadows ('vertical offset is always 2x the horizontal one')
- 🟢 DS · **As elevation increases, increase BOTH blur radius and Y-offset and DECREASE per-layer opacity (the three move together); pull large layers in with a negative spread so they don't balloon into a halo.** — joshwcomeau.com/css/designing-shadows; Tailwind box-shadow docs (lg -3px, xl -5px, 2xl -12px spread); MDC _elevation-theme.scss (negative umbra/penumbra spread)
- 🟢 DS · **Use the Tailwind elevation ramp as concrete two-layer tokens (0.05-0.25 alpha): cards≈md, dropdowns/popovers≈lg, modals≈xl, hero≈2xl. (v3 names; v4 renamed sm→xs etc.)** — v3.tailwindcss.com/docs/box-shadow (exact values); tailwindcss.com/docs/box-shadow (v4 remap)
- 🟢 DS · **Build Material elevation from three stacked shadows (key-light umbra + penumbra + ambient) at fixed opacities 0.20/0.14/0.12, mapped to the dp level scale.** — MDC _elevation-theme.scss (committed 0.2/0.14/0.12); m3.material.io/styles/elevation/tokens; designfornative.com (M3 dp summary)
- 🟢 SPEC · **In dark mode convey elevation by LIGHTENING the surface with a semi-transparent white overlay (higher = brighter), not by darkening shadows. M3 expresses elevation via a tonal surface-tint overlay + shadow.** — m2.material.io/design/color/dark-theme (overlay table); Android Compose Material3 docs (tonal overlays); m3.material.io/styles/elevation/applying-elevation
- ⚪ OP · **Tint shadows with the background's hue at reduced lightness instead of pure black/grey; on colored surfaces a desaturated black reads as dull grey film.** — joshwcomeau.com/css/designing-shadows
- ⚪ FOLK · **Add a 1px inset hairline (~10% opacity, black light / white dark, outline-offset:-1px) on images/media so light-on-light media doesn't bleed into the page. NOTE: the 10% value is folklore — the technique is sound but no authoritative source pins the number.** — jakub.kr (technique, 10% value); learnui.design '37 ways' (low-opacity image borders, weaker corroboration)
### 6. Typography
- 🟢 SPEC · **Never break layout when users override spacing to the WCAG 1.4.12 floors: line-height 1.5×, letter 0.12×, word 0.16×, paragraph 2× font-size.** — w3.org/WAI/WCAG21/Understanding/text-spacing (SC 1.4.12 normative)
- 🟢 SPEC · **Constrain body measure to ~66ch (45-75 comfort band, hard cap ~90ch) and set max-width in a font-relative unit (ch/em), not px, so measure stays correct across font-size and zoom.** — practicaltypography.com/line-length (Butterick 45-90); Bringhurst/Elements of Typographic Style (45-75, 66 ideal)
- ⚪ OP · **Set body line-height ~1.5-1.6 unitless, headings ~1.1; longer measures need more leading, mobile/narrow less.** — pimpmytype.com/line-length-line-height (Oliver Schöndorfer); m3.material.io/styles/typography/applying-type
- 🟡 CONV · **Tighten letter-spacing as size grows: −0.02 to −0.03em for display (>~60px), ~0 body; inversely, ALL-CAPS labels want POSITIVE tracking ~+0.05 to +0.1em.** — loremforge.com/learn/kerning-tracking-letter-spacing; fonts.com tracking guide; Pimp my Type / Butterick (all-caps)
- 🟢 DS · **For Inter, compute letter-spacing from size with the Dynamic Metrics curve instead of one value: tracking = −0.0223 + 0.185·e^(−0.1745·size_px).** — d.rsms.me/inter-website/v3/dynmetrics (Rasmus Andersson, font author); rsms.me/inter
- 🟢 SPEC · **Apply text-wrap:balance only to headings/short text (≤6 lines Chromium, ≤10 Firefox); use text-wrap:pretty on body to kill last-line orphans (Chromium refines last 4 lines). Don't substitute one for the other.** — developer.chrome.com/docs/css-ui/css-text-wrap-balance (6-line cap); MDN text-wrap / Firefox bug 1851756 (10-line); developer.chrome.com/blog/css-text-wrap-pretty (last 4 lines)
- 🟢 SPEC · **Keep font-optical-sizing:auto (default) on variable fonts with an opsz axis so glyphs re-shape per rendered size; only override opsz when art-directing.** — MDN font-optical-sizing; fonts.google.com/knowledge/glossary/optical_size_axis
- 🟢 SPEC · **Use font-variant-numeric:tabular-nums for numbers that change in place or align in columns (timers, counters, tables, prices, numeric inputs); leave proportional for prose.** — MDN font-variant-numeric; raunofreiberg/interfaces; jakub.kr; vercel.com/design (triple-corroborated)
- 🟢 SPEC · **Keep body and label text at least 11pt (iOS) / pass color-contrast at size; apply -webkit-font-smoothing:antialiased once at the root for macOS crispness (no-op elsewhere).** — Apple 'UI Design Dos and Don'ts' (developer.apple.com/design/tips); MDN font-smooth; dbushell.com/2024/11 (post-Mojave)
### 7. Color & Contrast
- 🟢 SPEC · **Give body text ≥4.5:1 contrast; large text (≥24px or ≥18.67px bold) may drop to 3:1; AAA pushes to 7:1 / 4.5:1. Never round before comparing.** — w3.org/WAI/WCAG21/Understanding/contrast-minimum (1.4.3); WCAG 1.4.6 (AAA); webaim.org/articles/contrast (px conversions)
- 🟢 SPEC · **Give UI component boundaries, state borders, and meaningful icons/graphics ≥3:1 contrast against adjacent colors.** — w3.org/WAI/WCAG21/Understanding/non-text-contrast (1.4.11)
- 🟢 SPEC · **Make the keyboard focus indicator ≥2px thick covering the full perimeter, with ≥3:1 change-of-contrast between the same pixels focused vs unfocused; add ~2px outline-offset so it lifts off the edge.** — w3.org/WAI/WCAG22/Understanding/focus-appearance (SC 2.4.13); sarasoueidan.com/blog/focus-indicators
- 🟢 SPEC · **Render M3 interaction feedback as a translucent state-layer overlay (hover 8%, focus 10%, pressed 10%, dragged 16%) tinted with the content's 'on-' color, not a swapped background. (Legacy mdui/M2 use focus/pressed 12% — prefer M3 values.)** — m3.material.io/foundations/interaction/states/state-layers (8/10/10/16); mdui (M2-derived 12% — alternative)
- 🟢 DS · **Render disabled content at 38% opacity, disabled containers at 12%, and exempt disabled controls from contrast checks; never add hover/pointer feedback to them.** — m3.material.io (disabled tokens 0.38/0.12); WCAG 1.4.3/1.4.11 (inactive exemption)
- 🟢 DS · **Dim the background behind modals/dialogs/sheets with a scrim of black at ~32% opacity (Material); systems vary 30-60%.** — m3.material.io/components/dialogs/specs (scrim 32%); m2.material.io/components/dialogs
- 🟡 CONV · **Map status meaning to conventional hues (red=error/destructive, green=success, amber=warning, blue=info) and never carry meaning by hue alone — pair with icon/text.** — cross-DS convention (Material, Carbon, Polaris, Spectrum); w3.org/WAI/WCAG21/Understanding/use-of-color (1.4.1, spec for the color-independence half)
- 🟢 SPEC · **Under APCA (WCAG 3 draft, NOT yet binding) target Lc 75 body min / Lc 90 preferred / Lc 60 non-body / Lc 45 headline / Lc 30 min text / Lc 15 non-text, gated by font size+weight.** — git.apcacontrast.com/documentation/APCA_in_a_Nutshell (draft, flagged non-binding)
### 8. States & Feedback (microinteractions)
- 🟡 CONV · **Design every data-bearing component for all five states — empty, loading (skeleton), error, content/success, and ideal/populated — with a CTA in empty and a retry in error.** — Dan Saffer 'Microinteractions'; carbondesignsystem.com/patterns/empty-states-pattern; nngroup.com/articles/empty-state-interface-design
- 🟢 DS · **On :active press, scale the control to ~0.95-0.97 over ~150ms ease-out for tactile feedback, then spring back; drive it with a CSS transition so an early release retargets smoothly.** — tailwindcss.com (active:scale-95); raunofreiberg/interfaces ('~0.96, ~0.9 or so'); animations.dev easing-blueprint (0.97/150ms); jakub.kr (scale 0.96, never below 0.95)
- ⚪ OP · **Start entrance scale from ~0.9-0.96 (not 0), fade opacity in, and set transform-origin to the anchor so popovers/dropdowns scale FROM their trigger (use --radix-*-transform-origin).** — emilkowalski skills SKILL.md (0.96); raunofreiberg/interfaces (~0.8); Emil '7 Practical Tips' (origin-aware, 0.93 demo)
- 🟡 CONV · **Animate a contextual icon swap (copy→check) with scale 0.25→1 + opacity 0→1 + blur 4px→0 on a no-bounce spring (~0.3s, bounce 0); keep both variants in the DOM (one absolutely positioned) for a cross-fade.** — jakub.kr animations.md (seed library canon)
- 🟢 SPEC · **Make animations interruptible and retargetable — a new target mid-flight redirects from the current position preserving velocity; use CSS transitions/springs (which retarget) for re-triggered UI, @keyframes only for one-shot sequences.** — Emil Kowalski 'Great Animations'; Apple WWDC18 'Designing Fluid Interfaces' (Session 803); jakub.kr animations.md; motion.dev/docs/react-use-spring
- 🟢 SPEC · **For low-risk likely-to-succeed mutations, update the UI immediately (optimistic) and reconcile/rollback on failure with an explicit message; assign request identity so only the latest commits; never for payments/deletes/irreversible actions.** — react.dev/reference/react/useOptimistic; tanstack.com/query optimistic-updates
- 🟢 DS · **Delay hover-triggered panels by a short intent window (~100ms, 6px sensitivity) and keep them open a ~300ms grace period after the cursor leaves; for mega-menus use a cursor→submenu 'safe triangle' (tolerance ~75px), not a fixed timeout.** — Brian Cherne jQuery hoverIntent (interval 100, sensitivity 6); kamens/jQuery-menu-aim (tolerance 75, DELAY 300); Emil '7 Practical Tips' (grouped tooltips 0ms)
- 🟢 SPEC · **Use the three standard haptic generators by meaning (iOS): selection for value changes, impact (light/medium/heavy/soft/rigid) for collisions/boundaries, notification (success/warning/error) for outcomes — never decoratively, always with an on-screen change.** — developer.apple.com/design/human-interface-guidelines/playing-haptics; UIKit UIFeedbackGenerator
- 🟡 CONV · **Auto-dismiss an actionless toast/snackbar after 4-10s (Material guideline); if it carries an action, keep it until the user acts or dismisses. NOTE: Android's LENGTH_LONG implementation default is ~2.75s, below the 4s guideline.** — m3.material.io/components/snackbar/guidelines (4-10s); material-components-android Snackbar.java (LENGTH_SHORT 1500 / LENGTH_LONG 2750 — impl caveat)
### 9. Targets & Pointer
- 🟢 SPEC · **Give every interactive control a hit area ≥44×44pt (Apple/WCAG AAA), ≥48×48dp (Material/Android ≈9mm), and never below the 24×24 CSS px WCAG 2.2 AA floor — padding the touch area beyond the visible glyph.** — developer.apple.com/design/tips (44pt verbatim); support.google.com/accessibility/android/answer/7101858 (48dp ≈9mm); w3.org/WAI/WCAG22/Understanding/target-size-minimum (24px AA); w3.org/WAI/WCAG21/Understanding/target-size (44px AAA)
- 🟢 SPEC · **Make any pointer target ≥24×24 CSS px, OR if smaller keep undersized targets 24px apart (24px-diameter circles centered on each must not intersect); inline text links and UA-controlled sizes exempt.** — w3.org/WAI/WCAG22/Understanding/target-size-minimum (SC 2.5.8 verbatim)
- 🟢 SPEC · **Leave at least 8pt/8dp between the edges of adjacent tappable controls; prefer 12-16pt when layout allows.** — support.google.com/accessibility/android/answer/7101858 ('8dp or more'); developer.apple.com/design/human-interface-guidelines/buttons (~8pt for ≥24pt icons)
- 🟢 SPEC · **On visionOS give interactive elements a 60×60pt hit region (visible control may stay 44pt with padding); ≈2.5° angular / ~4.4cm at 1m.** — Apple HIG visionOS / WWDC25 'Design hover interactions for visionOS'
- 🟢 SPEC · **Cut pointing time by making targets bigger and/or closer (Fitts: MT = a + b·log2(D/W+1)); pin high-frequency global targets to a screen edge/corner where they behave as infinitely wide.** — MacKenzie 'Information-Theoretic Basis for Fitts' Law' (yorku.ca/mack/JMB89.html); Fitts 1954; ixdf.org/literature/topics/fitts-law
- 🟡 CONV · **Reduce decision time by limiting/grouping choices — reaction time grows with log2(n+1), not linearly (Hick-Hyman); chunking lowers effective n. Does NOT apply to sorted/searchable lists users already know.** — Hick 1952 / Hyman 1953; en.wikipedia.org/wiki/Hick's_law; Proctor & Schneider 2018 (scope limits)
- 🟢 DS · **Use platform gesture timing constants: long-press ~500ms (Android 400 / iOS-RN 500), don't start a drag until past ~8dp touch-slop (~4px mouse), resolve a tap at ~100ms and reserve ~300ms for double-tap.** — Apple UILongPressGestureRecognizer (0.5s default); Android ViewConfiguration.java (LONG_PRESS 400, TOUCH_SLOP 8dp, TAP 100, DOUBLE_TAP 300); React Native Gesture Handler (500ms)
- 🟢 SPEC · **Don't override reserved system edge gestures (Home indicator, screen-edge back, Control/Notification Center); keep custom edge interactions out of those regions.** — developer.apple.com/design/human-interface-guidelines/gestures
- 🟢 SPEC · **Every drag interaction must also work via a single tap/click without dragging (WCAG 2.5.7); keyboard support alone does NOT satisfy it.** — w3.org/WAI/WCAG22/Understanding/dragging-movements (SC 2.5.7 verbatim, failure F108)
- 🟢 SPEC · **Set cursor:pointer on actually-clickable controls (and nowhere else), text I-beam on editable/selectable text, grab→grabbing on drag, not-allowed on disabled, zoom-in/out, crosshair for precision; pick one button-cursor policy project-wide; pair every cursor with a non-cursor affordance (touch shows no cursor).** — w3.org/TR/css-ui-4; kizu.dev/cursor-pointer vs adamsilver.io (button-cursor camps); twbs/bootstrap#16088 (pointer-events trap); a11y-solutions.stevenwoodson.com (touch)
### 10. Scroll & Gesture
- ⚪ OP · **At scroll/drag boundaries apply rubberband resistance (drag translation = pow(rawOffset, ~0.7)) so the surface continues with diminishing offset instead of hard-stopping. (0.7 exponent is practitioner-derived; UIScrollView ships elastic by default.)** — Nathan Gitter 'Building Fluid Interfaces' (pow(offset,0.7) reconstruction); Apple UIScrollView (elastic by default)
- 🟢 SPEC · **Model momentum/inertial scroll with exponential decay v(t)=v0·d^t using the platform deceleration constant (0.998 normal lists, 0.99 fast paging); project the fling's resting position X=x0+v0/(1000·|ln d|) to decide snap/dismiss, not raw displacement.** — Apple UIScrollView.DecelerationRate (normal 0.998, fast 0.99); Lobanov 'Scrolling mechanics of UIScrollView'; Apple WWDC 'Designing Fluid Interfaces' (projection)
- 🟢 DS · **Dismiss a sheet/card when the drag passes ~30-50% of its height OR a fast flick's projected endpoint clears it; otherwise spring back. Two paths (distance OR velocity), not one. Trigger pull-to-refresh only past a fixed threshold (~80dp / 50-100px).** — lucaszischka/BottomSheet (0.3 default, 0.1 min); Material 3 Compose pullToRefresh (80.dp); m2.material.io/components/sheets-bottom
- 🟢 SPEC · **Use scroll-snap proximity for long vertical content and mandatory + scroll-snap-stop:always for full-bleed carousels; set scroll-padding-top = fixed-header height so snapped/anchor content clears the header.** — web.dev/articles/css-scroll-snap; MDN scroll-snap-type / scroll-snap-stop
- 🟢 SPEC · **Put overscroll-behavior:contain on modals, drawers, chat panes, and nested scrollers to stop scroll-chaining to the page behind them; use overscroll-behavior-y:none only when you must also kill native pull-to-refresh and the boundary glow/rubber-band.** — developer.chrome.com/blog/overscroll-behavior; MDN overscroll-behavior
- 🟢 SPEC · **Register scroll/touchstart/touchmove/wheel listeners as {passive:true} unless you genuinely preventDefault; express directional scroll-locking with touch-action (pan-y for horizontal carousels; manipulation to drop the 300ms tap delay) instead of preventDefault; drive scroll-linked effects with IntersectionObserver / animation-timeline:scroll()/view(), not scroll-event JS.** — developer.chrome.com/blog/scrolling-intervention; MDN scroll_event (20ms throttle / IntersectionObserver); developer.chrome.com/docs/css-ui/sticky-headers; MDN Scroll-driven animations
- 🟢 SPEC · **Enable CSS scroll-behavior:smooth only inside a prefers-reduced-motion:no-preference guard (UA controls duration/easing, not author-settable in CSS).** — MDN scroll-behavior; css-tricks scroll-behavior almanac
- 🟡 CONV · **Pad fixed bottom bars with env(safe-area-inset-bottom) and offset fixed top headers by env(safe-area-inset-top) (with viewport-fit=cover) so controls clear the iOS home indicator / notch — never hardcode the px.** — css-tricks.com/almanac/functions/e/env; CSS Environment Variables spec
### 11. Response Time & Perceived Performance
- 🟢 SPEC · **Paint a visible result within 100ms of a direct action (keep input-handler work <50ms, idle/background work in ≤50ms chunks) so it feels instantaneous — no loader needed below this.** — nngroup.com/articles/response-times-3-important-limits (0.1s); web.dev/articles/rail (process input <50ms, idle 50ms)
- 🟢 SPEC · **Keep end-to-end response under 400ms (Doherty) to hold flow and 1s (Nielsen) before the sense of direct manipulation is lost; past 10s show a determinate percent-done indicator plus a cancel control.** — Doherty & Thadani IBM Systems Journal 1982 / lawsofux.com/doherty-threshold; nngroup.com/articles/response-times-3-important-limits (1s, 10s); Apple HIG Progress indicators
- 🟢 SPEC · **Target Interaction to Next Paint ≤200ms at p75 (200-500ms needs-improvement, >500ms poor); render each animation frame in <16.6ms (60fps) — ~10ms script after browser overhead — animating only transform/opacity.** — web.dev/articles/inp (official CWV); web.dev/articles/rail (16ms/60fps); web.dev/articles/defining-core-web-vitals-thresholds
- 🟢 DS · **Don't show a loading spinner for operations under ~1s: gate the loader behind a ~200ms-1s delay timer (cleared if the response resolves first) and, once shown, hold it a minimum (~500ms-1s) to avoid a flash. NOTE: concrete framework anchor is 200ms (Vue defineAsyncComponent); the 1s headline is inferred from Nielsen, not spec.** — Vue defineAsyncComponent (delay 200ms); mitchgavan.com/delay-loading-spinners-appearance; nngroup.com (1s flow limit)
- ⚪ FOLK · **Use a layout-matching skeleton for content-shaped surfaces (feeds, dashboards, lists) and a spinner for short discrete actions (save/auth/payment); only show either if the wait exceeds ~1s. NOTE: 'skeletons feel ~30% faster' is folklore — the layout-match principle is sound, the percentage is not.** — nngroup.com/articles/skeleton-screens (1s threshold; mixed evidence on % gain); Viget 2017 study (skeletons performed worst on perceived duration — the 30% figure is uncorroborated)
- 🟢 DS · **Animate a skeleton placeholder with a calm pulse (opacity 1→~0.5 over ~1.5-2s ease-in-out) or a left-to-right shimmer sweep (~1.4-2s linear, narrow highlight band via animated background-position), gated behind prefers-reduced-motion and animating only compositor-friendly properties.** — tailwindcss.com/docs/animation (animate-pulse 2s); MUI Skeleton.js (wave 2s linear, 0.5s delay); ant-design skeleton (1.4s); carbon _skeleton.scss (reduced-motion guard)
- 🟡 CONV · **Tween a changing number over ~0.4-1.0s (~700-750ms hero, shorter for small UI) with an ease-out/decelerate curve, rolling only the digit columns that changed; use tabular-nums and snap to the final value under reduced-motion.** — NumberFlow (number-flow.barvian.me, ~750ms/bounce defaults); css-tricks.com/animating-number-counters; M3 emphasized-decelerate token; Odometer.js / CountUp.js (2s defaults flagged too long)
- 🟡 CONV · **Debounce live-search/typeahead ~200-300ms (trailing edge, sized to ~150ms inter-keystroke cadence); debounce autosave and async/remote validation ~500ms (with save-on-blur and a maxWait cap); show a pending state if a remote check exceeds ~1s.** — algolia.com/doc (200ms preferred, >300ms degrades, WPM-tuned); design.gitlab.com/patterns/saving-and-feedback (autosave 3s/500ms validation); lodash debounce maxWait; react.dev/reference/react/useDeferredValue (render vs network)
- 🟡 CONV · **Throttle continuous streams — scroll/resize/pointer-move that PAINT to one frame (16ms via requestAnimationFrame), those that only SAMPLE to ~50-250ms; act on the trailing edge for resize. Use debounce for settled intent, throttle for sampled continuous activity.** — css-tricks.com/debouncing-throttling-explained-examples (Corbacho); MDN scroll_event; lodash docs
- 🟢 SPEC · **When a real wait is unavoidable, bias the progress animation to feel faster: backward-moving, decelerating ribbing and front-loaded progress (fast start, slow end) cuts perceived duration ~11%; never let the value move backward or stall.** — Harrison, Yeo & Hudson 'Faster Progress Bars' ACM CHI 2010 (peer-reviewed, ~11%)
### 12. Layout Stability (CLS)
- 🟢 SPEC · **Keep Cumulative Layout Shift ≤0.1 at p75 of real-user loads (segmented mobile/desktop); shifts ≥0.15 are consistently perceived as disruptive and 0.25 is the start of 'poor'. Score = impact fraction × distance fraction over the worst session window (gaps <1s, ≤5s).** — web.dev/articles/cls; web.dev/articles/defining-core-web-vitals-thresholds; wicg.github.io/layout-instability
- 🟢 SPEC · **Reserve space before content loads: width+height attributes on every <img>/<video> (→ aspect-ratio), CSS aspect-ratio for responsive media/embeds, min-height (sized to the largest creative) for ad/async slots, and never collapse a reserved slot to zero on empty fill.** — web.dev/articles/optimize-cls; developers.google.com/publisher-tag/guides/minimize-layout-shift; MDN aspect-ratio
- 🟢 SPEC · **Never inject/expand content above existing content unless it's the direct ≤500ms result of a user interaction (scroll and pointer-move do NOT qualify); otherwise reserve space up front or append below the fold; animate movement with transform, never layout properties.** — web.dev/articles/optimize-cls; wicg.github.io/layout-instability (recent-input 500ms; scroll/pointer excluded)
- 🟢 SPEC · **Eliminate font-swap CLS: use font-display:optional (≤100ms block, no swap) for zero first-visit shift, or font-display:swap WITH a fallback @font-face carrying size-adjust/ascent-override/descent-override/line-gap-override tuned to occupy the same box.** — web.dev/articles/preload-optional-fonts; web.dev/articles/optimize-cls; MDN @font-face ascent-override
- 🟢 SPEC · **Prevent scrollbar-induced shift: set scrollbar-gutter:stable on the scroll ROOT (:root/html, not body — not propagated like overflow) so locking body scroll for a modal doesn't shift content; use 'stable both-edges' for centered layouts; it's a no-op on overlay-scrollbar platforms. In JS fallbacks measure innerWidth−clientWidth BEFORE setting overflow:hidden, never a hardcoded 15px.** — w3.org/TR/css-overflow-3 (§4.2); MDN scrollbar-gutter; bram.us (root not body; both-edges); theKashey/react-remove-scroll-bar (--removed-body-scroll-bar-size)
- 🟢 DS · **Animate accordion/disclosure height via grid-template-rows 0fr→1fr (with the inner element overflow:hidden), or interpolate-size:allow-keywords / calc-size(auto) where supported — never transition straight to height:auto (a no-op); run it ~200-300ms (collapse ~0.8× expand) and gate behind reduced-motion.** — css-tricks.com/css-grid-can-do-auto-height-transitions; developer.chrome.com/docs/css-ui/animate-to-height-auto (interpolate-size/calc-size); tailwindlabs discussion #11186; MUI/Material (300ms, collapse<expand)
### 13. Modals, Overlays & Z-Index
- 🟢 SPEC · **On modal open move keyboard focus into the dialog (autofocus the intended first action, or a tabindex=-1 container for long content); trap Tab so it wraps last↔first; close on Escape; on close restore focus to the invoking trigger.** — w3.org/WAI/ARIA/apg/patterns/dialog-modal; MDN <dialog> (showModal); radix-ui Dialog
- 🟢 SPEC · **While the modal is open make the rest of the page inert (aria-modal=true + inert / native top-layer) so nothing behind the scrim is focusable, clickable, or read by AT — but always keep a keyboard-escapable exit (Esc / focusable close); never a dead-end trap.** — w3.org/WAI/ARIA/apg/patterns/dialog-modal; w3.org/WAI/WCAG22/Understanding/no-keyboard-trap (SC 2.1.2); MDN <dialog>
- 🟢 SPEC · **Give the overlay role=dialog (or native <dialog>) with an accessible name via aria-labelledby (visible title) or aria-label; keep the focused element at least partially visible (not hidden behind a sticky header/scrim); dim the background with a ~32% scrim.** — w3.org/WAI/ARIA/apg/patterns/dialog-modal; w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum (2.4.11); m3.material.io/components/dialogs/specs (scrim 32%)
- 🟢 SPEC · **Allow backdrop/scrim click to dismiss non-destructive dialogs (light dismiss) but disable it for forms with unsaved input or destructive flows; if closing would lose user-entered content, intercept and confirm/discard instead of silently destroying it.** — MDN <dialog> closedby; nngroup.com/articles/accidental-overlay-dismissal; developer.apple.com/design/human-interface-guidelines/modality
- 🟢 DS · **Assign every overlay to a named, role-based z-index token on a small ordered ladder (dropdown<sticky<fixed<offcanvas<modal<popover<tooltip<toast), spaced ~10-20 apart with backdrops one step below their surface, tooltip/toast ABOVE modal; cap in the low thousands.** — getbootstrap.com/docs/5.3/layout/z-index (canonical scale); Primer DESIGN_TOKENS_GUIDE (semantic layers); design.learn.microsoft.com/tokens/z-index
- 🟢 SPEC · **Portal modals/popovers/dropdowns/tooltips/toasts to document.body (or one overlay root) to escape overflow:clip and ancestor stacking contexts; know that transform/filter/opacity<1/will-change/isolation/contain/position fixed|sticky on an ancestor create a stacking context that TRAPS descendant z-index — portal out (or isolation:isolate to fence internals), don't inflate the number.** — radix-ui Portal docs; MDN Stacking context (canonical trigger list); smashingmagazine.com (parent drop-shadow filter = most common z-index bug)
### 14. Performance & GPU Discipline
- 🟢 SPEC · **Animate only transform and opacity (composite-only, GPU); never use `transition: all` — explicitly list the properties that change. Layout properties (width/height/top/left/margin/padding) trigger layout+paint+composite and jank.** — vercel-labs/web-interface-guidelines ('Never transition: all'); emilkowal.ski/ui/great-animations (transform/opacity = composite only); browser rendering pipeline docs
- 🟡 CONV · **Use will-change only for compositor-promotable properties (transform/opacity/filter/clip-path) and only while actively animating (add then remove); never will-change:all, never on layout properties, never blanket across a grid.** — jakub.kr performance.md (compositable table); MDN will-change (warns against leaving it set); web.dev/learn/design/interaction
- 🟢 SPEC · **Treat the blur() px value as the Gaussian standard deviation — a given N spreads visibly wider than N pixels (budget perceived spread ~2-3×); keep backdrop-filter blur 8-24px (~12-16px default), low (≤10px) on mobile fixed elements to avoid scroll jank.** — w3.org/TR/filter-effects-1 ('standard deviation to the Gaussian function'); graffino.com (Safari fixed-blur jank); MDN backdrop-filter
### 15. Material & Glass (backdrop-filter)
- 🟡 CONV · **Build frosted glass from blur 8-24px + saturate(120-200%) + a translucent fill (10-25% decorative cards, 50-80% text-bearing chrome) + a 1px translucent light hairline; ship behind an opaque @supports fallback (≥0.9 alpha base) and emit -webkit-backdrop-filter for Safari (never a CSS variable as its value).** — v3.tailwindcss.com/docs/backdrop-blur (4/8/12/16/24px); joshwcomeau.com/css/backdrop-filter (16px, saturate, @supports); css-tricks.com/backdrop-filter-effect-with-css; caniuse + MDN (Safari -webkit- prefix)
- 🟢 SPEC · **Compute text contrast against the WORST-CASE show-through background (≥4.5:1 text / ≥3:1 large/UI), raise fill opacity (frostier) as the backdrop gets busier, render foreground in vibrant/dynamic system colors (not fixed hex), and add a prefers-reduced-transparency / increased-contrast branch swapping glass to near-opaque high-contrast.** — w3.org/TR/UNDERSTANDING-WCAG20 (1.4.3 — does not account for semi-transparent overlays); Apple HIG Materials (vibrancy); Apple WWDC25 Liquid Glass (Reduced Transparency → frostier)
### 16. Accessibility & Motion-Safety
- 🟢 SPEC · **Gate all non-essential movement behind prefers-reduced-motion: under `reduce` cut MOTION (transform/translate/scale/rotate, position, scroll, parallax, blur) and KEEP opacity/color, substituting a cross-fade rather than deleting the transition; collapse global animation/transition durations to ~0.01ms (not 0ms, which skips transitionend) and force scroll-behavior:auto.** — Emil Kowalski 'Great Animations'; w3.org/WAI/WCAG21/Understanding/animation-from-interactions; web.dev/articles/prefers-reduced-motion (fade kept/scale dropped); Andy Bell modern CSS reset (0.01ms); WCAG 2.3.3 errata (blur in scope)
- 🟢 SPEC · **Replace slide/zoom/parallax with a cross-dissolve/fade when Reduce Motion is on (iOS App Store criteria) — keep conveying meaning without large positional motion; vestibular risk scales with how much of the VIEWPORT the motion sweeps, not physical screen size.** — Apple App Store Connect 'Reduced Motion evaluation criteria' ('dissolve, highlight fade, or color shift'); Val Head 'Designing Safer Web Animation' (A List Apart); webkit.org/blog/7551 (Responsive Design for Motion)
- 🟢 SPEC · **Nothing may flash more than 3 times in any 1-second window; auto-starting moving/blinking/scrolling content running >5s alongside other content needs a pause/stop/hide control; interaction-triggered non-essential motion must be disablable.** — w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold (3 flashes; luminance 10%, not 25%); w3.org/WAI/WCAG22/Understanding/pause-stop-hide (5s, SC 2.2.2); w3.org/WAI/WCAG22/Understanding/animation-from-interactions (SC 2.3.3)
- 🟢 SPEC · **Never set outline:none on a focusable element without a visible replacement; scope focus rings to :focus-visible (not :focus); render rings with box-shadow/radius-aware outline (bare outline ignored border-radius historically); keep focus order = DOM source order (tabindex only in {-1,0}); hide focusable offscreen elements by positioning, not display:none.** — w3.org/WAI/WCAG (2.4.7 Focus Visible, 2.4.3 Focus Order); sarasoueidan.com/blog/focus-indicators ('Do. Not. Do. This.'); webaim.org/techniques/keyboard ('no tabindex ≥1'); raunofreiberg/interfaces (box-shadow not outline)
- 🟢 SPEC · **Gate hover styles behind @media (hover: hover) and (pointer: fine) so touch taps don't get stuck in a hover state, and set form input font-size ≥16px so iOS Safari doesn't auto-zoom on focus (or pin maximum-scale=1); never autofocus inputs on touch.** — raunofreiberg/interfaces (@media hover:hover; 16px no-zoom); vercel-labs/web-interface-guidelines; W3C Media Queries L4 (hover/pointer); WebKit iOS 16px auto-zoom behavior
- 🟢 SPEC · **When an input error is automatically detected, identify the field and describe the error in TEXT (not color/icon alone, aria-invalid + aria-describedby); never silently block submit — surface the first invalid field, move focus to it or to a top error summary (tabindex=-1, focused, 'Error:' page title), and don't shift layout when the message appears.** — w3.org/WAI/WCAG22/Understanding/error-identification (SC 3.3.1); design-system.service.gov.uk/components/error-summary (GOV.UK); nngroup.com/articles/error-message-guidelines
### 17. Form Validation Timing
- 🟡 CONV · **Validate a clean field only on blur (and only when non-empty); the moment a field shows an error, switch it to live keystroke revalidation so the error clears as soon as the input becomes valid — 'reward early, punish late'.** — Mihael Konjević 'Inline validation in forms' (WDstack); smashingmagazine.com/2022/09/inline-validation-web-forms-ux (Friedman); baymard.com/blog/inline-form-validation ('keystroke level')
- 🟡 CONV · **For fixed-length constrained fields (ZIP, phone, card number) you may validate as soon as the input reaches the expected length; confirm correct entries with a positive inline marker (post-blur, not mid-typing). For high-assurance/accessibility-first forms a documented counter-position validates on SUBMIT only — choose per audience.** — baymard.com/blog/inline-form-validation (validate at length); design-system.service.gov.uk/patterns/validation ('Do not validate when the user moves away from a field' — counter-position)
---
## Appendix A — Gaps noted by synthesis
RESIDUAL GAPS (what the corpus does not yet quantify well, plus integrity flags):
1. UNDISCLOSED SYSTEM CONSTANTS. The true iOS rubberband curve and the exact UIScrollView momentum-to-snap projection are only available as single-practitioner reconstructions (Nathan Gitter's pow(offset,0.7), Lobanov's derivation). Apple never published these as tokens, so they remain single-opinion despite being load-bearing for native feel.
2. SPRING TUNING BY CONTEXT is single-source. The per-interaction spring triples (tap 0.4/0.2, drawer 0.8/0.3, PiP 1.0/0.4) come from one Medium reconstruction. There is no provenance-graded table mapping interaction class → spring params across platforms.
3. PERCEIVED-PERFORMANCE NUMBERS ARE THIN. Only one quantified, peer-reviewed perceived-duration result exists (Harrison CHI 2010, ~11% from backward ribbing). The widely-cited 'skeletons feel ~30% faster' is folklore (2017 Viget testing actually found skeletons worst on perceived duration); the corpus keeps the skeleton-vs-spinner pattern but the percentage is unverified. NN/g's real threshold is 1s, not the 500ms repeated in several gap-fill findings.
4. GAP-FILL TIER NOT INDIVIDUALLY VERIFIED. ~150 'gap-fill' findings (debounce/throttle, skeleton animation, counters, hover-elevation, cursors, CLS/scrollbar, accordions, validation, modals, z-index, glass) carry verified:false / provenance_tier:single-opinion assigned at synthesis — many cite reputable named sources (WCAG, Bootstrap, Radix, MDN, web.dev) and are effectively spec/ds-token grade, but the raw corpus did not run the adversarial verification pass on them. I upgraded tiers where the underlying source is clearly authoritative (WCAG SC, committed DS tokens, official platform docs), but a second verification pass on the gap-fill band would harden ~40% of these from 'single-opinion' to their true tier.
5. VERSION/DATE DRIFT in several findings (scroll-snap-stop browser support, scroll-driven-animations 'Dec 2024', Tailwind v3→v4 shadow rename) — the VALUES are right but the support/version metadata is stale or fabricated and was stripped/corrected here. Any AI consuming this must re-check baseline support at generation time, not trust embedded dates.
6. CROSS-DENSITY / PLATFORM SCALING is under-specified. Material notes wearables run ~30% shorter durations and desktop hover ramps differ from touch, but there is no quantified multiplier table for compact/comfortable/spacious density, watch/TV/desktop, or pointer-fine vs coarse beyond the touch-target split.
7. SEMANTIC COLOR EXACT SHADES. The hue MAPPING (red/green/amber/blue) is convention-solid, but the exact per-system error/success/warning shades that simultaneously hit 4.5:1 text and 3:1 non-text on both light and dark surfaces are not enumerated — left to each DS's token file.
8. EASING ↔ DURATION PAIRING is asserted directionally (decelerate+long for enters) but not given as a joint lookup table; an AI must currently pick duration and curve from separate rules rather than one (component-role → {duration token, curve token}) map.
9. CONTENT/COPY, EMPTY-STATE WORDING, ICON SEMANTICS, and INFORMATION DENSITY are out of scope — this corpus quantifies the physical/temporal/contrastive layer of 'feel', not editorial or IA decisions.
10. CONFLICTS PRESERVED, NOT ALL RESOLVED. Genuine two-source disagreements are intentionally kept with both positions: on-blur validation (Baymard/Konjević) vs submit-only (GOV.UK); state-layer 8/10/10/16 (M3) vs 12% (M2/mdui); button cursor pointer (app convention) vs default (strict spec); long-press 400ms (Android) vs 500ms (iOS/RN). These are audience/platform choices, not errors — downstream must pick per context, and the machine_checks enforce internal consistency (pick one) rather than a single global winner.
## Appendix B — Overclaimed numbers (demote spec→taste)
The completeness critic flagged these as presented with spec-like precision but actually single-implementation / textbook-average / folklore. In `omd:feel` they are kept but **disclosed as heuristics, never enforced as gates**:
- Reaction-time RT = a + b·log2(n+1) with b ≈ 0.155 s/bit (Hick-Hyman) — the corpus already hedges 'empirical/convention not spec'; the specific 0.155 s/bit slope is a textbook average that varies widely by stimulus/practice and is routinely misapplied to menus; demote to illustrative, not a design constant
- Fitts's-law throughput b ≈ 100-150 ms/bit for a mouse — device- and study-dependent (ISO 9241-9 throughput varies ~3.7-4.9 bits/s); the ms/bit figure is a loose convention, verify before quoting as a number
- Cross-fade incoming 150ms / outgoing 75ms (linear) — the exact 75ms outgoing half is presented crisply but reads as a single-implementation convention rather than a sourced spec; re-verify the source (looks Material-motion-derived but the precise split is folklore-adjacent)
- Hover-panel open intent ~100ms (hoverIntent default) + keep-open ~300ms (menu-aim grace) + safe-triangle tolerance ~75px — the 75px tolerance and 300ms grace are library/blog-derived defaults (jQuery hoverIntent / Ben Kamens menu-aim writeups), not vendor specs; re-verify or label as practitioner convention
- Long-press Android ViewConfiguration default 400ms vs iOS 500ms — worth re-verifying: Android's getLongPressTimeout has historically been 500ms (user-adjustable), so the flat '400ms' may be wrong/outdated; confirm against current ViewConfiguration source
- Android paging slop 16dp and touch slop ~8dp — the generic 'touch slop ~8dp' is right-order but ViewConfiguration touchSlop is density/version dependent; the 16dp 'paging slop' is a specific constant that should be re-sourced before quoting
- Momentum-scroll deceleration constants d = 0.998 (normal) / 0.99 (fast) and factor ≈499.5 px per px/ms — these are reverse-engineered from a specific JS implementation (react-use-gesture / rebound style), not platform constants; iOS UIScrollView's actual decelerationRate (normal 0.998, fast 0.99) is per-frame at 60fps, so the headline math is implementation-coupled — flag the 499.5 derived figure as fragile
- Rubberband resistance exponent k ≈ 0.7 — already self-flagged as 'practitioner-derived not an Apple constant'; the well-known iOS rubberband formula uses a 0.55 constant (b·d·c/(d + c·x) form), not a pow(x,0.7), so the specific 0.7 should be demoted or reconciled
- Optimistic-UI / direct-manipulation '0ms perceived' and the '~11% perceived-duration reduction' for backward-ribbing progress — the 11% is correctly tagged as 'the one peer-reviewed result' but is from a single study (Harrison et al.) on a narrow stimulus; keep but mark as not generalizable beyond progress bars
- Pressed-scale floor 'never below 0.95' and exit animations '~0.8× (≈20% faster, or ~50ms shorter)' — both are reasonable taste heuristics but the precise 0.95 floor and the 0.8×/50ms exit ratio are single-author craft conventions presented with spec-like precision; demote to taste
- Stagger '≈80ms per word, ≈100ms per section' and reveal translateY '~8-12px' — sensible defaults but the per-word/per-section ms figures are uncited practitioner numbers; re-verify or label as convention
- Icon optical nudge 'icon-side padding = text-side padding − 2px' and 'play triangle ~2px right' — the 2px is shape/size dependent (the corpus admits this) yet states a fixed 2px; demote the literal 2px to 'a small optical nudge, not a constant'
- Toast/snackbar 4-10s with '4s typical' vs Android LENGTH_LONG ~2.75s — the corpus already notes the Android constant undercuts the guideline; flag that the '4-10s' band itself is a soft UX guideline, not a measured optimum, and the upper bound conflicts with WCAG 2.2.1 timing-adjustable concerns
- Apple default spring (response 0.55, dampingFraction 0.825, blendDuration 0) as 'the baseline for standard state changes' — these are the documented defaults of one SwiftUI spring initializer, but calling them THE baseline for standard changes overstates; many Apple system animations use other presets — re-verify the 'default/baseline' framing
- Carbon slow-02 700ms 'background dim' and the full productive ladder figures — worth spot-verifying against current Carbon motion tokens, which have been revised; some of these ms values may reflect an older version of the token set
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |