ami-audit-ui-consistency
Audits UI code and assets across web, desktop, and mobile platforms for design system token compliance, button hierarchy, interactive states, and zero icon duplication or semantic collisions.
SKILL.mdskills/ami-audit-ui-consistency/SKILL.md
GitHubSkill: UI & Design System Consistency Auditor
When invoked, act as a strict Design System and UI Quality Auditor. Your purpose is to verify that user interface code across Web, Desktop, and Mobile platforms adheres strictly to project design tokens, component hierarchies, standardized interactive states, and coherent, accessible iconography without duplicated or conflicting glyphs.
Workflow
1. Scope and Platform Discovery
Inspect modified files (git diff or target directories) to detect the active interface technology:
- Web: Tailwind CSS, CSS Modules, Styled Components, vanilla HTML5, or UI component libraries (Radix, Shadcn, MUI).
- Desktop: WinUI 3, WPF, MAUI, or WinForms (XAML ResourceDictionaries, styles, controls).
- Mobile: Jetpack Compose, Flutter, or React Native (MaterialTheme, ThemeData, StyleSheet).
Identify the project's source of truth for design tokens:
- Web:
tailwind.config.*,globals.css, CSS root variables (:root { --... }). - Desktop:
App.xaml,Colors.xaml,MergedDictionaries, or sharedResourceDictionary. - Mobile:
Theme.kt,Color.kt(Compose) ortheme.dart(Flutter).
2. Design Tokens and Color Palette Audit
Inspect modified UI code for raw, hardcoded visual values:
- Color Invariant (New vs. Legacy Code):
- New Code / Modified Lines: The presence of hardcoded hexadecimal (
#[0-9a-fA-F]{3,8}),rgb(...), orhsl(...)values outside theme configuration files is a CRITICAL BLOCKING DEFECT. All colors must reference declared design tokens or theme resources. - Legacy / Preexisting Code: If hardcoded colors existed before the current change, report them as a WARNING with a concrete suggestion for the nearest matching project token.
- New Code / Modified Lines: The presence of hardcoded hexadecimal (
- Spacing and Typography Consistency:
- Detect arbitrary inline measurements (e.g.,
margin: 13px,p-[17px],FontSize="15") that break the established spacing or typographic scale. - Enforce using standard scale tokens (e.g.,
p-4,text-sm,StaticResource BaseTextBlockStyle).
- Detect arbitrary inline measurements (e.g.,
- Concentric Border-Radius Invariant (Nested Containers & Avatars):
- Inspect nested rounded elements (e.g., image within a padded container, inner card inside an outer outline).
- Verify that outer and inner radii follow the concentric law: $R_{\text{inner}} = R_{\text{outer}} - \text{padding}$.
- Flag as a warning any squircle/radius mismatch where $R_{\text{inner}} > R_{\text{outer}} - \text{padding}$ that pinches corner margins or creates optical distortion.
- Theme Parity & Scrollbar Styling:
- Verify that surfaces and text elements support Light and Dark modes without inverted or unreadable contrast.
- If custom scrollbar rules are defined (
::-webkit-scrollbar*), verify that dark mode track and thumb styles (.dark ::-webkit-scrollbar-*or standardscrollbar-coloronhtml.dark) are physically declared to prevent glaring white scroll tracks in dark mode.
3. Component Hierarchy and Interactive States Audit
Inspect buttons, inputs, and interactive controls for structural discipline:
- Button Hierarchy Discipline:
- Single Primary Action Rule: In any single screen, modal, dialog, or form context, there must be at most one prominent
PrimaryorAccentcall-to-action button. Secondary actions must useSecondary,Outline, orGhostvariants. - Destructive Actions: Deletion or irreversible actions must use designated
DangerorDestructivevisual styling.
- Single Primary Action Rule: In any single screen, modal, dialog, or form context, there must be at most one prominent
- Interactive States Completeness:
- Verify that buttons and interactive controls declare all three standard interaction states:
- Hover / PointerOver: Subtle visual feedback when hovered.
- Focus-Visible: Accessible keyboard focus ring or boundary highlight for accessibility navigation.
- Disabled: Dimmed opacity and disabled pointer events when inactive (
disabled,IsEnabled="False",enabled = false).
- Verify that buttons and interactive controls declare all three standard interaction states:
4. Iconography and Asset Hygiene Audit
Inspect icon usages, icon libraries, and visual assets:
- Single Icon Family Lock:
- Verify that the project uses a single established icon library (e.g., Lucide, Heroicons, Segoe Fluent Icons, or Material Symbols).
- Flag as a defect the introduction of a secondary icon library when an established family already exists in dependencies.
- Zero Duplicate Glyphs (Semantic Invariance):
- Ensure that the same conceptual action or entity uses the identical glyph throughout the application (e.g., do not mix an outlined trash can in one view with a filled trash can in another).
- Semantic Collision Prevention:
- Verify that identical icons are not repurposed for opposing or contradictory actions across screens.
- Accessibility on Icon-Only Controls:
- Any button, link, or clickable element displaying only an icon without visible text MUST include an accessible label (
aria-label,title,AutomationProperties.Name, orcontentDescription).
- Any button, link, or clickable element displaying only an icon without visible text MUST include an accessible label (
- Asset Cleanup:
- Detect orphaned, unused, or duplicate SVG files residing in
assets/,public/, or resource folders.
- Detect orphaned, unused, or duplicate SVG files residing in
5. Multi-Platform Quick Verification Matrix
| Platform | Tokens Check | Button Hierarchy | Iconography Check |
|---|---|---|---|
| Web | No raw hex in .tsx/.vue/.html; use Tailwind classes or var(--...). |
Max 1 variant="primary" per view; verify :focus-visible ring. |
Single SVG/icon package; require aria-label on icon buttons. |
| Desktop | Use StaticResource/ThemeResource; no inline Background="#...". |
Use AccentButtonStyle for primary; adhere to desktop_app_stability.md. |
Use FontIcon Glyph or SymbolIcon; set AutomationProperties.Name. |
| Mobile | Use MaterialTheme.colorScheme or Theme.of(context).colorScheme. |
Use FilledButton (Primary), OutlinedButton, TextButton. |
Use consistent Icons.Default.* / CupertinoIcons; set contentDescription. |
6. Reporting and Remediation
Emit a structured audit report:
- [CRITICAL] Blocking Defects: Raw hex colors in new code, conflicting primary buttons, missing accessibility labels on icon buttons.
- [WARNING] Hygiene Advisories: Hardcoded values in legacy code, duplicate SVGs in asset folders, missing hover states.
CONFIRMATION 1 - Remediation Approval: STOP and present the findings to the user with exact token and icon replacement suggestions. Await explicit approval before modifying any UI files.
Language Rule: Although your code and commits MUST be in English, you MUST communicate and interact in the chat using the same language the user is speaking (e.g., Spanish, French, etc.).