name: mobile-responsiveness

description: > Ensure every website, web app, landing page, dashboard, or UI component is fully responsive across all screen sizes — mobile, tablet, desktop, ultrawide, and foldable devices. ALWAYS use this skill whenever you are asked to create, build, generate, or code any web page, website, web application, UI component, dashboard, layout, landing page, portfolio, form, or any HTML/CSS/JS/React/Vue/Svelte/Angular output. This skill applies regardless of the CSS framework (Tailwind, Bootstrap, plain CSS, CSS Modules, styled-components, etc.) or UI library being used. Even if the user does not mention “responsive” or “mobile” — every web output MUST be responsive by default. Treat responsiveness as a non-negotiable baseline, not an optional add-on. Triggers on: website, web page, web app, UI, component, layout, dashboard, landing page, portfolio, form, artifact, HTML, React, frontend, build me a site, create a page, make a component, or any request whose output will be rendered in a browser.

Mobile Responsiveness Skill

Golden Rule: Every web output is responsive by default. No exceptions.

When building any web interface, responsiveness is not a feature — it is a fundamental requirement. Every layout, component, and interactive element must adapt gracefully from 320px mobile screens to 2560px+ ultrawide monitors. This document provides the complete set of rules and patterns to follow, regardless of your tech stack or CSS framework.

1. Mobile-First Mindset

Build for the smallest screen first, then progressively enhance for larger viewports.

Why mobile-first matters: Starting with mobile forces you to prioritize content, simplify layouts, and design for constraints. Enhancing upward is far easier and more reliable than trying to shrink a desktop layout down to mobile.

In practice, this means:

Your base (un-media-queried) styles define the mobile layout
Use min-width media queries to layer on tablet and desktop enhancements
Never write desktop-first CSS that you then override with max-width queries for mobile
Content hierarchy should be determined at the mobile level — desktop just gets more room

2. The Viewport Meta Tag

Every HTML document MUST include this in the <head>:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Without this tag, mobile browsers will render the page at a virtual desktop width (~980px) and zoom out, making everything tiny and unreadable. This single line is the foundation of all mobile responsiveness. Never omit it.

3. Breakpoint Strategy

Use these breakpoints as your standard reference. They cover all common device categories:

Token	Min-width	Target devices
`xs`	0	Small phones (320px–479px)
`sm`	480px	Large phones (480px–639px)
`md`	640px	Small tablets, large phones landscape
`lg`	768px	Tablets portrait
`xl`	1024px	Tablets landscape, small laptops
`2xl`	1280px	Laptops, desktops
`3xl`	1536px	Large desktops, ultrawide

Framework mappings (for reference):

Tailwind CSS: sm:640, md:768, lg:1024, xl:1280, 2xl:1536
Bootstrap: sm:576, md:768, lg:992, xl:1200, xxl:1400
Plain CSS: Use the table above with @media (min-width: ...) queries

Important: Don’t use breakpoints mechanically. Test your layout by resizing continuously from 320px to 2000px+. If something breaks at 520px, add a breakpoint at 520px. Content dictates breakpoints, not arbitrary device widths.

4. Layout Rules

4.1 Fluid Containers

Every top-level container must be fluid with a sensible max-width:

Container behavior:
  - width: 100%
  - max-width: 1200px–1400px (adjust to your design)
  - padding-inline: 16px (mobile) → 24px (tablet) → 32px+ (desktop)
  - margin-inline: auto (centers the container)

Never use a fixed pixel width on your main container. It will overflow on any screen smaller than that width.

4.2 Grid and Flex Layouts Must Collapse

Every multi-column layout must gracefully reduce columns on smaller screens:

Column behavior by viewport:
  < 480px:    1 column  (full width, stacked)
  480–767px:  1–2 columns
  768–1023px: 2–3 columns
  1024px+:    3–4+ columns (as designed)

CSS Grid approach: Use auto-fit or auto-fill with minmax() so the grid adapts automatically:

grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));

Flexbox approach: Use flex-wrap: wrap so items flow to the next row when space runs out.

Tailwind approach:

grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4

4.3 No Horizontal Overflow

This is a hard rule. At no viewport width should the page produce a horizontal scrollbar on the main content. Common causes and fixes:

Fixed-width elements: Replace with max-width: 100%
Wide tables: Wrap in a horizontally scrollable container
Long unbroken text/URLs: Apply overflow-wrap: break-word or word-break: break-word
Absolute positioned elements: Ensure they don’t extend beyond the viewport
Large images: Always use max-width: 100%; height: auto;
Pre/code blocks: Wrap in overflow-x: auto container

4.4 Spacing Scales Down

Padding and margins should reduce on smaller screens. Generous whitespace on desktop becomes tighter on mobile to conserve precious vertical space:

Desktop padding/gap: 32px–48px
Tablet padding/gap:  24px–32px
Mobile padding/gap:  12px–16px

Use relative units (rem, em, clamp()) or responsive utility classes to achieve this.

5. Typography Rules

5.1 Fluid Typography

Text must be readable at every viewport width without manual zooming.

Minimum base font size: 16px (1rem). Never go below this for body text on any device. Mobile browsers may zoom in on inputs with font-size below 16px, causing layout shifts.

Use clamp() for fluid scaling:

font-size: clamp(1rem, 0.9rem + 0.5vw, 1.25rem);       /* body */
font-size: clamp(1.5rem, 1.2rem + 1.5vw, 3rem);         /* h1 */
font-size: clamp(1.25rem, 1rem + 1vw, 2rem);             /* h2 */

5.2 Line Length

Optimal reading line length is 45–75 characters. On wide screens, constrain text containers with max-width: 65ch or similar to prevent lines from stretching too far.

5.3 Text Overflow

Long titles, names, or dynamic content must not break layouts:

Apply overflow: hidden; text-overflow: ellipsis; white-space: nowrap; for single-line truncation
Or use -webkit-line-clamp for multi-line truncation
For URLs or code: word-break: break-all or overflow-wrap: anywhere

6. Images and Media

6.1 Responsive Images

Every image must have:

img {
  max-width: 100%;
  height: auto;
  display: block;
}

For hero/banner images, use object-fit: cover with a defined aspect ratio to prevent distortion:

.hero-img {
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

6.2 Art Direction with `<picture>`

When an image needs different crops at different sizes (e.g., a wide panorama on desktop vs. a square crop on mobile), use the <picture> element:

<picture>
  <source media="(min-width: 768px)" srcset="wide.jpg">
  <img src="square.jpg" alt="Description">
</picture>

6.3 Embedded Media (Videos, Maps, Iframes)

Use the aspect-ratio technique to make embeds responsive:

.embed-container {
  position: relative;
  width: 100%;
  aspect-ratio: 16 / 9;
}
.embed-container iframe {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
}

7. Navigation

Navigation is the most common responsiveness failure point. Follow these patterns:

7.1 Mobile Navigation (< 768px)

Hide the full nav behind a hamburger menu icon (minimum 44×44px tap target)
On toggle: show a full-screen overlay, slide-out drawer, or dropdown panel
Nav items stacked vertically with minimum 48px height per item
Include a visible close button
Prevent background scrolling when nav is open (overflow: hidden on body)

7.2 Tablet Navigation (768px–1023px)

Condensed horizontal nav with fewer visible items
“More” dropdown for overflow items
Or: icon-only nav with tooltips

7.3 Desktop Navigation (1024px+)

Full horizontal navigation bar with all items visible
Dropdown submenus on hover or click
Search bar inline if applicable

Key principle: Never let navigation items wrap to a second row and create a messy layout. Either they all fit in one row, or you switch to a mobile pattern.

8. Touch and Interaction Targets

Mobile users interact with fingers, not precise mouse cursors.

8.1 Minimum Tap Target Sizes

Buttons: 44px × 44px minimum (48px recommended)
Links in lists/menus: 44px minimum height
Icon buttons: The tap area must be 44×44px even if the icon is 24px
Spacing between adjacent targets: 8px minimum gap

8.2 Hover States

Hover effects don’t exist on touch devices. Never hide essential information or actions behind hover-only interactions.

Use hover as an enhancement on desktop, not a requirement
Ensure every hover-revealed element is also accessible via tap or is always visible on mobile
Consider using @media (hover: hover) to apply hover styles only on devices that support it

8.3 Form Inputs on Mobile

Input height: 44px minimum
Font size in inputs: 16px minimum (prevents iOS zoom)
Use appropriate type attributes (tel, email, number, date) to trigger correct mobile keyboards
Labels above inputs (not inline or floating on mobile)
Submit buttons: full-width on mobile

9. Component-Specific Patterns

9.1 Tables

Tables are notoriously hard to make responsive. Choose one of these strategies:

Strategy A — Horizontal scroll: Wrap the table in a container with overflow-x: auto. Keep the table intact but scrollable. Optionally make the first column sticky.

Strategy B — Card transformation: On mobile, transform each row into a card with label-value pairs stacked vertically. Hide the <thead> and use data-label attributes.

Strategy C — Priority columns: Show only essential columns on mobile with a “Show more” toggle to reveal the rest.

9.2 Modals and Dialogs

Mobile: Full-screen (100vw × 100vh), fixed header/footer, scrollable body
Desktop: Centered overlay with max-width (500–700px), backdrop click to close
Always prevent body scroll when modal is open
Close button must be prominent and easily tappable

9.3 Sidebars

Mobile: Hidden by default, revealed via toggle as an overlay (off-canvas)
Tablet: Collapsible icon-only rail
Desktop: Persistent full sidebar

9.4 Cards

Mobile: Full-width, stacked vertically
Tablet: 2-column grid
Desktop: 3–4 column grid
Card actions (buttons/links) should be full-width on mobile, inline on desktop

9.5 Hero Sections

Mobile: Stack text and image vertically, center-aligned text, full-width CTA button
Desktop: Side-by-side layout (text + image), left-aligned text, inline CTA

10. CSS Techniques Reference

These patterns work in any framework. Use the equivalent utility classes if you’re in Tailwind/Bootstrap/etc.

10.1 The `clamp()` Function

/* Fluid sizing that respects min and max bounds */
width: clamp(300px, 50vw, 800px);
font-size: clamp(1rem, 2.5vw, 2rem);
padding: clamp(1rem, 3vw, 3rem);

10.2 Container Queries (Modern CSS)

/* Respond to parent container size, not viewport */
@container (min-width: 400px) {
  .card { flex-direction: row; }
}

Use when components need to adapt based on where they’re placed, not just the screen size.

10.3 Logical Properties

/* Internationalization-friendly spacing */
padding-inline: 1rem;   /* left/right in LTR, right/left in RTL */
margin-block: 2rem;      /* top/bottom */

10.4 Aspect Ratio

.video-wrapper { aspect-ratio: 16 / 9; }
.avatar { aspect-ratio: 1; }

10.5 Hiding/Showing Elements

Sometimes content needs to be hidden on certain viewports (e.g., a decorative element that clutters mobile). Use:

/* Plain CSS */
@media (max-width: 767px) { .desktop-only { display: none; } }
@media (min-width: 768px) { .mobile-only { display: none; } }

<!-- Tailwind -->
<div class="hidden md:block">Desktop only</div>
<div class="block md:hidden">Mobile only</div>

11. Testing Checklist

Before considering any web output complete, verify ALL of the following:

Viewport resizing test (mandatory):

Resize browser continuously from 320px → 2000px+ — nothing breaks
No horizontal scrollbar appears at any width
All text remains readable without zooming
All images stay within their containers
No content is cut off or hidden unintentionally

Breakpoint tests:

320px — small phone (iPhone SE, Galaxy S series)
375px — standard phone (iPhone 12/13/14/15)
428px — large phone (iPhone Pro Max)
768px — tablet portrait (iPad)
1024px — tablet landscape / small laptop
1280px — standard laptop/desktop
1920px — full HD monitor

Interaction tests:

All buttons and links have 44px+ tap targets
Navigation works correctly at every viewport
Forms are usable on mobile (correct keyboards, adequate input sizes)
Modals/dropdowns fit within the viewport on mobile
No functionality is locked behind hover-only interactions

Content tests:

Long text content wraps properly, never overflows
Dynamic content (user-generated, API-fetched) doesn’t break layouts
Empty states and loading states are responsive too
Scrolling is smooth and only vertical on main content

12. Common Mistakes to Avoid

These are the most frequent responsiveness failures. Actively check for each one:

Forgetting the viewport meta tag — Page renders at 980px virtual width on mobile
Using fixed pixel widths on containers, columns, or cards
Desktop-only navigation — Links overflow or wrap on mobile with no hamburger menu
Tiny tap targets — Buttons/links too small to tap accurately on touch screens
Hiding content behind hover states — Invisible to touch users
Images without max-width: 100% — They overflow their containers on small screens
Input font-size < 16px — Triggers unwanted zoom on iOS Safari
Fixed positioning that ignores mobile — Elements covering content on small screens
Testing only at one “mobile” width — Missing issues at intermediate sizes
Ignoring landscape orientation — Many users rotate their phones
Long unbroken strings — URLs, email addresses, code that overflow containers
Hardcoded heights — Content gets clipped when it needs more vertical space on mobile

13. Quick-Reference: Framework Cheatsheet

Plain CSS — Responsive Grid

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: 1rem;
}

Tailwind CSS — Responsive Card Grid

<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 p-4">
  <div class="bg-white rounded-lg shadow p-4">Card</div>
</div>

Bootstrap — Responsive Columns

<div class="container">
  <div class="row">
    <div class="col-12 col-md-6 col-lg-4">Column</div>
  </div>
</div>

CSS-in-JS (styled-components, Emotion, etc.)

const Container = styled.div`
  display: grid;
  grid-template-columns: 1fr;
  gap: 1rem;
  @media (min-width: 768px) {
    grid-template-columns: repeat(2, 1fr);
  }
  @media (min-width: 1024px) {
    grid-template-columns: repeat(3, 1fr);
  }
`;

Summary

When you build any web interface, apply these rules automatically:

Include the viewport meta tag — Always, no exceptions
Design mobile-first — Base styles = mobile, enhance upward
Use fluid layouts — %, fr, auto-fit, clamp(), not fixed px
Collapse grids — Multi-column → single-column on mobile
Make images responsive — max-width: 100%; height: auto;
Adapt navigation — Hamburger/drawer on mobile, full bar on desktop
Size touch targets — 44px minimum on all interactive elements
Scale typography — clamp() or responsive utilities, min 16px body text
Eliminate horizontal scroll — At every viewport width
Test at all widths — 320px through 2000px+, not just one “mobile” size

Responsiveness is not optional. It is the default state of every web output.