hci-foundations
Applies human-computer interaction principles to evaluate or design any interface. Use whenever the user asks for a usability review, UX critique, heuristic evaluation, design justification, or wants to know why a screen feels confusing, mentions Nielsen heuristics, Norman, Shnei
Install
npx skills add https://github.com/MehranQadirian/skills/tree/main/hci/hci-foundations
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install mehranqadirian-skills@llmmart
git clone https://github.com/MehranQadirian/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole mehranqadirian/skills collection as a plugin from our marketplace. Git is the plain clone.
README
hci-foundations
A Claude skill that applies HCI principles to evaluate and design interfaces, and turns findings into a prioritized report.
What it does
- Reviews screens and flows with Nielsen's 10 heuristics, Norman's principles and Shneiderman's golden rules
- Explains problems with the law or principle behind them (Fitts, Hick, Doherty, Jakob and more)
- Rates severity from 0 to 4 and produces a report with
heuristic_audit.py - Flags heuristics with no findings so nothing is silently skipped
- Chooses the right evaluation method and routes to the platform skill for fixes
Try it
Do a heuristic evaluation of this checkout flow.
Why does this settings screen feel confusing? Name the principles.
Which is better for the primary action here, a bottom bar or a floating button, and why?
Install
Claude.ai: zip this folder, then go to Settings > Capabilities > Skills > Upload.
Claude Code:
cp -r hci/hci-foundations ~/.claude/skills/
Structure
hci-foundations/
├── SKILL.md skill instructions for Claude
├── scripts/heuristic_audit.py prioritized report generator
├── references/principles.md principles and laws
├── references/evaluation-methods.md methods and procedures
└── templates/ findings CSV and report skeleton
Skill manifest
hci-foundations
The base of the hci category. It turns principles into questions you can answer from the actual interface, rates problems by severity and produces a report that tells a team what to fix first.
hci-foundations/
├── SKILL.md
├── scripts/
│ └── heuristic_audit.py findings CSV or JSON to a prioritized report (text, md, json)
├── references/
│ ├── principles.md Nielsen 10, Norman, Shneiderman 8, laws of UX, Gestalt, ethics, severity scale
│ └── evaluation-methods.md which method to use, heuristic evaluation, cognitive walkthrough, small tests
└── templates/
├── findings.csv example findings with the right columns
└── heuristic-evaluation-report.md report skeleton
When to use
- Reviewing a screen, flow, prototype or live product for usability
- Explaining why something is confusing, with a named principle and evidence
- Choosing between two design options and justifying the choice
- Planning an evaluation, or preparing findings for stakeholders
- Deciding which platform or concern skill to apply next
Workflow
- Frame the review: who are the users, what are the 3 to 5 key tasks, which screens or flows are in scope, what device and context. Ask only for what you cannot infer. If you only have a description or a screenshot, say what you could not check (motion, timing, real data).
- Walk each task step by step and ask the heuristic questions in
references/principles.md(visibility, match, control, consistency, error prevention, recognition, efficiency, minimalism, error recovery, help). - Record each problem with location, the issue as observed (not as opinion), the violated heuristic, evidence, a severity from 0 to 4 and a specific fix. Use
templates/findings.csvas the format. - Rate severity by frequency, impact and persistence. Do not inflate: a cosmetic issue is a 1.
- Generate the report:
python3 scripts/heuristic_audit.py findings.csv --format md --out report.md. It prioritizes by severity, counts by heuristic and lists heuristics with no findings so you can confirm they were examined, not skipped. The exit code is 1 when a severity 4 finding exists, so it can gate a release. - Recommend fixes that are concrete and minimal, and say which platform skill covers the implementation (see Related skills).
- State the limits: an expert review finds likely problems, real users show actual ones. Recommend a small usability test (
hci-usability-testing) for the top findings.
Rules
- Tie every finding to evidence from the interface; avoid "I do not like it"
- Describe the problem and its effect on the user, not the designer's intent
- One problem per finding; keep severity honest
- Include what works well, so good patterns are kept
- Do not invent user data or test results; label assumptions
- Do not recommend dark patterns even when they raise a metric
- Apply accessibility as part of every heuristic, not as a separate afterthought
What to report back
| Field | Content |
|---|---|
| Scope | users, tasks, screens, what was not seen |
| Top problems | three at most, with evidence and fix |
| Full findings | table by severity, heuristic and location |
| Strengths | what to keep |
| Next steps | fixes in priority order, and the test that will verify them |
Related skills
hci-react-native,hci-flutter,hci-android-native,hci-ios-swiftui: mobile implementationhci-web-accessibility: web and WCAGhci-desktop-apps,hci-cli-ux: desktop and command linehci-rtl-localization: right-to-left and multilingual UIhci-microcopy: wording of messages and labelshci-usability-testing: verify with real users
Files (skills)
-
references
-
evaluation-methods.md 2.8 KB
Loading… -
principles.md 5.9 KB
Loading…
-
-
scripts
-
heuristic_audit.py 5.8 KB
Loading…
-
-
templates
-
findings.csv 699 B · in bundle
-
heuristic-evaluation-report.md 689 B
Loading…
-
-
README.md 1.4 KB
# hci-foundations A [Claude skill](../../README.md) that applies HCI principles to evaluate and design interfaces, and turns findings into a prioritized report. ## What it does - Reviews screens and flows with Nielsen's 10 heuristics, Norman's principles and Shneiderman's golden rules - Explains problems with the law or principle behind them (Fitts, Hick, Doherty, Jakob and more) - Rates severity from 0 to 4 and produces a report with `heuristic_audit.py` - Flags heuristics with no findings so nothing is silently skipped - Chooses the right evaluation method and routes to the platform skill for fixes ## Try it > Do a heuristic evaluation of this checkout flow. > Why does this settings screen feel confusing? Name the principles. > Which is better for the primary action here, a bottom bar or a floating button, and why? ## Install **Claude.ai:** zip this folder, then go to Settings > Capabilities > Skills > Upload. **Claude Code:** ```bash cp -r hci/hci-foundations ~/.claude/skills/ ``` ## Structure ``` hci-foundations/ ├── SKILL.md skill instructions for Claude ├── scripts/heuristic_audit.py prioritized report generator ├── references/principles.md principles and laws ├── references/evaluation-methods.md methods and procedures └── templates/ findings CSV and report skeleton ``` -
SKILL.md 4.3 KB
--- name: hci-foundations description: Applies human-computer interaction principles to evaluate or design any interface. Use whenever the user asks for a usability review, UX critique, heuristic evaluation, design justification, or wants to know why a screen feels confusing, mentions Nielsen heuristics, Norman, Shneiderman, Fitts, Hick, cognitive load, affordances or feedback, or asks which HCI principle applies, even if they only say "does this UI make sense?". Produces evidence-based, severity-rated findings and a prioritized report, then points to the platform skill for fixes. --- # hci-foundations The base of the `hci` category. It turns principles into questions you can answer from the actual interface, rates problems by severity and produces a report that tells a team what to fix first. ``` hci-foundations/ ├── SKILL.md ├── scripts/ │ └── heuristic_audit.py findings CSV or JSON to a prioritized report (text, md, json) ├── references/ │ ├── principles.md Nielsen 10, Norman, Shneiderman 8, laws of UX, Gestalt, ethics, severity scale │ └── evaluation-methods.md which method to use, heuristic evaluation, cognitive walkthrough, small tests └── templates/ ├── findings.csv example findings with the right columns └── heuristic-evaluation-report.md report skeleton ``` ## When to use - Reviewing a screen, flow, prototype or live product for usability - Explaining why something is confusing, with a named principle and evidence - Choosing between two design options and justifying the choice - Planning an evaluation, or preparing findings for stakeholders - Deciding which platform or concern skill to apply next ## Workflow 1. **Frame the review**: who are the users, what are the 3 to 5 key tasks, which screens or flows are in scope, what device and context. Ask only for what you cannot infer. If you only have a description or a screenshot, say what you could not check (motion, timing, real data). 2. **Walk each task step by step** and ask the heuristic questions in `references/principles.md` (visibility, match, control, consistency, error prevention, recognition, efficiency, minimalism, error recovery, help). 3. **Record each problem** with location, the issue as observed (not as opinion), the violated heuristic, evidence, a severity from 0 to 4 and a specific fix. Use `templates/findings.csv` as the format. 4. **Rate severity** by frequency, impact and persistence. Do not inflate: a cosmetic issue is a 1. 5. **Generate the report**: `python3 scripts/heuristic_audit.py findings.csv --format md --out report.md`. It prioritizes by severity, counts by heuristic and lists heuristics with no findings so you can confirm they were examined, not skipped. The exit code is 1 when a severity 4 finding exists, so it can gate a release. 6. **Recommend fixes** that are concrete and minimal, and say which platform skill covers the implementation (see Related skills). 7. **State the limits**: an expert review finds likely problems, real users show actual ones. Recommend a small usability test (`hci-usability-testing`) for the top findings. ## Rules - Tie every finding to evidence from the interface; avoid "I do not like it" - Describe the problem and its effect on the user, not the designer's intent - One problem per finding; keep severity honest - Include what works well, so good patterns are kept - Do not invent user data or test results; label assumptions - Do not recommend dark patterns even when they raise a metric - Apply accessibility as part of every heuristic, not as a separate afterthought ## What to report back | Field | Content | |-------|---------| | Scope | users, tasks, screens, what was not seen | | Top problems | three at most, with evidence and fix | | Full findings | table by severity, heuristic and location | | Strengths | what to keep | | Next steps | fixes in priority order, and the test that will verify them | ## Related skills - `hci-react-native`, `hci-flutter`, `hci-android-native`, `hci-ios-swiftui`: mobile implementation - `hci-web-accessibility`: web and WCAG - `hci-desktop-apps`, `hci-cli-ux`: desktop and command line - `hci-rtl-localization`: right-to-left and multilingual UI - `hci-microcopy`: wording of messages and labels - `hci-usability-testing`: verify with real users
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.