Ask Claude Code to "make this responsive" without explaining anything. Here's what
you get: desktop-first media queries with max-width everywhere,
text-align: justify that looks like swiss cheese on an iPhone SE, 32px-tall
buttons untappable with a thumb, and no font-size: 16px on inputs —
so guaranteed automatic iOS zoom. This isn't incompetence, it's a lack of context.
Claude codes with the generic CSS rules it knows, not the mobile-specific rules you
have in mind.
The solution: a specialized CLAUDE.md file. Not the project's generic CLAUDE.md, a dedicated file for mobile redesign and CSS design, with precise rules, pitfalls to avoid, and targets to reach. Claude reads it at session startup and applies these rules consistently.
The problem: Claude without mobile context
Claude Code is a generalist tool. It knows CSS, it knows responsive design, but it doesn't know what your priorities are. Does the project target iPhone SE at 375px or tablets at 768px? Does Lighthouse Accessibility need to hit 90? Is dark mode mandatory? Do you prefer BEM or utility-first?
Without this information, Claude produces correct but generic CSS. It will:
- Start from desktop and work down (
max-width) rather than the reverse - Forget
min-width: 0on flex items — result: mysterious overflows - Leave inputs at 14px — iOS zoom on every tap
- Add
text-align: justifybecause "it looks clean" - Ignore
prefers-reduced-motionandsafe-area-inset - Not test dark mode
Each of these problems takes 10 seconds to fix once detected. The problem is they pile up and you detect them after shipping.
The specialized CLAUDE.md concept
Claude Code automatically reads CLAUDE.md files present in the project
— at the root, and in subdirectories if the instruction is in the config. This is the
official mechanism for injecting persistent context into a Claude Code session, without
having to repeat it in every prompt.
Most projects have a generic CLAUDE.md: project architecture, code conventions, dev commands. The idea here is different: create specialized CLAUDE.md files for specific tasks. A file dedicated to mobile redesign contains exactly what Claude needs for that task — and nothing superfluous.
You can call it CLAUDE-MOBILE.md and reference it from the main CLAUDE.md,
or simply drop it temporarily at the root as CLAUDE.md for the duration
of the responsive work. Claude Code also supports the .claude/ directory
for additional context files — they're loaded in addition to the root CLAUDE.md,
not instead of it.
What this MD contains — and why each section
The file is structured in five sections. Each one responds to a specific moment in the work.
Section 1 — Audit workflow. Before writing any CSS, you need to know where to look. This section gives Claude a precise order: first the viewport tag, then input font sizes, then horizontal overflow, then touch targets. This is the order that minimizes time spent debugging problems caused by an upstream oversight. It also includes Lighthouse targets and the "mobile done" checklist — which prevents Claude from declaring the work finished too early.
Section 2 — Mobile testing tools. Playwright scripts for automated
screenshots across multiple device profiles — iPhone SE, iPhone 14, Pixel 7, iPad —
without leaving the terminal. Variants for dark mode and prefers-reduced-motion.
MCP servers (Puppeteer MCP, Playwright MCP) that allow Claude Code to interact directly
with a headless browser during the session. And Lighthouse via CLI to audit in JSON or
HTML without opening DevTools.
Section 3 — CSS rules. The complete reference of mobile rules with
concrete code for each. Not generic docs: ready-to-use snippets with edge cases already
handled. The min-width: 0 trap on flex items, coexistence of the manual
toggle with prefers-color-scheme, HTML inputmode attributes
that complement the CSS for forms — everything that gets lost when working fast.
Section 4 — Generic CSS conventions. Mobile or not, these rules
apply to any CSS work: custom properties for theming, BEM for components,
focus-visible for keyboard accessibility, modern properties
(clamp(), gap, aspect-ratio, logical properties),
and the rule on !important. This is what prevents the session's CSS from
looking like a patch applied over existing code.
Section 5 — Test checklist. Devices to test, modes (landscape, dark, reduced motion, text zoom), Lighthouse targets by metric, and screen reader testing basics. Claude uses this to know when the task is truly done, not just "passes on my Chrome emulator at 1440px".
How to use it
Three ways, from simplest to cleanest:
Option 1 — Temporary replacement. Rename or save the existing CLAUDE.md,
drop this file at the root as CLAUDE.md for the duration of the responsive
work. Restore the original when done. Simple, no configuration.
Option 2 — Reference from existing CLAUDE.md. Add a line to the project's CLAUDE.md:
## Mobile context
For all responsive and CSS work:
see CLAUDE-MOBILE.md at the project root.Claude Code follows references and reads the pointed file.
Option 3 — .claude/ directory. Place the file in
.claude/mobile-css.md. Claude Code automatically loads files
in this directory in addition to the root CLAUDE.md. Useful if you have
multiple specialized contexts (one for mobile, one for tests, one for deployment)
and don't want to merge them.
In all cases, the file stacks with the existing context — it doesn't replace already-present instructions.
The complete file
Here is the exact content to copy. This is the raw file, ready to paste.
# 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×44pxDownload the file
The file is available directly:
Download the CLAUDE.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.