make-interfaces-feel-better

# Details that make interfaces feel better Great interfaces rarely come from a single thing. It's usually a collection of small details that compound into a great experience. Apply these principles when building or reviewing UI code. ## Quick Reference | Category | When to Use | | --- | --- | | [Typography](typography.md) | Text wrapping, font smoothing, tabular numbers | | [Surfaces](surfaces.md) | Border radius, optical alignment, shadows, image outlines, hit areas | | [Animations](animations.md) | Interruptible animations, enter/exit transitions, icon animations, scale on press | | [Performance](performance.md) | Transition specificity, `will-change` usage | ## Core Principles ### 1. Concentric Border Radius Outer radius = inner radius + padding. Mismatched radii on nested elements is the most common thing that makes interfaces feel off. ### 2. Optical Over Geometric Alignment When geometric centering looks off, align optically. Buttons with icons, play triangles, and asymmetric icons all need manual adjustment. ### 3. Shadows Over Borders For elevation (dropdowns, modals, cards) use the `shadow-subtle`/`shadow-medium`/`shadow-overlay`/`shadow-card` tokens. In this repo neutral edges and dividers stay as `--border` borders (`.claude/rules/sim-styling.md`, Line weight) — do not swap them for `0 0 0 1px` shadow rings. ### 4. Interruptible Animations Use CSS transitions for interactive state changes — they can be interrupted mid-animation. Reserve keyframes for staged sequences that run once. ### 5. Split and Stagger Enter Animations Don't animate a single container. Break content into semantic chunks and stagger each with ~100ms delay. ### 6. Subtle Exit Animations Use a small fixed `translateY` instead of full height. Exits should be softer than enters. ### 7. Contextual Icon Animations Animate contextual icons with opacity, scale, and blur instead of toggling visibility; see animations.md for the Motion and CSS cross-fade patterns. ### 8. Font Smoothing Apply `-webkit-font-smoothing: antialiased` to the root layout on macOS for crisper text. In this repo, do not add root-level smoothing or other global styles (CLAUDE.md "Styling and EMCN"); raise it as a design-system proposal instead. ### 9. Tabular Numbers Use `font-variant-numeric: tabular-nums` for any dynamically updating numbers to prevent layout shift. ### 10. Text Wrapping Use `text-wrap: balance` on headings. Use `text-wrap: pretty` for body text to avoid orphans. ### 11. Image Outlines Add a subtle 1px low-opacity outline to images; see surfaces.md. In this repo, use the `--border` token (`outline-[var(--border)]`), not raw black/white alphas. ### 12. Scale on Press A subtle scale-down (about 0.96-0.97) on press gives tactile feedback. In this repo a press affordance belongs in the emcn `Button`/`Chip` chrome (`packages/emcn`), not in consumer classes — neither component implements one today, so propose it there rather than adding per-call-site transforms. ### 13. Skip Animation on Page Load Use `initial={false}` on `AnimatePresence` to prevent enter animations on first render. Verify it doesn't break intentional entrance animations. ### 14. Never Use `transition: all` Always specify exact properties: `transition-property: scale, opacity`. Tailwind's `transition-transform` covers `transform, translate, scale, rotate`. ### 15. Use `will-change` Sparingly Only for `transform`, `opacity`, `filter` — properties the GPU can composite. Never use `will-change: all`. Only add when you notice first-frame stutter. ### 16. Minimum Hit Area Interactive elements need at least 40×40px hit area. Extend with a pseudo-element if the visible element is smaller. Never let hit areas of two elements overlap. ## Common Mistakes | Mistake | Fix | | --- | --- | | Same border radius on parent and child | Calculate `outerRadius = innerRadius + padding` | | Icons look off-center | Adjust optically with padding or fix SVG directly | | Hard borders between sections | In this repo, the `--border` hairline token; elsewhere, layered `box-shadow` with transparency | | Jarring enter/exit animations | Split, stagger, and keep exits subtle | | Numbers cause layout shift | Apply `tabular-nums` | | Heavy text on macOS | Apply `antialiased` to root | | Animation plays on page load | Add `initial={false}` to `AnimatePresence` | | `transition: all` on elements | Specify exact properties | | First-frame animation stutter | Add `will-change: transform` (sparingly) | | Tiny hit areas on small controls | Extend with pseudo-element to 40×40px | ## Review Output Format Present changes as markdown tables with **Before** and **After** columns, one table per principle with a heading above it, one diff per row, and cite file and property when the snippet is not self-explanatory. ### Example #### Concentric border radius | Before | After | | --- | --- | | `rounded-xl` on card + `rounded-xl` on inner button (`p-2`) | `rounded-2xl` on card (`12 + 8`), `rounded-lg` on inner button | | `border-radius: 16px` on both nested surfaces | Outer `24px`, inner `16px` with `8px` padding | #### Tabular numbers | Before | After | | --- | --- | | `<span>{count}</span>` on animated counter | `<span className="tabular-nums">{count}</span>` | | Default numerals on timer | Added `font-variant-numeric: tabular-nums` to root | #### Scale on press | Before | After | | --- | --- | | `Chip` has no press affordance | Proposed in `packages/emcn/src/components/chip/chip.tsx` (`chipVariants`): `active:scale-[0.96] transition-transform` | | `scale(0.9)` on press | Raised to `scale(0.96)` — anything below `0.95` feels exaggerated | Rows should cite the specific file and the specific property that changed when it isn't obvious from the snippet. If a principle was reviewed but nothing needed to change, omit that table entirely — empty tables add noise. ## Review Checklist - [ ] Nested rounded elements use concentric border radius - [ ] Icons are optically centered, not just geometrically - [ ] Shadows used instead of borders where appropriate - [ ] Enter animations are split and staggered - [ ] Exit animations are subtle - [ ] Dynamic numbers use tabular-nums - [ ] Font smoothing is applied - [ ] Headings use text-wrap: balance - [ ] Images have subtle outlines - [ ] Buttons use scale on press where appropriate - [ ] AnimatePresence uses `initial={false}` for default-state elements - [ ] No `transition: all` — only specific properties - [ ] `will-change` only on transform/opacity/filter, never `all` - [ ] Interactive elements have at least 40×40px hit area ## Reference Files - [typography.md](typography.md) — Text wrapping, font smoothing, tabular numbers - [surfaces.md](surfaces.md) — Border radius, optical alignment, shadows, image outlines - [animations.md](animations.md) — Interruptible animations, enter/exit transitions, icon animations, scale on press - [performance.md](performance.md) — Transition specificity, `will-change` usage