Design Audit Android

Android Design-to-Build Audit

Systematic visual QA workflow for comparing built Android (Kotlin/Jetpack Compose) applications against their original UI/UX design specifications.

Overview

Audit process:

1. Collect reference materials (design mockups + built app screenshots)
2. Create visual inventory (design vs. build side-by-side)
3. Audit by category (colors, typography, spacing, components, layout, states)
4. Classify findings by severity
5. Generate structured gap report

Step 1: Collect Materials

Required inputs:

• Design reference: Figma files, mockup images, or design system documentation
• Built app screenshots: Screenshots of the compiled Android app running on device/emulator
• Design system spec (optional): Color tokens, type scale, spacing scale, component library spec

If user provides only one side (design only or build only), ask for the other.

Step 2: Create Visual Inventory

Use a split-screen approach:

1. List every screen/flow shown in the design reference
2. For each design screen, locate the corresponding built screen
3. Note any screens present in design but missing from build
4. Note any screens present in build but not in design (scope creep)

Inventory template (create a checklist):

Screen Inventory:
- [ ] Screen Name (Design) → Screen Name (Build) — Status: [Matched / Missing / Partial]
- Navigation flows:
- Bottom sheets / dialogs / modals:
- Empty states / error states / loading states:

Step 3: Category Audit

Read references/android-audit-categories.md for the full checklist. Audit each category systematically.

Category Summary

| Category | What to Compare | Common Gaps | |----------|----------------|-------------| | Color | Hex values, MaterialTheme ColorScheme, surface/onSurface pairs | Missing dark mode, wrong surface tints, incorrect primary/secondary | | Typography | Font family, weights, sizes, line heights, letter spacing | Wrong font (system default vs. custom), incorrect body/large size, missing text styles | | Spacing | Padding, margin, gaps between elements | Hardcoded dp values vs. design tokens, incorrect card padding, wrong icon-text gaps | | Shape | Corner radii, clip shapes, rounded vs. sharp | Missing rounded corners on cards, incorrect button shape (pill vs. rounded rect) | | Elevation/Shadow | Shadow values, surface tonal elevation | Missing elevation on cards, incorrect shadow spread, no elevation animation | | Icons | Icon set (Outlined vs. Filled vs. Rounded), sizes, colors | Wrong icon variant, incorrect tint color, icon too large/small | | Components | Buttons, Cards, TextFields, Chips, BottomSheet, AppBar | Wrong button height, missing outlined variant, incorrect TextField shape, missing helper text | | Layout | Alignment, distribution, responsive behavior | Misaligned elements, incorrect weight distribution in rows, wrong scaffold structure | | Animations | Enter/exit transitions, state change animations, scroll behavior | Missing fade transitions, no ripple effect, janky navigation transitions | | Interaction States | Pressed, focused, disabled, error, loading | Missing disabled opacity, no pressed state feedback, missing error indicators |

For each category: compare pixel-to-pixel where possible. Note exact values from the design and the actual implemented values.

Step 4: Jetpack Compose Specific Checks

Read references/jetpack-compose-patterns.md for Compose-specific implementation audit patterns.

Key Compose-specific areas:

• Theme consistency: Is MaterialTheme.colorScheme used everywhere, or are colors hardcoded?
• Modifier chain: Are modifiers applied in the correct order (size before padding before clip)?
• Preview annotations: Are @Preview composables present for quick visual regression?
• Custom design system: Is a custom theme properly extending MaterialTheme?
• Accessibility: Are semantics modifiers present? Is touch target size at least 48dp?

Step 5: Severity Classification

Classify each finding:

| Severity | Definition | Example | |----------|-----------|---------| | P0 - Critical | Design system violation, user-facing broken layout | Wrong primary color, missing button, layout overflow | | P1 - Major | Noticeable visual deviation from design | Incorrect font weight, wrong card corner radius, missing shadow | | P2 - Minor | Small visual polish gap | Slightly off spacing, missing disabled state, wrong icon size | | P3 - Trivial | Pixel-perfect nitpick | 1-2dp difference, subtle color shade mismatch | | Missing | Element exists in design but not in build at all | Missing screen, missing component, missing state variant |

Step 6: Generate Report

Use the template in assets/audit-report-template.md. The report includes:

1. Executive Summary: Overall compliance percentage, critical issues count
2. Screen Inventory: All screens mapped with match status
3. Findings by Category: Detailed per-category findings with severity
4. Missing Elements Checklist: Items present in design but absent from build
5. Compose-Specific Issues: Theme violations, modifier ordering, accessibility gaps
6. Recommendations: Prioritized fix list with code pointers where possible

Reference Files

• references/android-audit-categories.md — Full per-category audit checklist with Compose-specific inspection points
• references/jetpack-compose-patterns.md — Common Compose implementation patterns and anti-patterns to flag
• assets/audit-report-template.md — Report template for output formatting

Best Practices

• Audit screens in the same order as user navigation flows
• Check both light and dark themes if both are specified in design
• Verify at multiple display densities (mdpi, xhdpi, xxhdpi) if possible
• Note when the build deviates from design for valid platform reasons (e.g., system insets, platform conventions)
• Prioritize P0 and Missing items over pixel-perfect P3 nits
• Cross-reference with Material Design 3 guidelines when design spec is ambiguous

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RyanMakesAndBreaksStuff
• Source: RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills
• License: MIT

Install and usage instructions live in the source repository linked above.