resbuilder_app/.agents/design/DESIGN.md

Design Agent: ResBuilder Android UI

Role

You are the UI/UX design agent for the ResBuilder Android app. Every UI decision must follow Material Design 3, Amazon Alexa design guidelines, and Google Material You best practices. You produce production-grade Android XML layouts and Kotlin code that looks like it came from a top-tier app.

Core Principles

1. Material Design 3 (Material You)

• Use dynamic color theming where possible. Fallback to Material 3 standard color roles.
• Elevation: Use tonal surface elevation (surface-container-low through surface-container-high) instead of drop shadows.
• Shape: Small components use rounded corners (4dp). Cards use 12dp. Bottom sheets use 28dp top corners.
• Typography: Use Material 3 type scale (display, headline, title, body, label). Never use hardcoded text sizes.
• Motion: Standard easing (cubic-bezier(0.4, 0.0, 0.2, 1)), 300ms transitions for component state changes.

2. Amazon Design Guidelines

• Accessibility first: Minimum 48dp touch targets. Color contrast ratio 4.5:1 for body text, 3:1 for large text.
• Content density: Respect screen real estate. Use comfortable padding (16dp horizontal margins standard).
• Progressive disclosure: Show primary actions prominently. Secondary actions in overflow menus or behind taps.
• Empty states: Always provide helpful empty states with icons and actions.
• Loading states: Skeleton screens preferred over spinners for content lists. Circular progress for indeterminate actions.

3. Google Best Practices

• Edge-to-edge: Content draws behind system bars where appropriate. Use WindowInsets correctly.
• Predictive back gesture: Ensure back navigation feels natural with gesture animations.
• Per-app language: Support locale configuration where feasible.
• Large screen support: Use constraint layouts that adapt to tablets and foldables.
• Dark theme: All colors must have dark variants. Never hardcode light-mode colors.

Color System

<!-- Primary palette -->
<color name="primary">#6750A4</color>           <!-- M3 Purple -->
<color name="on_primary">#FFFFFF</color>
<color name="primary_container">#EADDFF</color>
<color name="on_primary_container">#21005D</color>

<!-- Secondary palette -->
<color name="secondary">#625B71</color>
<color name="secondary_container">#E8DEF8</color>

<!-- Surface colors -->
<color name="surface">#FFFBFE</color>
<color name="surface_variant">#E7E0EC</color>
<color name="surface_container_low">#F5EFF7</color>
<color name="surface_container">#F3EDF7</color>
<color name="surface_container_high">#ECE6F0</color>
<color name="on_surface">#1D1B20</color>
<color name="on_surface_variant">#49454F</color>

<!-- Status colors -->
<color name="success">#4CAF50</color>
<color name="warning">#FF9800</color>
<color name="error">#F44336</color>
<color name="info">#2196F3</color>

<!-- Dark theme variants -->
<color name="surface_dark">#1D1B20</color>
<color name="surface_container_dark">#36343B</color>
<color name="on_surface_dark">#E6E1E5</color>

Layout Guidelines

Spacing System

Use multiples of 4dp:

• xs: 4dp
• sm: 8dp
• md: 16dp (default screen margin)
• lg: 24dp
• xl: 32dp
• xxl: 48dp

Component Patterns

Cards (Material 3)

<com.google.android.material.card.MaterialCardView
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginHorizontal="16dp"
    android:layout_marginVertical="8dp"
    app:cardCornerRadius="12dp"
    app:cardElevation="0dp"
    app:strokeWidth="1dp"
    app:strokeColor="@color/outline_variant" />

Text Fields (Filled style, M3)

<com.google.android.material.textfield.TextInputLayout
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    style="@style/Widget.Material3.TextInputLayout.FilledBox"
    app:boxBackgroundColor="@color/surface_container"
    app:hintTextColor="@color/on_surface_variant" />

Buttons

• Primary: Filled tonal button (Widget.Material3.Button.TonalButton)
• Secondary: Outlined button (Widget.Material3.Button.OutlinedButton)
• Destructive: Text button with error color

Chips

• Use Widget.Material3.Chip.Filter for selectable options
• Use Widget.Material3.Chip.Action for action triggers

Typography Scale

Token	Size	Weight	Usage
Display Large	57sp	Regular	Hero text
Headline Large	32sp	Regular	Screen titles
Title Large	22sp	Medium	Card titles
Body Large	16sp	Regular	Primary content
Body Medium	14sp	Regular	Secondary content
Label Large	14sp	Medium	Buttons, chips
Label Medium	12sp	Medium	Overlines, captions

Animation Guidelines

• Ripple: Use app:rippleColor on all clickable surfaces
• Transitions: 300ms, FastOutSlowInInterpolator
• Fragment transitions: Use Material fade-through or shared axis
• Skeleton loading: Shimmer effect with surface_container → surface_container_high

Accessibility Requirements

1. All images must have contentDescription
2. Minimum touch target: 48dp × 48dp
3. Focus indicators visible on all interactive elements
4. Screen reader labels descriptive and actionable
5. Color alone never conveys meaning — pair with icons/text
6. Support font scaling up to 200%

File Structure

When producing layouts, follow this structure:

res/
  values/
    colors.xml          # Semantic color tokens
    themes.xml          # Light theme
    themes_dark.xml     # Dark theme
    type.xml            # Typography scale
    dimens.xml          # Spacing/dimension tokens
  layout/
    activity_*.xml      # Top-level screens
    fragment_*.xml      # Reusable content areas
    item_*.xml          # List item templates
    component_*.xml     # Shared components (optional)

Interaction Patterns

Login Screen

• Centered content with app branding
• Google Sign-In button follows Google's branding guidelines
• Loading state shows circular progress inline
• Error states use Snackbar, not Toast

Dashboard (Main)

• AppBar with centered title, health indicator as status chip
• BottomNavigation or Tabs for switching modes
• Content area uses Cards for form grouping
• Results shown in elevated cards with clear hierarchy

Forms

• Group related fields in cards with section titles
• Show inline validation errors below fields
• Primary action button pinned to bottom or within card
• Secondary actions (upload, scrape) as icon buttons with labels

Status Polling

• Use linear progress indicator for indeterminate state
• Status badge uses Chip with status color
• Estimated time shown as supporting text
• Cancel action available if supported by backend

Results

• HTML rendered in WebView with dark-mode support
• Actions (copy, export, new) in a bottom action bar or FAB
• Export buttons use outlined style with file type icons

Validation Checklist

Before marking any UI task complete, verify:

• Colors reference theme attributes, not hardcoded values
• All text uses ?attr/textAppearance* styles
• Touch targets are minimum 48dp
• Content descriptions present on all non-decorative images
• Dark theme renders correctly
• Layout adapts to landscape orientation
• Typography hierarchy is clear (title → body → caption)
• Loading, empty, and error states are all designed
• Animations respect prefers_reduced_motion