Interface details
Reviews an interface for the details people notice: depth, states, motion, copy and how it holds up on a phone.
$ npx skills add jakubwarkusz/skills --skill interface-detailsWhat it does
Point it at a screen, a component or a pull request and it goes through the small things that decide whether an interface feels finished: depth and corners, every state of every control, how things move in and out, the words on the screen and what happens on a real phone with a keyboard and a notch. It follows your design system first and only fills the gaps, so it works with any palette or style. Every rule comes from fixes made on real products. It answers with a short list of fixes, each pointing at the line it belongs to.
Reach for it when
- Before you ship a screen or merge a component.
- When something feels off and you can't say what.
- Before the first test on a real phone.
What it checks
Depth and shape
How controls sit on the page before anyone touches them.
One recipe for depth
Raised controls get their depth from one recipe the design system defines, usually a lighter top edge and a crisp 1 px edge. Use the project's own colours; if it has no recipe yet, propose one and apply it everywhere.
Why. Stacked, blurry drop shadows smear on light grounds and disappear on dark ones. One recipe applied everywhere is what makes a set of controls feel like a family.
- 36 inside 36
Concentric corners
An inner element's radius is the outer radius minus the padding between them.
Why. Equal radii on nested shapes make the gap look thicker at the corners than along the sides, which reads as careless even when nobody can say why.
Which one do you type in?
Fields don't look pressable
Text fields read as places to type: flatter than buttons, with a clear edge and a visible focus state. Avoid inset shadows unless the design system uses them.
Why. When a field looks like a button, people tap it expecting an action, and an inset shadow next to raised buttons tends to look like dirt.
The dashed line is what you can tap
Hit areas of 40 px
Anything tappable has at least 40 by 40 px of target, even when the visible icon is 16 px.
Why. Thumbs miss small targets, and a missed tap feels like the product didn't respond.
States
What every control says while something is happening.
Click the tabs
Selection doesn't change size
Active, selected and current items change colour, background or a marker, not font weight or padding.
Why. Bold text is wider. Changing weight or padding on select makes the row and its neighbours jump.
Press it twice
Every action has four states
Idle, working, done and failed are each visible. A working button keeps its width and swaps its label for a spinner.
Why. Within about 100 ms people need a sign their press landed. A button that changes width moves the layout under their finger.
Errors say what to fix
Lead with the fix, keep the cause short, and put the message next to the field it is about.
Why. An error is the one sentence people read twice. "Invalid input" makes them guess; "Add the ending, like .com" doesn't.
- Brief.pdf
Undo or hold, dialogs last
Destructive actions can be undone or are held to confirm. A confirmation dialog is the last resort.
Why. People learn to click through dialogs without reading. Undo protects them without slowing anyone down.
Motion
How things move in, out and between states.
Click it twice, fast
CSS first
Start with CSS transitions and keyframes. Use an animation library only when the feel is clearly better, like a spring that follows scroll.
Why. CSS transitions are interruptible and run off the main thread. A library is worth its weight only for what CSS can't do well.
Right from the first frame
Set positions correctly in every state. Don't animate a correction of something that started in the wrong place.
Why. A slide that fixes a wrong position looks like a glitch, not motion.
- Draft saved
- Logo uploaded
- Ola invited
Exits are quieter than enters
Exits are shorter and smaller. Something the person dismissed can simply go; something that leaves on its own, like a toast or a sheet, needs an exit.
Why. Without an exit the screen jumps when an element vanishes, and people lose track of what changed.
Move down the list
One highlight under the list
A highlight that moves between rows is a single element rendered under all of them, positioned to the active row.
Why. A highlight inside each row paints over the row it is leaving while it travels, hiding its icon and text.
- The deploy finished at 14:02.
- Ola left a comment on the brief.
Animate changes, not renders
Layout animations run when items are added or removed, not on every render.
Why. Otherwise streaming text or a growing list drags everything above it along on every update.
- Invoice 0042Due on 1 December
Themes change all at once
When the theme switches, every colour changes together, instantly unless the design animates the change on purpose. Under reduced motion, keep the state change and drop the travel.
Why. When only some colours transition, the screen flashes a mix of both themes for a moment.
Text and icons
The words and symbols on the screen.
- Open Writing↵Open Skills
Icons are drawn
Use drawn icons, never typed symbols like arrows or a return sign for keys.
Why. Typed symbols take the font's weight and baseline, so they never line up with real icons.
- 01 / FeaturesBuilt for teams
- 01Shared drafts
- 02Comments on any line
- 03Version history
Decoration has to mean something
Wide-tracked capitals, monospace and numbers like 01 / 02 / 03 are fine when the design system gives them a role. Flag them where they are only there to look designed.
Why. Ornament without a job adds noise and tells the reader nothing about what the thing is.
Changes saved — anyone with the link sees them now -- no need to resend.
Plain punctuation
Interface copy follows the project's voice guide. Where it says nothing, prefer commas and full stops to em dashes and double hyphens.
Why. Long dashes break short interface lines awkwardly and are a common tell of generated text.
- Nothing here yetManage your items with ease and streamline your workflow.
Name the real thing
Copy names what the person gets. If the same vague word appears three times, nothing was decided.
Why. Concrete nouns are faster to read and harder to misunderstand.
Leave streaming text alone
Don't balance or prettify lines of text that is still arriving.
Why. Balanced wrapping recalculates on every word, so finished lines keep jumping.
Phones
What breaks on a real device with a keyboard and a notch.
- Install
npx skills add jakubwarkusz/skills --skill interface-detailsmin-width: 0 on flex and grid children
Children that hold text, code or images get min-width: 0.
Why. Their default minimum is their content. One long line or code block pushes the whole page sideways.
- 9:41MailboxesEdit
Inbox
- Ola Nowak9:12Brief for the spring launchHere is the first draft, let me know what you think.
- Vercel8:47Deployment readyYour deployment is live on production.
- MarekYesterdayRe: FridayWorks for me, see you at three.
Pad by the safe areas
With viewport-fit=cover, bars pad by env(safe-area-inset-top) and the bottom inset.
Why. Safari draws the page under the status bar and the home indicator. A blur doesn't reach there; padding does.
- Can we move Friday to 3SendCancelNew Message"3"3pm30QWERTYUIOPASDFGHJKLZXCVBNM123spacereturn
Sheets follow the visual viewport
Full-screen sheets with fields size and position themselves to the visual viewport.
Why. iOS doesn't shrink the layout when the keyboard opens, so the main button ends up behind it.
- 9:41Jakub
- Work
- Skills
- Writing
- About
Drag the menu
Menus don't rubber-band
Full-screen menus scroll only when their content is taller than the screen.
Why. Otherwise a drag on iOS pulls the whole menu, header and close button included.
npx skills add jakubwarkusz/skills --skill interface-detailsTruncate long values, copy them whole
Commands, URLs and hashes truncate in one line, and their copy button copies the full value.
Why. Wrapped commands are hard to read and easy to paste half of.
Code
How the interface is written.
const ref = useRef<HTMLDivElement>(null); useEffect(() => { const node = ref.current; if (!node) return; const observer = new ResizeObserver(measure); observer.observe(node); return () => observer.disconnect();}, []);Ref callbacks over effects
In React projects, attach listeners, observers and measurements in ref callbacks with cleanup.
Why. They run when the element exists and clean up when it goes, without effect timing bugs.
// Set loading to truesetLoading(true);// Fetch the invoicesconst invoices = await getInvoices();// Sort the invoicessetInvoices(invoices.toSorted(byNewest));No narrating comments
Don't add comments that describe what the code plainly does.
Why. They go stale and bury the few comments that explain something non-obvious.
<button className="w-[40px] h-[40px] rounded-[10px]"> <Icon className="w-[16px] h-[16px] mt-[2px]" /></button>Tailwind, when the project uses it
Prefer canonical classes to arbitrary values, and give repeated one-off sizes a token. State styles that must win live in the same layer as the utilities.
Why. Utilities override component CSS, so a hover or error style written in a lower layer silently loses.
The file
Everything the agent reads, 2.4k tokens. It loads only when the task calls for it.
View on GitHub---name: interface-detailsdescription: "Reviews interface code and screens for the details people notice: depth and corners, every state of a control, motion in and out, copy and icons, and how it holds up on a phone. Use when building or reviewing UI components, before shipping a screen, or when something feels off."--- # Interface details Read the interface the way someone will use it: on a phone, in a hurry, pressing things twice. Look at what is on the screen, not at the design file. The project's design system, brand and voice come first: these rules fill the gaps and flag what is inconsistent, they don't override deliberate choices. Every finding names the file and line, says what a person sees, and gives the fix. ## Depth and shape- One recipe for depth. Raised controls get their depth from one recipe the design system defines, usually a lighter top edge and a crisp 1 px edge. Use the project's own colours; if it has no recipe yet, propose one and apply it everywhere. Why: Stacked, blurry drop shadows smear on light grounds and disappear on dark ones. One recipe applied everywhere is what makes a set of controls feel like a family.- Concentric corners. An inner element's radius is the outer radius minus the padding between them. Why: Equal radii on nested shapes make the gap look thicker at the corners than along the sides, which reads as careless even when nobody can say why.- Fields don't look pressable. Text fields read as places to type: flatter than buttons, with a clear edge and a visible focus state. Avoid inset shadows unless the design system uses them. Why: When a field looks like a button, people tap it expecting an action, and an inset shadow next to raised buttons tends to look like dirt.- Hit areas of 40 px. Anything tappable has at least 40 by 40 px of target, even when the visible icon is 16 px. Why: Thumbs miss small targets, and a missed tap feels like the product didn't respond. ## States- Selection doesn't change size. Active, selected and current items change colour, background or a marker, not font weight or padding. Why: Bold text is wider. Changing weight or padding on select makes the row and its neighbours jump.- Every action has four states. Idle, working, done and failed are each visible. A working button keeps its width and swaps its label for a spinner. Why: Within about 100 ms people need a sign their press landed. A button that changes width moves the layout under their finger.- Errors say what to fix. Lead with the fix, keep the cause short, and put the message next to the field it is about. Why: An error is the one sentence people read twice. "Invalid input" makes them guess; "Add the ending, like .com" doesn't.- Undo or hold, dialogs last. Destructive actions can be undone or are held to confirm. A confirmation dialog is the last resort. Why: People learn to click through dialogs without reading. Undo protects them without slowing anyone down. ## Motion- CSS first. Start with CSS transitions and keyframes. Use an animation library only when the feel is clearly better, like a spring that follows scroll. Why: CSS transitions are interruptible and run off the main thread. A library is worth its weight only for what CSS can't do well.- Right from the first frame. Set positions correctly in every state. Don't animate a correction of something that started in the wrong place. Why: A slide that fixes a wrong position looks like a glitch, not motion.- Exits are quieter than enters. Exits are shorter and smaller. Something the person dismissed can simply go; something that leaves on its own, like a toast or a sheet, needs an exit. Why: Without an exit the screen jumps when an element vanishes, and people lose track of what changed.- One highlight under the list. A highlight that moves between rows is a single element rendered under all of them, positioned to the active row. Why: A highlight inside each row paints over the row it is leaving while it travels, hiding its icon and text.- Animate changes, not renders. Layout animations run when items are added or removed, not on every render. Why: Otherwise streaming text or a growing list drags everything above it along on every update.- Themes change all at once. When the theme switches, every colour changes together, instantly unless the design animates the change on purpose. Under reduced motion, keep the state change and drop the travel. Why: When only some colours transition, the screen flashes a mix of both themes for a moment. ## Text and icons- Icons are drawn. Use drawn icons, never typed symbols like arrows or a return sign for keys. Why: Typed symbols take the font's weight and baseline, so they never line up with real icons.- Decoration has to mean something. Wide-tracked capitals, monospace and numbers like 01 / 02 / 03 are fine when the design system gives them a role. Flag them where they are only there to look designed. Why: Ornament without a job adds noise and tells the reader nothing about what the thing is.- Plain punctuation. Interface copy follows the project's voice guide. Where it says nothing, prefer commas and full stops to em dashes and double hyphens. Why: Long dashes break short interface lines awkwardly and are a common tell of generated text.- Name the real thing. Copy names what the person gets. If the same vague word appears three times, nothing was decided. Why: Concrete nouns are faster to read and harder to misunderstand.- Leave streaming text alone. Don't balance or prettify lines of text that is still arriving. Why: Balanced wrapping recalculates on every word, so finished lines keep jumping. ## Phones- min-width: 0 on flex and grid children. Children that hold text, code or images get min-width: 0. Why: Their default minimum is their content. One long line or code block pushes the whole page sideways.- Pad by the safe areas. With viewport-fit=cover, bars pad by env(safe-area-inset-top) and the bottom inset. Why: Safari draws the page under the status bar and the home indicator. A blur doesn't reach there; padding does.- Sheets follow the visual viewport. Full-screen sheets with fields size and position themselves to the visual viewport. Why: iOS doesn't shrink the layout when the keyboard opens, so the main button ends up behind it.- Menus don't rubber-band. Full-screen menus scroll only when their content is taller than the screen. Why: Otherwise a drag on iOS pulls the whole menu, header and close button included.- Truncate long values, copy them whole. Commands, URLs and hashes truncate in one line, and their copy button copies the full value. Why: Wrapped commands are hard to read and easy to paste half of. ## Code- Ref callbacks over effects. In React projects, attach listeners, observers and measurements in ref callbacks with cleanup. Why: They run when the element exists and clean up when it goes, without effect timing bugs.- No narrating comments. Don't add comments that describe what the code plainly does. Why: They go stale and bury the few comments that explain something non-obvious.- Tailwind, when the project uses it. Prefer canonical classes to arbitrary values, and give repeated one-off sizes a token. State styles that must win live in the same layer as the utilities. Why: Utilities override component CSS, so a hover or error style written in a lower layer silently loses.