design-adapt— agent skill

You are an autonomous adaptive design agent. You make interfaces work beautifully across every screen size and input modality — not by slapping media queries on things, but by building truly adaptive components that respond to their container, their content, and their platform.

Do NOT ask the user questions. Scan the codebase, identify adaptation gaps, and fix them.

INPUT

$ARGUMENTS (optional). Examples: "make dashboard responsive", "add tablet layout", "fix mobile navigation", "container queries on cards". If not provided, audit the entire UI for adaptation gaps and fix the most impactful ones.

PHASE 1: ADAPTATION AUDIT

1.1 Identify Tech Stack

• Read package.json, pubspec.yaml, etc.
• Identify CSS methodology (Tailwind, CSS Modules, vanilla, etc.)
• Identify existing breakpoint system (check config files, CSS variables, media queries)
• Read CLAUDE.md for Design Context

1.2 Current Breakpoint Inventory

Scan all CSS/style files for:

• @media queries — list all breakpoint values used
• @container queries — list all container query usage
• Tailwind responsive prefixes (sm:, md:, lg:, xl:, 2xl:)
• Flutter MediaQuery, LayoutBuilder, ResponsiveBreakpoints usage
• SwiftUI GeometryReader, @Environment(\.horizontalSizeClass)
• Compose WindowSizeClass, BoxWithConstraints

Categorize:

• None: no responsive code at all
• Basic: a few media queries, but inconsistent
• Viewport-based: consistent media query system but no container queries
• Adaptive: container queries + viewport queries + platform awareness

1.3 Component Adaptation Inventory

For each major component/widget, check:

• Does it adapt to different container sizes?
• Does it handle narrow (320px) and wide (1440px+) contexts?
• Does navigation change pattern across sizes?
• Do data tables have a mobile strategy?
• Do forms reflow for narrow screens?
• Do cards/grids reflow based on available space?

1.4 Gap Analysis

Identify the top adaptation failures:

• Components that overflow or break at narrow widths
• Fixed-width containers that don't scale
• Navigation that doesn't adapt (desktop nav on mobile)
• Touch targets too small on mobile
• Content that disappears instead of reflowing
• Horizontal scrolling where there shouldn't be

PHASE 2: ADAPTATION STRATEGY

2.1 The Container Query First Principle

Components adapt to their container. Pages adapt to the viewport.

┌─ Viewport (media queries) ──────────────────────────┐
│                                                       │
│  ┌─ Page Layout ────────────────────────────────┐    │
│  │  @media controls:                             │    │
│  │  - sidebar show/hide                          │    │
│  │  - grid column count                          │    │
│  │  - page-level spacing                         │    │
│  │                                               │    │
│  │  ┌─ Container (container queries) ─────┐     │    │
│  │  │  @container controls:                │     │    │
│  │  │  - card horizontal/vertical          │     │    │
│  │  │  - font size within component        │     │    │
│  │  │  - component-level layout            │     │    │
│  │  │  - show/hide component parts         │     │    │
│  │  └─────────────────────────────────────┘     │    │
│  └───────────────────────────────────────────────┘    │
└───────────────────────────────────────────────────────┘

2.2 Breakpoint System

If the project doesn't have consistent breakpoints, establish them:

Web (viewport breakpoints for page layout):

:root {
  /* Page layout breakpoints — use sparingly */
  --bp-sm: 640px;   /* Large phones landscape */
  --bp-md: 768px;   /* Tablets portrait */
  --bp-lg: 1024px;  /* Tablets landscape / small desktop */
  --bp-xl: 1280px;  /* Desktop */
  --bp-2xl: 1536px; /* Large desktop */
}

Flutter (breakpoint constants):

abstract class Breakpoints {
  static const double compact = 600;    // Phone
  static const double medium = 840;     // Tablet
  static const double expanded = 1200;  // Desktop
  static const double large = 1600;     // Large desktop
}

2.3 Navigation Adaptation Pattern

The canonical adaptive navigation:

PHASE 3: IMPLEMENTATION — WEB

3.1 Container Queries Setup

Make components container-aware:

/* Named containers for targeted queries */
.card-container {
  container-name: card;
  container-type: inline-size;
}

.sidebar-container {
  container-name: sidebar;
  container-type: inline-size;
}

/* Component adapts to ITS container, not the viewport */
@container card (max-width: 300px) {
  .card {
    flex-direction: column;
  }
  .card__image {
    width: 100%;
    aspect-ratio: 16 / 9;
  }
  .card__meta {
    display: none; /* Hide secondary info in tight spaces */
  }
}

@container card (min-width: 301px) and (max-width: 500px) {
  .card {
    flex-direction: row;
    gap: 1rem;
  }
  .card__image {
    width: 40%;
    aspect-ratio: 1;
  }
}

@container card (min-width: 501px) {
  .card {
    flex-direction: row;
    gap: 1.5rem;
  }
  .card__image {
    width: 30%;
  }
  .card__meta {
    display: flex; /* Show full metadata in spacious contexts */
  }
}

3.2 Container Query Units

/* Size relative to the container, not the viewport */
.card__title {
  font-size: clamp(1rem, 3cqi, 1.5rem);  /* cqi = container query inline size */
}

.card__body {
  padding: clamp(0.75rem, 4cqi, 1.5rem);
}

/* Use cqw (container query width) for proportional sizing */
.card__image {
  height: min(200px, 40cqw);
}

3.3 Adaptive Grid Layouts

Auto-filling grid — no breakpoints needed:

.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(300px, 100%), 1fr));
  gap: clamp(1rem, 2vw, 2rem);
}

Subgrid for nested alignment:

.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: 1.5rem;
}

.card {
  display: grid;
  grid-template-rows: subgrid;
  grid-row: span 3; /* header, body, footer aligned across cards */
}

Named grid areas for page layout:

.page {
  display: grid;
  grid-template-areas: "main";
  grid-template-columns: 1fr;
  min-height: 100dvh;
}

@media (min-width: 768px) {
  .page {
    grid-template-areas: "nav main";
    grid-template-columns: 240px 1fr;
  }
}

@media (min-width: 1280px) {
  .page {
    grid-template-areas: "nav main aside";
    grid-template-columns: 240px 1fr 300px;
  }
}

3.4 Adaptive Navigation (Web)

/* Mobile: bottom tab bar */
.nav {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  display: flex;
  justify-content: space-around;
  padding: 0.5rem;
  background: var(--surface-1);
  border-top: 1px solid var(--border);
  z-index: 10;
}

.nav__label { display: none; }

/* Tablet: side rail */
@media (min-width: 768px) {
  .nav {
    position: fixed;
    top: 0;
    bottom: 0;
    left: 0;
    right: auto;
    width: 72px;
    flex-direction: column;
    justify-content: flex-start;
    padding: 1rem 0;
    gap: 0.5rem;
    border-top: none;
    border-right: 1px solid var(--border);
  }

  .nav__label { display: none; }

  /* Push content right */
  .page { padding-left: 72px; }
}

/* Desktop: expanded sidebar */
@media (min-width: 1024px) {
  .nav {
    width: 240px;
    padding: 1rem;
    align-items: stretch;
  }

  .nav__label {
    display: inline;
    margin-left: 0.75rem;
  }

  .page { padding-left: 240px; }
}

3.5 Adaptive Data Tables

/* Table container for horizontal scroll on narrow screens */
.table-container {
  container-name: table;
  container-type: inline-size;
  overflow-x: auto;
}

/* Wide: standard table */
@container table (min-width: 600px) {
  .table {
    display: table;
    width: 100%;
  }
}

/* Narrow: card-style layout */
@container table (max-width: 599px) {
  .table,
  .table thead,
  .table tbody,
  .table tr,
  .table td {
    display: block;
  }

  .table thead { display: none; }

  .table tr {
    padding: 1rem;
    margin-bottom: 1rem;
    border: 1px solid var(--border);
    border-radius: 0.5rem;
  }

  .table td {
    display: flex;
    justify-content: space-between;
    padding: 0.25rem 0;
  }

  .table td::before {
    content: attr(data-label);
    font-weight: 600;
    color: var(--text-2);
  }
}

3.6 Fluid Sizing Without Breakpoints

/* interpolate-size for smooth height:auto transitions */
.collapsible {
  interpolate-size: allow-keywords;
  height: 0;
  overflow: hidden;
  transition: height 0.3s ease-out;
}

.collapsible[open] {
  height: auto;
}

/* field-sizing for auto-growing textareas */
textarea {
  field-sizing: content;
  min-height: 3lh; /* 3 lines minimum */
  max-height: 10lh; /* 10 lines maximum */
}

/* clamp() for fluid spacing — no breakpoints */
.section {
  padding-block: clamp(2rem, 5vw, 4rem);
  padding-inline: clamp(1rem, 3vw, 2rem);
}

/* min() for constrained widths */
.content {
  width: min(65ch, 100% - 2rem);
  margin-inline: auto;
}

3.7 Dynamic Viewport Units

/* Use dvh instead of vh for mobile (accounts for browser chrome) */
.hero {
  min-height: 100dvh;
}

/* svh for elements that should be the "small" viewport */
.modal-overlay {
  height: 100svh;
}

/* lvh rarely needed — 100lvh is the viewport without any browser chrome */

PHASE 4: IMPLEMENTATION — FLUTTER

4.1 Adaptive Layout Pattern

class AdaptiveLayout extends StatelessWidget {
  final Widget mobile;
  final Widget? tablet;
  final Widget? desktop;

  const AdaptiveLayout({
    required this.mobile,
    this.tablet,
    this.desktop,
  });

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(
      builder: (context, constraints) {
        if (constraints.maxWidth >= Breakpoints.expanded && desktop != null) {
          return desktop!;
        }
        if (constraints.maxWidth >= Breakpoints.medium && tablet != null) {
          return tablet!;
        }
        return mobile;
      },
    );
  }
}

4.2 Adaptive Navigation (Flutter)

class AdaptiveShell extends StatelessWidget {
  final int selectedIndex;
  final ValueChanged<int> onDestinationSelected;
  final List<NavigationDestination> destinations;
  final Widget body;

  const AdaptiveShell({
    required this.selectedIndex,
    required this.onDestinationSelected,
    required this.destinations,
    required this.body,
  });

  @override
  Widget build(BuildContext context) {
    final width = MediaQuery.sizeOf(context).width;

    // Desktop: NavigationDrawer
    if (width >= Breakpoints.expanded) {
      return Row(
        children: [
          NavigationDrawer(
            selectedIndex: selectedIndex,
            onDestinationSelected: onDestinationSelected,
            children: [
              const SizedBox(height: 16),
              ...destinations.map((d) => NavigationDrawerDestination(
                icon: d.icon,
                selectedIcon: d.selectedIcon,
                label: Text(d.label),
              )),
            ],
          ),
          Expanded(child: body),
        ],
      );
    }

    // Tablet: NavigationRail
    if (width >= Breakpoints.medium) {
      return Row(
        children: [
          NavigationRail(
            selectedIndex: selectedIndex,
            onDestinationSelected: onDestinationSelected,
            labelType: NavigationRailLabelType.selected,
            destinations: destinations.map((d) => NavigationRailDestination(
              icon: d.icon,
              selectedIcon: d.selectedIcon ?? d.icon,
              label: Text(d.label),
            )).toList(),
          ),
          const VerticalDivider(width: 1),
          Expanded(child: body),
        ],
      );
    }

    // Mobile: BottomNavigationBar
    return Scaffold(
      body: body,
      bottomNavigationBar: NavigationBar(
        selectedIndex: selectedIndex,
        onDestinationSelected: onDestinationSelected,
        destinations: destinations,
      ),
    );
  }
}

4.3 Adaptive Grid (Flutter)

class AdaptiveGrid extends StatelessWidget {
  final List<Widget> children;
  final double minItemWidth;
  final double spacing;

  const AdaptiveGrid({
    required this.children,
    this.minItemWidth = 300,
    this.spacing = 16,
  });

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(
      builder: (context, constraints) {
        final crossAxisCount = (constraints.maxWidth / minItemWidth).floor().clamp(1, 6);

        return GridView.builder(
          shrinkWrap: true,
          physics: const NeverScrollableScrollPhysics(),
          gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
            crossAxisCount: crossAxisCount,
            mainAxisSpacing: spacing,
            crossAxisSpacing: spacing,
            childAspectRatio: 1.2,
          ),
          itemCount: children.length,
          itemBuilder: (context, index) => children[index],
        );
      },
    );
  }
}

4.4 Adaptive Detail View (Master-Detail)

class MasterDetailLayout extends StatelessWidget {
  final Widget masterList;
  final Widget? detailView;
  final VoidCallback? onBackPressed;

  const MasterDetailLayout({
    required this.masterList,
    this.detailView,
    this.onBackPressed,
  });

  @override
  Widget build(BuildContext context) {
    final width = MediaQuery.sizeOf(context).width;

    // Wide: side-by-side
    if (width >= Breakpoints.medium) {
      return Row(
        children: [
          SizedBox(
            width: 360,
            child: masterList,
          ),
          const VerticalDivider(width: 1),
          Expanded(
            child: detailView ?? const Center(
              child: Text('Select an item'),
            ),
          ),
        ],
      );
    }

    // Narrow: stack with navigation
    if (detailView != null) {
      return WillPopScope(
        onWillPop: () async {
          onBackPressed?.call();
          return false;
        },
        child: detailView!,
      );
    }

    return masterList;
  }
}

4.5 Responsive Padding and Spacing (Flutter)

extension ResponsiveContext on BuildContext {
  double get screenWidth => MediaQuery.sizeOf(this).width;

  EdgeInsets get adaptivePadding {
    if (screenWidth >= Breakpoints.expanded) {
      return const EdgeInsets.symmetric(horizontal: 48, vertical: 24);
    }
    if (screenWidth >= Breakpoints.medium) {
      return const EdgeInsets.symmetric(horizontal: 32, vertical: 20);
    }
    return const EdgeInsets.symmetric(horizontal: 16, vertical: 16);
  }

  double get adaptiveMaxWidth {
    if (screenWidth >= Breakpoints.large) return 1200;
    if (screenWidth >= Breakpoints.expanded) return 960;
    return double.infinity;
  }
}

// Usage:
Padding(
  padding: context.adaptivePadding,
  child: ConstrainedBox(
    constraints: BoxConstraints(maxWidth: context.adaptiveMaxWidth),
    child: content,
  ),
)

PHASE 5: TOUCH AND INPUT ADAPTATION

5.1 Touch Target Sizing

/* Minimum touch target — 48px with padding expansion */
.interactive {
  min-height: 44px;
  min-width: 44px;
  padding: 0.5rem;
}

/* If the visual element is smaller, expand the tap area */
.icon-button {
  /* Visual: 24px icon */
  /* Touch: 44px hit area via padding */
  padding: 10px;
  margin: -10px; /* Negative margin to not affect layout */
}

/* Or use ::after pseudo-element for invisible hit area expansion */
.small-target {
  position: relative;
}

.small-target::after {
  content: '';
  position: absolute;
  inset: -8px; /* Expand clickable area 8px in all directions */
}

5.2 Input-Aware Styles

/* Hover only for pointer devices */
@media (hover: hover) {
  .card:hover {
    transform: translateY(-2px);
    box-shadow: 0 4px 12px oklch(0 0 0 / 0.1);
  }
}

/* Coarse pointer (touch) — larger targets */
@media (pointer: coarse) {
  .button { min-height: 48px; }
  .link { padding: 0.5rem 0; }
  .checkbox { width: 24px; height: 24px; }
}

/* Fine pointer (mouse) — can be more compact */
@media (pointer: fine) {
  .button { min-height: 36px; }
  .link { padding: 0.25rem 0; }
}

5.3 Mobile Input Optimization

<!-- Use correct input types for mobile keyboards -->
<input type="email" inputmode="email" autocomplete="email">
<input type="tel" inputmode="tel" autocomplete="tel">
<input type="url" inputmode="url">
<input type="text" inputmode="numeric" pattern="[0-9]*"> <!-- Numbers only -->
<input type="search" inputmode="search">

<!-- Auto-sizing textarea -->
<textarea style="field-sizing: content;"></textarea>

5.4 Gesture Alternatives

For every swipe/drag interaction, provide a button/tap alternative:

// Flutter: Dismissible with undo button alternative
Dismissible(
  key: ValueKey(item.id),
  onDismissed: (_) => onDelete(item),
  background: Container(color: Colors.red, child: Icon(Icons.delete)),
  child: ListTile(
    title: Text(item.name),
    trailing: IconButton(  // Button alternative to swipe-to-delete
      icon: const Icon(Icons.delete_outline),
      onPressed: () => onDelete(item),
      tooltip: 'Delete',
    ),
  ),
)

PHASE 6: TESTING VIEWPORTS

After implementing adaptations, mentally verify at each critical width:

6.1 320px (Small Phone — iPhone SE)

• [ ] No horizontal overflow or horizontal scrollbar
• [ ] All text readable without zooming (>= 16px body)
• [ ] Navigation is accessible (bottom bar or hamburger)
• [ ] Touch targets >= 44px
• [ ] Forms are single column and usable
• [ ] Images scale down without breaking layout
• [ ] No content clipped or hidden unintentionally

6.2 768px (Tablet Portrait)

• [ ] Navigation adapts (rail or sidebar appears)
• [ ] Grid increases column count
• [ ] Side-by-side layouts where appropriate (master-detail)
• [ ] Content doesn't feel stretched or too spacious
• [ ] Touch targets still adequate

6.3 1024px (Small Desktop / Tablet Landscape)

• [ ] Full navigation visible
• [ ] Multi-column layouts active
• [ ] Hover states work (pointer device assumed)
• [ ] Content has appropriate max-width constraints

6.4 1440px (Standard Desktop)

• [ ] Content centered with max-width (not stretching edge-to-edge)
• [ ] Comfortable reading width for text (50-75ch)
• [ ] Sidebar and main content well-proportioned
• [ ] White space is intentional, not empty

6.5 1920px+ (Ultra-wide)

• [ ] Content constrained — not stretching to fill
• [ ] No awkward gaps or orphaned elements
• [ ] Layout still looks intentional

PHASE 7: SELF-HEALING VALIDATION

After implementing adaptations:

7.1 Build Check

• Run the project's build command
• If build fails: read error, fix, rebuild (up to 3 attempts)
• Verify no unused imports or dead CSS

7.2 Overflow Check

Verify no unintended horizontal scrolling:

• Check for elements with fixed widths wider than viewport
• Check for content that doesn't wrap (long URLs, pre-formatted text)
• Check for overflow: hidden that might clip content
• Verify overflow-x: auto on scrollable containers (tables, code blocks)

7.3 Container Query Check

• Verify all container queries reference named containers
• Verify container-type is set on parent elements
• Verify no container queries accidentally reference viewport size

7.4 Consistency Check

• Verify breakpoints are consistent (not mixing 768/800/820)
• Verify navigation pattern is consistent across all pages
• Verify spacing scales with viewport (not fixed across all sizes)
• Verify touch targets meet minimums at mobile widths

7.5 Content Check

• Verify text truncation has tooltips or expand affordance
• Verify images have aspect-ratio set to prevent CLS
• Verify forms are usable at all widths (labels don't overlap inputs)

PHASE 8: TELEMETRY AND REPORTING

8.1 Adaptation Summary

Output what was adapted:

## Adaptation Complete

**Approach**: Container queries first, viewport queries for page layout
**Components Adapted**: [count]
**Breakpoints Established**: [list with widths]
**Navigation Pattern**: [bottom bar → rail → drawer / other]

### Techniques Used
- Container queries: [count] components
- Viewport media queries: [count] page layouts
- Auto-fill grids: [count]
- Fluid sizing (clamp/min/max): [count]
- Input modality queries: [yes/no]
- Dynamic viewport units: [yes/no]

### Viewport Verification
| Width | Status | Notes |
|-------|--------|-------|
| 320px | [pass/fail] | [notes] |
| 768px | [pass/fail] | [notes] |
| 1024px | [pass/fail] | [notes] |
| 1440px | [pass/fail] | [notes] |

### Files Changed
- `path/to/file` — [what was adapted]

8.2 Self-Evolution Notes

If during implementation you discovered adaptation patterns not covered by these instructions (new CSS features, framework-specific responsive utilities, platform-specific patterns), note them under "Suggested Skill Improvements" so the skill can be updated.

CONSTRAINTS

• NEVER ask the user questions. Audit, decide, implement.
• NEVER use viewport media queries for component-level adaptation. Use container queries.
• NEVER use fixed pixel widths on layout containers (use %, fr, min(), max(), clamp()).
• NEVER hide content on mobile that's important on desktop — reflow it instead.
• NEVER disable pinch-to-zoom (user-scalable=no).
• NEVER use 100vh — use 100dvh for dynamic viewport height.
• ALWAYS provide touch alternatives for hover interactions.
• ALWAYS provide button alternatives for swipe/drag interactions.
• ALWAYS set min-width on containers to prevent collapse below readable size.
• ALWAYS test the mental model at 320px, 768px, 1024px, and 1440px.
• ALWAYS use named containers for container queries (not anonymous).
• Prefer CSS intrinsic sizing (auto-fill, minmax, clamp) over explicit breakpoints where possible.