/mobile-first

Mobile first

Make the primary task usable on narrow, zoomed, touch, keyboard, and reduced-motion presentations. Reconsider layout relationships when width changes; do not merely shrink the desktop composition or optimize for the shortest possible page.

Own responsive behavior, not the product

This skill owns viewport-dependent layout, reflow, overflow, touch ergonomics, focus visibility, mobile navigation behavior, and responsive verification.

It does not rewrite the proposition, remove product requirements, invent a mobile-only conversion funnel, or replace the project's visual system. Use landing-page or interface-design first when the underlying information architecture or interface job is wrong.

Choose the mode

• Audit — measure and report without changing files.
• Repair — measure, implement the smallest coherent responsive changes, then compare.
• Build — apply the responsive contract while creating a new interface; there is no before-state baseline.
• Handoff — provide sequenced, independently executable change briefs when the user asks another person or agent to implement.

Infer the mode from the request and state it in one sentence. A request to fix or build authorizes in-scope implementation; do not stop at prompts unless handoff was requested.

Inspect before choosing a transform

Read the repository's instructions, layout primitives, tokens, breakpoints, navigation, content extremes, browser tests, and supported device requirements. Render the current interface when possible.

For an existing interface, read references/audit.md and record the baseline before editing. Page height is diagnostic context, not a target: a shorter page can be worse when it hides comparison, proof, controls, or recovery paths.

Resolve consequential choices interactively

Most responsive repairs are reversible; make them without interrogation. Ask only when two plausible layouts materially change content order, navigation access, comparison behavior, or the primary action.

When blocked, present the observed constraint, a recommended option, and one alternative with its tradeoff. Ask one concise question. Examples include whether dense data must remain comparable, whether a persistent action is a real product requirement, or which content owns priority when two desktop columns cannot remain simultaneous.

Do not ask the user to choose breakpoints, CSS properties, or implementation details the repository can answer.

Choose layout from the content relationship

Read references/patterns.md when a desktop primitive fails narrowly. Decide per component:

• Preserve sequence when items must be read in order.
• Preserve comparison when differences matter simultaneously.
• Preserve access to navigation and primary actions without making every action sticky.
• Use a contained horizontal region only when the content genuinely benefits from two-dimensional or browseable presentation.
• Keep reading content within the viewport; never let an intentional table or carousel expand the document.

Breakpoints belong where content or controls stop working, not at arbitrary device labels. Reuse existing breakpoints when they solve the observed failure.

Implement within the existing system

• Prefer intrinsic sizing, wrapping, grid minmax(0, 1fr), flex children with min-width: 0, and content-driven constraints before adding breakpoints.
• Preserve semantic order even when visual order changes.
• Keep focus order aligned with reading and interaction order.
• Give custom controls a practical touch target while applying WCAG size and spacing exceptions correctly.
• Contain tables, diagrams, and carousels in named, keyboard-reachable scroll regions when horizontal scrolling is necessary.
• Account for safe areas and obscured focus when controls are fixed or sticky.
• Choose svh, dvh, or ordinary document flow from the intended behavior; do not mechanically replace every vh declaration.
• Provide a complete static state for reduced-motion users rather than merely shortening animations.

Do not add a carousel, hamburger, bottom CTA bar, or mobile-only content duplication as a default. Each needs a content or product reason.

Verify the outcome

Read references/standards.md before making a compliance claim. After implementation:

1. Re-run the baseline measurements at 320px, 375px, 768px, and 1440px where supported.
2. Test 200% zoom and the 320 CSS-pixel reflow condition; use 400% zoom when validating WCAG reflow on a 1280px-wide presentation.
3. Exercise keyboard navigation, visible focus, touch controls, orientation changes, text enlargement, and reduced motion.
4. Test realistic long labels, localization expansion, error states, open menus, dialogs, and software-keyboard behavior where relevant.
5. Check a real phone when browser chrome, safe areas, input keyboards, or installed-web-app behavior could change the result.
6. Run the repository's build, tests, and browser checks.

Deliver

For an audit, provide the measurement table, ranked findings, preserved strengths, and sequenced repairs without editing files.

For a repair or build, report:

• the observed failures and chosen responsive transformations;
• files changed and meaningful product tradeoffs;
• before/after measurements where a baseline existed;
• widths, zoom levels, states, inputs, and motion preferences tested;
• real-device or production checks that remain.

Do not claim “mobile complete” from a single screenshot or the absence of document overflow.

Responsive audit

Use this procedure before repairing an existing interface and again afterward. Adapt the matrix to the product's supported environments.

Measurement matrix

Capture at least 320px, 375px, 768px, and 1440px widths when the application supports the web. Record browser, device scale, theme, authentication state, and whether the data is real or fixture content.

At each relevant width inspect:

1. document scrollWidth versus viewport width;
2. total page height as context, not a pass/fail score;
3. each section or major region's height and dominant content;
4. clipped, overlapping, truncated, or off-screen elements;
5. line wrapping for headings, controls, URLs, code, and long labels;
6. navigation, dialogs, menus, forms, errors, and software-keyboard interaction;
7. fixed or sticky elements that obscure content or focused controls.

Distinguish overflow correctly

• Document-level overflow: normally a defect for reading content. Identify the exact element expanding the layout.
• Contained two-dimensional region: potentially valid for a table, diagram, comparison, or browseable panels. The container must stay within the viewport and expose an understandable scroll affordance.
• Decorative bleed: acceptable only when it cannot create a scrollbar, hide information, or capture interaction.

Do not flag descendants of a correctly contained scroll region merely because their bounding boxes extend past the viewport.

Interaction and accessibility

List custom buttons, links outside running prose, form controls, and icon controls that are smaller than 24×24 CSS pixels or fail the WCAG spacing test. Separately identify controls below the project's ergonomic target, often 44×44, without calling that WCAG AA failure.

Measure text contrast against the background that actually renders. Test keyboard order, visible focus, focus not obscured by sticky UI, names and states, 200% text resize, and the 320 CSS-pixel reflow condition.

Emulate prefers-reduced-motion: reduce. List animations and verify that content remains visible and every essential state change remains understandable.

Content and action inventory

Record:

• distinct CTA labels and destinations;
• content whose order changes by breakpoint;
• content hidden at any width and the alternative access path;
• dense regions that stack into long repetition;
• tasks that require comparison, scanning, or simultaneous context.

Output table

Rank findings by task failure, information loss, inaccessible interaction, unintended document overflow, obscured focus, and then avoidable friction. Do not rank purely by page height.

Responsive layout patterns

Use these as candidate transformations after measurement. Choose from content relationships; none is a universal mobile replacement.

Multi-column content

• Stack when items form a sequence or each needs full-width reading.
• Wrap into fewer columns when cards are independent and comparison is not essential.
• Contained browse row when a small set is independently meaningful and partial next-item visibility can communicate scrollability.
• Selector plus one detail panel when many options share a large detail body.
• Compact comparison when differences must remain simultaneous; reduce decoration before removing information.

Avoid turning ordered instructions, accessibility-critical content, or more than a small browseable set into a swipe-only carousel.

Tables and dense data

Preserve the table when row-to-column relationships matter. First try concise headers, sensible column priorities, wrapping, sticky row labels, and a contained scroll region. Provide a stacked or detail view only when it preserves the same meaning and actions.

Name scroll regions, make them keyboard reachable when needed, retain visible focus, and give touch and keyboard users a cue that more content exists. Never let a minimum-width table expand unrelated page content.

Split layouts and heroes

Choose mobile order from the task, not DOM convenience. Product evidence may belong before supporting copy when recognition is the main uncertainty; the action may belong before media when the visitor already understands the product.

Keep source order semantic. Use CSS visual reordering sparingly because keyboard and assistive-technology order generally follows the DOM.

Navigation

Keep essential destinations and the current location available. A compact menu is valid when it has an accessible name, visible trigger state, focus management, escape behavior, and a usable open layout.

A persistent bottom action is appropriate only when the action remains relevant throughout the task, does not obscure content or focus, accounts for safe areas, and has product approval. It is not required merely because the navigation collapsed.

Viewport height and fixed UI

• Use ordinary document flow when content should define height.
• Use 100svh when a panel must fit within the smallest viewport with browser chrome present.
• Use 100dvh when live toolbar resizing is intended and tested for jank.
• Use safe-area environment insets for edge-fixed controls on devices that expose them.

Test dialogs, drawers, onboarding panels, and input screens with browser chrome and the software keyboard visible.

Intrinsic CSS repairs

Before adding a breakpoint, check:

• grid tracks that need minmax(0, 1fr);
• flex or grid children that need min-width: 0;
• long strings that need overflow-wrap: anywhere or an appropriate code scroller;
• media missing max-width: 100% and intrinsic dimensions;
• fixed widths that should be capped with min(), max(), or clamp();
• absolute positioning that detached content from document flow;
• component containers that could use container queries instead of page-level device assumptions.

Responsive standards and evidence

Consult these sources before claiming accessibility or performance compliance. Re-check maintained sources when a release depends on the exact requirement.

Accessibility

• WCAG 2.2 — Reflow: Level AA expects content to work at a 320 CSS-pixel equivalent without two-dimensional scrolling, except content such as data tables, diagrams, maps, and interfaces whose meaning requires two dimensions. Contain exceptions so unrelated content still reflows.
• WCAG 2.2 — Target Size (Minimum): Level AA requires a 24×24 CSS-pixel target or a qualifying spacing/equivalent/inline/user-agent/essential exception.
• WCAG 2.2 — Target Size (Enhanced): Level AAA uses 44×44 CSS pixels with exceptions. A project may adopt 44×44 as an ergonomic target without mislabeling smaller qualifying controls as AA failures.
• WCAG 2.2 — Contrast: Level AA requires 4.5:1 for ordinary text and 3:1 for large-scale text, with defined exceptions.
• WCAG 2.2 — Focus Not Obscured: sticky and fixed UI must not entirely hide the keyboard-focused component.

Platform behavior

• MDN viewport units: svh, lvh, and dvh represent different viewport states. Select the unit from the interaction instead of replacing vh mechanically.
• MDN prefers-reduced-motion: respect the user's operating-system motion preference and preserve a complete static state.

Usability evidence

• Nielsen Norman Group iPad usability report: contained horizontal browsing can work when its affordance is clear. Treat this as historical usability evidence, not a mandate for carousels.
• GOV.UK design principles: start with user needs, design with data, understand context, and remain consistent without forcing uniformity.

Provenance

This package reconstructs Tushar Mehta's earlier mobile-first draft. It retains the useful “choose a mobile-appropriate primitive” thesis and measurement discipline while removing universal carousel, fixed-CTA, and page-height prescriptions and restoring the missing audit, patterns, and standards resources.