---
name: designing-interfaces
description: Makes a product's UI look deliberate and current instead of dated or improvised — auditing a screen against hierarchy, type scale, spacing scale, color tokens, layout and component consistency; introducing design tokens before restyling anything; and verifying every change visually with before/after screenshots. Use when building or restyling any web or app screen, reviewing a UI that looks old, cluttered or inconsistent, starting a design system for an existing app, or planning a design-improvement issue.
title: designing-interfaces
canonical_url: https://skilld.dev/gh/wdm0006/python-skills/ui-design
last_updated: 2026-11-15T17:02:12.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [MODERNIZING.md](https://skilld.dev/api/skills-raw/wdm0006/python-skills/ui-design/MODERNIZING.md), [TOKENS.md](https://skilld.dev/api/skills-raw/wdm0006/python-skills/ui-design/TOKENS.md).
>
> If the user asked to install this Skill, run `npx skilld install wdm0006/python-skills/ui-design`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/ui-design`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/wdm0006/python-skills/ui-design) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/ui-design`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/ui-design --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/ui-design --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Designing Interfaces

Most "ugly" apps are not missing talent, they are missing **constraints**: twelve
font sizes, spacing picked per element, a dozen near-identical greys, and buttons
that each grew their own style. Good design here is mostly removing choices. Fix
the system first (tokens, scales), then the screens fall into line.

## Contents
- Step 1 — Look before you touch anything
- Step 2 — Audit against the six fundamentals
- Match the visual language to the product
- Step 3 — Tokens first, restyle second
- Step 4 — Components and states
- Step 5 — Verify visually
- Native apps
- Scoping design work into issues
- Anti-patterns

## Step 1 — Look before you touch anything

Run the app with local data and screenshot the screens that matter at desktop and
phone widths. Design judged from source code is guesswork.

```bash
uvx --from playwright playwright screenshot --viewport-size "1280,800" "http://127.0.0.1:$PORT/" before-home-desktop.png
uvx --from playwright playwright screenshot --viewport-size "390,844"  "http://127.0.0.1:$PORT/" before-home-phone.png
```

Keep these "before" images; every design change is reviewed as a before/after pair.

## Step 2 — Audit against the six fundamentals

Score each screen; the lowest scores are where the work is.

1. **Hierarchy** — squint at the screenshot. Is there exactly one obvious primary
   thing (heading, primary action), then a clear second level, then the rest? If
   everything is bold, large, or colored, nothing is. Demote before you promote:
   most fixes make secondary text smaller and lighter, not the primary bigger.
2. **Typography** — one or two families, a modular scale of 5–7 sizes (e.g. 12, 14,
   16, 20, 24, 32, 40), body at 16px with ~1.5 line height, line length 50–75
   characters, weights limited to regular/medium/semibold. Count the distinct font
   sizes in the CSS; more than eight is a finding.
3. **Spacing** — every margin, padding and gap comes from one scale on a 4px base
   (4, 8, 12, 16, 24, 32, 48, 64). Related things sit closer together than
   unrelated things (proximity *is* grouping). Generous whitespace reads as quality;
   cramped reads as old.
4. **Color** — for a utility interface, start with a neutral ramp (8–10 greys,
   one slightly tinted family), one brand accent, and semantic colors (success,
   warning, danger, info). Games and playful consumer/social apps can use several
   saturated accents with stable roles; see "Match the visual language to the
   product" below. Text meets contrast (4.5:1 body, 3:1 large text and UI borders)
   — see the `building-accessible-interfaces` skill.
5. **Layout** — a max content width (≈ 1100–1280px for apps, ≈ 680–720px for
   reading), a consistent grid or column structure, alignment to shared edges, and
   a layout that reflows at phone width rather than shrinking.
6. **Consistency** — the same thing looks the same everywhere: one button style per
   role, one card style, one input style, one icon set at one stroke weight, one
   corner radius scale (e.g. 4/8/12/999). Inconsistency is the main thing that
   makes an app look assembled rather than designed.

## Match the visual language to the product

Choose the intended feel before choosing tokens. A restrained utility palette is
one starting point, not a universal definition of quality. Games should feel
playable; consumer/social apps built around fun should carry that energy in their
visual language.

- Use saturated accents for distinct roles (primary action, play surface, reward),
  rather than adding unrelated colors per component. Keep warning/danger meanings
  distinct from decorative or reward colors.
- Pair a playful display face for short headings with a readable body face; keep
  dense controls and data in the body face.
- Make game controls feel pressable with chunky shapes, consistent outlines and
  solid offset shadows. Show a pressed state by reducing the shadow and moving the
  control toward it; preserve the visible keyboard focus ring.
- Use drawn vector icons from one coherent set instead of emoji for game controls;
  emoji rendering varies by platform and weakens the shared visual language.

For example, a game can give its board a saturated background, its main action a
contrasting fill and offset shadow, and its score a reward accent while keeping
instructions on a quiet, readable surface. Hierarchy still needs one obvious
primary action. Expressiveness changes styling, not features or product scope.

Other audiences need their own register, not a default framework theme:

- **Professional B2B tools** should stay calm but carry a real identity: a
  distinctive palette with one signature accent, a display face for headings and
  key numerals, and a custom mark. A stock component-library theme with a
  swapped primary color reads as unfinished.
- **Developer-facing products** should look developer-made: a dark theme with
  monospaced type for code, identifiers and most chrome, instead of a light
  clean-SaaS look. Check contrast on the dark surfaces, not just the light ones.
- **Financial and quantitative workbenches** should be information-dense but
  calm: light, warm surfaces and natural colors (sage, cream, meadow green,
  gold) rather than a black terminal look, which tires the eye and reads as
  intimidating. Density comes from compact rows, small type and many figures per
  screen, not from darkness. Use tabular (fixed-width) numerals and right-align
  numeric columns so digits line up, keep decimals consistent per column, and
  reserve color for sign and state (gain/loss, alert) rather than decoration.
  Never rely on red versus green alone: add a sign, arrow or label. Dense must
  still be beautiful and not overwhelming: group with spacing and quiet rules,
  and keep one clear focal figure per panel.
- **Consumer products with a theme** should lean into it: illustrated scenes,
  dividers and textures drawn from the subject, with bold display type, rather
  than a generic dashboard that happens to have the subject's name on it.
- **Ornament** (blobs, squiggles, shapes) is fine when it is designed: one
  consistent shape language and outline weight, cropped by its container,
  asymmetric but balanced, and never placed over text or controls.
- **Cleanup removes noise, not color.** When tidying a playful screen, fix
  alignment, spacing and clutter but keep the large saturated surfaces and
  display type; flattening it to white and cream turns a character into a
  template.
- **Keep an existing logo as shipped** in mockups and redesign targets. A
  restyle changes the surrounding system; replacing the mark is a separate,
  explicit brand decision.

## Step 3 — Tokens first, restyle second

Before changing how any screen looks, introduce **design tokens** — named values
for color, type, spacing, radius, shadow — in one place, and point existing styles
at them. Then restyling becomes editing tokens, not hunting hex codes.

- Web: CSS custom properties on `:root` (works with any framework, including none).
  If the app already uses Tailwind, put the scales in the Tailwind theme instead of
  adding a parallel system.
- Name by role, not by value: `--color-text-muted`, not `--grey-500`; `--space-4`,
  not `--sixteen`.
- Define dark mode by overriding the role tokens under
  `@media (prefers-color-scheme: dark)`, never by restyling components.

A starter token set (CSS custom properties with scales, semantic colors, and a dark
override) is in [TOKENS.md](https://skilld.dev/api/skills-raw/wdm0006/python-skills/ui-design/TOKENS.md). The order of operations for retrofitting an
old app — and how to split it into reviewable PRs — is in
[MODERNIZING.md](https://skilld.dev/api/skills-raw/wdm0006/python-skills/ui-design/MODERNIZING.md).

## Step 4 — Components and states

Build or fix the handful of primitives everything else uses: button (primary,
secondary, ghost, danger), input/select/textarea with label and help text, card,
table, badge, alert, modal, nav. Each needs every state, not just the resting one:
default, hover, focus-visible, active, disabled, loading — plus the screen-level
states (empty, loading, error, success) covered in the
`designing-interaction-states` skill.

A component library (shadcn/ui, Radix, Headless UI, a design-system package) is a
good choice for a new app. For an old server-rendered app, a small set of
hand-written classes on top of tokens is usually lighter than migrating frameworks.

## Step 5 — Verify visually

Re-take the same screenshots after the change, at both widths, and compare side by
side. Check: the hierarchy squint test, nothing overflowing at 390px, focus rings
visible when tabbing, dark mode if supported. Attach the before/after pair to the
PR — reviewers approve design changes by looking, not by reading CSS diffs.

### Consolidating CSS without changing the design

Stacked restyles often leave the same selector defined several times. Editing
the first block can have no visible effect because a later block wins. Before
retinting or consolidating a component, inspect every definition and the winning
declarations in browser DevTools.

- Scan with a CSS parser (such as PostCSS), grouping repeated selectors by their
  enclosing at-rule context. A selector in a dark-mode or narrow-screen media
  query is not a duplicate of its base rule. Repeated rules can also be deliberate;
  preserve cascade order when consolidating declarations.
- For a cleanup intended to preserve appearance, compare base and branch at the
  same viewport, theme, data and UI state. Dump `getComputedStyle(element)` for
  matching elements, plus `::before` and `::after` when their `content` is present.
  This catches a changed winning declaration even when a screenshot looks close.
- Cover light/dark themes and the relevant empty, active, paused and settings
  screens, including hover, focus, disabled and invalid controls. Disable
  animations for the comparison; settling one default screenshot is insufficient.
- Keep screenshots as a layout check, but mask or freeze live clocks and
  countdowns before pixel comparison. A base-versus-base capture reveals which
  differences are nondeterministic rather than caused by the cleanup.

An empty duplicate-selector report proves only structural cleanup. Matching
computed styles across the exercised states and matching layouts provide the
evidence that the cleanup preserved the design.

## App chrome and dense views

The frame around the content is judged as hard as the content itself.

- **Sidebar:** in an app shell, make it a full-bleed rail attached to the left, top and bottom viewport edges, with one background step against the page. A rounded box floating inside a margin wastes width and reads as a widget, not a frame.
- **Footer:** one slim row (about 48px) of minimal text and a few links. Tall multi-column footers belong on marketing pages, not in a product, and even there they should be earned.
- **Dense lists and boards:** single-line titles that truncate with a tooltip, compact rows, small buttons, and horizontal scroll inside a board rather than wrapping cards into tall stacks. Density is a hierarchy choice: keep the one primary action per row visible and demote the rest to a menu.
- **Chrome follows the product's character:** a playful product's header and footer should carry the same outlines, accents and shadows as its content (an outlined floating pill header, a colored or ink footer), not a flat neutral bar that makes the page look like two designs stitched together.
- **Brand marks are inputs, not design targets:** a restyle uses the shipped logo as-is. Rework the layout, color and type around it; never redraw or "refresh" it as a side effect.

## Native apps

On iOS and macOS, follow the platform (Apple's Human Interface Guidelines) rather
than porting web conventions: system fonts and Dynamic Type text styles, semantic
system colors (`.primary`, `.secondary`, `Color(.systemBackground)`), SF Symbols,
standard navigation and list patterns, 44pt minimum touch targets. "Looks like a
good Apple app" beats "looks like our website". The fundamentals above still apply
— hierarchy, spacing rhythm, consistency — expressed through platform styles.

**Cover every platform the product ships on.** When a product runs on desktop and
phone (or Mac and iPhone), a design target, mockup or restyle issue must include
each one. A single-platform mock leaves the other to be improvised in code and
drift from the intended language. Share the tokens and visual identity across
platforms, but design each layout natively: a desktop sidebar and dense table do
not shrink into a phone screen, they become a tab bar or stack and a card list.

## Scoping design work into issues

Design improvements are legitimate, valuable issues — an app that looks abandoned
loses users before they try a feature. Keep each one a single reviewable PR:

- "Introduce design tokens and route existing colors through them" (no visual change)
- "Adopt a type scale; remove the N ad-hoc font sizes"
- "Rebuild the primary/secondary button styles on tokens across all pages"
- "Redesign the dashboard empty state and first-run screen"
- "Make the settings page responsive at phone width"

Each issue names the screens it touches and includes before screenshots; each PR
includes after screenshots. Avoid "redesign the whole app" issues — they never
finish and can't be reviewed.

## Anti-patterns

- Restyling screen by screen without tokens, which recreates the inconsistency.
- Swapping CSS frameworks as a "design fix" — it changes the plumbing, not the design.
- Gradients, shadows and animation added to compensate for weak hierarchy.
- A thick colored stripe down one edge of every card, alert or panel to signal category or state. It is the most recognizable generic-template tell. Keep one uniform border (or none) on every card and carry state with a dot, chip, icon or text label — which also survives for color-blind users.
- The template look: an indigo/purple primary, a grid of identical rounded cards each with a tinted icon tile, pastel tinted chips, window-dot browser mockups, floating badges, and colored or italicized words inside headlines. Each is harmless alone; together they read as generated. Replace them with one identity: a paper-and-ink palette, an editorial serif for headings paired with a neutral sans (keep serifs out of dense tables), monospaced type for data, ruled sections instead of boxed ones, and a single signature highlight accent.
- A design target that covers one platform. If the product ships on desktop and phone (or macOS and iOS), the target and the before/after screenshots cover each.
- Light grey text on white to look "clean" (it fails contrast and reads as disabled).
- Centering everything; long centered paragraphs are hard to read.
- Designing only the happy path at desktop width.
