a2host/.agents/skills/responsive-mobile-first/SKILL.md

3.2 KiB

name description
responsive-mobile-first Enforces mobile-first responsive architecture and viewport stability guidelines for all frontend components, ensuring seamless adaptivity from mobile screens (320px) to ultrawide displays (1440px+). Use when building, styling, or refactoring layouts, sidebars, modals, tables, or chat views.

Responsive Mobile-First Skill

Core Principles

  1. Mobile-First CSS:

    • Write base CSS/Tailwind classes for mobile (320px - 480px) first without prefixes.
    • Expand layout and spacing progressively with breakpoint prefixes:
      • sm: (640px)
      • md: (768px) - Tablet portrait / collapsed sidebars transition
      • lg: (1024px) - Desktop / expanded multi-column views
      • xl: (1280px) and 2xl: (1536px) - Ultrawide / max-width containers
    • Never write desktop styles as base and attempt to override them with negative mobile queries.
  2. Dynamic Viewport Height:

    • Do NOT use rigid 100vh for full-screen application shells (causes overflow and clipping due to dynamic URL bars in iOS Safari and Chrome Android).
    • Use dynamic viewport height: h-[100dvh] or min-h-[100dvh] (fallback: h-screen).
    • Use h-[calc(100dvh-Xpx)] for internal scrollable flex containers.
  3. Safe Area Insets:

    • For bottom bars, floating action buttons, and top navigation bars, support mobile notches and home indicators:
      padding-top: max(1rem, env(safe-area-inset-top));
      padding-bottom: max(1rem, env(safe-area-inset-bottom));
      padding-left: max(1rem, env(safe-area-inset-left));
      padding-right: max(1rem, env(safe-area-inset-right));
      
  4. Off-Canvas Navigation & Sidebars:

    • On screens < 768px (max-md:), sidebars must:
      • Render as an off-canvas drawer (fixed inset-y-0 left-0 z-50 or right-0).
      • Include an animated backdrop overlay (fixed inset-0 bg-black/60 backdrop-blur-sm z-40).
      • Smoothly slide in and out (transition-transform duration-300).
      • Close automatically on backdrop click, Escape key, or route navigation.
      • Preserve a floating hamburger trigger visible only on mobile (md:hidden fixed top-3 left-3 z-30).
    • On desktop (md: and above):
      • Mount as structural flex children (shrink-0 relative).
  5. Adaptive Modals and Dialogs:

    • Desktop (md:): Centered floating dialog (max-w-lg mx-auto rounded-2xl).
    • Mobile: Bottom-sheet behavior (fixed inset-x-0 bottom-0 rounded-t-2xl max-h-[90dvh] overflow-y-auto).
  6. Flexible Data & Grid Layouts:

    • Tables must be wrapped with horizontal scroll containers:
      <div className="w-full overflow-x-auto -mx-4 px-4 sm:mx-0 sm:px-0">
      
    • Cards and tile lists must use auto-fit CSS grids instead of fixed column counts:
      grid-template-columns: repeat(auto-fit, minmax(min(100%, 280px), 1fr));
      
  7. Touch Targets & Typography:

    • Minimum interactive touch target size: 44px x 44px (or min-h-[44px] min-w-[44px]).
    • Inputs must have font-size >= 16px on mobile to prevent automatic browser zoom in iOS Safari.
    • Text truncation: Use truncate or line-clamp-2 with full tooltips or expandable views.