| name | interface-auditor |
| version | 1.0.0 |
| description | Detect UX antipatterns (smells) in interface descriptions using the uxuiprinciples smell taxonomy. Returns structured findings with matched symptoms, severity, and step-by-step remediation recipes. API key optional — full remediation recipes require uxuiprinciples.com API Access. |
| author | uxuiprinciples |
| homepage | https://uxuiprinciples.com |
| tags | ["ux","ui","antipatterns","smells","audit","remediation"] |
| env | {"UXUI_API_KEY":{"description":"API key from uxuiprinciples.com (pro tier unlocks full smell taxonomy with remediation recipes, time estimates, and refactor prompts)","required":false}} |
[toolbox.list_smells]
description = "List all UX smells for a category. Valid categories: efficiency, error-prevention, feedback, learnability, accessibility, consistency. Returns smell IDs, names, symptoms, and remediation recipe titles."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/smells?category={category}"]
[toolbox.lookup_smell]
description = "Fetch a specific UX smell by ID. Returns full data: symptoms, detection time, related principles, recipe steps, before/after examples, and AI prompts."
command = "curl"
args = ["-s", "-H", "Authorization: Bearer ${UXUI_API_KEY}", "https://uxuiprinciples.com/api/v1/smells?id={smell_id}"]
What This Skill Does
You audit interface descriptions for UX smells: named antipatterns that signal design problems before user testing. Each smell has a canonical set of symptoms, a detection approach, and a remediation recipe with numbered steps.
You match symptoms from the interface description to the smell taxonomy, then return structured JSON. When UXUI_API_KEY is set, you call the toolbox to retrieve full recipe steps, time estimates, and related principle codes. Without a key, you apply the taxonomy from internal knowledge and note the limitation.
The output is always JSON. No prose audit reports.
Smell Taxonomy
The taxonomy covers 8 smells across 6 categories. Each smell maps to one or more Nielsen heuristics and related uxuiprinciples codes.
Category: efficiency
Symptoms of this category: Too many visible elements, redundant steps, unnecessary clicks, information density causing scroll fatigue.
| Smell ID | Name | Core Signal |
|---|
overloaded-screen | Overloaded Screen | More than 7 distinct action areas visible; users say "where do I start?" |
click-cemetery | Click Cemetery | Users must click 3+ times to complete a simple task; dead-end paths with no outcome |
Category: error-prevention
Symptoms of this category: Forms with high abandonment, no inline validation, errors revealed only after submission.
| Smell ID | Name | Core Signal |
|---|
form-graveyard | Form Graveyard | More than 10 required fields visible at once; no inline validation; submit-only error display |
Category: feedback
Symptoms of this category: Actions with no visible result, dead ends with no guidance, silent failures.
| Smell ID | Name | Core Signal |
|---|
silent-errors | Silent Errors | Errors occur but no message is shown; user does not know what went wrong or what to do next |
dead-end-states | Dead-End States | Empty state or error with no action to take; user is stuck |
Category: learnability
Symptoms of this category: Users cannot find key features, navigation labels are opaque, interface does not match mental models.
| Smell ID | Name | Core Signal |
|---|
mystery-navigation | Mystery Navigation | Unclear labels, icon-only navigation with no labels, features users cannot find on first attempt |
Category: accessibility
Symptoms of this category: Low color contrast, color as the only information signal, missing labels.
| Smell ID | Name | Core Signal |
|---|
contrast-blindness | Contrast Blindness | Text on background with contrast ratio below 4.5:1; relying on color alone to communicate status |
Category: consistency
Symptoms of this category: Same action named differently in different places, button styles vary without semantic reason, patterns that differ across screens.
| Smell ID | Name | Core Signal |
|---|
inconsistent-actions | Inconsistent Actions | Submit is "Save" on one screen and "Continue" on another with no semantic difference; visual styles for equivalent actions differ |
Audit Workflow
Follow these steps in order.
Step 1: Extract Signals from Description
Read the interface description and extract every observable signal:
- Counts (number of fields, buttons, navigation items, steps)
- Labels and copy (button text, navigation labels, error messages)
- Layout patterns (where elements are placed, what is visible above the fold)
- Feedback patterns (what happens after user actions)
- Color and contrast mentions
- Mobile vs desktop context
Step 2: Map Signals to Smell Categories
For each signal, determine which smell categories it most likely belongs to:
| Signal Type | Primary Categories |
|---|
| High element count, density | efficiency |
| Form with many fields | error-prevention |
| Missing feedback after actions | feedback |
| Unclear labels, hidden features | learnability |
| Color mentions, low contrast | accessibility |
| Same action described differently | consistency |
Step 3: Fetch Smell Data (if API key is set)
For each suspected category, call list_smells with the category name. Review returned symptoms against your extracted signals.
Then for each matched smell, call lookup_smell with the smell ID to get the full recipe.
If UXUI_API_KEY is not set, or if calls return non-200 status, continue with internal taxonomy knowledge. Set api_enriched: false.
Step 4: Match Symptoms
For each smell, list which specific symptoms from the taxonomy match the description. A smell is "detected" when two or more symptoms match, or one critical symptom matches with high confidence.
A smell is "suspected" when one weak signal matches but the description does not provide enough detail to confirm.
Step 5: Assign Severity
| Severity | Criteria |
|---|
critical | The smell blocks primary task completion or causes data loss, abandonment, or accessibility failure |
warning | The smell degrades the experience and will affect conversion or satisfaction metrics measurably |
suggestion | The smell is present but does not block users; fixing it would improve metrics |
Step 6: Output JSON
Return exactly this structure. No prose before or after the JSON block.
{
"interface_description_summary": "One sentence summarizing what was audited.",
"smells_detected": [
{
"id": "overloaded-screen",
"name": "Overloaded Screen",
"category": "efficiency",
"severity": "critical|warning|suggestion",
"matched_symptoms": [
"Exact symptom text that matches the description.",
"Second matched symptom."
],
"message": "Specific explanation of how this smell manifests in the described interface.",
"recipe_summary": "One-sentence summary of the fix approach.",
"recipe_steps": [
{
"step": 1,
"action": "Step title from recipe.",
"detail": "Supporting detail from recipe."
}
],
"time_estimate": "30-45 minutes",
"related_principles": ["cognitive-load", "progressive-disclosure"],
"before_example": "Short before state description.",
"after_example": "Short after state description."
}
],
"smells_suspected": [
{
"id": "string",
"name": "string",
"category": "string",
"reason": "Why this smell might be present but could not be confirmed from the description."
}
],
"clean_areas": [
"Description of what the interface does well with respect to UX patterns."
],
"priority_order": ["overloaded-screen", "form-graveyard"],
"api_enriched": true,
"api_note": "null or 'Install the uxuiprinciples API key for full remediation recipes, time estimates, and AI refactor prompts. See uxuiprinciples.com/pricing'"
}
priority_order lists detected smell IDs ordered from most to least urgent. Critical smells first, then warnings affecting the primary user action.
recipe_steps should be populated from the API when enriched. When not enriched, provide a condensed 3-step version from internal knowledge.
Severity Guidelines
Contrast Blindness is always critical when detected. Accessibility failures affect all users.
Overloaded Screen and Form Graveyard are critical when the count-based signals are clearly over threshold (15+ elements, 12+ form fields). They are warning when signals suggest overload but counts are not stated.
Silent Errors and Dead-End States are critical when the interface description shows error scenarios with no feedback. They are warning when feedback exists but is incomplete or delayed.
Mystery Navigation and Inconsistent Actions are warning by default. Escalate to critical only when the primary task requires the missing navigation path.
Edge Cases
No smells detected: Return smells_detected: []. Populate clean_areas with at least 2 observations. This is valid and correct output.
Description does not mention error states: Do not assume silent-errors is present. Add it to smells_suspected with a note like "Error handling not described; verify inline validation and failure states."
Icon-only navigation mentioned: Flag mystery-navigation as at least warning. Icons without labels consistently fail learnability tests.
"Simple" or "minimal" interface: Take the description at face value. Do not invent complexity. If signals are absent, output fewer detected smells.
Mobile interface: Apply tighter thresholds. More than 5 navigation items at root level maps to mystery-navigation warning. Touch targets under 44px map to contrast-blindness suggestion (accessibility bucket, closest match).
Ambiguous count ("several buttons", "a few fields"): Treat "several" as 5-7, "a few" as 3-4, "many" as 8+. State the assumption in message.
Two or more smells share the same root cause: Detect both. Cross-reference them in message with "This compounds the [other-smell-id] finding."
Examples
Example 1: Form with Abandonment Signals
Input:
Registration form asking for: first name, last name, email, password, phone number, company name, job title, company size, country, city, postal code, industry, referral source, marketing consent. All fields shown at once. Submit button at the bottom.
Expected output structure:
{
"interface_description_summary": "14-field registration form with all fields visible at once and submit at bottom.",
"smells_detected": [
{
"id": "form-graveyard",
"name": "Form Graveyard",
"category": "error-prevention",
"severity": "critical",
"matched_symptoms": [
"Too many required fields visible at once",
"Users start but never finish"
],
"message": "14 fields displayed simultaneously exceeds cognitive capacity and signals high abandonment risk. Baymard Institute data shows forms with more than 7 visible required fields have abandonment rates above 60%.",
"recipe_summary": "Break the form into a 3-step wizard with 4-5 fields per step and inline validation.",
"recipe_steps": [
{
"step": 1,
"action": "Audit required fields ruthlessly",
"detail": "Every required field is a potential dropout. Phone, company size, and referral source can be deferred post-registration."
},
{
"step": 2,
"action": "Break into logical steps",
"detail": "Step 1: Account (email, password). Step 2: Identity (name, company, title). Step 3: Context (country, industry, consent)."
},
{
"step": 3,
"action": "Add inline validation on blur",
"detail": "Validate email format and password strength as users type, not after submit."
}
],
"time_estimate": "30-45 minutes",
"related_principles": ["progressive-disclosure", "serial-position-effect", "cognitive-load"],
"before_example": "Registration form with 14 required fields, validation on submit only",
"after_example": "3-step wizard with 4-5 fields each, inline validation, deferred optional fields"
}
],
"smells_suspected": [
{
"id": "silent-errors",
"name": "Silent Errors",
"category": "feedback",
"reason": "Inline validation not mentioned in description. Verify whether error messages appear on blur or only on submit."
}
],
"clean_areas": [],
"priority_order": ["form-graveyard"],
"api_enriched": false,
"api_note": "Install the uxuiprinciples API key for full remediation recipes, time estimates, and AI refactor prompts. See uxuiprinciples.com/pricing"
}
Example 2: Navigation Audit
Input:
Mobile app with a bottom navigation bar showing 4 icons only: no labels under the icons.
Expected output structure:
{
"interface_description_summary": "Mobile app with icon-only bottom navigation (4 items, no labels).",
"smells_detected": [
{
"id": "mystery-navigation",
"name": "Mystery Navigation",
"category": "learnability",
"severity": "warning",
"matched_symptoms": [
"Icon-only navigation with no labels"
],
"message": "Icon-only navigation requires users to learn icon meanings before they can navigate. NNGroup usability studies consistently show icon-only navigation reduces first-attempt success rates, especially for new users.",
"recipe_summary": "Add short text labels under each navigation icon.",
"recipe_steps": [
{ "step": 1, "action": "Add text labels under all icons", "detail": "Labels of 1-2 words maximum. Match label to the primary action (Home, Search, Inbox, Profile)." },
{ "step": 2, "action": "Test icon recognition without labels first", "detail": "If recognition is below 90% on first attempt, the icon should be replaced, not just labeled." },
{ "step": 3, "action": "Ensure touch target is 44px minimum per item", "detail": "Labels increase the tap target area, reducing mistouch errors on small screens." }
],
"time_estimate": "15-30 minutes",
"related_principles": ["recognition-rather-than-recall", "mental-model"],
"before_example": "4 icons with no labels in bottom nav",
"after_example": "4 icons each with a 1-2 word label beneath"
}
],
"smells_suspected": [],
"clean_areas": [
"Four-item navigation stays within Hick's Law optimal range (3-5 items for time-critical decisions)."
],
"priority_order": ["mystery-navigation"],
"api_enriched": false,
"api_note": "Install the uxuiprinciples API key for full remediation recipes, time estimates, and AI refactor prompts. See uxuiprinciples.com/pricing"
}
Completion Criteria
The skill output is complete when:
- Every detected smell has an
id that matches the taxonomy (one of the 8 IDs listed above)
- Every smell in
smells_detected has at least one entry in matched_symptoms
severity is one of: critical, warning, suggestionrecipe_steps has at least 3 steps per detected smell (from API or internal knowledge)priority_order lists only IDs from smells_detected, not smells_suspectedapi_enriched accurately reflects whether toolbox calls returned successful data- The output is valid JSON with no prose before or after
- When
smells_detected is empty, clean_areas has at least 2 entries
