Systems & Platforms. Make every decision once, then respect the ground you build on.

Warm-up: how systematic is your product today?

Before any theory, a quick diagnostic. You already have a design system. Every product does. The only question is whether it is written down and deliberate, or scattered across a hundred files as accidents. Answer these honestly about the product you are building now (or the last one you shipped).

1. Count your grays. Search your stylesheet or Swift code for color literals. How many distinct grays are there? Teams that have never audited usually find a dozen or more, and nobody chose most of them.
2. Count your button styles. Open five screens. How many different paddings, radii and font weights do your buttons use?
3. Try dark mode. If you flipped to dark mode today, how many files would you have to touch? One, or fifty?
4. Ask the platform question. On your main platform, where does the back action live, where do settings live, and which side of a dialog does the confirm button sit on? If you hesitate, Part five is for you.

A design system is a set of decisions you make once and reuse forever. For a team it is about alignment; for one person it is about speed, consistency and protecting your limited attention from a thousand tiny choices.

Most writing about design systems is written for companies with fifty designers and three hundred engineers. Their problem is coordination: how do you stop twelve teams from inventing twelve date pickers? You do not have that problem. You have a different one, and it is just as real: every time you build a screen, you face dozens of micro-decisions. How much padding here? Which gray for this caption? Is this button 36 or 40 pixels tall? Should the error be red text or a red border? Each decision costs a little attention, and attention is the scarcest thing a solo creator has.

Worse, you make each decision slightly differently each time, because you made the last one three weeks ago and do not remember. The result is drift: four grays that are nearly the same, buttons that are 38, 40 and 42 pixels tall, and dialogs that put the confirm button on different sides. No single screen looks wrong. Together they make the product feel subtly cheap, the way a room feels off when the picture frames are hung at slightly different heights. People rarely name it, but they feel it, and it lowers their trust.

Three things a system buys you

Consistency. When the same thing always looks and behaves the same way, people learn it once. A red text link that deletes in one place and a red filled button that deletes in another make people re-learn. Consistency is a usability feature first and an aesthetic one second (it is one of Jakob Nielsen's ten usability heuristics: "consistency and standards").

Speed. Once you have a Button, a TextField, a Sheet and a ListRow that you trust, a new screen is assembly, not design. Many solo creators report that their second year of building is several times faster than the first for exactly this reason.

Fewer decisions. Decision fatigue is real enough at the end of a long building day. A system turns "what padding?" into "space-4", which is not a decision at all. You will make better product decisions with the attention you save.

The minimum viable system

The danger for a solo creator is the opposite of the team's: building a system for its own sake. A beautiful Figma library with 140 components and seven documentation pages is a hobby, not a tool, if your product has nine screens. The minimum you need is small and fits on a page or two of code:

1. Tokens. Named values for color, type, spacing, radius, shadow and motion. Perhaps 40 to 80 of them. Part two is about these.
2. About a dozen components. Button, icon button, text field, select or picker, checkbox and switch, list row, card or section, sheet or dialog, menu, toast, empty state, navigation bar. That covers most of the screens of most small products.
3. A handful of patterns. How you do forms, confirmation, undo, errors, loading, empty states and search. A pattern is a recipe made of components; see Structure & Interaction for the patterns themselves.
4. Voice. Ten rules for how your product speaks: sentence case, verbs on buttons, no blame in errors. Covered in Words.

A design system isn't a project. It's a product, serving products.Nathan Curtis, title of an essay on EightShapes' Medium publication, 2016

Curtis wrote that for organizations, but it lands differently for you. Your system is a product whose only customer is you, six months from now, tired, at 11 pm, trying to add a feature quickly. Design it for that person: obvious names, few options, no cleverness.

In the wild

• NYC Transit Authority Graphics Standards ManualUnimark (Vignelli, Noorda), 1970
  A ring binder that specified every sign in the subway: typeface, arrow shapes, color discs for lines, module sizes. Decades before software, it is a design system in the full sense: a few rules, applied relentlessly. A system is decisions plus documentation. The medium does not matter.
• iA WriterInformation Architects, 2010–today
  Very few typefaces, one accent color, a tightly limited set of controls across Mac, iOS, Windows and Android. The product feels like one object on every device. A small system, held tightly, is a brand.
• LinearLinear, 2019–today
  The interface is extremely consistent: the same command menu, list rows, status icons and keyboard grammar everywhere. The consistency is a big part of why it feels fast. Consistency is perceived as quality and as speed.

Atomic design is a mental model: interfaces are made of small parts that combine into larger ones. It is a superb way to think about reuse, and a poor filing system if you take the chemistry literally.

In 2013 Brad Frost published a blog post, and in 2016 a book, both called Atomic Design. Borrowing from chemistry, he described five stages. Atoms are the smallest useful parts: a label, an input, a button, a color. Molecules are small groups that do one job together: a search form made of a label, an input and a button. Organisms are larger sections made of molecules: a header containing a logo, navigation and the search form. Templates place organisms into a page layout with placeholder content, showing the structure. Pages are templates filled with real content, which is where you discover whether the system actually holds up when a title is 80 characters long or a list is empty.

What atomic design gets right

The model's lasting gift is a habit of mind: look at any screen and see it as parts and wholes at the same time. When you design a settings screen, you are also designing a list row, a switch and a section header that every future screen will use. Frost was clear that the stages are not a step-by-step process:

Atomic design is not a linear process, but rather a mental model to help us think of our user interfaces as both a cohesive whole and a collection of parts at the same time.Brad Frost, Atomic Design, chapter 2, 2016

The second gift is the page stage. Many systems stop at components and never stress-test them with real, ugly content. The page stage says: put the 80-character title, the user with no avatar, the list with 2,000 items and the list with zero items into the layout, and see what breaks.

Where it breaks

Practitioners have criticized the literal taxonomy for years, and the criticisms are worth knowing because you will feel them yourself:

• The boundaries are arbitrary. Is a card a molecule or an organism? Is a list row with an avatar, two labels and a switch a molecule? Teams lose hours to these debates, and the answer never changes what anyone builds.
• The chemistry names mean nothing to anyone else. "Organism" does not tell future-you where the date picker lives. "Forms", "Navigation" and "Feedback" do.
• Real systems are graphs, not ladders. A button appears inside a dialog, a toolbar, a card and a form. A dialog can contain a form that contains a list. Parts compose in every direction.
• It says nothing about behavior. States, keyboard handling, accessibility and motion are where most component work actually goes, and the atomic model is silent about them.

What to keep, what to drop

Keep the habit of thinking in parts and wholes, and keep the page stage as your stress test. Drop the five folders. Organize your components by job, the way most published systems now do: Actions (button, icon button, link), Inputs (field, select, checkbox, switch), Feedback (toast, banner, progress, empty state), Navigation (tab bar, sidebar, breadcrumb), Containers (card, sheet, dialog, popover). Future-you will look for "the thing that shows a message after save" under Feedback, never under Molecules.

In the wild

• Pattern LabBrad Frost and Dave Olsen, 2013
  An open-source tool built to make atomic design concrete: you build atoms, molecules and organisms as templates and see them assembled into pages with real data. The page stage needs tooling that renders real content, not just a gallery.
• Storybookopen source, 2016–today
  The most common way web teams view components in isolation, one "story" per state. It is organized by whatever folders you choose, and most teams choose purpose-based ones. Isolation is good for building; real pages are still needed for testing.
• GOV.UK Design SystemGovernment Digital Service, 2018–today
  Splits the library into Styles, Components and Patterns, with patterns named after user tasks ("Ask users for addresses", "Check answers"). Name things by the job people come to do.

Large companies publish their systems for free. Each one has solved a problem you will meet. Study them for their reasoning, not their visuals, and steal one idea from each.

Reading a mature design system is like reading the code of a well-run open-source project: you see thousands of hours of decisions, and the documentation often explains why. You do not need to adopt any of them. You need to know which one has thought hardest about the thing you are stuck on. Here is how they differ, and the one idea most worth taking from each.

How to read a system in one hour

1. Read the principles page, then ignore it. Every system has one; they are mostly similar. Note any principle that forces a trade-off (GOV.UK's "do less" is a real constraint; "be delightful" is not).
2. Open the button page. It shows you their whole approach in miniature: hierarchy, states, sizes, content rules and accessibility notes.
3. Open the color or token page. How many layers? How are tokens named? How do they theme?
4. Find one pattern you need now (confirmation, empty state, form validation) and read it closely, including the "don't" examples.
5. Write down one idea to steal and one thing you would deliberately not copy.

In the wild

• GOV.UK "Start now" buttonGOV.UK Design System
  The start button is documented as its own variant, with an arrow, meant only for the beginning of a service. It is not a general "big button". A variant should exist for one clearly described job, or it should not exist.
• Material dynamic colorAndroid 12, 2021
  Material You derives a full color scheme from the user's wallpaper. It only works because every component asks for a role ("primary container") rather than a color ("blue 200"). Semantic tokens make radical theming possible.
• shadcn/ui2023
  Became very popular quickly by inverting the usual model: you run a command that copies the component's source into your repository. Updates are yours to merge. For a soloist, owning the code can beat depending on a package.

A design token is a named design decision. The power comes from layering: primitives say what values exist, semantic tokens say what each value is for, and component tokens say where it is used. Code only ever reads the upper layers.

The term "design tokens" was popularized at Salesforce around 2014, where Jina Anne and Jon Levine used it for the named values that fed the Lightning Design System across web and native platforms. The idea is older than the name: any time you wrote $brand-blue in Sass you were using a token. What changed is the discipline around them, and that discipline is mostly about layers.

Layer 1: primitives (also called global, base or core tokens)

Primitives are your palette and your scales: every gray, every hue step, every spacing step, every font size. Names describe the value, not the use: gray-600, blue-500, space-4, radius-2. They are the paint on your palette. Nothing in your interface should reference them directly, because the moment a screen says "gray-600" it has made a decision that a theme cannot change.

Layer 2: semantic tokens (alias or system tokens)

Semantic tokens name a purpose: color-text, color-text-secondary, color-bg, color-surface, color-border, color-accent, color-danger, space-inset-card, radius-control. Each points to a primitive. This is the layer your product mostly reads, and the layer that changes between themes: in light mode color-text points to gray-900; in dark mode it points to gray-50. Not a single component changes.

Layer 3: component tokens (optional for you)

Component tokens name a specific slot in a specific component: button-primary-bg, field-border-focus. Large systems need them so that one team can tweak the button without touching everything that uses color-accent. A solo creator usually does not. Add a component token only when a component genuinely needs to differ from the semantic default, for example when your primary button uses a slightly darker accent than links for contrast. Otherwise, components read semantic tokens directly and you have two layers, which is plenty.

/* tokens.css: the whole idea in 20 lines */
:root {
  /* 1 · primitives: values, named by what they are */
  --gray-900: #1C1D1F;  --gray-600: #5F6267;
  --gray-200: #D6D6D2;  --gray-50:  #F1F1EF;
  --amber-500: #E9A800; --red-600: #B03D2B;
  --space-2: 8px; --space-3: 12px; --space-4: 16px;

  /* 2 · semantic: purposes, named by what they are for */
  --color-text:           var(--gray-900);
  --color-text-secondary: var(--gray-600);
  --color-bg:             var(--gray-50);
  --color-border:         var(--gray-200);
  --color-accent:         var(--amber-500);
  --color-danger:         var(--red-600);
  --space-inset-card:     var(--space-4);

  /* 3 · component: only where a component must differ */
  --button-primary-bg:    var(--color-text);
  --button-primary-label: var(--color-bg);
}

Naming: the part that lasts

Values change; names stay for years, and every rename touches every file. Nathan Curtis's essay "Naming Tokens in Design Systems" (EightShapes, 2020) breaks a token name into ordered parts. Simplified for a one-person system, a name reads from general to specific:

--blue
--blue-dark-2
--gray-text
--big-padding
--header-color-new
--modal-bg-FINAL
--color-red-for-errors

--blue-500          /* primitive */
--gray-600          /* primitive */
--space-6           /* primitive */
--color-accent      /* semantic */
--color-text-secondary
--color-danger
--space-inset-dialog

A format you can share between platforms

If you ship on more than one platform, keep tokens in one neutral file (usually JSON) and generate CSS variables, Swift constants and Android resources from it. The W3C Design Tokens Community Group has worked for several years on a standard JSON format for exactly this, and tools such as Style Dictionary (originally from Amazon) transform one token file into each platform's format. Chapter 11 shows the pipeline. If you ship on one platform, skip the JSON: a single tokens.css or Tokens.swift is your source of truth.

In the wild

• Apple semantic colorsUIKit / SwiftUI, iOS 13, 2019
  With dark mode, Apple asked developers to use colors like label, secondaryLabel and systemBackground instead of fixed colors. These are semantic tokens that resolve differently in light, dark and increased-contrast settings. The platform itself works in semantic tokens; your custom colors should too.
• Material 3 color rolesGoogle, 2021
  Roles such as primary, onPrimary, primaryContainer, onPrimaryContainer, surface and onSurface. The "on" pairing guarantees a readable foreground for every background. Name tokens in pairs: a surface and the content that sits on it.
• Primer primitivesGitHub
  GitHub publishes base scales separately from functional tokens such as foreground, background and border variants, which components consume. Even very large systems keep the same two core layers.

Primitives are not a bag of values; they are scales. A scale with a clear rule (each step twice the last, or a fixed ratio) makes good choices easy and bad ones impossible.

Ask someone to choose "the right padding" and they will deliberate. Give them a scale of eight steps and they will pick in a second, and their picks will relate to each other visually. That is the whole trick. Scales turn a continuous space of options into a small menu where every item looks good next to every other item.

Spacing: a 4-point base

Most modern systems use a base unit of 4 or 8 points. Both divide evenly into common screen densities (1×, 2×, 3×), so edges land on whole pixels. A 4-point base with steps that grow faster as they get bigger works for almost everything: small steps for tight relationships inside a control, large steps for separating sections. The jump between steps should be visible; if you cannot see the difference between two steps, you have one too many.

Type: a modular scale, few steps

Font sizes are a scale too. A ratio of about 1.2 (a "minor third") to 1.25 (a "major third") gives sizes that feel related: 13, 15, 17, 20, 24, 30. Most products need five or six text styles, each a token bundling size, line height, weight and letter spacing: text-caption, text-body, text-body-strong, text-title, text-headline, text-display. On Apple platforms, use the built-in text styles (.body, .headline, .title2…) as your tokens, because they scale with Dynamic Type for free. The details of choosing the scale are in Typography.

Radius: few values, and the nesting rule

Three or four radii are enough: radius-small (about 4) for chips and small controls, radius-control (about 8) for buttons and fields, radius-container (about 12 to 16) for cards and sheets, and radius-full for pills and avatars. When one rounded shape sits inside another, the inner radius should equal the outer radius minus the padding between them. Otherwise the gap between the curves is uneven, and the corners look pinched.

Shadow and elevation: two or three levels

Shadows say "this is above that". A product needs very few heights: flat (most things), raised (cards, if you use shadows at all), overlay (menus, popovers) and modal (dialogs, sheets). Make each a token bundling offset, blur and opacity. In dark mode shadows almost disappear against dark backgrounds, so dark themes usually express elevation by making higher surfaces slightly lighter instead. That is one reason color-surface-raised is a separate semantic token.

Motion: durations and curves

Motion gets tokens too: three or four durations (for example duration-fast about 120 ms for hovers and toggles, duration-base about 200 to 250 ms for most transitions, duration-slow about 350 to 400 ms for large surfaces like sheets) and two or three easing curves (standard, enter, exit). Tokenizing motion also gives you one place to honor reduced-motion settings. The craft of timing is in Motion & Feel.

In the wild

• Material spacingGoogle
  Material layouts are built on a 4 dp base and 8 dp grid for components and layout, so elements align across apps. A shared base unit makes unrelated screens feel like one product.
• Apple text stylesiOS 7, 2013–today
  Large Title, Title 1–3, Headline, Body, Callout, Subheadline, Footnote, Caption 1–2. Eleven tokens that every app shares and that resize together with the user's text-size setting. Type tokens are an accessibility feature.
• Tailwind CSS spacingTailwind Labs
  Classes like p-4 and gap-6 map to a 0.25 rem step scale, so a whole team picks from the same menu. A scale with a short name is easier to obey than a free number.

A theme is a different mapping from semantic tokens to primitives. If your components only read semantic tokens, a new theme is a new mapping table, and nothing else in the product changes.

Dark mode used to be a rewrite. With semantic tokens it is an afternoon, and most of that afternoon is judgment, not plumbing. The plumbing is simple: the same names, different arrows.

Dark mode is not inversion

Inverting light mode produces glaring white text on pure black, accents that vibrate, and shadows that vanish. A good dark theme follows a few rules that come up again and again in platform guidelines:

• Dark gray, not black, for most surfaces. Very dark gray lets you show elevation with lighter surfaces and reduces the halo around bright text. (Pure black can be right for OLED-focused media apps, but it is a choice, not a default.)
• Off-white text, and less contrast for secondary text than you think. Body text around 87 to 92% white is common.
• Desaturate and lighten accents. Saturated colors on dark backgrounds vibrate; a lighter, slightly less saturated accent reads as the same brand.
• Elevation by lightness. Raised surfaces get a lighter gray rather than a stronger shadow.
• Check every pair again. Contrast ratios change; WCAG asks for at least 4.5:1 for body text and 3:1 for large text and UI component boundaries. See Accessible & Inclusive.

(These two mockups use your course theme's colors, so in dark mode they flip too. Look at the structure, not the absolute colors.)

High contrast and forced colors

Operating systems let people ask for more contrast: "Increase Contrast" on Apple platforms, contrast themes on Windows, and on the web the media queries prefers-contrast: more and forced-colors: active. Apple's semantic system colors already include higher-contrast variants. For your custom tokens, a high-contrast mapping typically pushes secondary text toward primary text, makes borders darker and thicker, removes translucent tints, and never relies on color alone for state. Under Windows forced colors, the browser replaces your colors with the user's palette entirely, so borders and outlines (not background tints) must carry structure.

:root { --color-text: var(--gray-900); --color-bg: var(--gray-50); }

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-text: var(--gray-50); --color-bg: var(--gray-950);
  }
}
:root[data-theme="dark"] { /* same mapping, for a manual toggle */ }

@media (prefers-contrast: more) {
  :root { --color-text-secondary: var(--color-text);
          --border-width: 2px; }
}

// In the asset catalog, give each color set
// "Any", "Dark" and "High Contrast" appearances.
extension Color {
  static let textSecondary = Color("TextSecondary")
  static let surfaceRaised = Color("SurfaceRaised")
}
// Prefer system semantic colors where they fit:
Text(note.title).foregroundStyle(.primary)
Text(note.date).foregroundStyle(.secondary)

// Jetpack Compose with Material 3
val scheme = when {
  dynamic && Build.VERSION.SDK_INT >= 31 ->
    if (dark) dynamicDarkColorScheme(ctx) else dynamicLightColorScheme(ctx)
  dark -> DarkColors
  else -> LightColors
}
MaterialTheme(colorScheme = scheme) { App() }
// Components read roles: MaterialTheme.colorScheme.onSurfaceVariant

In the wild

• macOS dark modemacOS Mojave, 2018
  Apple introduced system-wide dark mode on the Mac and asked apps to use semantic and dynamic colors. Apps built on hard-coded colors looked broken in dark mode until their developers updated them. The platform changes under you; semantic tokens make you ready.
• Kindle and iA Writer reading themesAmazon; Information Architects
  Reading apps commonly offer light, sepia and dark (and sometimes a dimmer "night") as first-class themes, because reading comfort varies with ambient light. Themes are a feature when they serve the core activity.
• Linear's theme generationLinear, 2024 redesign
  Linear has described generating its themes from a few inputs (a base color, an accent and a contrast level) rather than hand-picking every value. With semantic tokens, a theme can be computed, not drawn.

Every component has named parts (its anatomy) and a small set of choices (its API). Design the API like a function signature: few parameters, clear names, no impossible combinations.

When you design a component you are designing two things at once. The first is what people see: a container, a label, maybe an icon and a focus ring. The second is what future-you sees: the options you can pass when you use it. The second is easier to get wrong, and harder to fix later, because every screen that uses the component depends on it.

Anatomy: name the parts

Draw the component and label every part. This sounds pedantic until you need to say "the leading icon in the text field gets the secondary text color, except in the error state". Named parts make specifications, tokens and bug reports precise.

Variants versus props

Figma calls them variants and properties; code calls them props, parameters or modifiers. Either way, a component's options come in two kinds:

• Variants change what the component is: a primary versus a secondary versus a destructive button. Different jobs, different appearance. Keep them few and named by purpose.
• Props configure an instance without changing its identity: the label text, an optional icon, the size, whether it is full-width, whether it is loading.

The trap is multiplying them. Four kinds × three sizes × seven states × with-or-without icon = 168 combinations. In Figma, teams sometimes draw all 168 as variants. In code, nobody draws them; they fall out of the logic. That is one of the strongest arguments for designing components in code as a solo creator (more in Chapter 11): code handles combinations by composition, while a drawing tool needs each one drawn.

Rules for a good component API

1. Few options, named by purpose. kind: .destructive, not color: .red. A purpose can be restyled; a color is a promise you cannot keep.
2. Make impossible states impossible. If a button cannot be both loading and disabled-with-reason, use one state enum instead of two booleans.
3. Sensible defaults. The most common use should need the fewest arguments: Button("Save").
4. Content is a prop, not a variant. "Button with icon" is not a different component; the icon is optional content.
5. No escape hatches for style. A customColor prop is the start of drift. If you need a new look, add a new purpose-named kind.

Composition over configuration

When a component grows its fifteenth prop, it is usually trying to be several components. A Card with props for header, subtitle, image, badge, two buttons, a menu and a footer is a monster nobody can predict. Prefer small pieces that nest: Card contains a CardHeader, any content, and an optional CardActions that contains Buttons. SwiftUI and React both reward this style: views made of views.

<Card title subtitle image
  imagePosition badge badgeColor
  primaryAction primaryLabel
  secondaryAction secondaryLabel
  showMenu menuItems footer
  footerAlign compact elevated
  customPadding customColor />

<Card>
  <Card.Header title subtitle />
  <ArticlePreview article />
  <Card.Actions>
    <Button kind="secondary">Later</Button>
    <Button>Read</Button>
  </Card.Actions>
</Card>

Sizes

Most components need at most three sizes, and many need one. A common set: small for dense toolbars and tables (desktop only, pointer input), regular for almost everything, large for one primary action on a mobile screen or a landing page. Remember that on touch screens the hit area must stay at least 44 × 44 points (Apple) or 48 × 48 dp (Material) even when the visible control is smaller. Size is a prop, and the hit area is a rule the component enforces on its own.

In the wild

• SwiftUI Button and ButtonStyleApple, 2019–today
  A Button holds an action and a label; how it looks is a separate ButtonStyle you apply, and roles like .destructive and .cancel describe purpose. Separate what a component does from how it looks.
• Radix DialogWorkOS, Radix Primitives
  A dialog is built from parts: Root, Trigger, Portal, Overlay, Content, Title, Description, Close. You compose exactly what you need. Composition makes complex components flexible without props soup.
• Figma component propertiesFigma, 2022
  Figma added boolean, text and instance-swap properties alongside variants, largely to stop teams from drawing every combination. Even the drawing tool moved toward props.

A component is not finished until every state is designed: default, hover, focus, pressed, disabled, loading and error, in every variant. Missing states are where products feel broken.

Designers draw the default state, because that is what appears in mockups. Users live in all the others. They hover with a mouse before clicking, tab with a keyboard, press and hold on a phone, wait while something loads, and hit errors. Each of those moments needs a deliberate answer, and the answer should be the same everywhere in your product.

Default (rest)

The component waiting for input. Everything else is a change from this.

Hover

A pointer is over it. Pointer devices only; touch screens have no hover, so hover must never be the only way to discover something.

Focus

It will receive keyboard input. Must be clearly visible: WCAG 2.2 adds requirements for visible focus that is not hidden by other content. Show the ring for keyboard focus (:focus-visible), not necessarily for mouse clicks.

Pressed (active)

Being clicked or touched right now. On touch screens this is the main feedback that a tap registered, so it must appear within about 100 ms.

Disabled

Exists but cannot be used now. Lower contrast is allowed (WCAG exempts inactive controls from contrast rules), but people should be able to find out why.

Loading

The action is in progress. Keep the component's size, show progress, prevent double submission.

Error

Something is wrong with this component's value or action. Use more than color: an icon, a message, a thicker border.

Rules that make states consistent

• One recipe per state across components. Hover always mixes about 10 to 20% of the text color into the background. Focus is always the same 2 px ring in color-focus with a 2 px offset. Pressed always darkens a little more than hover.
• State never changes size. A loading button keeps its width; an error field does not jump down the page. Layout shifts during interaction feel broken and make people misclick.
• Never color alone. Error adds an icon and a message; selected adds a checkmark or weight change. This is required for people with color vision deficiencies and helpful for everyone.
• Disabled is a last resort. A disabled button tells people "no" but not "why". Often it is better to keep the button enabled and explain on press what is missing (see the next chapter).
• Focus order follows reading order. The state matrix says how focus looks; your layout decides where it goes next.

In the wild

• GOV.UK focus stateGOV.UK Design System
  A very visible yellow focus highlight with a thick black underline or outline, used consistently across links, buttons and inputs. Focus can be bold and on-brand at the same time.
• Material state layersMaterial 3
  Hover, focus, pressed and dragged are shown by an overlay of the content color at fixed opacities over the container. One recipe, every component. Encode a state as a formula, not a list of colors.
• iOS button highlightApple
  System buttons dim or highlight immediately on touch-down and restore on release or drag-off. There is no hover on iPhone, so pressed feedback carries everything. On touch, the pressed state is your only chance to say "got it".

The button is the smallest complete design problem in software: hierarchy, size, label, states, placement and accessibility in one rectangle. Get it right and the rest of your system inherits the care.

Hierarchy: one primary per view

Buttons come in a ladder of emphasis. The primary button is the action most people want next, filled with your strongest color. There should be at most one per view (a screen, a dialog, a section of a long page). Secondary buttons are alternatives: outlined or tinted. Tertiary or quiet buttons are text-only, for low-stakes options like "Skip" or "Learn more". Destructive is not a level of emphasis but a purpose: it uses the danger color, and is usually not primary, because the most likely action should rarely be destroying something.

Size and hit area

Visible size and touchable size are different numbers. Apple's guidance is a minimum hit target of 44 × 44 points; Material's is 48 × 48 dp. WCAG 2.2's minimum target size criterion (2.5.8, level AA) asks for 24 × 24 CSS pixels or enough spacing around smaller targets. On desktop with a mouse, a compact 28 to 32 px button is fine in toolbars; on touch, use 44 or more. A small icon button can have a visually small glyph inside an invisible, larger hit area.

Labels: verbs that predict the result

A button label should say what will happen, as a verb, in sentence case: "Save note", "Send invite", "Delete 3 photos". Avoid "OK", "Yes", "Submit" and "Confirm", which make people re-read the question to know what they are agreeing to. In a dialog, the confirming button repeats the verb from the title: "Delete draft?" → "Delete". Polaris and GOV.UK both document this; the full craft is in Words.

Loading without jumping

Placement

Where buttons go is a platform convention more than a personal choice (Part five covers this in detail). Some rules hold everywhere: put the primary action where the eye ends its journey through the content (usually the bottom or bottom-right of a form or dialog); keep the destructive action away from the most-pressed spot; on phones, consider a full-width primary button within thumb reach at the bottom of a long form; and keep button order identical across your whole product.

In the wild

• Stripe CheckoutStripe
  The pay button states the amount ("Pay ₹2,499" or "Pay $20.00") rather than "Submit". The label predicts the exact consequence. The best label is a promise people can check.
• GitHub "Danger zone"GitHub repository settings
  Destructive repository actions sit in a separate, red-bordered section at the bottom of settings, and deleting asks you to type the repository's name. Distance and friction should scale with the damage.
• iOS action sheetsApple
  Destructive options appear in red, and Cancel sits apart at the bottom of the sheet. Color and position together mark danger and escape.

Components are nouns; patterns are sentences made of them. Document both briefly, in the codebase, for the one reader who matters: you, months from now, having forgotten why.

From components to patterns

A pattern is a recurring solution to a user task, assembled from components: "confirm a destructive action" uses a dialog, a title, a body, a destructive button and a cancel button, plus rules about when to use a dialog versus an undo toast. Your product needs a handful of these, and you will reuse them on every new feature. The patterns themselves (forms, validation, empty states, lists, search, undo, onboarding) are taught in Structure & Interaction. Here the point is simpler: write down your version of each, once.

The one-page component doc

Big systems have long documentation sites. You need one page per component, ideally a comment block at the top of the component file or a Markdown file beside it, so it is updated in the same commit as the code. Every page answers the same questions in the same order:

/**
 * Button
 * Purpose: triggers an action in place. Use Link to navigate.
 * Use when: one clear action. Don't: toggles (use Switch), navigation (use Link).
 * API: kind = primary | secondary | quiet | destructive (default primary)
 *      size = small (desktop toolbars only) | regular | large
 *      icon? leading icon; label required even when visually hidden
 *      state = idle | loading  (disabled only with a visible reason)
 * Content: verb first, sentence case, ≤ 3 words ("Save note").
 * A11y: hit area ≥ 44pt; Enter/Space; icon-only needs a label.
 * Decisions:
 *   2026-03 dropped "outline" kind: testers read it as disabled.
 *   2026-07 loading keeps width (layout shift caused misclicks).
 */

In the wild

• GOV.UK component pagesGOV.UK Design System
  Each component page has "When to use", "When not to use", "How it works", and a section on research findings and known issues. "When not to use" and recorded research are what make a system trustworthy.
• Architecture decision recordsSoftware practice, from Michael Nygard's 2011 post
  Engineers record decisions as short dated documents with context, decision and consequences. The same format works for design decisions. A decision without a reason will be relitigated.

A solo creator should keep one source of truth, and it should usually be code. Use a drawing tool to explore, then promote what you decide into tokens and components in code, where it can no longer drift.

This is not an argument against Figma or sketching. Drawing tools are faster than code for divergent thinking: trying ten layouts in ten minutes, laying screens side by side, making a flow you can see at once. Code is better for convergent work: real data, real states, real text sizes, real devices, and above all, a system that is impossible to violate because the product is built from it. The question is not which tool, but where each decision finally lives.

The concepts map one to one

The good news is that modern drawing tools have converged on the same model as CSS and SwiftUI. If you learn the concepts once, you can move between them without translation loss.

Your system in each stack

/* tokens.css is the system; components read only semantic tokens */
.button {
  min-height: 44px;
  padding: 0 var(--space-4);
  border-radius: var(--radius-control);
  font: 600 var(--text-body-size)/1 var(--font-ui);
  background: var(--button-primary-bg);
  color: var(--button-primary-label);
  transition: background-color var(--duration-fast) var(--ease-standard);
}
.button:hover  { background: color-mix(in srgb, var(--button-primary-bg) 85%, var(--color-bg)); }
.button:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }

/* app.css: Tailwind v4 reads design tokens from @theme */
@import "tailwindcss";
@theme {
  --color-ink: #1C1D1F;
  --color-paper: #F1F1EF;
  --color-accent: #E9A800;
  --radius-control: 0.5rem;
  --spacing: 0.25rem;      /* the base of the spacing scale */
}
/* Now classes like bg-accent, text-ink, rounded-control exist,
   and every token is also a CSS variable at runtime. */

enum Space { static let s2: CGFloat = 8; static let s3: CGFloat = 12; static let s4: CGFloat = 16 }
enum Radius { static let control: CGFloat = 10 }

struct PrimaryButtonStyle: ButtonStyle {
  func makeBody(configuration: Configuration) -> some View {
    configuration.label
      .font(.body.weight(.semibold))
      .padding(.horizontal, Space.s4)
      .frame(minHeight: 44)
      .background(Color.accent.opacity(configuration.isPressed ? 0.8 : 1))
      .foregroundStyle(Color.onAccent)
      .clipShape(RoundedRectangle(cornerRadius: Radius.control))
  }
}
// A ViewModifier packages a recurring look:
struct CardSurface: ViewModifier {
  func body(content: Content) -> some View {
    content.padding(Space.s4)
      .background(Color.surfaceRaised, in: .rect(cornerRadius: Radius.control + Space.s2))
  }
}
extension View { func cardSurface() -> some View { modifier(CardSurface()) } }

One source of truth across platforms

If you ship to more than one platform, put tokens in one neutral file and generate the rest. Tools like Style Dictionary read a token JSON file and output CSS variables, Swift, Kotlin or XML resources. Figma can import variables too, either through plugins or its API, so even your design file becomes an output. The arrow always points one way: from the token file outward.

A workflow that works for one person

1. Sketch to diverge. Paper or Figma, fast and ugly, using your real tokens if your tool has them. Ten options, not one.
2. Pick one, build it in code. Use existing components only. If something new is needed, write it as a local, unstyled piece first.
3. Review on the device. Real data, both themes, largest text size, keyboard, touch.
4. Promote. If the new piece appears a second or third time, move it into the system: tokens, component, doc block.
5. Regenerate the design file only if you still use one for exploration.

In the wild

• SwiftUI previews and Xcode canvasApple, 2019–today
  Live previews render views in multiple configurations (dark mode, large text, devices) next to the code. For Apple platforms, the code editor is now a reasonable design tool. Design where the states are real.
• Figma Dev Mode and variablesFigma, 2023
  Figma added variables with modes and a developer-focused inspection mode, explicitly to close the gap between design files and code. The industry is converging on tokens as the shared language.
• Style Dictionaryoriginally Amazon, open source
  A widely used build tool that turns one token source into platform files. The pipeline is solved; you only need to choose to use it.

People spend most of their time in other products, so they expect yours to work like those. Every convention you follow is something they already know; every convention you break is something they must learn.

Users spend most of their time on other sites.Jakob Nielsen, on what is now called Jakob's Law of the Internet User Experience, 2000

Nielsen was writing about websites, but the idea generalizes to every platform. Jon Yablonski's Laws of UX made it widely known as "Jakob's law": users prefer your product to work the same way as all the others they already know. Your app is one of perhaps eighty on someone's phone. Their thumb has learned where back is, what a swipe does and which side of a dialog confirms, from all the others. Norman's term for this is a conceptual model people bring with them; conventions are shared conceptual models.

What counts as a convention

A convention is any behavior people predict without being told: tapping a back chevron goes back; ⌘Z undoes; a red button destroys; a blue underlined phrase on the web is a link; swiping left on an iPhone list row reveals actions; settings on a Mac live under the app menu. Conventions live at every level: gestures, shortcuts, placement, iconography, words ("Settings" on most current platforms; older macOS used "Preferences" until 2022), and timing.

When to break one

Break a convention only when all three are true: the convention measurably hurts your core task, your alternative is clearly better for that task, and you can teach the new behavior in the moment it is needed. Loren Brichter's pull-to-refresh in Tweetie 2 (2009) is the classic case of a broken convention that became one; it is famous precisely because such successes are rare. For everything outside your core innovation, be boring. Spend your novelty budget where it matters.

The conventions table

Here are the conventions that most often trip up people who build for several platforms. Treat it as a starting checklist and verify details in each platform's current guidelines; they change across releases.

In the wild

• Tweetie pull-to-refreshLoren Brichter, Tweetie 2, 2009
  A new gesture for a core, repeated task, discoverable because the list visibly stretched. It became a convention across platforms. Break a convention only where you can do dramatically better, and make the new behavior self-explaining.
• macOS Settings renamemacOS Ventura, 2022
  When System Preferences became System Settings, well-behaved Mac apps renamed their own "Preferences…" menu item to "Settings…". Following conventions includes following their changes.
• Electron apps on the Macvarious
  Cross-platform desktop apps are often criticized by Mac users when they ignore the menu bar, standard shortcuts or native text behavior, and praised when they respect them. Users judge you by the platform's standard, not your framework's limits.

iPhone design is built on a few strong structures: navigation stacks you can swipe back through, a tab bar for top-level places, sheets for focused tasks, and text and symbols that scale with the user's settings. Learn these and most screens design themselves.

The essentials, briefly

Navigation bar and large titles

The top bar shows where you are and holds the back button and a few actions. Large titles that collapse as you scroll work well for top-level screens; detail screens usually use inline titles.

Tab bar

Top-level destinations at the bottom, always visible on iPhone. Each tab remembers its own navigation stack. Do not hide the tab bar on drill-down unless the task is immersive.

Sheets and full-screen covers

Sheets present a focused task (compose, edit, filter) with Cancel and Done; detents let a sheet sit at medium height. Full-screen covers are for immersive tasks (a camera, a reader).

Swipe back

A left-edge swipe pops the stack, interactively. People use it constantly; breaking it makes an app feel cheap.

SF Symbols

Apple's icon set of thousands of symbols, designed to align with San Francisco text and to scale and change weight with it. Using them keeps icons consistent with the system and with Dynamic Type.

Dynamic Type

People choose their text size, from smaller than the default (17 pt body) up to accessibility sizes around three times larger. Use text styles, let layouts reflow (stack horizontally arranged items vertically at large sizes), and test at the largest size.

Swipe actions and context menus

Rows can reveal actions on swipe; long-press shows a context menu with a preview. Both are shortcuts, so the same actions must also be reachable another way.

Haptics

System controls give subtle haptic feedback (toggles, pickers). Add your own sparingly, for confirmations that matter (see Motion & Feel).

iPadOS: not a big iPhone

On iPad, the tab bar often becomes a sidebar, and split views show a list and its detail side by side (the classic master–detail layout). People use iPads with keyboards, trackpads and Apple Pencil, so hover effects, keyboard shortcuts and drag and drop matter. Apps also run in resizable windows next to other apps, so your layout must adapt to many widths, not just "iPad portrait" and "iPad landscape" (Chapter 18). Recent iPadOS versions moved further toward Mac-like windowing and added a menu bar, which makes the Mac conventions in the next chapter increasingly relevant on iPad too.

In the wild

• Apple Notes and MailApple
  Navigation stacks on iPhone, a split view with sidebar on iPad and Mac, swipe actions on rows, sheets for compose. Study the system's own apps first; they define the conventions.
• Things 3Cultured Code, 2017
  A highly distinctive iPhone app (the "Magic Plus" button you drag to insert a task) that still respects the stack, swipe back, Dynamic Type and system share sheets. Innovate in your core interaction; follow the platform everywhere else.
• HalideLux, 2017–today
  A camera app with a custom, gesture-rich interface that is immersive by necessity, yet uses system conventions for settings and the photo library. Immersive tasks earn custom UI; administrative tasks do not.

A Mac app is a keyboard-and-pointer tool that lives in windows, with every command in the menu bar. "Native feel" is not a look; it is dozens of small behaviors people expect without thinking.

Mac users are famously particular. They notice when ⌘, does not open settings, when a text field does not support the standard emacs-style shortcuts, when a window does not remember its size, or when the menu bar is empty. Each is small. Together they decide whether your app feels like a guest or a resident.

The behaviors that make it feel native

1. A complete menu bar. Every command your app has should appear in a menu, with its shortcut shown. The menu bar is how Mac users discover features and learn shortcuts, and it is searchable from Help.
2. Standard shortcuts, untouched. ⌘N new, ⌘O open, ⌘W close window, ⌘Q quit, ⌘, settings, ⌘Z / ⇧⌘Z undo and redo, ⌘F find, ⌘C/⌘V copy and paste. Never reassign them.
3. Settings in their own window. App menu → Settings…, opened with ⌘,. Usually a small window with a toolbar of tabs. Changes apply immediately; there is no Save button.
4. Windows that behave. Multiple windows where documents warrant them, remembered size and position, full-screen support, and correct behavior when the last window closes.
5. Native text. Text fields that support system spelling, standard editing shortcuts, services and the system font panel where relevant. Re-implementing text editing is where most cross-platform apps fail.
6. Right-click everywhere. Context menus on every object, mirroring commands that also exist in the menu bar.
7. Density for pointers. A mouse is precise, so controls can be smaller and denser than on touch: regular controls are typically compact compared with iOS.
8. Drag and drop, in and out. Files, text and images should drag into your app and out to Finder and other apps.

In the wild

• ReederSilvio Rizzi
  A three-pane reader (sources, list, article) with full keyboard navigation and a calm, native look. Mentioned in the earlier field guide for its restraint; it is also a model of Mac conventions. Calm and native are the same direction.
• RaycastRaycast, 2020–today
  A launcher built around the keyboard: every action shows its shortcut, and a single action panel (⌘K) lists everything you can do with the selected item. On the Mac, discoverable shortcuts are a feature, not an extra.
• Mac Catalyst appsApple, 2019–today
  iPad apps brought to the Mac with Catalyst feel native only when developers add menus, shortcuts, pointer-sized controls and Mac-style settings. Porting is not adapting.

Android has its own grammar: a system back gesture, a bottom navigation bar, a floating action button for the main creative action, and colors that can come from the user's wallpaper. Respect it instead of shipping your iPhone app in disguise.

The essentials

System back

Android has a system-wide back action (a swipe from either edge in gesture navigation, or a button). Your app must handle it correctly at every level: closing a sheet, leaving a screen, or exiting at the root. Predictive back (introduced across Android 13 to 15) shows a preview of where back will go as the user swipes, so your navigation must be honest about its history.

Top app bar

Title, navigation icon (up arrow or menu) and a few actions, with an overflow menu for the rest. It can collapse on scroll.

Navigation bar, rail and drawer

Bottom navigation bar for 3 to 5 destinations on phones; a navigation rail on medium widths (tablets, unfolded foldables); a navigation drawer for many destinations or large screens.

Floating action button (FAB)

One prominent button for the primary creative action of a screen. Not every screen needs one.

Snackbars

Brief messages at the bottom, often with a single action such as "Undo". The Material way to confirm an action without interrupting.

Dynamic color

Since Android 12 (2021), Material You can generate the color scheme from the user's wallpaper. Apps that use Material color roles adapt automatically; you can opt in fully, partially, or keep your brand colors.

Edge to edge

Recent Android versions draw apps behind the status and navigation bars by default (enforced for apps targeting Android 15). Handle window insets as you would iOS safe areas.

Windows and Fluent, briefly

If you ship on Windows, Microsoft's Fluent 2 design system and the WinUI guidance are your HIG. A few conventions matter most: Segoe UI Variable as the system typeface; materials like Mica that tint the window background with the desktop wallpaper; rounded corners (8 px for top-level windows, 4 px for controls in Windows 11); a navigation view with settings at the bottom of the pane; dialogs with the primary button first (left) and Close last; full keyboard access with Alt-key access keys; and respect for the user's contrast theme. Many solo creators reach Windows through a cross-platform framework; the same rule applies as on the Mac: budget time for the keyboard, the title bar and the system's dialog order.

In the wild

• Google Keep and GmailGoogle
  FAB for compose, snackbars with Undo after archive or delete, top app bars with search. The reference implementations of Material on phones. Study the platform owner's apps before designing yours.
• Pocket CastsAutomattic
  A podcast app with a shared visual identity on iOS and Android. Install both versions side by side and list which conventions each adapts (navigation, back, sheets, typography) and which it keeps identical. The best cross-platform apps share brand and adapt behavior.

The web's conventions are older and deeper than any app platform's: URLs, links, the back button, text you can select and zoom. A web product that breaks them feels like a trap. One that honors them feels trustworthy.

URLs are part of the interface

On the web, every meaningful view should have its own URL. That single rule gives people back and forward, bookmarks, sharing, opening in a new tab, and restoring after a crash. Single-page apps often break it by changing the screen without changing the URL. Put the state people would want to return to in the URL: the screen in the path, filters and view modes in the query, a position in the hash.

The web's other conventions

• Links navigate, buttons act. Use <a href> for anything that goes somewhere, so ⌘/Ctrl-click and middle-click open new tabs. Use <button> for actions. Do not make clickable divs.
• Text is text. People select, copy, translate, search with ⌘/Ctrl-F, and zoom. Do not render text as images or disable selection on content.
• Responsive by default. Ethan Marcotte's "Responsive Web Design" (A List Apart, 2010) established fluid grids, flexible images and media queries. Today container queries let components respond to their own space too (Chapter 18).
• Progressive enhancement. A term coined by Steven Champeon in 2003: start with HTML that works, then layer CSS and JavaScript on top. A form that submits without JavaScript, links that work before the app loads. It makes products sturdier on bad networks and old devices.
• Respect the browser's settings. Use rem units so the user's default font size applies; never block pinch zoom; honor prefers-color-scheme, prefers-reduced-motion and prefers-contrast.
• Progressive web apps. The term was coined in 2015 by Alex Russell and Frances Berriman for web apps that can be installed, work offline (via service workers) and send notifications. With a manifest and a service worker, your web product can live on a home screen or dock; on iOS, home screen web apps gained web push in iOS 16.4 (2023). A PWA should still behave like the web inside: URLs and all.

The small screens: watch and widgets

Watch apps and widgets are not small versions of your app. They are glances: one piece of information or one action, available in a second or two. Apple's guidance for watchOS emphasizes brief interactions; widgets on iOS, iPadOS, macOS and Android show timely content and open the app (or, since iOS 17, run a simple action with a button or toggle) when tapped.

In the wild

• Linear and GitHub URLsLinear; GitHub
  Issues have short, stable, readable URLs that people paste into chat and documents. The URL is a product feature. A good URL is a shareable unit of your product.
• GOV.UKGovernment Digital Service
  Built with progressive enhancement: pages and forms work before or without JavaScript, which matters for people on old phones and poor connections. Sturdy beats clever when everyone must be able to use it.
• Apple Fitness ringsApple Watch, 2015–today
  Three rings readable in under a second, the canonical example of a glanceable complication. The smaller the screen, the fewer the questions.

Share what makes your product yours (its content, model, brand and voice). Adapt what makes each platform familiar (navigation, controls, gestures, dialogs, shortcuts). A feature should feel designed for each device, not shipped to it.

Shared and native layers

What your framework means for design

Your choice of technology shapes how much adaptation is free and how much is work. This is a design decision as much as an engineering one.

Worked example: "Highlight and add a note" on four platforms

Imagine a reading app called Margin. The feature: while reading, select a passage, highlight it, and optionally add a note. Shared across platforms: the highlight colors (tokens), the word "Highlight", the data model (passage, color, note, date), and sync. Everything else adapts.

In the wild

• iA WriterInformation Architects, Mac, iOS, Windows, Android
  A distinctive, shared identity (typography, focus mode, Markdown handling) delivered through apps that each follow their platform's file handling, menus and controls. Identity in the content area; conventions in the chrome.
• Apple's own apps on iPhone, iPad and MacNotes, Mail, Reminders
  Same data and features, but a stack on iPhone, a split view on iPad, and windows with menus and an inspector on Mac. Even the platform owner adapts rather than copies.
• Slack and other Electron appsvarious
  Largely identical across Windows, Mac and Linux, which makes them easy to learn once but often criticized for not feeling native on any. Uniformity is a trade-off; know when you are making it.

Design for ranges, not devices: a layout that works from 320 to 1,600 points and reflows at a few meaningful widths. And design for inputs, not screens: a finger, a mouse, a keyboard and a pen ask for different things on the same screen size.

Breakpoints from content, size classes from platforms

A breakpoint is a width where the layout changes. Do not choose them from device lists, which change every year; choose them where your content breaks: when a line of text becomes too long (more than about 75 characters, see Typography), when two columns become cramped, when a sidebar crowds the content. Platforms give you named ranges to anchor on. Material defines window size classes: compact (under 600 dp wide, most phones in portrait), medium (600 to 839 dp, tablets in portrait and many unfolded foldables) and expanded (840 dp and up, tablets in landscape and desktops), with larger classes added for very wide windows. Apple uses size classes, compact or regular in each dimension.

Input is a separate axis

Screen size does not tell you how someone is pointing. A 13-inch touchscreen laptop, an iPad with a Magic Keyboard and a phone with a Bluetooth mouse all break the "small means touch" assumption. On the web, query the input directly: @media (hover: hover) and (pointer: fine) for precise pointers, (pointer: coarse) for touch. On native platforms, use the system's controls, which already adapt (iPadOS shows pointer effects, macOS uses denser controls).

Layout shifts, desktop windows and foldables

• Reserve space. Images without dimensions, late-loading banners and fonts that swap cause content to jump while people are reading or about to tap. Give media an aspect ratio, reserve space for async content, and keep component sizes stable across states (Chapter 8).
• Desktop windows are any size. People tile windows side by side, so your Mac or web app may be 500 points wide on a 5K display. Treat window width, not screen size, as the input, and define a sensible minimum window size.
• Container queries. Supported in all major browsers since 2023, they let a component respond to the width of its own container. A card can switch from horizontal to stacked whether it lives in a sidebar or a main column.
• Foldables. A device can change size while your app is open: folded phone, unfolded tablet, half-open "tabletop" posture with a hinge across the middle. Preserve state through the change (the scroll position and the open note must survive), avoid putting critical content across the hinge, and use the medium and expanded layouts you already have.

In the wild

• Gmail on AndroidGoogle
  Switches from a single list with a bottom bar on phones to a navigation rail and list-detail layout on tablets and unfolded foldables. The same app, three canonical layouts.
• The Boston Globe responsive site2011, with Ethan Marcotte and Filament Group
  One of the first major responsive news sites, often cited as proof that a single fluid design could serve phones to desktops. Responsive design was a design decision before it was a technique.

Every shortcut you take in the interface is a loan. Design debt compounds quietly until a simple change takes a week. Pay it down on a schedule: inventory, consolidate, version, and deprecate gently.

Engineers know technical debt: code that works but makes future changes expensive. Design debt is its twin: the third gray nobody chose, the dialog that puts the buttons on the other side, the screen that uses its own spacing, the component with a customColor prop. Each one was a reasonable choice under time pressure. The trouble is interest. Every inconsistency makes the next change slower (which version do I follow?), makes theming leakier, and teaches users that your product is unpredictable.

The interface inventory

In 2013 Brad Frost described the interface inventory: screenshot every instance of every kind of UI element in your product and paste them into one document, grouped by type. All buttons together. All headings. All form fields. All dialogs. All icons. The power is in the side-by-side view. Inconsistencies that are invisible across fifty screens become embarrassing on one page, and the embarrassment is useful: it creates the motivation to consolidate.

Running an inventory alone, in one afternoon

1. Capture. Walk through every screen in both themes and screenshot each instance of: buttons, text styles, form fields, icons, dialogs and sheets, empty states, colors (use a color picker on screenshots).
2. Group. Paste into one canvas or document, one row per type. Do not judge yet.
3. Count. Write the count of distinct variants per row: "buttons: 10 styles".
4. Decide. For each row, choose the keepers (usually the ones closest to your tokens) and map every other instance to one of them.
5. Consolidate. Replace instances in code with the system component. Do the most-used screens first.
6. Prevent. Add a search, lint rule or code review habit that catches new literals and one-off styles.

Versioning your system

Even for one person, a version number on your system is useful because it marks moments of change you can look back on, and it lets you migrate gradually. Use the familiar rules of semantic versioning (major.minor.patch, from semver.org): a patch fixes something without changing how you use it (a contrast tweak); a minor version adds something backward-compatible (a new component, a new token); a major version breaks something (a token renamed or removed, a component API changed).

In the wild

• GOV.UK FrontendGovernment Digital Service
  The code behind the GOV.UK Design System is released with version numbers and published release notes that explain breaking changes and how to migrate. Release notes are documentation for future-you.
• Interface inventoryBrad Frost, 2013
  Frost's article walks through screenshotting a site's elements into categories and using the result to start a system and get buy-in. For a solo creator, the buy-in you need is your own. Seeing all variants at once is the motivation to fix them.

Wrap-up

Practice assignment for the next two weeks

1. Days 1–2: census and tokens. Exercises 1.1 and 4.1. End with a token file and two migrated screens.
2. Days 3–4: scales and themes. Exercises 5.1 and 6.1. Ship dark mode and the contrast table.
3. Days 5–6: components. Exercises 7.1 and 8.1. Build the torture page (2.1) with the state matrix on it.
4. Day 7: rest and review. Use your app for a full day in dark mode with large text. Write down everything that annoys you.
5. Days 8–9: button and docs. Exercises 9.1 and 10.1. Five documented components, three patterns.
6. Day 10: one source of truth. Exercise 11.1.
7. Days 11–12: platforms. Exercise 12.1 plus the chapter exercise for your main platform (13.1, 14.1, 15.1 or 16.1). Fix the top three mismatches.
8. Day 13: sizes. Exercise 18.1, the slow drag.
9. Day 14: inventory. Exercise 19.1. Tag system 1.0.0, write the changelog, and book the monthly system day in your calendar.

Reading list

• Atomic Design
  Brad Frost, 2016 (free to read online) · The model in full, plus the interface inventory and how to keep a pattern library alive. Read chapters 1, 2 and 4.
• Design Systems
  Alla Kholmatova, Smashing Magazine, 2017 · The best book on the human side of systems: shared language, functional versus perceptual patterns, strict versus loose systems.
• EightShapes essays on tokens and systems
  Nathan Curtis, Medium, 2016–today · Especially "Naming Tokens in Design Systems". The most precise thinking available on token architecture.
• Expressive Design Systems
  Yesenia Perez-Cruz, A Book Apart, 2019 · How to keep a system from flattening your product's personality.
• Refactoring UI
  Adam Wathan and Steve Schoger, 2018 · Practical, visual advice on scales for spacing, type, color and shadow, from the makers of Tailwind.
• Apple Human Interface Guidelines
  Apple, continuously updated · Read the pages for navigation, sheets, alerts, menus, typography and the platform considerations for each device you ship.
• Material Design 3
  Google, continuously updated · Read color roles, window size classes and canonical layouts, even if you never ship on Android.
• GOV.UK Design System
  Government Digital Service · The model for documenting components and patterns with research and "when not to use".
• Laws of UX
  Jon Yablonski, O'Reilly, 2020 (and the website) · Jakob's law and its relatives, with the psychology behind them.
• Responsive Web Design
  Ethan Marcotte, A Book Apart, 2011 (from his 2010 A List Apart article) · The origin of designing for ranges instead of devices.
• Resilient Web Design
  Jeremy Keith, 2016 (free online) · Progressive enhancement and the web's long history of sturdy conventions.
• NYCTA Graphics Standards Manual
  Unimark International (Massimo Vignelli, Bob Noorda), 1970; facsimile reissued 2014 · A design system before software: rules, measurements and examples on every page.

Next: Designing with AI, where your documented system becomes the context an AI assistant needs to build screens the way you would.