What is the better-ui skill?
The better-ui skill carries the visual polish for surfaces, icons and motion, each with an exact value. A pressed button scales to 0.96 over 150ms, outer radius equals inner radius plus padding, and exits run shorter than enters. It applies after the interaction itself is sound.
Better-ui is where the small numbers live. It says a press scales to 0.96 and not 0.95, and that one easing curve is not interchangeable with another. Most values are exact, with optical nudges as the exception.
It also respects your project. A deliberate, consistent convention, such as a design with no shadows, is a preference. The same detail done two different ways inside one project is the finding.
Surfaces and icons
- Nested radius: outer equals inner plus padding plus border width, until padding passes 24px.
- Shadows give elevation and borders give structure. Keep a transparent border under a shadow ring for forced colors mode.
- Content images get a 1px outline at 10 percent black in light mode and 10 percent white in dark mode.
- Icons use currentColor, match stroke to text weight and mirror under RTL only when meaning follows reading direction.
Motion rules
Interactive state uses transitions, not keyframes, because transitions retarget when the user reverses mid flight. Entrances stagger by 100ms, exits run 150ms, and every movement sits behind the reduced-motion preference.
Where it fits
Best for
- Reviewing components that feel slightly off but pass every functional test.
- Replacing transition: all and hand-tuned bounce with named properties and fixed curves.
- Keeping hover effects from latching on touch screens.
Not for
- Hit areas, keyboard support and the reduced-motion requirement itself, which belong to better-accessibility.
- Spacing, breakpoints and color tokens, which sit with better-layout and better-colors. Related: emil-animate and improve-animations.
Use it with UiChemy
Tune surfaces and motion on the coded prototype your agent produced, then bring the page into WordPress through UiChemy AI to WordPress, which routes AI builds via Figma, Composer or MCP before converting. Get Started on uichemy.com.
How to install Better UI Skill: Exact Radius, Shadow and Motion Values
git clone https://github.com/jakubkrehel/skills.gitClone the repository
Run
git clone https://github.com/jakubkrehel/skills.git. The skill folder is skills/better-ui.Copy the folder and references
Copy skills/better-ui to your agent's skills location. Keep surfaces.md, animations.md, enter-exit.md, icon-transitions.md, icons.md and performance.md beside SKILL.md.
Claude Code plugin option
Run
/plugin marketplace add jakubkrehel/skillsand/plugin install interfaces@interfaces, the commands in the README.Ask for a polish review
Name a component and ask for a UI polish pass. A review does not edit files unless you ask for the fixes too.
Check that it loaded
Ask for a review of one animated component. The report should cite file and line, show before and after values such as 0.96, and finish with Block or Approve.
Key features
- Concentric radiusWhere nested surfaces share an even inset, outer radius is inner radius plus padding plus any border width. Past 24px of padding the layers keep their own tokens.
- Optical alignmentGeometric centering is nudged by eye: 2px less padding on a button's icon side, and a play triangle shifted toward its point.
- Shadow over border for depthBorders that exist only to create depth become layered transparent shadows. Dividers, table cells, selected states and form inputs keep their borders.
- Image outlinesContent images get a 1px outline inset by 1px, in pure black or white at 10 percent, so a tinted neutral never leaves a colored fringe.
- Press and hover rulesA pressed button scales to 0.96 over 150ms with ease-out and a disabled one never scales. Hover styling sits behind a hover-capable media query.
- Frequency aware motionKeystrokes, row hovers and tab switches get instant feedback or a transition of 150ms or less. Expressive motion is saved for infrequent moments.
- Enter and exit timingStaged entrances stagger by 100ms and run 300ms with 12px of translateY and 4px of blur. Exits run 150ms and are smaller than the enter.
- Icon cross-fadesAn icon swap on an infrequent state change scales 0.25 to 1 while fading and unblurring. With a motion library, the spring uses a 0.3 second duration and bounce 0.
- Theme switch suppressionTransitions are disabled for the theme swap, flushed, and restored after the next frame, so colors do not all animate at once.
- Scoped performance hintsTransitions name their properties and never use all. will-change is added only after first-frame stutter and names the animated property.
Frequently asked questions
What is the better-ui skill?
It is a skill in Jakub Krehel's skills repository that holds the visual polish for surfaces, icons and motion, each with its exact value. It applies once the underlying interaction works, and a polish finding never outranks a broken interaction.
How do I install better-ui?
Clone jakubkrehel/skills and copy skills/better-ui, with its six reference files, into the folder your agent loads skills from. In Claude Code you can run the plugin marketplace add and plugin install commands from the README. Then ask for a polish review of a named component. Related: web-design-guidelines.
Are its numbers fixed or approximate?
Mostly exact. The skill says a cubic-bezier of 0.2, 0, 0, 1 is not 0.4, 0, 0.2, 1, and 0.96 is not 0.95. The optical nudges and the concentric padding cutoff are the exceptions, treated as starting points you judge by eye.
What if my design deliberately avoids shadows?
A deliberate and consistent project convention, such as a style with no shadows, counts as a preference and is not reported. Doing the same detail two different ways inside one project is reported, and the skill keeps your component library, tokens and density.
Which AI coding agents can use better-ui?
The README documents a Claude Code plugin install, and the skill folder includes an agents/openai.yaml file. For other agents, copy the folder to their skills location. The README lists no other agents, so confirm yours reads SKILL.md folders.
How does it treat reduced motion?
Accessibility owns the requirement, but no recipe ships without it. Movement, scale and blur run only under prefers-reduced-motion: no-preference, and under reduced motion they are replaced with an opacity cross-fade instead of the element vanishing instantly.
Which findings are HIGH in better-ui?
A finding that breaks an interaction, such as a keyframe toggle that cannot reverse or a hover state stuck on touch. Motion that ignores prefers-reduced-motion and a state change carried by motion alone are better-interface escalation triggers, so they are HIGH on sight.