# UI Audit > Comprehensive UI component audit for Momentum CMS. Use when asked to audit, review, check, or validate a UI component. Checks Storybook stories, interaction tests, variants, kitchen sink integration, admin dashboard usage, accessibility, and responsive design (mobile-first). AUTOMATICALLY FIXES issues found and verifies with visual inspection. Triggers include "audit button", "review the card component", "check accessibility of tabs", or "/ui-audit ". Use when this capability is needed. - Skill: `tomevault-io/ui-audit` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/ui-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ui-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/ui-audit --- # UI Component Audit Comprehensive audit combining static code analysis with visual browser inspection via Storybook and kitchen sink. **This skill automatically FIXES issues and VERIFIES fixes visually.** ## ⚠️ CRITICAL: DO NOT SKIP VISUAL INSPECTION ⚠️ **Static code analysis is NOT sufficient.** You MUST perform visual inspection using browser automation (Claude-in-Chrome MCP or agent-browser). ### MANDATORY Visual Inspection Steps 1. **Storybook Screenshots** - Navigate to the component's stories and take screenshots of EVERY story variant in BOTH light and dark mode. If you don't have screenshots, you haven't completed the audit. 2. **Admin Portal Verification** - Navigate to the admin dashboard and verify how the component is actually used. Take screenshots showing real usage. Many bugs are only visible in real usage context. 3. **Responsive Testing** - Resize browser to mobile (375px), tablet (768px), and desktop (1280px) and screenshot each. ### Why This Matters **Code review alone misses these issues:** - Badge text invisible against card backgrounds (duplicate CSS variables) - Borders invisible due to matching colors - Icons not rendering in Storybook (missing icon provider) - Hover effects not working - Focus states not visible - Spacing issues only visible when rendered ### Verification Checklist (before completing audit) - [ ] Did I take screenshots of Storybook stories? - [ ] Did I verify both light AND dark mode visually? - [ ] Did I navigate to admin portal and see the component in use? - [ ] Did I test responsive breakpoints visually? - [ ] Can I visually confirm badges/text are readable? - [ ] Can I visually confirm hover effects work? **If any checkbox is unchecked, the audit is INCOMPLETE.** --- ## Requirements Summary 1. **Browser automation** for visual inspection - MUST take screenshots 2. **Auto-fix** - MUST fix issues found, not just report them 3. **Visual verification** - MUST verify fixes with browser screenshots ## Quick Start ```bash # Audit a component by name /ui-audit button /ui-audit data-table /ui-audit sidebar ``` ## Audit Workflow ### Phase 1: Component Discovery Find all component files: ```bash # Component location pattern libs/ui/src/lib// ├── .component.ts # Main component ├── .types.ts # Type definitions (optional) ├── .stories.ts # Storybook stories ├── .spec.ts # Unit tests └── index.ts # Barrel export (optional) ``` Verify export in `libs/ui/src/index.ts`. ### Phase 2: Static Code Analysis Check component follows Angular 21 + Momentum patterns: **Required Patterns:** - [ ] Uses `input()` / `input.required()` (not `@Input()`) - [ ] Uses `output()` (not `@Output()`) - [ ] Uses `computed()` for derived state - [ ] Uses `ChangeDetectionStrategy.OnPush` - [ ] Host styling via `host: { '[class]': 'hostClasses()' }` - [ ] Accepts `class` input for Tailwind customization - [ ] Selector prefix: `mcms-` - [ ] No `standalone: true` (default in Angular 21) ### Phase 3: Variant Coverage Extract variants from types and verify story coverage: ```typescript // Example: Button variants type ButtonVariant = 'primary' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link'; type ButtonSize = 'sm' | 'md' | 'lg' | 'icon'; ``` **Required Stories:** - [ ] One story per variant value - [ ] `AllVariants` or combined story showing all - [ ] `Sizes` story (if applicable) - [ ] `Disabled` story - [ ] Interaction story with `play` function ### Phase 4: Storybook Visual Inspection ⚠️ MANDATORY **DO NOT SKIP THIS PHASE.** Static code analysis cannot catch visual bugs. Start Storybook and capture screenshots of EVERY story: ```bash # Ensure Storybook is running nx storybook ui --port 4400 # Navigate and screenshot agent-browser open "http://localhost:4400/?path=/story/components-button--primary" agent-browser wait --load networkidle agent-browser screenshot ./audit/button-primary-light.png # Toggle dark mode (click theme button in toolbar) agent-browser snapshot -i agent-browser click @e agent-browser wait 500 agent-browser screenshot ./audit/button-primary-dark.png ``` **What to look for in screenshots:** - [ ] All text is readable (sufficient contrast) - [ ] Badges and labels are visible against backgrounds - [ ] Borders are distinguishable (not same color as background) - [ ] Icons render correctly (not empty boxes or missing) - [ ] Hover states show visual feedback - [ ] Focus rings are visible - [ ] Component layout matches expected design **If ANY of these are wrong, you have found a visual bug that code review missed!** ### Phase 5: Interaction Tests Verify interaction tests pass: ```bash # Run component tests nx test ui --testNamePattern="" # Check Storybook play functions work agent-browser open "http://localhost:4400/?path=/story/components-button--click-interaction" agent-browser wait --load networkidle # The play function should auto-run agent-browser screenshot ./audit/button-interaction.png ``` ### Phase 6: Kitchen Sink Integration ⚠️ MANDATORY **DO NOT SKIP THIS PHASE.** Components must be verified in the kitchen sink context. Verify component appears in kitchen sink: ```bash # Check import exists in kitchen-sink.page.ts grep -l "" libs/ui/src/lib/kitchen-sink/kitchen-sink.page.ts # Visual verification nx serve example-angular agent-browser open "http://localhost:4200/kitchen-sink" agent-browser wait --load networkidle agent-browser find text "Buttons" scrollintoview # or component section agent-browser screenshot ./audit/kitchen-sink-buttons.png ``` ### Phase 6.5: Admin Portal Usage Verification ⚠️ MANDATORY **DO NOT SKIP THIS PHASE.** Components must be verified in their actual usage context in the admin portal. Navigate to the admin portal and verify how the component is used in real context: ```bash # Using Claude-in-Chrome MCP mcp__claude-in-chrome__tabs_context_mcp({ createIfEmpty: true }) mcp__claude-in-chrome__navigate({ url: "http://localhost:4200/admin", tabId }) mcp__claude-in-chrome__computer({ action: "wait", duration: 2, tabId }) mcp__claude-in-chrome__computer({ action: "screenshot", tabId }) ``` **What to verify in Admin Portal:** - [ ] Component renders correctly in actual usage - [ ] Component works with real data (not just placeholder) - [ ] Interactions work (hover, click, expand/collapse) - [ ] Component integrates well with surrounding components - [ ] Dark mode toggle works and component looks correct **Common issues found in Admin Portal:** - Sidebar icons not rendering (icon provider missing) - Badge counts invisible (CSS variable conflict) - Hover effects not firing (event binding issues) - Focus states not visible (accessibility regression) - Layout breaking with real data lengths ### Phase 7: Responsive Testing Test at mobile-first breakpoints: ```bash # Mobile (iPhone) agent-browser set viewport 375 812 agent-browser screenshot ./audit/responsive-mobile.png # Tablet (iPad) agent-browser set viewport 768 1024 agent-browser screenshot ./audit/responsive-tablet.png # Desktop agent-browser set viewport 1280 800 agent-browser screenshot ./audit/responsive-desktop.png # Large Desktop agent-browser set viewport 1920 1080 agent-browser screenshot ./audit/responsive-desktop-lg.png ``` ### Phase 8: Visual Design Quality ⚠️ CRITICAL - DO NOT SKIP **THIS PHASE IS THE MOST IMPORTANT.** Code review and static analysis cannot catch visual bugs. Use browser automation to ACTUALLY LOOK at the UI. Many bugs are only visible when rendered. #### Theme CSS Variable Analysis Check for duplicate color values in dark mode (common bug): ```bash # Search for potentially identical values grep -A 30 ".dark {" libs/admin/src/styles/theme.css | grep "mcms-" ``` **Red Flags** - Multiple variables with identical HSL values: ```css /* BAD: These are all the same, badges will be invisible */ --mcms-card: 217 33% 17%; --mcms-secondary: 217 33% 17%; /* Same as card! */ --mcms-border: 217 33% 17%; /* Same as card! */ ``` **Required Color Differentiation:** | Variable | Purpose | Relative Lightness | |----------|---------|-------------------| | `--mcms-card` | Base | 15% | | `--mcms-secondary` | Badges | 25% (+10) | | `--mcms-muted` | Subtle BG | 20% (+5) | | `--mcms-accent` | Hover | 22% (+7) | | `--mcms-border` | Borders | 22% (+7) | #### Visual Verification with Browser ```typescript // Navigate to admin dashboard mcp__claude-in-chrome__navigate({ url: "http://localhost:4200/admin", tabId }) mcp__claude-in-chrome__computer({ action: "wait", duration: 2, tabId }) mcp__claude-in-chrome__computer({ action: "screenshot", tabId }) // Test hover effect on cards mcp__claude-in-chrome__computer({ action: "hover", coordinate: [400, 240], tabId }) mcp__claude-in-chrome__computer({ action: "screenshot", tabId }) ``` **What to Look For:** - [ ] Badge counts visible against card backgrounds - [ ] Card borders distinguishable from background - [ ] Hover effects provide visual feedback - [ ] Text contrast is adequate - [ ] Visual hierarchy is clear #### Card/Component Quality Checks - [ ] Cards have hover effects with transitions - [ ] Shadows are visible (not too subtle) - [ ] Border radius is consistent (0.75rem recommended) - [ ] Button spacing is adequate (gap-3 minimum) #### Dashboard/Page Layout Quality - [ ] Header has proper hierarchy (text-4xl + subtitle) - [ ] Sections have headers (uppercase, tracking-wider) - [ ] Empty states have icons and helpful text - [ ] Grid responsive breakpoints work (1/2/3 columns) ### Phase 9: UX Design Quality Review ⚠️ CRITICAL - DO NOT SKIP **Ask yourself: "Would I ship this?"** If the answer is no, the audit FAILS. This phase catches design quality issues that technical audits miss. Compare against industry standards and ask critical UX questions. #### Navigation Design Checklist - [ ] **Icons present** - Every nav item has an icon (not just text) - [ ] **Active state clear** - Current page has strong visual indicator (left border, background, etc.) - [ ] **Hover states work** - Items respond visually on hover - [ ] **Consistent spacing** - No awkward gaps or cramped areas #### Visual Hierarchy Checklist - [ ] **Brand presence** - Logo/app name is prominent, not lost - [ ] **Section headers** - Clear separation between content groups - [ ] **Empty space intentional** - No large unexplained gaps - [ ] **Information density** - Not too sparse, not too cramped #### Industry Comparison Compare against established admin panels. Ask: - [ ] Does our sidebar match Payload CMS quality? (icons, active states, collapsible sections) - [ ] Does it match Strapi? (clean hierarchy, good spacing) - [ ] Does it match Vercel dashboard? (minimal but complete) **If our UI is notably worse than these, the audit FAILS.** #### The "Ship It" Test Look at the screenshot and honestly answer: - [ ] Would I be proud to show this to a client? - [ ] Does it look like a finished product or a prototype? - [ ] Are there obvious missing elements (icons, borders, indicators)? - [ ] Is there wasted space that makes it look incomplete? **If ANY answer is negative, document the issues and FIX THEM before completing the audit.** #### Common Design Quality Failures | Issue | What It Looks Like | Fix | | ----------------- | ------------------------------ | --------------------------------------- | | No icons | Plain text nav items | Add Lucide/Heroicons to each item | | Weak active state | Subtle background only | Add left border accent + stronger bg | | Empty space | Big gap between nav and footer | Add more nav items or collapse spacing | | No brand | App name same size as nav | Make logo/name larger, add icon | | Invisible borders | Sidebar bleeds into content | Increase border-sidebar-border contrast | ### Phase 10: CDK & ARIA Primitives Audit Verify component uses Angular CDK and @angular/aria primitives correctly. **Responsive Detection (CDK Layout):** - [ ] Uses `BreakpointObserver` for responsive detection (NOT `window.innerWidth`) - [ ] Breakpoints align between CSS (Tailwind) and JS (CDK) - [ ] SSR-safe with `isPlatformBrowser` check **Bad:** ```typescript ngOnInit(): void { this.isMobile = window.innerWidth < 768; // WRONG } ``` **Good:** ```typescript readonly isMobile = toSignal( this.breakpointObserver.observe(['(max-width: 767px)']) .pipe(map(result => result.matches)), { initialValue: false } ); ``` **Focus Management (CDK A11y):** - [ ] Uses `cdkTrapFocus` for modals and drawers - [ ] Uses `FocusMonitor` for focus tracking - [ ] Uses `LiveAnnouncer` for screen reader announcements **Positioned Content (CDK Overlay):** - [ ] Uses CDK Overlay for dropdowns, tooltips, popovers (NOT custom CSS positioning) - [ ] Handles backdrop click to close - [ ] Handles Escape key to close **ARIA Directives (@angular/aria):** - [ ] Uses `hostDirectives` pattern for semantic behavior - [ ] Uses Menu/MenuItem for dropdown navigation - [ ] Uses Tabs/TabList for tab navigation - [ ] Uses Accordion for collapsible sections **Flex Child Wrappers:** - [ ] Wrapper components use `host: { class: 'shrink-0 h-full' }` for proper flex sizing - [ ] Parent flex layouts properly pass height to children - [ ] Avoid `class="contents"` - it breaks height inheritance See [references/angular-primitives.md](references/angular-primitives.md) for complete patterns. ### Phase 10.5: Debugging Common Layout Issues **⚠️ Dev Server Caching:** Angular dev server may cache stale library code. If fixes aren't appearing: ```bash # Kill port and restart lsof -i :4200 | awk 'NR>1 {print $2}' | xargs kill -9 nx serve example-angular ``` **Sidebar Footer Not at Bottom:** | Symptom | Likely Cause | Fix | | --------------------------------------- | ----------------------------------- | ----------------------------------------- | | Footer in middle, nav stretches | ng-content not wrapped | Add wrapper divs with `shrink-0`/`flex-1` | | Footer at bottom only when content tall | Using `min-h-screen` | Change to `h-screen` on aside | | Entire sidebar has wrong height | Parent wrapper uses `contents` | Change to `shrink-0` | | Footer moves when content grows | Content not using `overflow-y-auto` | Add `overflow-y-auto` to content div | **Key Pattern for Sidebar Flex Layout:** ```html ``` **Why wrapper divs are required for ng-content:** - `ng-content` alone creates NO DOM element - Flex classes (`shrink-0`, `flex-1`) need an element to apply to - Wrap each `ng-content select="..."` in a div with appropriate flex classes ### Phase 11: Accessibility Audit Check accessibility requirements: **ARIA Attributes:** - [ ] Proper `role` attribute (if not native element) - [ ] `aria-label` for non-text content - [ ] `aria-expanded` for expandable elements - [ ] `aria-selected` for selectable items - [ ] `aria-disabled` for disabled state **Focus Management:** - [ ] Visible focus ring (`:focus-visible`) - [ ] Logical tab order - [ ] Keyboard navigation (Arrow keys for lists) **Color Contrast:** - [ ] Minimum 4.5:1 for text - [ ] Focus indicators visible in both themes ### Phase 12: Auto-Fix Issues **CRITICAL: This skill MUST automatically fix issues, not just report them.** For each issue found, apply the appropriate fix: #### Visual Design Fixes **Fixing invisible badges (duplicate CSS variables):** ```css /* Before - in theme.css .dark block */ --mcms-secondary: 217 33% 17%; /* Same as card! */ /* After - distinct from card */ --mcms-secondary: 215 28% 25%; /* Visible badge */ ``` **Adding card hover effects:** ```typescript // Before styles: ` :host { box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05); } `, // After - with hover effect styles: ` :host { box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1); transition: box-shadow 0.2s ease, border-color 0.2s ease; } :host(:hover) { box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1); } `, ``` **Improving dashboard layout:** ```typescript // Before

Dashboard

// After - proper hierarchy with sections

Dashboard

Manage your content

Collections

...
``` #### Accessibility Fixes **Missing `aria-label` on icon buttons:** ```typescript // Before // After - ADD aria-label ``` **Missing `aria-hidden` on decorative icons:** ```typescript // Before // After - ADD aria-hidden="true"