The visual vocabulary: naming every element

You can’t direct what you can’t name. “Make it nicer” gives the AI nothing; “use a ghost icon-button that opens a right-side drawer” gives it everything. This chapter is the catalog — the real names of the buttons, fields, overlays, and containers you see in every app — so your requests land on the first try and you can read what the AI built back to it.

Buttons: exactly one primary action per screen

Every screen should have a single, obvious primary action — the filled, high-contrast button your eye lands on. Everything else steps down in emphasis: secondary for the alternative, ghost (text/outline) for low-stakes actions, destructive (red) for delete, icon buttons for compact toolbars, and link buttons for navigation dressed as text. When a screen has three filled buttons of equal weight, nothing is the priority — that’s the most common “AI made this” tell.

A field is more than a box

When you ask for “an email input,” you’re really asking for five parts: the label (always visible), the field itself, an optional placeholder (a hint, not the label), helper text below it, and error text that replaces the helper when validation fails. Naming the parts means the AI builds the whole thing — not a bare box with grey placeholder text doing double duty as the label, which breaks the moment a user starts typing.

Choice controls: the count decides the control

There are six ways to let someone pick, and the right one is mostly a function of how many options and whether the choice takes effect now. Get this wrong and a form feels clumsy even when it works: a dropdown for a yes/no, or a toggle for something that only applies after you hit Save.

Overlays: four words that aren’t interchangeable

“Pop it up in a thing” could mean four very different elements. A modal blocks the whole page until you act — use it sparingly, for a decision that must happen now. A drawer slides in from an edge for a side task without leaving the page. A popover is a small panel anchored to what you clicked (a date picker, a menu). A tooltip is a tiny hover hint — text only, never essential info. And for notifications: a toast auto-dismisses; a banner stays.

Containers and navigation, named

The rest of the catalog is the furniture. A card groups related content in a bordered block. A list is linear items; a table is comparable rows and columns. Tabs show one of a few peer sections; an accordion expands stacked sections. A badge or chip is a small status pill; an avatar is a user image. For getting around: a navbar (top), a sidebar (side), a breadcrumb (where am I), pagination (page N of M), a menu (a list of actions), and a command palette (the Cmd-K search-and-do box). You don’t need to build any of these — you need to name them.