pbakaus_impeccable/skill/reference/adapt.md

Additional context needed: target platforms/devices and usage contexts.

Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.

Platform

Everything below is responsive web, mobile web included. Native targets (ios / android / adaptive): adapting means conforming to the platform's navigation model, controls, and touch sizing, never reflowing a web layout. Load ios.md / android.md (adaptive loads both).

---

Assess Adaptation Challenge

Understand what needs adaptation and why:

1. Identify the source context:

   • What was it designed for originally? (Desktop web? Mobile app?)
   • What assumptions were made? (Large screen? Mouse input? Fast connection?)
   • What works well in current context?

2. Understand target context:

   • Device: Mobile, tablet, desktop, TV, watch, print?
   • Input method: Touch, mouse, keyboard, voice, gamepad?
   • Screen constraints: Size, resolution, orientation?
   • Connection: Fast wifi, slow 3G, offline?
   • Usage context: On-the-go vs desk, quick glance vs focused reading?
   • User expectations: What do users expect on this platform?

3. Identify adaptation challenges:

   • What won't fit? (Content, navigation, features)
   • What won't work? (Hover states on touch, tiny touch targets)
   • What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)

CRITICAL: Adaptation is rethinking the experience for the new context, not scaling pixels.

Plan Adaptation Strategy

Create context-appropriate strategy:

Mobile Adaptation (Desktop → Mobile)

Layout Strategy:

• Single column instead of multi-column
• Vertical stacking instead of side-by-side
• Full-width components instead of fixed widths
• Bottom navigation instead of top/side navigation

Interaction Strategy:

• Touch targets 44x44px minimum (not hover-dependent)
• Swipe gestures where appropriate (lists, carousels)
• Bottom sheets instead of dropdowns
• Thumbs-first design (controls within thumb reach)
• Larger tap areas with more spacing

Content Strategy:

• Progressive disclosure (don't show everything at once)
• Prioritize primary content (secondary content in tabs/accordions)
• Shorter text (more concise)
• Larger text (16px minimum)

Navigation Strategy:

• Hamburger menu or bottom navigation
• Reduce navigation complexity
• Sticky headers for context
• Back button in navigation flow

Tablet Adaptation (Hybrid Approach)

Layout Strategy:

• Two-column layouts (not single or three-column)
• Side panels for secondary content
• Master-detail views (list + detail)
• Adaptive based on orientation (portrait vs landscape)

Interaction Strategy:

• Support both touch and pointer
• Touch targets 44x44px but allow denser layouts than phone
• Side navigation drawers
• Multi-column forms where appropriate

Desktop Adaptation (Mobile → Desktop)

Layout Strategy:

• Multi-column layouts (use horizontal space)
• Side navigation always visible
• Multiple information panels simultaneously
• Fixed widths with max-width constraints (don't stretch to 4K)

Interaction Strategy:

• Hover states for additional information
• Keyboard shortcuts
• Right-click context menus
• Drag and drop where helpful
• Multi-select with Shift/Cmd

Content Strategy:

• Show more information upfront (less progressive disclosure)
• Data tables with many columns
• Richer visualizations
• More detailed descriptions

Print Adaptation (Screen → Print)

Layout Strategy:

• Page breaks at logical points
• Remove navigation, footer, interactive elements
• Black and white (or limited color)
• Proper margins for binding

Content Strategy:

• Expand shortened content (show full URLs, hidden sections)
• Add page numbers, headers, footers
• Include metadata (print date, page title)
• Convert charts to print-friendly versions

Email Adaptation (Web → Email)

Layout Strategy:

• Narrow width (600px max)
• Single column only
• Inline CSS (no external stylesheets)
• Table-based layouts (for email client compatibility)

Interaction Strategy:

• Large, obvious CTAs (buttons not text links)
• No hover states (not reliable)
• Deep links to web app for complex interactions

Implement Adaptations

Apply changes systematically:

Responsive Breakpoints

Choose appropriate breakpoints:

• Mobile: 320px-767px
• Tablet: 768px-1023px
• Desktop: 1024px+
• Or content-driven breakpoints (where design breaks)

Layout Adaptation Techniques

• CSS Grid/Flexbox: Reflow layouts automatically
• Container Queries: Adapt based on container, not viewport
• clamp(): Fluid sizing between min and max
• Media queries: Different styles for different contexts
• Display properties: Show/hide elements per context

Touch Adaptation

• Increase touch target sizes (44x44px minimum)
• Add more spacing between interactive elements
• Remove hover-dependent interactions
• Add touch feedback (ripples, highlights)
• Consider thumb zones (easier to reach bottom than top)

Content Adaptation

• Use display: none sparingly (still downloads)
• Progressive enhancement (core content first, enhancements on larger screens)
• Lazy loading for off-screen content
• Responsive images (srcset, picture element)

Navigation Adaptation

• Transform complex nav to hamburger/drawer on mobile
• Bottom nav bar for mobile apps
• Persistent side navigation on desktop
• Breadcrumbs on smaller screens for context

IMPORTANT: Test on real devices. Device emulation in DevTools is helpful but not perfect.

NEVER:

• Hide core functionality on mobile (if it matters, make it work)
• Assume desktop = powerful device (consider accessibility, older machines)
• Use different information architecture across contexts (confusing)
• Break user expectations for platform (mobile users expect mobile patterns)
• Forget landscape orientation on mobile/tablet
• Use generic breakpoints blindly (use content-driven breakpoints)
• Ignore touch on desktop (many desktop devices have touch)

Verify Adaptations

Test thoroughly across contexts:

• Real devices: Test on actual phones, tablets, desktops
• Different orientations: Portrait and landscape
• Different browsers: Safari, Chrome, Firefox, Edge
• Different OS: iOS, Android, Windows, macOS
• Different input methods: Touch, mouse, keyboard
• Edge cases: Very small screens (320px), very large screens (4K)
• Slow connections: Test on throttled network

When the adaptation feels native to each context, hand off to {{command_prefix}}impeccable polish for the final pass.

---

Reference Material

The sections below were previously responsive-design.md and live inline now so the adapt flow has its deep responsive reference in one place.

Responsive Design

Mobile-First: Write It Right

Start with base styles for mobile, use min-width queries to layer complexity. Desktop-first (max-width) means mobile loads unnecessary styles first.

Breakpoints: Content-Driven

Don't chase device sizes; let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use clamp() for fluid values without breakpoints.

Detect Input Method, Not Just Screen Size

Screen size doesn't tell you input method. A laptop with touchscreen, a tablet with keyboard. Use pointer and hover queries:

/* Fine pointer (mouse, trackpad) */
@media (pointer: fine) {
  .button { padding: 8px 16px; }
}

/* Coarse pointer (touch, stylus) */
@media (pointer: coarse) {
  .button { padding: 12px 20px; }  /* Larger touch target */
}

/* Device supports hover */
@media (hover: hover) {
  .card:hover { transform: translateY(-2px); }
}

/* Device doesn't support hover (touch) */
@media (hover: none) {
  .card { /* No hover state - use active instead */ }
}

Critical: Don't rely on hover for functionality. Touch users can't hover.

Safe Areas: Handle the Notch

Modern phones have notches, rounded corners, and home indicators. Use env():

body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

/* With fallback */
.footer {
  padding-bottom: max(1rem, env(safe-area-inset-bottom));
}

Enable viewport-fit in your meta tag:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

Responsive Images: Get It Right

srcset with Width Descriptors

<img
  src="hero-800.jpg"
  srcset="
    hero-400.jpg 400w,
    hero-800.jpg 800w,
    hero-1200.jpg 1200w
  "
  sizes="(max-width: 768px) 100vw, 50vw"
  alt="Hero image"
>

How it works:

• srcset lists available images with their actual widths (w descriptors)
• sizes tells the browser how wide the image will display
• Browser picks the best file based on viewport width AND device pixel ratio

Picture Element for Art Direction

When you need different crops/compositions (not just resolutions):

<picture>
  <source media="(min-width: 768px)" srcset="wide.jpg">
  <source media="(max-width: 767px)" srcset="tall.jpg">
  <img src="fallback.jpg" alt="...">
</picture>

Layout Adaptation Patterns

Navigation: Three stages: hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. Tables: Transform to cards on mobile using display: block and data-label attributes. Progressive disclosure: Use <details>/<summary> for content that can collapse on mobile.

Testing: Don't Trust DevTools Alone

DevTools device emulation is useful for layout but misses:

• Actual touch interactions
• Real CPU/memory constraints
• Network latency patterns
• Font rendering differences
• Browser chrome/keyboard appearances

Test on at least: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you'll never see on simulators.

---

Avoid: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.