--- name: responsive-mobile-first description: >- 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: ```css 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: ```jsx
``` - Cards and tile lists must use auto-fit CSS grids instead of fixed column counts: ```css 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.