/information-architecture

name: information-architecture
description: Naming, navigation, a UI that mirrors the data model, confirms for irreversible changes. Use when structuring a large application or naming its entities.
metadata:
  priority: 9
  pathPatterns:
    - "components/**"
    - "src/components/**"
    - "**/*.tsx"
    - "**/*.jsx"
    - "design-system/**"
    - "ui/**"
    - "app/**"
    - "pages/**"
  promptSignals:
    phrases:
      - "information architecture"
      - "navigation structure"
      - "naming"
      - "mental model"
      - "data model"
      - "entity"
      - "confirm dialog"
      - "destructive action"
      - "large application"
      - "ia"
      - "terminology"
      - "microcopy"
      - "button label"
      - "what to call"
retrieval:
  aliases:
    - information architecture
    - IA
    - naming
    - mental model
    - data model UI
    - navigation structure
    - confirm dialog
    - destructive action
    - terminology
    - microcopy
    - button label length
    - customer vs internal vocabulary
  intents:
    - structure a large application
    - name entities clearly
    - design navigation for complex product
    - model the UI around data
    - add confirm dialog for dangerous action
    - build user mental model
    - choose customer-facing terminology vs internal
    - write concise button labels
  examples:
    - how should I structure navigation for this app
    - what should I call this entity
    - add a confirm dialog before deleting
    - design the data model for this UI
    - make this large app easier to navigate
    - what should we call this for customers, not internally
    - how long should button labels be

Information Architecture

In small products, users find their way by exploring. In large applications — multi-module SaaS, ERPs, analytics platforms, marketplaces — exploration breaks down. The structure itself must do the navigational work. Information architecture is the design of that structure: what exists, what it is called, and how it relates to everything else.

Good IA is invisible. Users find what they need without thinking about the structure. Bad IA forces users to hold a map in their head.

---

Naming is Design

The names given to entities, sections, and actions are one of the most consequential design decisions in a large application. Bad names create cognitive friction on every visit.

**Principles:**

• **Use the user's vocabulary, not the engineer's.** If users call it a "job", do not call it a `task_assignment`. If they call it a "client", do not surface `contact_entity`.
• **Be specific.** "Settings" is vague. "Account settings", "Workspace settings", "Notification preferences" tell the user exactly where they are.
• **Be consistent.** If it is called "Project" in the sidebar, it must be called "Project" in the breadcrumb, the page title, the confirmation dialog, and the API error message.
• **Distinguish similar things.** If the product has both "Users" and "Members", the distinction must be meaningful and consistently communicated.
• **Name actions by their effect.** "Archive" not "Hide". "Publish" not "Save to live". "Transfer ownership" not "Change user".

**Naming audit questions:**

• Would a new user understand this term without training?
• Is this name used consistently across every surface it appears?
• Does this name describe what the thing *does*, not how it is stored?

Internal vocabulary is not customer vocabulary

The terms a company uses internally are frequently *not* the terms the customer should see. An internal casual shorthand ("the recon job", "a P2 ticket") is precise for the team but opaque to an outsider. When a term crosses from the internal build into the customer-facing app, translate it to **the customer's word, or a universally understood one** — never ship the internal shorthand by default.

• **Introduce as few new terms as possible — a hard ceiling of ~10 invented terms for the whole product, and fewer is always better.** Every new coined term is something the user must learn before they can act. Prefer terms so universal that the end user already knows them over anything you'd have to teach.
• **Placement tells half the story.** Where a feature sits — which section, which nav group, next to what — communicates as much as its label. A well-placed control needs less naming; a well-named control in the wrong place still confuses. Design the location and the name together.

Label length: buttons are terse, titles continue the story

• **Buttons: 1 word, ideally — 2 is fine, 3 is the maximum.** A button is an action verb, not a sentence. "Save", "Publish", "Invite member".
• **Titles and headings carry the fuller explanation.** Let the surrounding title, section header, or helper text extend the narrative that the button can only hint at. The button says *what*; the title says *what this whole area is about*.

---

Mental Model Follows Data Model

The UI should be a direct, legible expression of the underlying data model. Users build a mental model of the product by interacting with it — that mental model should match how the data actually works.

**Match entities to screens.** Each major data entity (Project, Invoice, User, Product) typically deserves its own list view and detail view. Do not collapse distinct entities into one screen because it seems simpler — users will be confused when one action affects something they did not see.

**Expose relationships.** If a Project contains Tasks, and Tasks belong to Users, the UI hierarchy should reflect this:

Projects
  └── Project: Website Redesign
        └── Tasks
              └── Task: Fix header  [Assigned to: Maria]

Breadcrumbs, parent labels, and contextual references ("3 tasks in this project") reinforce the data relationships visually.

**Show transformation paths.** The UI should make it clear how data moves through the system. A draft becomes published. An invoice moves from pending to paid. A user is promoted