UI Doctor

Skill: UI Doctor

Audit and review application UI for IDS compliance, accessibility, usability, and cognitive load. This skill helps AI agents perform comprehensive UI reviews covering component usage, accessibility (WCAG), usability heuristics (Nielsen's 10), cognitive load, and progressive disclosure — then produce actionable reports with prioritised recommendations.

When to Use

Activate this skill when the user says things like:

• "Review this page / component / file for accessibility"
• "Check the usability of this UI"
• "Audit this for IDS compliance"
• "This feels like too much cognitive load"
• "Are we following IDS guidelines?"
• "Check for a11y issues"
• "Review this UI"
• "Is this form accessible?"
• "Can you do a UX review?"

Or more generally:

• Reviewing application UI code for IDS compliance
• Validating accessibility (WCAG 2.1 AA)
• Assessing usability and cognitive load
• Evaluating design token usage and consistency
• Generating a UI health report with a compliance score
• Providing recommendations to improve UX, accessibility, and IDS adoption

Audit Modes

Default: Quick UX Review. Use this unless the user specifically asks for accessibility or full compliance. Escalate to a more thorough mode if the quick review reveals significant issues.

Quick UX Review (default)

Use when the user asks for a general UI review, usability check, or "does this look right?"

1. Cognitive load & information architecture — Is the UI overwhelming? Are there too many items, options, or actions visible at once?
2. Usability heuristics — Evaluate against Nielsen's 10 (see audit checklist § Usability Heuristics)
3. Button hierarchy & layout consistency — One primary per section, consistent spacing
4. Quick component scan — Are obvious raw HTML elements used where IDS components exist?

Accessibility Review

Use when the user asks about a11y, WCAG, keyboard navigation, or screen reader support.

1. Form accessibility — Labels, required indicators, validation messages, id/htmlFor pairing
2. Keyboard & focus — Skip links, focus trapping in modals/slideouts, visible focus indicators
3. Screen reader — ARIA landmarks, dynamic content announcements, accessible names on interactive elements
4. Colour & contrast — WCAG AA contrast ratios, no reliance on colour alone
5. Cognitive load — Progressive disclosure, information density (see audit checklist § Cognitive Load)

Full Compliance Audit

Use when the user asks for a complete IDS audit or compliance report.

1. Run all checklist sections from the audit checklist
2. Validate component usage against replacement tables
3. Check design token usage and Provider/CSS setup
4. Evaluate patterns (forms, loading, navigation)
5. Assess usability and cognitive load
6. Generate a full report using the report template

Scoped Audits

If the user asks about a specific file, component, or page, focus the audit on that scope only. Apply the same checklist items but only to the files in question. Do not scan the entire application unless asked.

Example: "Check the accessibility of UserProfileForm.tsx" → run the Accessibility Review mode on that single file.

Audit Scope

Before starting, determine which files to scan.

Files to Scan

• All .tsx, .jsx, .ts, .js files in src/ (or the application source directory)
• CSS/SCSS/styled-component files for hardcoded design values
• Application entry point(s) for Provider and CSS import checks

Important: Always trace the component tree from the actual mount point (e.g. main.tsx, index.tsx) before evaluating Provider & Setup. The entry point may not be a route file — it could be a custom element wrapper, a shadow DOM host, or a separate bootstrap file that renders the router. Do not penalise missing Provider/CSS if a parent entry point already handles it.

Files to Exclude

• Test files (*.test.tsx, *.spec.tsx, __tests__/) — test mocks may legitimately use raw HTML
• Storybook stories (*.stories.tsx) — may intentionally show raw HTML for comparison
• Config files (*.config.ts, *.config.js) — not UI code
• Type definitions (*.d.ts) — no runtime UI code
• Third-party code (node_modules/, vendored libraries) — outside application control
• Build output (dist/, build/) — generated code

Version-Aware Auditing

IDS is currently on version 6. When auditing:

• Check the installed version — package.json for @iress-oss/ids-components
• v6 — Apply all rules as-is
• v5 — Flag v5-specific patterns as "migration opportunities" (key differences: IressForm uses rules prop, react-hook-form is a peer dependency, form state via useWatch/ref)
• Pre-v5 — Flag as requiring major migration; prioritise Provider/CSS setup first
• Always note the version in the audit report header

Audit Process

1. Evaluate UX, Accessibility & Cognitive Load

Start with what users experience — assess the UI's usability, accessibility, and information density before checking component compliance.

a. Usability Heuristics (Nielsen's 10)

Evaluate the application against all 10 heuristics. Each has IDS-specific guidance in the audit checklist § Usability Heuristics. Key areas:

1. Visibility of system status — Loading states use IressLoading (preferred) or IressSkeleton (for custom content placeholder patterns); active states visible on tabs, nav, breadcrumbs
2. Match between system and real world — Labels use plain language; icons paired with text; status colours follow conventions
3. User control and freedom — Modals/slideouts dismissible; destructive actions require confirmation; forms have cancel
4. Consistency and standards — All components from IDS; tokens used consistently; same action = same pattern
5. Error prevention — Declarative rules validation; required fields marked; constraints communicated via hint
6. Recognition rather than recall — Persistent navigation; visible breadcrumbs; labels always visible (not just placeholders)
7. Flexibility and efficiency — Keyboard shortcuts; skip links; searchable selects; autocomplete
8. Aesthetic and minimalist design — Clear visual hierarchy; consistent spacing; one primary action per section
9. Help users recognise/recover from errors — Human-readable validation; inline errors; IressValidationSummary for long forms
10. Help and documentation — Hint text; tooltips for non-obvious UI; placeholder supplementary to labels

b. Cognitive Load & Information Architecture

Evaluate whether the UI presents too much information or too many choices at once.

• Item count thresholds — Menus/dropdowns with >10 items should use searchable; long forms (>8 fields) should use IressForm pattern="long"; navigation with >7 top-level items should use grouping
• Progressive disclosure — Use IressExpander or IressTabSet to hide secondary content until needed; multi-step flows break complex tasks into stages
• Information density — Is the screen overwhelming? Use IressCard/IressPanel to group related content; use IressStack with adequate spacing
• Batch action safety — Bulk operations (select-all + delete) need explicit confirmation via IressModal; show count of affected items
• Focus management after state changes — After modal close, focus returns to trigger; after item deletion, focus moves to next/previous item; after form submission, focus moves to result or error
• Visual hierarchy — Primary content is prominent; secondary content is de-emphasised; use IressText textStyle to establish hierarchy

c. Accessibility (WCAG 2.1 AA)