UI Audit

AI skill for automated UI audits. Evaluate interfaces against proven UX principles for visual hierarchy, accessibility, cognitive load, navigation, and more. Based on Making UX Decisions by Tommy Geoco.

Security Scan

This is an instruction-only UI audit skill that is internally consistent with its stated purpose: it uses local reference files and checklists, requires no credentials or installs, and does not ask for unrelated system access.

Purpose & Capability

Name/description (UI audit) match the provided contents: SKILL.md and many references are design checklists and frameworks. The package.json, README, and references all align with an auditing/checklist skill. There are no unrelated credentials, binaries, or platform requirements.

Instruction Scope

Runtime instructions are limited to loading the included reference files, following checklists, and generating audit reports based on user-supplied designs (e.g., Figma URLs). The SKILL.md does not instruct the agent to read system files, environment variables, or to transmit data to unexpected external endpoints.

Install Mechanism

No install spec and no code files to execute; the skill is instruction-only. package.json exists (for distribution) but there is no install script that pulls remote artifacts or executes code beyond a harmless postinstall echo. Low install risk.

Credentials

The skill requests no environment variables, credentials, or config paths. All data the skill would act on is either included (reference files) or provided by the user (design URLs/files), which is appropriate for its purpose.

Persistence & Privilege

always:false (not force-included). disable-model-invocation:false is the platform default and acceptable here; nothing in the skill requests elevated or persistent privileges or modifies other skills or system settings.

Assessment

This skill appears coherent and low-risk: it only contains local UX guidance files and no credential or install requirements. Before using: (1) verify the author/homepage (audit.uxtools.co / GitHub link in package.json) if provenance matters to you; (2) avoid pasting private or sensitive design URLs/files unless you trust the agent/environment (reports may include sensitive UI content); (3) if you install via npm or a skills registry, prefer installing from the official repo or registry to avoid tampered packages; (4) review any generated audit output before sharing externally. If you need higher assurance, confirm the GitHub repository and npm package contents match these files.

UI Audit Skill

Evaluate interfaces against proven UX principles. Based on Making UX Decisions by Tommy Geoco.

When to Use This Skill

• Making UI/UX design decisions under time pressure
• Evaluating design trade-offs with business context
• Choosing appropriate UI patterns for specific problems
• Reviewing designs for completeness and quality
• Structuring design thinking for new interfaces

Core Philosophy

Speed ≠ Recklessness. Designing quickly is not automatically reckless. Recklessly designing quickly is reckless. The difference is intentionality.

The 3 Pillars of Warp-Speed Decisioning

1. Scaffolding — Rules you use to automate recurring decisions
2. Decisioning — Process you use for making new decisions
3. Crafting — Checklists you use for executing decisions

Quick Reference Structure

Foundational Frameworks

• references/00-core-framework.md — 3 pillars, decisioning workflow, macro bets
• references/01-anchors.md — 7 foundational mindsets for design resilience
• references/02-information-scaffold.md — Psychology, economics, accessibility, defaults

Checklists (Execution)

• references/10-checklist-new-interfaces.md — 6-step process for designing new interfaces
• references/11-checklist-fidelity.md — Component states, interactions, scalability, feedback
• references/12-checklist-visual-style.md — Spacing, color, elevation, typography, motion
• references/13-checklist-innovation.md — 5 levels of originality spectrum

Patterns (Reusable Solutions)

• references/20-patterns-chunking.md — Cards, tabs, accordions, pagination, carousels
• references/21-patterns-progressive-disclosure.md — Tooltips, popovers, drawers, modals
• references/22-patterns-cognitive-load.md — Steppers, wizards, minimalist nav, simplified forms
• references/23-patterns-visual-hierarchy.md — Typography, color, whitespace, size, proximity
• references/24-patterns-social-proof.md — Testimonials, UGC, badges, social integration
• references/25-patterns-feedback.md — Progress bars, notifications, validation, contextual help
• references/26-patterns-error-handling.md — Form validation, undo/redo, dialogs, autosave
• references/27-patterns-accessibility.md — Keyboard nav, ARIA, alt text, contrast, zoom
• references/28-patterns-personalization.md — Dashboards, adaptive content, preferences, l10n
• references/29-patterns-onboarding.md — Tours, contextual tips, tutorials, checklists
• references/30-patterns-information.md — Breadcrumbs, sitemaps, tagging, faceted search
• references/31-patterns-navigation.md — Priority nav, off-canvas, sticky, bottom nav

Usage Instructions

For Design Decisions

1. Read 00-core-framework.md for the decisioning workflow
2. Identify if this is a recurring decision (use scaffold) or new decision (use process)
3. Apply the 3-step weighing: institutional knowledge → user familiarity → research

For New Interfaces

1. Follow the 6-step checklist in 10-checklist-new-interfaces.md
2. Reference relevant pattern files for specific UI components
3. Use fidelity and visual style checklists to enhance quality

For Pattern Selection

1. Identify the core problem (chunking, disclosure, cognitive load, etc.)
2. Load the relevant pattern reference
3. Evaluate benefits, use cases, psychological principles, and implementation guidelines

Decision Workflow Summary

When facing a UI decision:

1. WEIGH INFORMATION
   ├─ What does institutional knowledge say? (existing patterns, brand, tech constraints)
   ├─ What are users familiar with? (conventions, competitor patterns)
   └─ What does research say? (user testing, analytics, studies)

2. NARROW OPTIONS
   ├─ Eliminate what conflicts with constraints
   ├─ Prioritize what aligns with macro bets
   └─ Choose based on JTBD support

3. EXECUTE
   └─ Apply relevant checklist + patterns

Macro Bet Categories

Companies win through one or more of:

Bet	Description	Design Implication
Velocity	Features to market faster	Reuse patterns, find metaphors in other markets
Efficiency	Manage waste better	Design systems, reduce WIP
Accuracy	Be right more often	Stronger research, instrumentation
Innovation	Discover untapped potential	Novel patterns, cross-domain inspiration

Always align micro design bets with company macro bets.

Key Principle: Good Design Decisions Are Relative

A design decision is "good" when it:

• Supports the product's jobs-to-be-done
• Aligns with company macro bets
• Respects constraints (time, tech, team)
• Balances user familiarity with differentiation needs

There is no universally correct UI solution—only contextually appropriate ones.

---

Generating Audit Reports

When asked to audit a design, generate a comprehensive report. Always include these sections:

Required Sections (always include)

1. Visual Hierarchy — Headings, CTAs, grouping, reading flow, type scale, color hierarchy, whitespace
2. Visual Style — Spacing consistency, color usage, elevation/depth, typography, motion/animation
3. Accessibility — Keyboard navigation, focus states, contrast ratios, screen reader support, touch targets

Contextual Sections (include when relevant)

4. Navigation — For multi-page apps: wayfinding, breadcrumbs, menu structure, information architecture
5. Usability — For interactive flows: discoverability, feedback, error handling, cognitive load
6. Onboarding — For new user experiences: first-run, tutorials, progressive disclosure
7. Social Proof — For landing/marketing pages: testimonials, trust signals, social integration
8. Forms — For data entry: labels, validation, error messages, field types

Audit Output Format

{
  "title": "Design Name — Screen/Flow",
  "project": "Project Name",
  "date": "YYYY-MM-DD",
  "figma_url": "optional",
  "screenshot_url": "optional - URL to screenshot",
  
  "macro_bets": [
    { "category": "velocity|efficiency|accuracy|innovation", "description": "...", "alignment": "strong|moderate|weak" }
  ],
  
  "jtbd": [
    { "user": "User Type", "situation": "context without 'When'", "motivation": "goal without 'I want to'", "outcome": "benefit without 'so I can'" }
  ],
  
  "visual_hierarchy": {
    "title": "Visual Hierarchy",
    "checks": [
      { "label": "Check name", "status": "pass|warn|fail|na", "notes": "Details" }
    ]
  },
  "visual_style": { ... },
  "accessibility": { ... },
  
  "priority_fixes": [
    { "rank": 1, "title": "Fix title", "description": "What and why", "framework_reference": "XX-filename.md → Section Name" }
  ],
  
  "notes": "Optional overall observations"
}

Checks Per Section (aim for 6-10 each)

Visual Hierarchy: heading distinction, primary action clarity, grouping/proximity, reading flow, type scale, color hierarchy, whitespace usage, visual weight balance

Visual Style: spacing consistency, color palette adherence, elevation/shadows, typography system, border/radius consistency, icon style, motion principles

Accessibility: keyboard operability, visible focus, color contrast (4.5:1), touch targets (44px), alt text, semantic markup, reduced motion support

Navigation: clear current location, predictable menu behavior, breadcrumb presence, search accessibility, mobile navigation pattern

Usability: feature discoverability, feedback on actions, error prevention, recovery options, cognitive load management, loading states