## Mobile context

For all responsive and CSS work:
see CLAUDE-MOBILE.md at the project root.

# CLAUDE.md — Mobile Redesign & CSS Design

> Specialized context for Claude Code. Drop this file at the project root to guide mobile responsive and CSS design work.

---

## Section 1: Mobile redesign workflow

### Initial audit — where to start

Before touching a single line of CSS, do a quick pass in this order:

1. **Viewport tag** — present? `width=device-width, initial-scale=1`? No `user-scalable=no`?
2. **font-size on inputs** — inspect `<input>`, `<textarea>`, `<select>` fields. If < 16px: iOS zoom guaranteed.
3. **Horizontal overflow** — open Chrome DevTools in mobile mode, check if a scrollbar appears at the bottom. Track with `* { outline: 1px solid red; }`.
4. **Touch targets** — tap buttons and nav links in emulation mode. Anything under 44px height needs fixing.
5. **Justified text** — search for `text-align: justify` in CSS. Remove or limit to desktop only.

### Mobile Lighthouse — targets

Run Lighthouse in "Mobile" mode (not Desktop) in DevTools:

| Metric | Target |
|--------|--------|
| Performance | ≥ 80 |
| Accessibility | ≥ 90 |
| Best Practices | ≥ 90 |
| SEO | ≥ 90 |

Priority alerts to fix: tap targets too small, insufficient contrast, missing viewport, inputs without label.

### DevTools device emulation

- Test with profiles: **iPhone SE (375px)**, **iPhone 14 (390px)**, **Pixel 7 (412px)**, **iPad (768px)**
- Enable "Show media queries" to see active breakpoints
- Test in landscape mode
- Simulate "Slow 4G" network to detect performance issues

### Testing on a real device

Emulation doesn't replace real testing. Specific points to check on an actual phone:
- Automatic iOS zoom on inputs (only visible on real device)
- Scroll momentum and bounce zones
- Safe areas (notch, navigation bar)
- Virtual keyboard pushing the layout

### "Mobile done" checklist

- [ ] No unintentional horizontal scroll
- [ ] All interactive elements ≥ 44×44px
- [ ] No input with font-size < 16px
- [ ] Correct viewport meta tag
- [ ] No `text-align: justify` on mobile
- [ ] Body text ≥ 16px, line-height ≥ 1.5
- [ ] Images with `max-width: 100%`
- [ ] Dark mode works (if implemented)
- [ ] Animations respect `prefers-reduced-motion`
- [ ] Lighthouse Accessibility ≥ 90

---

## Section 2: Mobile testing tools — screenshots, emulation, MCP

### Installing test dependencies

```

bash
# Playwright (recommended — multi-browser)
npm init -y
npm install playwright
npx playwright install chromium

# OR Puppeteer (Chromium only)
npm install puppeteer


```

### Automated mobile screenshots

```

javascript
// screenshot-mobile.mjs
import { chromium } from 'playwright';

const devices = [
  { name: 'iPhone SE', width: 375, height: 667, scale: 2 },
  { name: 'iPhone 14', width: 390, height: 844, scale: 3 },
  { name: 'Pixel 7', width: 412, height: 915, scale: 2.625 },
  { name: 'iPad', width: 768, height: 1024, scale: 2 },
];

const url = process.argv[2] || 'http://localhost:8000';

const browser = await chromium.launch();

for (const device of devices) {
  const context = await browser.newContext({
    viewport: { width: device.width, height: device.height },
    deviceScaleFactor: device.scale,
    isMobile: device.width < 768,
    hasTouch: device.width < 768,
  });
  const page = await context.newPage();
  await page.goto(url, { waitUntil: 'networkidle' });
  await page.screenshot({
    path: `screenshot-${device.name.toLowerCase().replace(/\s/g, '-')}.png`,
    fullPage: true,
  });
  console.log(`✓ ${device.name} (${device.width}px)`);
  await context.close();
}

await browser.close();


```

Usage:

```

bash
node screenshot-mobile.mjs http://localhost:8000
# Generates: screenshot-iphone-se.png, screenshot-iphone-14.png, etc.


```

Claude Code can read these screenshots to visually verify rendering.

### Dark mode and reduced motion screenshots

```

javascript
// screenshot-modes.mjs — dark mode and reduced motion variants
import { chromium } from 'playwright';

const url = process.argv[2] || 'http://localhost:8000';
const browser = await chromium.launch();

// Dark mode - iPhone 14
const darkCtx = await browser.newContext({
  viewport: { width: 390, height: 844 },
  deviceScaleFactor: 3,
  isMobile: true,
  hasTouch: true,
  colorScheme: 'dark',
});
const darkPage = await darkCtx.newPage();
await darkPage.goto(url, { waitUntil: 'networkidle' });
await darkPage.screenshot({ path: 'screenshot-dark-mode.png', fullPage: true });
console.log('✓ Dark mode');
await darkCtx.close();

// Reduced motion - iPhone 14
const reducedCtx = await browser.newContext({
  viewport: { width: 390, height: 844 },
  deviceScaleFactor: 3,
  isMobile: true,
  hasTouch: true,
  reducedMotion: 'reduce',
});
const reducedPage = await reducedCtx.newPage();
await reducedPage.goto(url, { waitUntil: 'networkidle' });
await reducedPage.screenshot({ path: 'screenshot-reduced-motion.png', fullPage: true });
console.log('✓ Reduced motion');
await reducedCtx.close();

await browser.close();


```

### Useful MCP Servers

**Puppeteer MCP** (`@modelcontextprotocol/server-puppeteer`):
- Allows Claude Code to navigate a site, take screenshots, inspect the DOM
- Configuration in `.claude/settings.json`:

```

json
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}


```

**Playwright MCP** (community `playwright-mcp`):
- Same principle, multi-browser
- Useful for testing rendering across different engines (Chromium, Firefox, WebKit/Safari)

### Lighthouse via CLI

```

bash
# Installation
npm install -g lighthouse

# Mobile audit
lighthouse http://localhost:8000 --preset=perf --form-factor=mobile --output=html --output-path=./lighthouse-mobile.html

# Mobile audit in JSON (parseable)
lighthouse http://localhost:8000 --form-factor=mobile --output=json --output-path=./lighthouse-mobile.json


```

Claude Code can read the HTML report to identify issues.

### Debug with Chrome DevTools Protocol

Playwright and Puppeteer expose CDP (Chrome DevTools Protocol), providing programmatic access to:
- **Network throttling** — simulate Slow 3G/4G to detect loading bottlenecks
- **CSS coverage** — identify CSS rules never applied (dead code)
- **Performance traces** — capture a full trace to analyze rendering frame by frame

---

## Section 3: Mobile CSS Rules — complete reference

### Viewport meta tag

```

html
<!-- ✅ Correct -->
<meta name="viewport" content="width=device-width, initial-scale=1">

<!-- If using safe-area-inset -->
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

<!-- ❌ Never do this: prevents zoom for visually impaired users -->
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, maximum-scale=1">


```

### Base reset

```

css
*,
*::before,
*::after {
    box-sizing: border-box;
}

html {
    -webkit-text-size-adjust: 100%;
    text-size-adjust: 100%;
}

html, body {
    overflow-x: hidden;
    max-width: 100%;
}

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


```

### Text alignment

Simple rule: **left by default, centered only for CTAs, never justify on mobile**.

```

css
/* Mobile base */
h1, h2, h3, h4 {
    text-align: left;
}

p, li {
    text-align: left;
}

/* CTA: centered */
.cta-wrapper {
    text-align: center;
}

/* Justify only on desktop with hyphenation */
@media (min-width: 768px) {
    .prose p {
        text-align: justify;
        hyphens: auto;
        -webkit-hyphens: auto;
    }
}


```

### Touch targets — 44×44px minimum

```

css
/* Buttons */
.btn {
    min-height: 44px;
    min-width: 44px;
    padding: 12px 20px;
    display: inline-flex;
    align-items: center;
    justify-content: center;
}

/* Navigation links */
nav a {
    display: block;
    min-height: 44px;
    padding: 12px 16px;
    line-height: 20px;
}

/* Clickable icons */
.icon-btn {
    width: 44px;
    height: 44px;
    display: flex;
    align-items: center;
    justify-content: center;
    cursor: pointer;
}

/* Enlarged tap zone without changing appearance */
.small-icon {
    position: relative;
    width: 20px;
    height: 20px;
}

.small-icon::after {
    content: '';
    position: absolute;
    inset: -12px;
}


```

### Font-size — iOS zoom prevention and readability

```

css
/* ❌ Less than 16px on inputs = automatic iOS zoom */

/* ✅ Absolute minimum on inputs */
input,
textarea,
select {
    font-size: 16px;
}

/* If different size desired on desktop */
@media (min-width: 768px) {
    input,
    textarea,
    select {
        font-size: 14px;
    }
}

/* Body text */
body {
    font-size: 16px;
    line-height: 1.6;
}

/* Fluid headings with clamp() */
h1 { font-size: clamp(1.5rem, 5vw, 2.5rem); }
h2 { font-size: clamp(1.25rem, 4vw, 2rem); }
h3 { font-size: clamp(1.1rem, 3vw, 1.5rem); }


```

### Media queries — mobile-first only

```

css
/* ✅ Mobile-first: base = mobile, add for larger screens */
.card {
    display: block;
    padding: 16px;
}

@media (min-width: 768px) {
    .card {
        display: flex;
        padding: 24px;
    }
}

@media (min-width: 1024px) {
    .card {
        padding: 32px;
    }
}

/* ❌ Desktop-first: avoid */
.card {
    display: flex;
    padding: 32px;
}

@media (max-width: 767px) {
    .card {
        display: block;
        padding: 16px;
    }
}


```

Standard breakpoints: `480px`, `768px`, `1024px`, `1280px`.

### overflow-x prevention

```

css
html, body {
    overflow-x: hidden;
    max-width: 100%;
}

/* Tables: scroll rather than breaking the layout */
.table-wrapper {
    overflow-x: auto;
}

table {
    min-width: 600px;
    width: 100%;
}

/* Debug: identify the overflowing element */
* { outline: 1px solid red; }


```

Warning: `overflow-x: hidden` on `body` can break `position: sticky`. If a sticky stops working, isolate `overflow-x: hidden` on a dedicated wrapper.

### Images and aspect-ratio

```

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

/* Fixed ratio to avoid CLS (Cumulative Layout Shift) */
.card-image {
    aspect-ratio: 4 / 3;
    width: 100%;
    object-fit: cover;
}

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

/* Different ratio on mobile */
@media (max-width: 767px) {
    .hero-image {
        aspect-ratio: 4 / 3;
    }
}


```

### Flex and Grid — common pitfalls

```

css
/* Flex: min-width: 0 required to prevent text overflows */
.flex-item {
    min-width: 0;
}

/* Automatic flex wrap */
.card-grid {
    display: flex;
    flex-wrap: wrap;
    gap: 16px;
}

.card-grid .card {
    flex: 1 1 280px;
    min-width: 0;
}

/* Responsive grid without media query */
.auto-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
    gap: 16px;
}

/* Grid: single column on mobile, two columns on desktop */
.two-col {
    display: grid;
    grid-template-columns: 1fr;
    gap: 24px;
}

@media (min-width: 768px) {
    .two-col {
        grid-template-columns: 1fr 1fr;
    }
}


```

### Safe area insets (notch, navigation bar)

```

css
/* Requires viewport-fit=cover in meta tag */

.bottom-nav {
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    height: 56px;
    padding-bottom: env(safe-area-inset-bottom);
    background: var(--color-bg);
}

.top-header {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    padding-top: env(safe-area-inset-top);
}

.main-content {
    padding-bottom: calc(56px + env(safe-area-inset-bottom));
    padding-left: env(safe-area-inset-left);
    padding-right: env(safe-area-inset-right);
}


```

If `viewport-fit=cover` is not defined, values equal 0 — these rules have no negative effect.

### prefers-reduced-motion

```

css
/* Animations defined normally */
.fade-in {
    animation: fadeIn 0.4s ease;
}

/* Global removal if user requests it */
@media (prefers-reduced-motion: reduce) {
    *,
    *::before,
    *::after {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        transition-duration: 0.01ms !important;
        scroll-behavior: auto !important;
    }
}

/* More granular approach */
@media (prefers-reduced-motion: reduce) {
    .fade-in {
        opacity: 1;
        animation: none;
    }
}


```

### prefers-color-scheme — dark mode

```

css
:root {
    --color-bg: #ffffff;
    --color-text: #1a1a1a;
    --color-text-muted: #6b7280;
    --color-border: #e5e7eb;
    --color-surface: #f9fafb;
    --color-primary: #2563eb;
    --color-primary-text: #ffffff;
    --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

@media (prefers-color-scheme: dark) {
    :root {
        --color-bg: #0f172a;
        --color-text: #e2e8f0;
        --color-text-muted: #94a3b8;
        --color-border: #1e293b;
        --color-surface: #1e293b;
        --color-primary: #3b82f6;
        --color-primary-text: #ffffff;
        --shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
    }

    img:not([src*=".svg"]) {
        filter: brightness(0.9);
    }
}

/* Manual toggle coexisting with system preference */
@media (prefers-color-scheme: dark) {
    :root:not([data-theme="light"]) {
        --color-bg: #0f172a;
        /* ... */
    }
}

[data-theme="dark"] {
    --color-bg: #0f172a;
    /* ... */
}

[data-theme="light"] {
    --color-bg: #ffffff;
    /* ... */
}


```

### Forms

```

css
input[type="text"],
input[type="email"],
input[type="password"],
input[type="tel"],
input[type="number"],
textarea,
select {
    width: 100%;
    font-size: 16px; /* required — prevents iOS zoom */
    padding: 12px 16px;
    min-height: 44px;
    border-radius: 8px;
    border: 1px solid var(--color-border);
    -webkit-appearance: none;
    appearance: none;
    background: var(--color-bg);
    color: var(--color-text);
}

label {
    display: block;
    font-size: 16px;
    margin-bottom: 6px;
    font-weight: 500;
}

.form-group {
    margin-bottom: 20px;
}


```

HTML attributes not to forget (CSS can't replace them):

```

html
<!-- Numeric keyboard -->
<input type="text" inputmode="numeric">

<!-- Decimal keyboard -->
<input type="text" inputmode="decimal">

<!-- Email keyboard with direct @ -->
<input type="email" inputmode="email">

<!-- URL keyboard -->
<input type="url" inputmode="url">


```

### Minimum lateral spacing

```

css
.container {
    padding-left: 16px;  /* absolute minimum on mobile */
    padding-right: 16px;
    max-width: 1200px;
    margin: 0 auto;
}

@media (min-width: 768px) {
    .container {
        padding-left: 24px;
        padding-right: 24px;
    }
}

@media (min-width: 1024px) {
    .container {
        padding-left: 32px;
        padding-right: 32px;
    }
}


```

---

## Section 4: CSS Conventions — generic rules

### CSS custom properties for theming

Always define repeated values as custom properties. Never hard-code colors or spacing values scattered throughout CSS.

```

css
:root {
    /* Colors */
    --color-primary: #2563eb;
    --color-primary-hover: #1d4ed8;
    --color-bg: #ffffff;
    --color-text: #1a1a1a;
    --color-text-muted: #6b7280;
    --color-border: #e5e7eb;
    --color-surface: #f9fafb;
    --color-danger: #dc2626;
    --color-success: #16a34a;

    /* Spacing */
    --space-xs: 4px;
    --space-sm: 8px;
    --space-md: 16px;
    --space-lg: 24px;
    --space-xl: 32px;
    --space-2xl: 48px;

    /* Typography */
    --font-size-sm: 0.875rem;
    --font-size-base: 1rem;
    --font-size-lg: 1.125rem;
    --font-size-xl: 1.25rem;
    --line-height-base: 1.6;
    --line-height-tight: 1.3;

    /* Radii */
    --radius-sm: 4px;
    --radius-md: 8px;
    --radius-lg: 12px;
    --radius-full: 9999px;

    /* Shadows */
    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
    --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
    --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);

    /* Transitions */
    --transition-fast: 0.15s ease;
    --transition-base: 0.25s ease;
}


```

### Naming conventions

Be consistent. BEM or utility-first, not both mixed in the same project.

**BEM** (recommended for isolated components):

```

css
/* Block */
.card {}

/* Element */
.card__title {}
.card__body {}
.card__footer {}

/* Modifier */
.card--featured {}
.card--compact {}
.card__title--large {}


```

### Accessibility

**focus-visible** — never remove the outline without replacing it:

```

css
/* ❌ Never do this */
* { outline: none; }
:focus { outline: none; }

/* ✅ Replace the native outline with a custom style */
:focus-visible {
    outline: 2px solid var(--color-primary);
    outline-offset: 2px;
    border-radius: 2px;
}

/* Remove outline only for mouse clicks (not keyboard) */
:focus:not(:focus-visible) {
    outline: none;
}


```

**WCAG AA contrasts**:

| Context | Minimum ratio |
|---------|--------------|
| Normal text (< 18px) | 4.5:1 |
| Large text (≥ 18px or ≥ 14px bold) | 3:1 |
| UI components, icons | 3:1 |

### CSS performance

```

css
/* ❌ Triggers repaint on every animation frame */
.card:hover {
    box-shadow: 0 8px 30px rgba(0,0,0,0.2);
}

/* ✅ Better: prepare the shadow on load, change opacity */
.card {
    box-shadow: 0 8px 30px rgba(0,0,0,0);
    transition: box-shadow var(--transition-base);
}
.card:hover {
    box-shadow: 0 8px 30px rgba(0,0,0,0.2);
}

/* ✅ Use opacity or transform — composited on GPU */
.element {
    transform: translateY(0);
    opacity: 1;
    transition: transform var(--transition-base), opacity var(--transition-base);
}

.element.hidden {
    transform: translateY(8px);
    opacity: 0;
}


```

### Modern CSS to prefer

```

css
/* clamp() — fluid sizes without media queries */
h1 { font-size: clamp(1.5rem, 5vw, 2.5rem); }
.container { padding: clamp(16px, 4vw, 48px); }

/* gap — more readable than margin on children */
.grid {
    display: flex;
    gap: 24px;
}

/* aspect-ratio — more reliable than the padding-top hack */
.video-wrapper {
    aspect-ratio: 16 / 9;
    width: 100%;
}

/* Logical properties — for multilingual support (RTL/LTR) */
.card {
    margin-inline: auto;
    padding-block: 24px;
    border-inline-start: 3px solid var(--color-primary);
}

/* inset — replaces top/right/bottom/left */
.overlay {
    position: fixed;
    inset: 0;
}


```

### Rule on !important

`!important` is accepted only in two cases:
1. Utility classes (`.sr-only`, `.hidden`, `.visually-hidden`) — by convention
2. Overriding third-party styles you don't control (plugins, libraries)

Outside these cases, a `!important` signals a specificity problem to fix at the source.

---

## Section 5: Test checklist

### Devices to test

| Device | Width | Priority |
|--------|-------|----------|
| iPhone SE (2020/2022) | 375px | High — narrowest mainstream screen |
| iPhone 14 / 15 | 390px | High — current iOS reference |
| Android mid-range (Pixel 6a, Samsung A54) | 360–412px | High |
| iPad / iPad Mini | 768px | Medium |
| Desktop laptop | 1280–1440px | Baseline |

### Modes to test

- [ ] Portrait (default)
- [ ] Landscape
- [ ] Dark mode
- [ ] Reduced motion
- [ ] Text zoom at 150%

### Lighthouse — targets

| Score | Target |
|-------|--------|
| Performance | ≥ 80 |
| Accessibility | ≥ 90 |
| Best Practices | ≥ 90 |
| SEO | ≥ 90 |

### Final checklist

- [ ] No horizontal scroll on any tested device
- [ ] All interactive elements keyboard accessible (Tab + Enter/Space)
- [ ] focus-visible visible and distinctive
- [ ] All inputs with font-size ≥ 16px
- [ ] Text with contrast ≥ 4.5:1 (normal) or 3:1 (large)
- [ ] Images with descriptive `alt` or `alt=""` if decorative
- [ ] Forms with `<label>` associated to each input
- [ ] Dark mode: readable text, no blinding white
- [ ] Reduced motion: no animation still playing
- [ ] Lighthouse Accessibility ≥ 90
- [ ] No automatic iOS zoom on inputs
- [ ] Touch targets ≥ 44×44px
```

`

## Download the file

The file is available directly: [Download the CLAUDE.md](https://www.web-developpeur.com/blog/claude-md/contexts/mobile-css-redesign.md). Drop it at the project root or in `.claude/`.

## What's next

The idea behind this file is to build a collection of specialized CLAUDE.md files by task type. Not a generic CLAUDE.md that tries to cover everything and becomes unreadable, but targeted files you activate based on the current work. Mobile CSS, Go unit tests, PostgreSQL migrations, security audit — each with its precise context, targets, and pitfalls.

This one is the first in the series. If you have specialized contexts you already use, or tasks for which you'd like a file of the same kind, the comments are open.

**📄 Associated CLAUDE.md**

[View](https://www.web-developpeur.com/blog/claude-md/view.php?ctx=mobile-css-redesign) • [Download](https://www.web-developpeur.com/blog/claude-md/contexts/mobile-css-redesign.md) • [Catalogue](https://www.web-developpeur.com/blog/claude-md/)