Communitygithub.com

omd:feel — Interface Feel, Quantified

Quantifies and applies (APPLY) or audits (AUDIT) the interface details that the design and frontend industry has been doing by 'feel' — expanding on Jakub Krebel's 'make interfaces feel better' philosophy into 17 axes and 113 rules with provenance tiers, covering animation, spacing, typography, targets, motion, and accessibility.

What is omd:feel — Interface Feel, Quantified?

The 'omd:feel' skill is a specialized AI agent tool for applying or auditing quantified interface feel rules. It translates subjective industry 'feel' — such as animation timing, spacing, and visual contrast — into measurable, checkable numbers backed by explicit provenance tiers (SPEC, DS, CONV, OP, FOLK). This gives developers and designers precise guidance on what numbers to aim for and when something is wrong, grounded in Jakub Krebel's philosophy that 'great interfaces are a collection of small things that compound,' extended by HIG, Material, WCAG, DS tokens, and practitioner research. The skill supports two main workflows: **APPLY** injects quantitative feel rules when building or polishing UI (e.g., 'make this feel better,' 'apply interface details'), while **AUDIT** scans existing HTML/JSX/TSX/CSS against a 17-axis, 113-rule checklist and produces tier-based severity reports (BLOCK/WARN/FYI) with a feel-score (e.g., '18/22 SPEC in-band'). It works across platforms including Claude Code, Cursor, and Codex, and integrates with the 'omd:apply' family for brand token precedence and 'omd:designer-review' for brand consistency audits. Key rules cover motion timing (50ms grid, exit ≈ 0.8× enter), easing (ease-out enter, spring with bounce <0.4), spacing (8px base, 4px half-step), typography (tablar-nums, text-wrap balance), color contrast (4.5:1 AA, 3:1 non-text), targets (44pt iOS/WCAG AAA minimum), scroll containment, layout stability (CLS ≤0.1), and accessibility (prefers-reduced-motion branches, focus rings). The design enforces guardrails against inventing numbers, overruling brand DESIGN.md tokens, and missing reduced-motion branches, ensuring honest quantification of feel into actionable engineering constraints.

Works with~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/nococn/omd-feel/tree/HEAD

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does omd:feel — Interface Feel, Quantified do?

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.

BadgeTierAPPLYAUDIT severity
🟢 SPECspec-authoritative (W3C/WCAG · HIG · normative)EnforceBLOCK
🟢 DSds-token (committed design system token)Enforce (unless brand overrides)BLOCK
🟡 CONVindustry-convention (≥2 independent practitioners converge)Apply as defaultWARN
⚪ OPsingle-opinion (trustworthy individual)Suggest onlyFYI
⚪ FOLKfolklore-unverified (origin untraceable)Suggest + state tierFYI

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.md token 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:apply reads 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: all is forbidden; will-change is 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

  1. Context detection — Is there a DESIGN.md in the project root / target folder? If yes, follow omd:apply procedure to read tokens (color · radius · spacing · motion · type) first. Brand tokens = authority.
  2. 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.
  3. Respect tiers — 🟢 apply as-is, 🟡 apply as defaults (yield if brand/request overrides), ⚪/FOLK propose with disclaimer: "This is a taste heuristic"
  4. 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.
  5. 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).

  1. Input: artifact_path (HTML/JSX/TSX/CSS) + (if present) design_md_path + viewport.
  2. machine_check scan — Apply each rule's 🔍 machine_check from reference.md to 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 without aria-modal, overlay without overscroll-behavior
  3. severity = tier mapping — SPEC/DS violation = BLOCK, CONV = WARN, OP/FOLK = FYI. (No severity inflation/deflation.)
  4. feel-score — Ratio of in-band to applicable axes: 🟢 in-band / 🟢 applicable as core metric, WARN/FYI as secondary. Example: "feel-score 18/22 SPEC in-band, BLOCK 2, WARN 5"
  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-motion branch.
  • ❌ 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 to omd:remember.

Manual verification: AUDIT a component with transition: all 0.6s + <button class="w-5 h-5"> + no prefers-reduced-motion branch — 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.

Related Skills