omd:feel — Interface Feel, Quantified
Translates interface details that the industry has been doing by feel — "about this speed," "about this shadow," "about this padding" — into source-graded, checkable numbers for applying and auditing. This skill inherits Jakub Krehel's proposition that "great interfaces are a collection of small things that compound", but goes further by answering what numbers to match / when it's wrong with precise values.
Key insight: Quality is the integral of dozens of small constraints kept within their own band. A 600ms checkbox tick, a 1px focus ring, 2.85:1 body contrast, a hover lift without a @media (hover:hover) guard — each is a measurable subtraction from "feel." This skill prevents those subtractions.
The full rule set (17 axes · 113 rules) is in reference.md, and the source, tier, and methodology for each number are in provenance.md. The cheat-sheet below is the always-loaded core; for deep audits and edge axes, read the reference.
When to Use
- APPLY — Inject quantitative feel rules when creating or modifying UI ("make it feel better," "polish the interactions," "apply detail").
- AUDIT — Scan existing HTML/JSX/TSX/CSS against the rule sheet and produce a feel-score with BLOCK/WARN/FYI report ("check the feel," "audit this screen").
Does not trigger on non-UI work. Copy-only or information-architecture tasks are out of scope.
0. Provenance Tier → Enforcement Strength (Heart of This Skill)
Every rule carries a tier, and the tier determines enforcement strength. This is how we honestly quantify "feel" — numbers from specs are gates, numbers from taste are suggestions.
| Badge | Tier | APPLY | AUDIT severity |
|---|---|---|---|
| 🟢 SPEC | spec-authoritative (W3C/WCAG · HIG · normative) | Enforce | BLOCK |
| 🟢 DS | ds-token (committed design system token) | Enforce (unless brand overrides) | BLOCK |
| 🟡 CONV | industry-convention (≥2 independent practitioners converge) | Apply as default | WARN |
| ⚪ OP | single-opinion (trustworthy individual) | Suggest only | FYI |
| ⚪ FOLK | folklore-unverified (origin untraceable) | Suggest + state tier | FYI |
Distribution: SPEC 61 · DS 24 · CONV 19 · OP 7 · FOLK 2 → 85/113 have spec/token backing (enforceable).
DESIGN.md always wins. If a brand
DESIGN.mdtoken conflicts with a rule, the brand token takes authority. These rules are the default when the brand is silent, not overrides. If a DESIGN.md exists in the project root,omd:applyreads tokens first, and only fills axes that remain empty with feel rules.
1. Cheat-sheet — Core Numbers Always Applied
Tier annotations: 🟢=enforce, 🟡=default, ⚪=suggest. In conflict: DESIGN.md > 🟢 > 🟡 > ⚪.
Motion & Timing
- Everyday UI transitions ~200ms (hover ≤150 · popover ~200 · overlay/modal ~300). Range 150–300ms, >400ms feels sluggish. 🟡
- Duration quantized to a 50ms grid (no 220/333ms). 🟢
- exit ≈ 0.8 × enter (close faster than open). 🟢
- No single global duration — proportionally scaled to movement area/distance. 🟢
Easing & Springs
- enter/user-trigger = ease-out
cubic-bezier(0,0,0.2,1)· exit = ease-in/accelerate · visible morph = ease-in-out · spinner/progress = linear. No ease-in on enter. 🟡 - Apple = spring default
(response 0.55, damping 0.825, bounce 0), functional UI bounce <0.4. 🟢 - Interruptible: Interactive states use transition/spring (retargetable), only one-shot animations use
@keyframes. 🟢
Spacing · Radius · Rhythm
- 8px base, 4px half-step (4·8·12·16·24·32·40·48·64). 🟢
- Internal padding ≤ outer gap between siblings. 🟡
- Concentric radius: outer = inner + padding. 🟢
- UI type scale ~1.25 (major third). 🟡
Shadow & Depth
- Layered shadows 3–5 layers, single top light source. Low elevation=tight+sharp, high elevation=diffuse+spread (Tailwind md→lg ramp). 🟡/DS
- Dark mode uses lighter surfaces rather than shadows for depth. 🟡
Typography
- Body line-height 1.5, measure ~66ch (45–75). 🟢
- Display tracking −0.02–−0.03em, all-caps +0.05–0.1em, body ~0. 🟡
- Variable numbers use tabular-nums; headings text-wrap: balance, body pretty; layout uses antialiased. (seed/jakub) 🟡
Color & Contrast
- Text 4.5:1 (large 3:1) AA · non-text/UI border 3:1 · focus ring 3:1 + 2px + ~2px offset. 🟢
- M3 state layers: hover 8% · focus 10% · pressed 10% · dragged 16%. 🟢
- Disabled ~38% opacity. 🟡
States & Feedback
- Data components define all 5 states (empty/loading/error/content/skeleton). 🟡
- Pressed: scale 0.96–0.97, 150ms ease-out (floor 0.95). DS/⚪
- Icon state swap: scale+opacity+blur 4px→0, spring ~0.3. 🟡
Targets & Pointer
- Tap targets 44pt (iOS/WCAG AAA) / 48dp (Material) / 24px (WCAG AA min), adjacent targets ≥8pt. 🟢
- cursor: interactive=pointer · disabled=not-allowed · drag=grab→grabbing · edit=text. 🟡
Scroll & Gesture
- Overlays/nested scrollers:
overscroll-behavior: contain(prevent scroll chaining/PTR). 🟢 - Swipe dismissal threshold ~30% distance or velocity flick. DS
- scroll-snap: long-form=proximity · carousel=mandatory. 🟢
Response Time & Perceived Performance
- 100ms = instant · 1s = cognitive flow limit · 10s = attention limit (show % progress). Doherty 400ms ceiling. 🟢
- INP ≤200ms p75, frame budget 16.6ms. 🟢
- Show spinner only when expected wait >1s; if shown, keep for at least 500ms (prevent flicker). If layout known, use skeleton. 🟡/DS
Layout Stability (CLS)
- CLS ≤0.1 p75. Reserve space for media via width/height or aspect-ratio.
scrollbar-gutter: stable.font-display: optional(or swap)+metric override. No inserting content above existing content outside the 500ms input window. 🟢
Modals · Overlays · Z-index
role=dialog+aria-modal=true, focus goes to dialog on open, Tab trap, Esc closes, focus returns to trigger on close, background is inert. Scrim#000 ~32%. 🟢- Light-dismiss: ON for transient/informational dialogs, OFF for data entry/destructive actions. 🟢
- Z-ladder: dropdown 1000 / sticky 1100 / fixed 1200 / backdrop 1300 / modal 1400 / popover 1500 / toast 1600 / tooltip 1700. Overlays use portal. (gap-fill)
Performance · Glass · A11y
- Animate only transform/opacity (+filter),
transition: allis forbidden;will-changeis transient (remove when idle). 🟢 - Glass:
backdrop-filter: blur(16px) saturate(180%)+ semi-transparent fill ~0.6 + 1px hairline + opaque fallback, text ≥4.5:1. 🟡/🟢 prefers-reduced-motion: reduce→ cross-fade/immediate transition, remove large movement/parallax (keep small opacity). ≤3 flashes/s. Do not remove focus outline without alternative (:focus-visible). 🟢
Form Validation
- First validation on blur, once an error field switches to on-change (live) (clear error as soon as user fixes it). Async validation debounce 300–500ms. 🟡
2. APPLY Workflow
- Context detection — Is there a
DESIGN.mdin the project root / target folder? If yes, followomd:applyprocedure to read tokens (color · radius · spacing · motion · type) first. Brand tokens = authority. - Fill empty axes — Only axes where DESIGN.md is silent are filled with cheat-sheet defaults. For deep axes (scroll physics · glass · z-ladder · CLS), reference the relevant section of
reference.md. - Respect tiers — 🟢 apply as-is, 🟡 apply as defaults (yield if brand/request overrides), ⚪/FOLK propose with disclaimer: "This is a taste heuristic"
- Leave evidence in output — For non-obvious numbers (e.g., exit 0.8×, focus offset 2px), include one line explaining why + the tier in code comments or descriptions. Do not invent numbers — if not in cheat-sheet/reference, read the reference or say you don't know.
- Always include
prefers-reduced-motion— If animation is added, also add a reduce branch (a11y is not optional).
3. AUDIT Workflow
Advisory (read-only) pattern like omd:designer-review + feel axes. Reread DESIGN.md on every call (no caching).
- Input:
artifact_path(HTML/JSX/TSX/CSS) + (if present)design_md_path+ viewport. - machine_check scan — Apply each rule's
🔍 machine_checkfromreference.mdto the artifact. Example detection:transition: all/ duration >400ms / off-grid duration- Tap targets <44px, focus outline removed, text contrast <4.5:1
<img>without aspect-ratio, modal withoutaria-modal, overlay withoutoverscroll-behavior
- severity = tier mapping — SPEC/DS violation = BLOCK, CONV = WARN, OP/FOLK = FYI. (No severity inflation/deflation.)
- feel-score — Ratio of in-band to applicable axes:
🟢 in-band / 🟢 applicableas core metric, WARN/FYI as secondary. Example: "feel-score 18/22 SPEC in-band, BLOCK 2, WARN 5" - Output:
<work_dir>/.reviews/feel-audit-round-<N>.md— each issue includes line ref + tier + machine_check evidence + fix (actionable). No issues without line ref, no rubber-stamp "looks good".
### [BLOCK] Tap target below minimum — icon button
- **Location:** `components/Toolbar.tsx:31`
- **Rule:** §8 Targets — 44pt/48dp/24px min (🟢 SPEC, WCAG 2.5.8)
- **Evidence:** `<button className="w-6 h-6">` → 24px, no hit-slop
- **Fix:** Pad to 44×44 hit region (`p-2.5` + keep visual 24px icon)
4. Guardrails
- ❌ Do not present folklore as spec. ⚪/FOLK always state the tier. (Corpus Appendix B demote list — Hick-Hyman 0.155s/bit, Fitts ms/bit, rubberband 0.7, pressed 0.95 floor, exit 0.8×, stagger 80/100ms, optical 2px etc. — do not enforce as number gates, only borrow direction.)
- ❌ Do not invent numbers. If not in cheat-sheet/reference, read the reference or say "I don't know."
- ❌ Do not ignore DESIGN.md and override with general best-practice. Brand tokens come first.
- ❌ Do not add motion without the
prefers-reduced-motionbranch. - ❌ In AUDIT, no severity inflation (all BLOCK), deflation (BLOCK to FYI), or issues without line ref.
- ❌ If numbers need changing, do not manually edit
reference.md— regenerate from corpus → generator.
5. omd Ecosystem Relationships
omd:apply— Applies brand DESIGN.md tokens. omd:feel sits on top and fills the feel layer where tokens are silent.omd:designer-review— Audits brand consistency (typo/color budget/radius scale). omd:feel AUDIT is its feel-axis counterpart (motion timing · targets · CLS · a11y).omd:taste— User preference dashboard (separate concept). When a repeated feel decision hardens into taste, it flows toomd:remember.
Manual verification: AUDIT a component with
transition: all 0.6s+<button class="w-5 h-5">+ noprefers-reduced-motionbranch — should produce at least 3 BLOCKs (transition all=GPU SPEC, 20px target=WCAG SPEC, missing reduced-motion=a11y SPEC) with line refs, and the feel-score should be reduced accordingly.