Interface Polish
Practical rules for making interfaces clearer, easier to use, and more polished. Apply these by default when writing or reviewing frontend code. Each rule is short; when one applies, just do it rather than asking.
Adapted and condensed from the interfaces.dev cheat sheet by Jakub Krehel, published here with his permission. For deeper typography, color, or motion work, pair this with the better-typography, better-colors, apple-design, and emil-design-eng skills if available.
Visual details
Concentric radii on nested elements. Inner radius = outer radius minus the gap between them. A card with 16px radius and 8px padding gives its inner element 8px radius. Never give a nested element the same radius as its parent.
Optical over geometric alignment. Center things by eye, not just by math. Play icons, arrows, and asymmetric glyphs usually need a 1–2px nudge to look centered.
Asymmetric button padding with icons. When a button has an icon plus text, reduce the padding on the icon side slightly (the icon carries visual weight that text doesn't).
Layered shadows over borders for depth. Stack 2–3 box-shadow layers (a tight low-opacity ring plus softer larger shadows) instead of a flat 1px border when you want elevation.
Hairline outlines on images. Give images a subtle inset ring so light images don't bleed into light backgrounds: outline: 1px solid rgb(0 0 0 / 0.08); outline-offset: -1px; (use white at 8% in dark mode).
Match icon stroke to adjacent text weight. An icon next to font-weight: 500 text should have a stroke width that reads at the same weight. Thin icons next to medium text (or vice versa) look mismatched.
Animation
Animate from the trigger, not the center. Set transform-origin based on where the trigger sits relative to the popover/menu (e.g., a menu opening below-left of a button gets transform-origin: top right).
Frequently opened menus: skip the enter animation. Context menus and other high-frequency surfaces should appear instantly and only animate on exit.
Exits are subtler than entrances. On exit, move a shorter distance while fading opacity and adding a small blur (~4px). Don't mirror the entrance exactly.
Never transition: all. Name the exact properties: transition: background-color 150ms ease, color 150ms ease. all causes accidental animations and jank.
Press feedback on buttons. Scale to 0.95–0.98 on :active with transition: scale 200ms ease-out.
Icon swaps crossfade. New icon: scale 0.25 → 1, opacity 0 → 1, blur 4px → 0. Old icon reverses the same values. Don't hard-swap.
Transitions for interactions, keyframes for sequences. CSS transitions can reverse mid-flight (hover off before hover animation ends); keyframes can't. Use keyframes only for one-shot sequences.
Kill transitions during theme switches. Temporarily disable all transitions when toggling light/dark mode so hundreds of properties don't animate at once.
Fix 1–2px jitter with will-change: transform. If an element shifts randomly while animating (common in iOS Safari), add it. Don't sprinkle it everywhere preemptively.
Stagger entrances in small groups. Animate sections in with short delays between groups rather than one giant block or every element individually.
No animations on page load unless intentional. Guard mount animations so a page refresh doesn't replay every transition (e.g., only animate after first paint or on state change).
Frequent interactions are instant. Hover color changes and similar high-frequency feedback should have zero or near-zero duration.
Typography
Only .woff2 on the web. Never ship .ttf or .otf; .woff only as a legacy fallback.
font-variant-numeric: tabular-nums for timers, counters, prices, and table columns so digits don't cause layout shift. Unnecessary in monospace fonts.
Line length 60–75 characters for articles and long-form text. Cap the measure with max-width (e.g., 65ch).
text-wrap: balance on headings, text-wrap: pretty on short descriptions. Neither on long-form body text.
Contain overflow. overflow-wrap: break-word keeps long URLs, IDs, and API keys inside their container. white-space: nowrap keeps labels and badges from wrapping.
Root-level font smoothing. -webkit-font-smoothing: antialiased and -moz-osx-font-smoothing: grayscale on the root layout for crisper text.
Write in normal case, transform with CSS. Store "Typographic detail" and apply text-transform: uppercase for display; don't hardcode shouting case in content.
Smart punctuation. Curly quotes, en dash for ranges (2010–2020), em dash for asides, real ellipsis character instead of three periods. (If the user's own writing preferences forbid em dashes, their preference wins for copy they'll publish.)
Clean underlines. text-underline-position: from-font with text-decoration-skip-ink: auto so descenders like g and y aren't crossed.
Truncation needs an escape hatch. Any text cut with an ellipsis must be readable in full via tooltip or an expanded view.
Color
Every palette step earns its place. Map each step to a purpose (page background, hover, border, solid fill, body text). Delete steps nothing uses.
Semantic tokens in components, never primitives. Components reference --color-text-secondary, not --blue-500. Primitives feed tokens; tokens feed components.
Name tokens by purpose, not appearance or location. --color-accent-solid, not --color-blue-button (breaks when the brand goes violet) or --color-sidebar-gray (breaks when reused elsewhere).
Reserve accent for brand color. Don't let primary mean both "brand color" and "primary text" — use --color-text-primary and --color-accent-solid as separate namespaces.
Measure contrast against the immediate background. Text on a card is measured against the card surface, not the page behind it.
Dark mode gets its own palette. Never invert the light palette; shadows, saturation, and hierarchy behave differently on dark surfaces.
One theming mechanism. Pick either prefers-color-scheme media queries or a .dark class for all tokens. Mixing both causes surfaces and text to disagree.
Choose gradient interpolation deliberately. in oklab for even brightness, in oklch for vivid midpoints, in srgb for muted midtones.
Accessibility
Native elements first. <button> for actions, <a href> for navigation. A div with a click handler loses middle-click, right-click menus, focus behavior, and screen reader semantics for free.
Style :focus-visible, not :focus. Never remove the outline without providing a replacement.
tabindex is only ever 0 or -1. Positive values scramble the natural focus order.
Icon-only buttons get aria-label. Never aria-hidden="true" on anything focusable.
Alt text describes purpose and content. Decorative images get alt="" (empty, not missing).
Every input gets a visible <label>. Placeholders are not labels — they vanish on input. Set type and inputmode so touch keyboards match the expected content (email, numeric, etc.).
Never block paste. People paste passwords and one-time codes.
Form validation pattern. Keep submit enabled until the request starts; validate on submit; mark bad fields aria-invalid="true"; link error text with aria-describedby; move focus to the first invalid field.
Hit areas: 24×24px minimum, aim for 44×44 on touch and 40×40 on desktop. They must never overlap.
pointer-events: none on decorative layers (glows, gradients, overlays) so they never swallow clicks.
Hover styles inside @media (hover: hover). On touch screens, :hover sticks after a tap and makes items look selected.
Respect reduced motion. Wrap animations in @media (prefers-reduced-motion: no-preference) so they only run for people who haven't reduced motion.
Live region roles. role="status" for routine updates ("Link copied"), role="alert" only for urgent errors.
Never color alone for status. Pair color changes with an icon, label, or underline.
Skip link first. The skip-to-content link is the first Tab stop. Add scroll-margin-top to headings so anchor jumps don't land flush against the viewport edge.
Layout
Group spacing ≥ 2× item spacing. If items within a group are 8px apart, groups are at least 16px apart. Proximity is what communicates grouping.
Writing (microcopy)
Buttons start with a verb. "Save draft", "Delete project" — never "OK!" or a bare "Yes".
Confirmation buttons state the outcome. "Delete project" next to "Cancel", not "Yes"/"No".
One continue label per flow. Pick "Continue" or "Next" and use it on every step; don't rotate through synonyms.
Links describe their destination. "Read the docs", never "Click here".
One capitalization style everywhere. Sentence case ("Save changes") is the safest default for buttons, headings, and labels.
Toggles are labeled by their on-state. "Send read receipts", never "Disable read receipts".
Empty states explain and offer one action. Say what belongs there and give a single starter action ("No projects yet… Create a project"), not just "No results."
Address the reader as "you". "You'll receive an email", never "The user will receive an email."
How to apply this skill
When writing new UI code: treat every rule above as a default. Don't announce each rule; just produce code that already follows them.
When reviewing UI code: scan against the categories in order (visual → animation → typography → color → accessibility → layout → writing) and report only violations, each with the concrete fix.
When rules conflict with an explicit user instruction or an established design system in their codebase, the user's system wins — note the deviation once and move on.
