interface-auditor

[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 UXUIAPIKEY 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.

Category: error-prevention

Symptoms of this category: Forms with high abandonment, no inline validation, errors revealed only after submission.

Category: feedback

Symptoms of this category: Actions with no visible result, dead ends with no guidance, silent failures.

Category: learnability

Symptoms of this category: Users cannot find key features, navigation labels are opaque, interface does not match mental models.

Category: accessibility

Symptoms of this category: Low color contrast, color as the only information signal, missing labels.

Category: consistency

Symptoms of this category: Same action named differently in different places, button styles vary without semantic reason, patterns that differ across screens.

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:

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 UXUIAPIKEY 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

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/en/checkout'"
}

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 smellsdetected: []. Populate cleanareas 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/en/checkout"
}

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/en/checkout"
}

Completion Criteria

The skill output is complete when:

1. Every detected smell has an id that matches the taxonomy (one of the 8 IDs listed above)
2. Every smell in smellsdetected has at least one entry in matchedsymptoms
3. severity is one of: critical, warning, suggestion
4. recipe_steps has at least 3 steps per detected smell (from API or internal knowledge)
5. priorityorder lists only IDs from smellsdetected, not smells_suspected
6. api_enriched accurately reflects whether toolbox calls returned successful data
7. The output is valid JSON with no prose before or after
8. When smellsdetected is empty, cleanareas has at least 2 entries