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

64 lines
3.2 KiB
Markdown

---
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
<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:
```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.