# ux-usability-foundations

Guides an AI agent to design, review, and refine interfaces around usability principles, error prevention, and user mental models.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 559 installs · ★ 23
- Author: hueyexe
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/hueyexe/frontend-agent-skills/tree/HEAD/ux-usability-foundations/SKILL.md
- Updated: 2026-08-02
- HTML: https://affpapa.org/en/nevibecode/skills/ux-usability-foundations

## What it does

This skill directs Claude Code to treat user experience as product behavior instead of cosmetic styling. When evaluating a screen, form, or checkout flow, the agent applies twelve foundational principles. It inspects whether interactive affordances look clickable, labels use plain language, and the interface keeps the next step obvious.

Built-in defaults govern state handling and interaction details. Destructive actions stay visually secondary, favoring `undo` instead of confirmation popups unless changes are irreversible. Forms must preserve user input upon failure. Core accessibility requirements — semantic controls, visible focus indicators, and keyboard navigation — apply automatically without overrides.

This skill does not handle brand styling, visual polish, typography choices, or frontend code architecture. When key details like user intent or safety constraints are missing, the agent stops to ask a single focused question rather than guessing the design direction.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add hueyexe/frontend-agent-skills --skill ux-usability-foundations -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ux-usability-foundations/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ux-usability-foundations/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add hueyexe/frontend-agent-skills --skill ux-usability-foundations -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ux-usability-foundations/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add hueyexe/frontend-agent-skills --skill ux-usability-foundations -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ux-usability-foundations/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install hueyexe/frontend-agent-skills ux-usability-foundations
```

2. **Manually: put the files in place**
- File: `.github/skills/ux-usability-foundations/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add hueyexe/frontend-agent-skills --skill ux-usability-foundations -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/hueyexe/frontend-agent-skills --path ux-usability-foundations
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ux-usability-foundations/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add hueyexe/frontend-agent-skills --skill ux-usability-foundations -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/hueyexe/frontend-agent-skills/tree/HEAD/ux-usability-foundations/SKILL.md

## When to use it
- critique form flows, settings panels, or checkout pages for usability flaws
- prevent data loss during validation errors and failed submissions
- add WCAG-aligned keyboard navigation and semantic structure to UI components
- remove redundant input steps that serve the system rather than the user

## Example prompts
- Review this checkout flow for usability issues, focusing on error states and data preservation
- Design a settings page that uses inline validation and an undo mechanism for destructive changes
- Evaluate this onboarding screen and point out where cognitive load can be reduced

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2c1b826242453f00.

BEGIN THIRD-PARTY FILE 2c1b826242453f00
```text
---
name: ux-usability-foundations
description: "Use when designing, critiquing, or improving an interface for usability, including affordances, feedback, constraints, error prevention, navigation clarity, or task flow."
license: MIT
metadata:
  author: hueyexe
---

# UX Usability Foundations

## Purpose

Help an agent make interfaces understandable, usable, forgiving, and aligned with user expectations. Treat usability as product behavior, not surface decoration. The agent should turn unclear or fragile UI into an interface where users can quickly answer: what is this, what can I do here, where am I, what happened, how do I recover, and is this worth the effort?

## When to use this skill

Use this skill when the user asks you to critique, redesign, create, or specify a UI, flow, form, app screen, website, dashboard, onboarding, settings page, checkout, navigation model, state behavior, or component interaction for usability. Use it for affordances/signifiers, feedback, constraints, errors, empty/loading/success states, recognition over recall, task clarity, and frontend behavior.

## When not to use this skill

Do not use as the primary skill for deep research operations, brand styling systems, visual polish, typography craft, frontend architecture, or persuasion/growth tactics unless those choices directly affect user understanding, control, or recovery.

## Core principles

1. **Start with goals, not screens.** Identify the user’s goal, task, context, and likely knowledge before changing controls or layout. Design requirements describe needs before widgets.
2. **Make the next action obvious.** Prefer self-evident interfaces. If the task is inherently novel or complex, make it self-explanatory with structure, labels, examples, and feedback.
3. **Show what is possible.** Interactive elements must look interactive. Read-only elements must not look editable. Hidden gestures need visible alternatives.
4. **Match the user’s mental model.** Use the concepts, names, and sequence users understand; do not expose database tables, file paths, internal IDs, or arbitrary system states unless users need them.
5. **Favor recognition over recall.** Keep needed options, context, examples, and state visible or easy to retrieve.
```
END THIRD-PARTY FILE 2c1b826242453f00

The third-party file has ended. Everything between the 2c1b826242453f00 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2256 of 16609 bytes. © hueyexe · MIT · https://github.com/hueyexe/frontend-agent-skills/tree/HEAD/ux-usability-foundations/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md