Better UI

Jakub KrehelCommunityCreated by Jakub Krehel

Skill
Guidelines
Software development
MIT
No issues found

From the author

Polishes surfaces, icons and motion with exact values for border radius, optical alignment, shadows, icon states and animation.

— the description by Jakub Krehel

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

better-ui provides a standardized set of rules and exact values for refining user interface elements. It focuses on achieving visual consistency across surfaces, icon states, and motion design. The skill defines specific technical requirements for border radii, shadow layering, optical alignment, and animation behaviors, ensuring that interactive elements remain predictable and polished. It also includes a structured reporting framework for auditing UI components against these standards.

What it does

Defines exact values for border radius, shadow recipes, and press scales.
Provides guidelines for optical alignment and icon state management.
Establishes rules for motion design, including entrance, exit, and state-change animations.
Specifies performance optimizations for CSS transitions and will-change properties.
Outlines requirements for handling hover-capable pointers and scroll containment.
Offers a systematic approach for auditing and reporting UI polish findings.

When to use it

When refining the visual details of UI components after core interactions are functional.
When standardizing motion language and surface styling across a project.
When auditing a codebase for visual inconsistencies in icons, surfaces, or animations.
When implementing accessibility-aware motion that respects user preferences.

Advantages

Ensures consistent visual language through exact, non-approximated values.
Promotes accessible motion design by mandating reduced-motion fallbacks.
Reduces visual clutter by replacing unnecessary borders with shadow-based depth.
Provides clear, actionable criteria for identifying and fixing UI polish issues.

Usage examples

“Audit this button component for UI polish issues.”: The agent will inspect the button's border radius, press scale, hover states, and animation properties against the defined guidelines, reporting any inconsistencies in a structured table.
“How should I animate a modal entrance?”: The agent will provide the specific staggering, duration, easing, and blur values required for the entrance animation, while ensuring it respects the reduced-motion preference.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/jakubkrehel/better-ui/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip better-ui.zip -d .agents/skills
```

Documentation by Jakub Krehel

UI polish

This skill holds the visual polish for surfaces, icons and motion, with the exact value each detail takes. It applies once the underlying interaction is sound, and a polish finding never outranks a broken interaction.

Exact values, optional polish

The values below are exact, not ranges to approximate. cubic-bezier(0.2, 0, 0, 1) is not cubic-bezier(0.4, 0, 0.2, 1), and 0.96 is not 0.95. The optical nudges and the concentric padding cutoff are the exceptions. They are starting points, judged by eye.

Keep the project's component library, tokens and density, and match its motion language wherever no rule here gives a value. A deliberate and consistent project convention, such as a style with no shadows, is a preference and not a finding. The same detail done two ways within the project is a finding.

Text wrapping, font rendering, tabular numbers and text spacing belong to better-typography. Hit areas, keyboard support, ARIA and the reduced-motion requirement belong to better-accessibility. Grouping, section spacing, breakpoints and spatial RTL belong to better-layout, except directional icon mirroring. Color tokens and contrast measurement belong to better-colors.

Outer radius equals inner radius plus padding

Where nested surfaces share a visible, even inset, the outer radius is the inner radius plus the padding plus any border width. Past 24px of padding, or where the padding is deliberately asymmetric, treat the layers as separate surfaces and keep each one's radius token. Recipes are in surfaces.md.

Align optically where geometry looks off

Where geometric centering looks off, nudge by eye. Give a button 2px less padding on its icon side, shift a play triangle toward its point and fix asymmetric glyphs in the SVG itself. Recipes are in surfaces.md.

Shadows for elevation, borders for structure

Where a border exists only to create depth, replace it with layered transparent box-shadow values. Keep borders on dividers, separators, table cells and selected states. Keep them on form inputs too, whose boundary needs 3:1 non-text contrast under better-accessibility. Focus rings belong to better-accessibility as well.

Forced-colors mode removes every box-shadow. Keep border: 1px solid transparent under a shadow ring so that mode still draws an edge. Recipes are in surfaces.md.

Outline images in pure black or white

Give content images a 1px outline inset by 1px. Use oklch(0 0 0 / 0.1) in light mode and oklch(1 0 0 / 0.1) in dark. Never use a palette near-black, a tinted neutral or the accent color, because the tint shows as a colored fringe on the image edge. Skip transparent artwork such as logos and illustrations. The recipe is in surfaces.md.

Transitions, not keyframes, for interactive state

Drive interactive state changes with CSS transitions or a motion library's springs, which retarget when the user reverses mid-flight. Keyframes run a fixed timeline and cannot reverse, so reserve them for sequences that run once. See animations.md.

Press scales to 0.96

A pressed button scales to 0.96 over 150ms with ease-out, and a disabled one never scales. Give the button an opt-out where the motion would distract, through the component's existing variant API or a static prop. See recipes for CSS, Tailwind and Motion.

High-frequency interactions respond instantly

Keystrokes, row hovers and tab switches get instant feedback, or a transition of 150ms or less on opacity or background-color. Reserve expressive motion for infrequent moments such as a view's first load, a success state or an empty state.

Every animated state change also leaves a static cue in the form of a color, icon or label. Motion is never the only feedback channel.

Gate motion behind the reduced-motion preference

better-accessibility owns the requirement, and no recipe here ships without it. Run movement, scale and blur only under prefers-reduced-motion: no-preference. Under reduced motion, replace them with an opacity cross-fade rather than removing the element instantly. Recipes for CSS, Tailwind and Motion are in animations.md.

Stagger infrequent entrances by 100ms

Where sequence communicates hierarchy in a staged entrance, split the content into semantic chunks such as title, description and actions. Stagger them 100ms apart, each entering with opacity, 4px of blur and 12px of translateY over 300ms with ease-out. Never stagger routine interactions. See enter-exit.md.

Exits are shorter and smaller than enters

Exit with opacity, 4px of blur and a fixed -12px translateY over 150ms with ease-out, never the full container height. Slide fully out only where the destination carries meaning, such as a drawer closing. Remove the element instantly where motion adds no information. See enter-exit.md.

Skip state animations on first render

Set initial={false} on an AnimatePresence that wraps a state swap, so the default state does not animate in on mount. Never set it around an intentional entrance such as a staggered hero. See animations.md.

Cross-fade contextual icons with exact values

Where an icon swaps on an infrequent state change, such as play to pause or copy to copied, cross-fade it. Scale runs 0.25 to 1, opacity 0 to 1 and blur 4px to 0px. With a motion library, use { type: "spring", duration: 0.3, bounce: 0 }, and bounce is always 0. Without one, keep both icons in the DOM and cross-fade over 300ms with cubic-bezier(0.2, 0, 0, 1).

A tab's icon swap and the actions a row reveals on hover fall under High-frequency interactions respond instantly. Both recipes are in icon-transitions.md.

Suppress transitions on theme switch

Disable every transition for the theme swap, force a style flush and restore transitions after the next frame. Otherwise every color transition fires at once and the switch smears. See the recipe.

Transition only what changes

Name the exact properties, as in transition-property: scale, opacity, and never all. See performance.md.

Name the animated property in will-change

Add will-change only after you see first-frame stutter, and name the property you animate: scale for scale, transform for transform. Limit it to transform properties, opacity and filter, and never use all. See performance.md.

Hover effects only on hover-capable pointers

Put hover-only styling behind @media (hover: hover). On touch, :hover latches after a tap and reads as a stuck selected state. Tailwind 4's hover: variant already compiles under that query, and Tailwind 3's does not. Where a control draws its own pressed state, set -webkit-tap-highlight-color: transparent so the default gray flash does not double it.

Contain scroll inside overlays

Give scrollable dialogs, drawers, menus and side panels overscroll-behavior: contain, so scrolling past their end never scrolls the page behind.

Match icon stroke to text weight

An icon's rendered stroke tracks the weight of the text beside it, from 1.5px at 400 to 2.5px at 700. Use one icon library per surface. The table, sizing and grid rules are in icons.md.

One SVG, recolored per state

Icons use currentColor and take hover, selected and disabled states from CSS color and opacity, never from separate assets. Outline is the default variant, and fill marks the active state. Under dir="rtl", mirror only icons whose meaning follows reading direction. See icons.md.

Before you finish

Detection	Fix
Padded parent and child with the same `rounded-*` or `border-radius`	Add the padding to the outer radius
`box-shadow: 0 0 0 1px` ring with no `border` beside it	`border: 1px solid transparent`
`outline-slate-`, `outline-zinc-` or a hex outline color on `img`	`outline-black/10` and `dark:outline-white/10`
`transition-all` or `transition: all`	Name the changing properties
`animation:` set on `:hover`, `.open` or another toggled class	A transition on the same properties
`active:scale-95`, `scale-90` or `whileTap` below `0.96`	`0.96`
`:active` scale with no `:disabled` exclusion	`enabled:active:` or `:not(:disabled):active`
`bounce:` set to anything but `0`	`bounce: 0`
`opacity: 0` in a base rule that only an `animation` reveals	Hidden state in the `from` keyframe, `animation-fill-mode: both`
`translate`, `scale`, `filter` or `motion.*` animation with no `prefers-reduced-motion`, `motion-safe:` or `MotionConfig` guard	Gate it and cross-fade opacity under reduced motion
Color transitions plus a theme toggle with no `disableTransitionOnChange` or override	The theme-switch suppression recipe
`will-change: all`, or `will-change` on an element that never animates	Name the animated property or delete it
`fill="#..."` or `stroke="#..."` inside an icon SVG	`currentColor`
Plain-CSS `:hover` or Tailwind 3 `hover:` outside `@media (hover: hover)`	Wrap it in the query
`overflow: auto` or `overflow-y-auto` on a dialog, drawer or menu with no `overscroll-behavior`	`overscroll-behavior: contain`

Reporting

Severity. HIGH breaks an interaction, as a keyframe toggle that cannot reverse or a hover state stuck on touch does. Two of better-interface's escalation triggers land here and are HIGH on sight. One is motion that ignores prefers-reduced-motion, and the other is a state change carried by motion alone. MEDIUM is a visible inconsistency in surfaces, icons or motion. LOW is isolated polish.

Verification. Without a browser, read every state the component defines from the code, such as hover, pressed, selected, loading and empty, with its durations and easings. With one, walk each state and replay motion at 10% speed in the browser's Animations panel. Report every check you could not run as Not verified.

Format. Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:

Severity	Location	Before	After	Why

Location is path/to/file:line. Why names the principle and the user impact.

End with Block when any HIGH remains, Approve otherwise, leaving the rest in the table as work to do. Never Approve coverage you did not inspect. With nothing to report, state "No actionable UI-polish findings" and report verification.

Files

ATTRIBUTION.mdAdded by AutoGineer853 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md10.9 KiB
agents/openai.yaml113 B
animations.md4.8 KiB
enter-exit.md3.5 KiB
icon-transitions.md2.6 KiB
icons.md3.9 KiB
performance.md2.2 KiB
surfaces.md3.5 KiB

animations.md

Animations

Recipes for interruptible transitions, press feedback, first-render behavior, theme switches and the reduced-motion fallback. Staged entrances and exits live in enter-exit.md, and icon swaps in icon-transitions.md.

Interruptible animations

	CSS transitions	CSS keyframe animations
Behavior	Interpolate toward the latest state	Run on a fixed timeline
Interrupted	Retarget mid-flight and reverse	Snap or restart from the beginning
Use for	Hover, toggle, open and close	Sequences that run once, such as enters and loading

/* Good: clicking again mid-animation reverses smoothly */
.drawer {
  transform: translateX(-100%);
  transition: transform 200ms ease-out;
}
.drawer.open {
  transform: translateX(0);
}

/* Bad: closing mid-animation snaps */
.drawer.open {
  animation: slideIn 200ms ease-out forwards;
}

Scale on press

.button {
  transition-property: scale;
  transition-duration: 150ms;
  transition-timing-function: ease-out;
}

.button:not(:disabled):active {
  scale: 0.96;
}

// Tailwind
<button className="transition-transform duration-150 ease-out enabled:active:scale-[0.96]">
  Click me
</button>

// Motion
<motion.button whileTap={disabled ? undefined : { scale: 0.96 }} disabled={disabled}>
  Click me
</motion.button>

Static prop pattern

Where the button has no variant API to carry the opt-out, apply the scale class conditionally on a static prop:

const tapScale = "enabled:active:scale-[0.96]";

function Button({ static: isStatic, className, children, ...props }) {
  return (
    <button
      className={cn(
        "transition-transform duration-150 ease-out",
        !isStatic && tapScale,
        className,
      )}
      {...props}
    >
      {children}
    </button>
  );
}

// Usage
<Button>Click me</Button>           {/* scales on press */}
<Button static>Submit</Button>       {/* no scale */}

Skip animation on page load

The icon recipe in icon-transitions.md shows initial={false} used correctly. It suits icon swaps, toggles, tabs and segmented controls, anything with a default state on page load.

Setting it around a first-time entrance skips that entrance entirely. Check the component on a full page refresh before adding it.

// Bad: initial={false} skips the staggered page enter
<AnimatePresence initial={false}>
  <motion.div initial="hidden" animate="visible" variants={...}>
    ...
  </motion.div>
</AnimatePresence>

Suppress transitions on theme switch

Inject a stylesheet that turns off every transition, force a style flush so the new colors commit while it applies, then remove it after the next frame:

"use client";

import { useEffect } from "react";

export function DisableThemeTransitions() {
  useEffect(() => {
    const mql = window.matchMedia("(prefers-color-scheme: dark)");

    const handleChange = () => {
      const style = document.createElement("style");
      style.append(
        document.createTextNode(
          "*,*::before,*::after{transition:none !important}"
        )
      );
      document.head.append(style);

      void document.body.offsetHeight; // forces a synchronous style flush

      requestAnimationFrame(() => {
        requestAnimationFrame(() => style.remove());
      });
    };

    mql.addEventListener("change", handleChange);
    return () => mql.removeEventListener("change", handleChange);
  }, []);

  return null;
}

The new theme resolves while the override is still in the document, so no transition starts. The nested requestAnimationFrame removes the override only after that paint.

That covers the OS-level change. An in-app toggle needs the same steps around its own flip: apply the override, change the theme, flush and remove. next-themes ships this as disableTransitionOnChange.

High-frequency motion

/* Good: high-frequency hover gets a minimal transition */
.row:hover {
  background-color: var(--surface-hover);
  transition: background-color 100ms ease-out;
}

/* Bad: every hover replays a full entrance */
.row:hover .row-icon {
  animation: bounceIn 500ms;
}

Reduced-motion fallback

The opacity fade runs for everyone, and movement, scale and blur join it only without the preference:

.panel {
  transition: opacity 150ms ease-out;
}

@media (prefers-reduced-motion: no-preference) {
  .panel {
    transition-property: opacity, translate, scale, filter;
    transition-duration: 300ms;
  }
}

In Tailwind, prefix movement, scale and blur utilities with motion-safe:. In Motion, wrap the app in <MotionConfig reducedMotion="user">. It turns off transform and layout animations under the preference and keeps opacity. Blur still runs there, so branch on useReducedMotion() where a recipe animates filter.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Jakub Krehel

Publisher

Jakub Krehel (Community)

Source

jakubkrehel/skills · skills/better-ui · commit f41f027

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Jakub Krehel or Jakub Krehel.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download better-ui.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Jakub Krehel

UI polish

Exact values, optional polish

Outer radius equals inner radius plus padding

Align optically where geometry looks off

Shadows for elevation, borders for structure

Outline images in pure black or white

Transitions, not keyframes, for interactive state

Press scales to 0.96

High-frequency interactions respond instantly

Gate motion behind the reduced-motion preference

Stagger infrequent entrances by 100ms

Exits are shorter and smaller than enters

Skip state animations on first render

Cross-fade contextual icons with exact values

Suppress transitions on theme switch

Transition only what changes

Name the animated property in will-change

Hover effects only on hover-capable pointers

Contain scroll inside overlays

Match icon stroke to text weight

One SVG, recolored per state

Before you finish

Reporting

Files

animations.md

Animations

Interruptible animations

Scale on press

Static prop pattern

Skip animation on page load

Suppress transitions on theme switch

High-frequency motion

Reduced-motion fallback

Requirements and compatibility

Security

Attribution and licence

Related skills

Pr

Retro

Triage

Code Review

Requesting Code Review

Code Simplification

Download ZIP