ux-design-principles
Skill2 starsChanged 9 months agoMITView on GitHub
Use when planning or designing features that involve user-facing UI, or before writing code for any new user-facing feature — pages, components, flows, or interactions — to apply user-centered design thinking before implementation begins
2 other projects use a version of this.
Adopted by
Most recently taken up by
- mahirautela2020-design/claude-skills-uxtheir own version, first seen Mar 12, 2026
- kayaman/skillstheir own version, first seen Mar 7, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- kayaman/skills★ 3same name
- mahirautela2020-design/claude-skills-ux★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- architecture-decision-recordsSkill
- boy-scout-ruleSkill
- domain-driven-designSkill
- functional-core-imperative-shellSkill
- git-commit-messageSkill
- react-best-practicesSkill
- revise-for-claritySkill
- ux-prototypingSkill
- ux-visual-evaluationSkill
- visual-feedback-loopSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Before technical questions (stack, architecture, data model), establish the user context.
- Distinctive: line 25
When comparing 2-3 approaches, evaluate each against the user's goal — not just technical trade-offs.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
UX Design Principles — Design for Users, Not Features
Companion to feature planning and design for UI features. Injects user-centered thinking into design decisions before any code is written.
Scope Gate
Is this feature user-facing? Pages, components, flows, interactions → apply. Infrastructure, APIs, data pipelines, backend-only logic → skip.
During Planning: Ask These First
Before technical questions (stack, architecture, data model), establish the user context. These questions come from Goal-Directed Design (Cooper):
- Who is the primary user? Just enough to anchor decisions. "Admin managing a team" and "end user checking status" lead to different interfaces. If multiple user types, which one is this feature primarily for?
- What is their goal? Goals are outcomes, not tasks. "Feel confident the deploy is safe" not "click the deploy button." This drives what to surface, hide, and emphasize.
- What's their context? Rushed or careful? Frequent or first-time? Mobile or desktop? High-stakes + infrequent = add confirmation. Low-stakes + frequent = minimize clicks.
- What do they already expect? Mental models from similar tools. If every competitor puts navigation on the left, putting it on the bottom needs a strong reason.
During Approach Evaluation: UX Lens
When comparing 2-3 approaches, evaluate each against the user's goal — not just technical trade-offs. The approach that gets the user to their goal with the least confusion wins, even if it's technically simpler. Ask: "Would [user type] trying to [goal] find this confusing?"
Design Principles to Apply
- Reduce before you design. Can the user achieve their goal with fewer steps, fields, or options? What's the simplest version that solves the primary goal? Progressive disclosure: show what's needed now, hide the rest.
- Structure by scanning priority. Users scan, they don't read. What does the user need first? What's secondary? What's rare? The primary goal drives the primary content area.
- Match user expectations. Favor designs that work like tools the user already knows. Surprising users costs more than surprising developers.
- Prevent errors, don't just handle them. Constrain inputs (date picker over text field), set smart defaults, confirm destructive actions. This is a design decision, not an implementation detail.
In the Design Document
Include a UX rationale section: who the user is, what their goal is, and which principles drove the key design decisions. This gives implementers context for judgment calls during coding.
What This Skill Does NOT Cover
- Visual design (spacing, color, hierarchy) —
ux-visual-evaluation - Accessibility implementation —
react-best-practices - Prototyping workflow —
ux-prototyping
Related Skills
- Next (complex UI):
ux-prototyping(when design involves novel interactions, complex flows, or visual-balance-critical layouts — prototype before implementing) - Next (standard UI): proceed to implementation →
visual-feedback-loop(verify the implementation visually) - Pairs with:
domain-driven-design(ubiquitous language should flow through to UI labels)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.