--- slug: affordance type: pattern summary: "The property of a design element that communicates its own purpose, so a button looks pressable and a field looks editable." created: 2026-04-04 updated: 2026-04-27 related: accessibility: relation: supports note: "" constraint: relation: depends-on note: "Platform constraints shape which affordances are available." user-feedback: relation: complements note: "Affordance tells users what they *can* do; feedback tells them what they *did*." ux: relation: refines note: "Affordance is one of the core mechanisms of good user experience." --- # Affordance > **Pattern** > > A named solution to a recurring problem. > "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](constraint.md) -- platform constraints shape which affordances are available. ## Context This is a **tactical** pattern within [UX](ux.md). 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. ## Sources - The psychologist James J. Gibson coined *affordance* in *[The Senses Considered as Perceptual Systems](https://openlibrary.org/books/OL5979223M/The_senses_considered_as_perceptual_systems)* (Houghton Mifflin, 1966) and developed the theory in *[The Ecological Approach to Visual Perception](https://openlibrary.org/works/OL8642476W/The_Ecological_Approach_To_Visual_Perception)* (Houghton Mifflin, 1979), where he framed an affordance as what the environment offers an actor — a relational property that depends on both the world and the perceiver's capabilities. - Don Norman imported the idea into design in *[The Psychology of Everyday Things](https://openlibrary.org/works/OL1879162W/The_Psychology_of_Everyday_Things)* (Doubleday, 1988; retitled *The Design of Everyday Things* in its 1990 reissue and revised in 2013). Norman recast affordance as something a designer engineers into an artifact so users can see what to do without instruction. In the 2013 revision he distinguished *affordance* (the action a design makes possible) from *signifier* (the perceptible cue that announces it), correcting a confusion that had spread through the HCI literature. - William Gaver's "[Technology Affordances](https://dl.acm.org/doi/10.1145/108844.108856)" (CHI 1991) brought the concept into human-computer interaction with the four-way distinction between perceptible affordances, hidden affordances, false affordances, and correct rejections — the vocabulary still used to diagnose interface failures today. --- - [Next: User Feedback](user-feedback.md) - [Previous: UX](ux.md)