Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Affordance

Pattern

A reusable solution you can apply to your work.

“When affordances are taken advantage of, the user knows what to do just by looking: no picture, label, or instruction needed.” — Don Norman, The Design of Everyday Things

Understand This First

  • Constraint – platform constraints shape which affordances are available.

Context

This is a tactical pattern within UX. Once you’re building an interface — whether graphical, command-line, conversational, or API-based — you face the question of how users will figure out what to do. Affordance is the property of a design element that communicates its own purpose. A well-afforded button looks pressable. A well-afforded text field looks editable. A well-afforded drag handle looks grabbable.

In agentic coding, affordance matters at multiple levels. The interfaces your agent builds need clear affordances for end users. And the tools you give an agent — function names, parameter descriptions, help text — are affordances for the agent itself.

Problem

Users encounter an interface and can’t figure out what to do. They click things that aren’t clickable, overlook features that are available, or misunderstand what an action will do. The system works correctly, but its design doesn’t communicate how to use it. How do you make an interface self-explanatory?

Forces

  • Minimalist design removes clutter but can also remove cues about how things work.
  • Familiar conventions (like underlined links) work until they do not — new interaction patterns lack established affordances.
  • Different platforms have different affordance conventions (touch vs. mouse, mobile vs. desktop).
  • Text labels explain everything but take up space and slow down experienced users.

Solution

Design every interactive element so that its appearance, position, or behavior suggests what it does and how to use it. This doesn’t mean making everything obvious through labels alone. It means using visual weight, shape, texture, cursor changes, hover states, and spatial relationships to communicate purpose.

Buttons should look like buttons: raised, colored, or outlined in ways that distinguish them from static text. Text fields should have visible borders or backgrounds that invite input. Draggable elements should have handles. Destructive actions should look different from safe ones (a red button with a confirmation step, not another link in a list).

For CLI tools and APIs, affordance comes through naming and structure. A command called project init affords its purpose more clearly than pi. A function parameter named max_retries communicates its role better than n. When building tools for AI agents, clear affordances in function signatures and descriptions directly affect how well the agent uses them.

How It Plays Out

A developer asks an agent to create a file management interface. The agent generates a list of files with small “X” icons for deletion. Users keep accidentally deleting files because the X icons look like close buttons for a dialog, not delete buttons for files. The fix: replace the X with a trash can icon, add a hover tooltip that says “Delete,” and require confirmation. The affordance now matches the action.

A team builds a CLI with subcommands like db migrate up, db migrate down, and db migrate status. The command names themselves are affordances — they communicate what each action does. Compare this to a tool where the same operations are db -m -u, db -m -d, and db -m -s. Same functionality, far worse affordance.

Note

Affordances are culturally learned, not universal. A hamburger menu icon (three horizontal lines) is a strong affordance for navigation to experienced web users but meaningless to someone who has never used a modern web app. Know your audience.

Example Prompt

“Replace the small X icons on the file list with trash can icons. Add a hover tooltip that says ‘Delete’ and require a confirmation dialog before actually deleting.”

Consequences

Good affordances reduce the learning curve, decrease errors, and make software feel intuitive. Users spend less time reading documentation and more time accomplishing their goals. Fewer people get stuck, so support costs drop.

The downside is that affordance design takes effort and testing. What seems obvious to the designer may not be obvious to the user. Affordances can also conflict with aesthetics; the most self-explanatory design isn’t always the most visually elegant.

  • Refines: UX — affordance is one of the core mechanisms of good user experience.
  • Complements: Feedback — affordance tells users what they can do; feedback tells them what they did.
  • Depends on: Constraint — platform constraints shape which affordances are available.