Information architecture and naming

Organizes navigation and terminology around user tasks so people can predict where information and actions belong.

information-architecture-naming

See how it helps

When is it useful?

Use when menus mirror database tables or similar actions have inconsistent names.

What does it help you do?

Groups destinations by user goals rather than internal structure.
Uses consistent labels and clear page and navigation orientation.
Coordinates equivalent terminology across supported languages.

Try asking this

Rename and regroup account settings so billing contacts, team members and invoices are easy to distinguish. Ask where a user would change the invoice recipient versus invite a teammate. Provide distinct navigation labels and matching page titles in each language.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Information Architecture & Naming

Users should never have to reverse-engineer the engineering team's database schema or microservice boundaries to find a feature or understand a button label (Steve Krug & Jakob Nielsen).

Workflow

Align navigation with user tasks, not backend tables:
- Audit top-level navigation, tabs, and sidebars:
  - Do menu items reflect the user's workflow and mental model, or do they mirror internal database entities ("ExecutionAttempts", "NodePortBindings", "TenantConfigBlobs")?
  - Check for overlapping menu buckets where a user cannot predict whether an item lives under Settings, Preferences, Configuration, or Workspace.
- Consolidate fragmented views that belong to the same user job into a single coherent workspace with clear sub-sections.
Enforce clear, consistent, self-explanatory naming:
- One concept = one term across the entire product: Never call the same entity a Project in the sidebar, a Workspace in the header, and a Repository in the modal.
- Verb + Noun for actions: Replace vague labels ("Process", "Execute", "Submit", "Manage", "OK") with specific action labels ("Start run", "Approve changes", "Revoke API key").
- Never replace critical labels with mystery icons: Icon-only buttons are acceptable only for universal actions (Close X, Search) with accessible aria-label and tooltip; domain actions require visible text labels.
Establish clear spatial and visual orientation:
- At any moment, the user must be able to answer three questions at a glance:
  1. Where am I? (Active navigation state, clear page title, workspace/project context indicator.)
  2. What state is this item in? (Visible status badge, e.g., Draft, Running, Waiting for approval.)
  3. What can I do next? (Clearly prioritized primary and secondary actions.)
Coordinate localized terminology:
- Ensure simplified, concrete terminology stays consistent across all supported languages and the project glossary.

Included files 1

SKILL.md