UI Craft

UI craft — what real apps do

By Achref Arabi · https://github.com/Achref23illi/ui-craft

A skill built from a study of 44 shipped iOS apps (Spotify, Airbnb, Instagram, TikTok, Apple Music, Apple TV, Netflix, VSCO, Halide, Denim, Photoshop, Riverside, Moises, Playground, Revolut, Linear, Notion, ChatGPT, Claude, Uber…). 2,602 screens were studied; about 270 were read closely and annotated. The point of the skill is not a style. It is the discipline these apps share: where they spend space and where they don't, how few things they show, and how every element earns its place.

Start here

Paths below are relative to this skill's folder (the one holding this file). The scripts need Python 3; scripts/sheet.py also needs Pillow.

1. Pick the job.

2. References first, every time. Run python3 scripts/refs.py "<pattern words>" (for example "video editor", "settings", "paywall"). It lists, best first, the local contact sheets to read (each is one image with six screens of one app: look for the ones that match), the matching patterns, measurements observed in those apps, and published before/after images. Read two or three sheets before drawing anything. refs.py --list prints the pattern names when you are unsure which words to use. If it reports no local library, work from the patterns and notes it prints and read at most two of the published images it lists; the rules below still hold. The published before/after images show one app's result: take the principle from them, never copy their layout, colours or branding into another product, and do not score a review by how closely a screen resembles them.

3. Apply the rules as numbers, not vibes. If a screen breaks one, the screen changes, not the rule. When sources disagree, this order wins:

1. the project's own design system and tokens (read them in code when you have it);
2. the rules and measurements in this file;
3. the screen recipes;
4. the per-app notes, which record what those apps do, not targets.

When you only have screenshots, you cannot see the project's tokens: report a deviation with its number and add "unless this is a deliberate token".

4. Use what the last redesign taught. Read "Lessons at a glance" below; open refs/lessons.md and refs/lessons-img/ when the screen involves motion, brand background, buttons, status indicators, tool panels, a second product space or reactions.

5. Verify on a real render. Screenshot the running app (iOS Simulator xcrun simctl io booted screenshot shot.png, Android adb exec-out screencap -p > shot.png, web a headless browser at 390 px wide), put several shots in one contact sheet with python3 scripts/sheet.py <folder>, read it, and run the checklist. Judge the render, never the code.

Fast review

For "review these screens" in minutes rather than an hour. No need to run doctor.py.

1. Collect screenshots of every screen in scope in one folder: same device, same data, tidy status bar. iOS Simulator: xcrun simctl status_bar booted override --time 9:41 --batteryState charged --batteryLevel 100 --wifiBars 3 --cellularBars 4 then xcrun simctl io booted screenshot shots/01-home.png. Android emulator: adb shell settings put global sysui_demo_allowed 1 then adb exec-out screencap -p > shots/01-home.png.

2. See everything at once: python3 scripts/sheet.py shots writes six screens per image into shots/sheets/; read the sheets, not the files, to judge layout, hierarchy and consistency.

3. Measure on the originals, not the sheets (sheets are too small for numbers): python3 scripts/measure.py shots/01-home.png gives the scale, the width in points and the side gutters; --col <x pt> and --row <y pt> list what a vertical or horizontal line crosses, with sizes and gaps in points (paddings, section gaps, row and button heights). The numbers in this file are for a 390-pt screen and hold from 375 to 430 pt.

4. References, three at most in fast mode: pick the two or three screens with the biggest problems, run scripts/refs.py with several words at once, and read one sheet per pattern. Skip references for screens that already follow a recipe.

5. Score against the checklist, global issues first: typeface and type scale, gutter, button sizes, icon set and labels, placeholder content, status bar. A global fix repairs every screen at once.

6. Report as a table, most important first, one line per finding:

   #	Screen	Rule	What is wrong (with the measurement)	Fix (with the number)

   Cap it at the ten findings that matter most; say what is already good in one line; end with what to fix first (usually the shared components).

Whole-app pass

1. Shared layer first: tokens (type, colour, spacing, radii), icon set, buttons, chips, fields, rows, headers, sheets, tab bar. Most screens then fix themselves.
2. Replace placeholder art with real pictures before judging anything.
3. Sweep every route: screenshot all of them and read them as contact sheets; list what is still off; fix in batches; sweep again.
4. Then the key screens by hand, each against its recipe.
5. Show the owner on a device and turn each note into a rule for the next pass (as refs/lessons.md round 2 did).

Lessons at a glance

From applying this skill to a real app and its owner's review (details, with screenshots, in refs/lessons.md):

• Tool screens (editors) are counted per band, not per screen; hiding their tools reads as a weak product. Tool panels fit without scrolling and use icon controls.
• Buttons were still too big at 48–52: the owner settled on 44 / 40 / 36, chips 30, with 44-pt touch areas.
• No transitions made a polished app feel like a prototype: slide for drill-down, rise for tasks, cross-fade for tabs, one animation per change, no bounce on tabs.
• A brand glow with grain gave identity without painting surfaces; it needs a vertical gradient, dark-and-light grain, transparent rows and a scroll backdrop.
• Status tags (synced, local, cloud, export…) are noise; icons are understood. Problems keep words.
• One owner's choices that worked well as defaults, not laws: a second space (community, marketplace) as a different stage of the same family with its own tab bar and a fixed way back; an own reaction set with one signature effect, not four.
• Replace striped placeholders with real images early; they hide spacing problems.
• A status bar style set by one dark screen lingers: set it per route.

The rules (with the numbers behind them)

1. Content carries the screen; chrome is nearly invisible. Artwork, video, photos and the user's words fill the frame. Headers are one title (15–17/600 centred, or 28–34/700 left) and at most two 24-pt glyphs. No decorative bars, no dividers between sections; a title and 12 pt of air are the divider. (Spotify, Apple TV, VSCO, Sora)

2. One primary action per screen state, pinned where the thumb is. A 44-pt pill at the bottom with 16 pt side gutters, full width only when the screen exists to make that one decision (rule 13); the secondary is text or a grey pill under it. Never two filled buttons side by side except as a strict pair (Play · My List, Submit · Retake). (Airbnb, Revolut, Headspace, Netflix)

3. Titles are close to their content and far from each other. Section title 20–22/700 on root and browsing screens, 17/700 for a section inside a detail screen, 13/600 grey for a group label above settings rows; 12 pt to its content (8 for group labels); 24–28 pt between sections. Screen title 28–34/700 with 8–12 pt to the first control. Body 15–16 with a 1.4 line height, never wider than the gutter. (Apple Music, Spotify, Denim, Superlist)

4. Rows are 44–56 pt and carry three things at most: a leading visual (24 icon, 40 avatar, 40–48 thumbnail), a title 15/500–600 with an optional 13 grey sub-line, and one trailing element (chevron, ⋯, value in grey, a 32–36 pt pill). Hairlines inset from the label, or none at all inside a card. Grouped screens put rows in white 12-pt cards on a grey ground; flat screens put them on white with hairlines. (Apple Music, Uber, Notion, Rewind, Opal)

5. Rails and grids have one geometry per screen. Rail tiles are square 112–160 pt or 16:9 at 160–180 wide, 12–20 pt corners, 8 pt gaps, with a 13–14 label and a 12 grey meta line under; 3 to 3.5 visible plus a peek. Grids are 2 columns with 8 pt gaps for browsing, 3 columns with 2–4 pt gaps for archives. Posters are 2:3, video 16:9, social 4:5. (Spotify, Apple TV, Denim, Pinterest, VSCO, Sora)

6. Tool UIs live on black with the picture at its own ratio. Editors, players and cameras: pure black stage, controls in bands below the picture (never over it except guides), tool labels 11 pt uppercase or 12–13 sentence case, the selected tool as a white or accent pill, the primary shutter/play as a 56–72 white disc, and one accent colour for "selected" or "has a value". Panels rise as sheets to about half the screen and never push the picture off. (Halide, Moises, Riverside, Denim, Photoshop, Analog)

7. Colour is a signal, not paint. One accent for the action (brand colour), one state colour at most (record red, live green), everything else ink and greys. Artwork supplies colour: dark players tint the top of the screen from the art. Brand colour on the tab bar's active item is enough branding. (Spotify, Netflix, Apple Music, Moises)

8. Sheets are the app's second surface. Anything transient rises as a sheet with a grabber, a 15–20/700 title, and an × disc: menus, pickers, filters, comments, share. Actions in a sheet are plain rows (icon 24 + label 15–16, ~56 pt), destructive last in red, "Cancel" as text. Alerts are centred dark/white cards with 15/600 title and two pills. (Spotify, Airbnb, Instagram, Threads, Riverside, Sora)

9. Empty, loading and error states are one sentence and one move. Centred, a 15–17 /600 line plus a 13 grey line, optionally a 48–64 pt glyph or small illustration, and at most one button. No paragraphs, no decoration. Toasts are dark pills (top or bottom) with 14/600 text and an optional trailing action. (TikTok, Meta AI, Notion, Pinterest)

10. Type does the hierarchy, not boxes. Two weights (500–600 for labels, 700–800 for titles), grey for the second line, mono or tabular figures only for numbers and readouts. Tracked uppercase only on 11–12 pt tool labels and eyebrows, never on titles. Cards are for objects (a place, an item, a plan), not for grouping text.

11. The tap budget: five choices in the first viewport, one of them primary. Count what makes a decision or starts an action above the fold (buttons, text links, chips, fields, toggles), except the tab bar and back. A set of options answering one question (a radio list, a segmented control, a set of destinations) counts as one. Content that opens an item (a tile, a row, a post) does not count. Five or fewer (W3C cognitive pattern), one filled primary, the rest as content (tiles, rows) or behind one clearly named "more" at most two levels deep (NN/g progressive disclosure). Two similar buttons side by side is the fastest way to make a user hesitate. Sources and numbers in refs/ux-research.md. Tool screens are the exception: an editor counts per band, not per screen. Header (back · undo · redo · primary), transport (play · full screen · timecode), timeline, and one scrollable band of 5–6 labelled tools that changes with the selection. Hiding tools there reads as "this app can't do it" (Splice, Instagram Reels, VN).

12. Every action icon carries a visible label. Only home, search, back and close stand alone; tab bars are always labelled; tool rows use icon + 10–11 pt label. Eleven studies over nineteen years and NN/g say the same thing: users match labels, not pictures, and rely on position for the rest. Tap targets 44 pt, 48 pt at the screen edges, with padding between neighbours.

13. Buttons are compact, and most screens need the smallest one. The main action is 44 pt (full width only where the screen exists to make one decision: intro, export, publish, paywall); dark buttons 40; everything else 36, hugging its label; chips 30 with 13-pt labels; tertiary actions are 15/600 text in the accent. Discs: 56 for source choices, 44 for media actions. Anything under 44 pt keeps a 44-pt touch area with hitSlop. Two big buttons on consecutive screens means one of them is a step, not a decision. Lessons in refs/lessons.md (§2, §7).

14. Motion follows the kind of screen, one animation per change. Places you drill into slide in from the right and follow the back swipe; tasks you open and close (search, editor, sign-in, import, forms) rise from the bottom and swipe down; tabs cross-fade in ~180 ms. Never let a container fade its content while the navigator also animates. Tiles, cards and big round actions ease to ~96 % and spring back; sheets ease out; panels rise. No bounce on the tab bar. Reduce Motion turns it all off. (refs/lessons.md §5)

15. Brand atmosphere comes from one glow, not from paint. A vertical gradient of the brand colour under the status bar (~34 % → 0 over ~380 pt) with a light-and-dark film grain masked to the same fade. Rows over it are transparent, fields are frosted white, and a status-bar backdrop fades in once content scrolls under the clock. A diagonal gradient leaves a seam; a white-only grain vanishes on white. (refs/lessons.md §6)

16. States are icons; problems are words. Synced, local, uploading, cloud-only, downloaded, preview-only, export: one icon at the row's trailing edge, the word for the screen reader. Conflicts, unsupported files and offline waits keep a word next to the warning icon. Tool panels follow the same idea: formatting choices are icon segments and steppers, and a panel fits without scrolling. (§8, §9)

17. If the product has a second space (a community, a marketplace), make it the same family on a different stage. These are defaults from one product's review; adapt them to yours. Same typeface, icons, radii, grain and components; a different ground (a night palette) and its second brand colour as the action. It gets its own tab bar (its sections as tabs, and a way back to the main space in a fixed place, for example the first tab with the main logo), illustrated icons for its main places and a plain outline for the profile. Its logo reuses the main wordmark's letter construction. Implement it as a theme scope that components read, never as forked components. (§10)

18. When the product has expressive details, own them, and give only one a big moment. For example reactions drawn in the brand gradients instead of system emoji, each with a small tap motion, and one of them (fire, in the case study) with a full-post effect. Optional; worth it for social and consumer products. (§11)

Measurements to reuse (390-pt screen; the same numbers hold from 375 to 430 pt)

Screen recipes

• Home with rails: title 28–34/700 (or wordmark 14 + title) · optional search pill 44 grey · sections of [title 20–22/700 + "See all" 14/600 accent] + rail · 24 between sections · tab bar. Nothing else above the first rail.
• Media detail: picture edge to edge at its ratio · title 17–20/700 · one 13 grey meta line · a row of 3–4 equal actions (44 discs with 12 labels, or 36 grey buttons) · related list. Sharing lives in the header or the ⋯ menu.
• Player / Now playing: dark, artwork square with 16 gutters · title 22–24/700 + 15–16 grey · thin progress with 11 times · 5-control row with a 64 disc · tertiary icon row · lyrics / queue as a peeking card.
• Editor: black stage · header (back · undo · redo · primary pill 32) · picture at its ratio · transport row (play centred, full screen right, timecode mono) · ruler with 2-s ticks · playhead line · video track 56–64 (thumbnails, selected with a 2-pt accent outline, trim handles) · audio track 40 (name + duration on a colour) · mute discs at the left · tool band of 5–6 labelled tools that scrolls and changes with the selection · tool panels as sheets with Cancel · title · Apply and a Reset in the header, each fitting without scrolling, formatting choices as icon segments and steppers.
• Publish / form: title 28/700 · destination tiles or radio cards · one field at a time with a 13 grey label · "More options" disclosure · pinned 44 CTA with a 12 grey line under it.
• Settings / profile: avatar 44–56 row · grouped cards of 44–52 rows · group labels 13/600 grey · footer links 12 grey. Destructive row last, in red.
• Comments / replies: sheet with "N replies" 20/700 · rows avatar 28–32 + handle 13/600 + time grey + body 14 + heart right · composer pill 44–48 docked · replies indented 40.
• Paywall: rail of what you get (artwork) or 3 benefit rows (icon 24 + 15/600 + 13 grey) · two plan cards with the selected outlined in the accent · one 44 CTA with the price · 12 grey legal links.
• Onboarding: one image or illustration · title 24–28/700 · one sentence 15–17 grey · dots · one 44 pill at the bottom. Permission explainers use a dark overlay with two "why / control" rows.

Checklist before calling a screen done

• Can you name the one thing this screen is for, and is it the only filled button?
• Is the title within 12 pt of what it titles, and is there ≥ 24 pt before the next section?
• Is the gutter 16 (or the project's one gutter token) everywhere, including inside sheets?
• Do rows carry ≤ 3 elements, and is the trailing one the only interactive one?
• Is there any box, border or divider that a change of ground or 12 pt of air could replace?
• Are all tiles in a rail the same size, corner and label style?
• Is the accent used ≤ 3 times on the screen (action, active tab, selection)?
• Are there ≤ 5 tappable choices in the first viewport (per band on a tool screen), and does every action icon have a label?
• Are buttons 44 / 40 / 36 with 44-pt touch areas, and is the only full-width one at a flow's end?
• Does each transition animate once (slide, rise or cross-fade), with no bounce on the tab bar?
• Are states shown as icons, with words only for problems, and does every tool panel fit without scrolling?
• Do empty, loading and error states exist, each as one line + one move?
• Is every number tabular, every timecode mono, every uppercase label ≤ 12 pt?
• Does the tool UI (if any) sit on black with the picture untouched?
• Does it read the same at 400-pt width and with Larger Text on?

Anti-patterns seen in weaker screens

Cards inside cards; three shadows on one screen; titles with an eyebrow, a title and a subtitle stacked; a segmented control and a chip row and tabs on the same screen; icons beside every heading or row label as decoration (action icons do carry labels, rule 12); gradient buttons next to flat ones; centred body text; more than one accent; "Learn more" links in the middle of a flow; a small centred header title repeating the large title right under it; all-caps 14-pt headings; toasts that need to be dismissed.

Files

• scripts/refs.py — references for a pattern: local sheets to read, patterns, app notes, published images.
• scripts/sheet.py — contact sheets (six screens per image) from any folder of screenshots.
• scripts/measure.py — sizes, gutters and gaps in points from a screenshot.
• scripts/doctor.py — checks an install; --refs also checks every sheet named in refs/patterns.md.
• refs/patterns.md — pattern → apps and sheets that do it well.
• refs/notes.md — per-app measurements and observations.
• refs/INDEX.md — the 44 apps and what each is good for.
• refs/ux-research.md — sourced findings on choices per screen, icon labels, tap targets, typefaces and icon systems.
• refs/lessons.md and refs/lessons-img/ — what changed when the rules met a real app and its owner's review.
• examples/before-after/ — that app before and after, screen by screen.
• refs/sheets/ (434 contact sheets), refs/screens/ (2,602 screens), refs/user-refs/ (editor references): the reference library.