How to document responsive website layouts with screenshots at tablet widths
Capture tablet-width layouts reproducibly by recording CSS-pixel viewports, targeting real breakpoints, and annotating each screenshot with the state it shows.
To document a responsive layout at tablet widths, capture the page at explicitly recorded CSS-pixel viewport dimensions, choose widths around the page’s actual layout transitions, and annotate each image with the visible behavior. “Tablet” does not identify one universal viewport size. A physical screen’s resolution, browser viewport, and device pixel ratio are different values, so record the viewport width and height in CSS pixels and DPR separately when it matters.
This workflow creates screenshots teammates can reproduce and compare. It documents visual states; it does not by itself establish accessibility conformance.
1. Choose the states worth documenting
Start with the responsive rules and components that matter to the page: navigation, sidebars, grids, card counts, sticky controls, forms, and content order. Find the CSS media queries or resize the page while watching for changes. Media queries can depend on viewport dimensions and other environment features, so there is no single breakpoint that all tablets share. MDN’s media query guide explains how conditions select styles.
For each meaningful transition at width B, capture just below, at, and just above it when the distinction is useful—for example, B - 1, B, and B + 1 CSS pixels. If the behavior changes over a range or depends on height or orientation, add only the additional viewports needed to show that behavior. Do not label arbitrary preset dimensions as “tablet” proof.
| What to show | Useful capture |
|---|---|
| Breakpoint behavior | Widths immediately on either side of the transition, plus the exact boundary if its inclusive behavior matters |
| Typical tablet composition | A representative portrait and/or landscape viewport selected for the page and team’s use case |
| One interaction or above-the-fold state | Viewport screenshot at the relevant scroll position, with the interaction state noted |
| Whole-page flow | Full-page screenshot, while noting that stitched full-page capture may not preserve sticky or interactive behavior exactly as seen while scrolling |
Record width and height, orientation where relevant, and DPR if it affects the asset or comparison. DPR changes how many image pixels represent a CSS-pixel viewport; it does not replace the viewport dimensions. Safari’s Responsive Design Mode is one documented way to preview viewport dimensions and pixel-ratio differences while using Web Inspector.
2. Capture repeatable screenshots in browser tools
- Open the exact route in the browser and set a consistent browser zoom, normally 100% for a layout comparison.
- Open the browser’s responsive design or device emulation mode. Enter the target width and height in CSS pixels; select or note DPR if your tool exposes it.
- Set orientation, scroll position, and relevant page state. Wait for the content being documented to finish loading.
- Inspect the layout at each chosen width. Record whether navigation collapses, columns stack, a sidebar moves, cards change count, or a control is hidden or replaced. Describe only what is visible and confirmed.
- Save the screenshot with a project convention that makes viewport units clear. For example:
product-detail-820x1180-portrait.png, where the numbers mean CSS pixels. - Repeat with the same route, browser/tool, zoom, dimensions, and state when making comparisons. Keep those variables constant unless one of them is what the comparison is testing.
For responsive behavior based on height, orientation, hover capability, or other media features, record those conditions too. Browser emulation is useful for repeatable viewport states. Check a physical tablet as an optional corroboration when a hardware or browser-specific issue matters; it is not required for ordinary layout documentation.
3. Annotate each image so another developer can reproduce it
Use a concise caption alongside the image. This template covers the details that typically matter:
Page/route — viewport W × H CSS px — orientation — DPR if relevant — browser/tool — state shown — observationExample: /products/widget — 820 × 1180 CSS px — portrait — DPR 2 — Safari Responsive Design Mode — initial page state — primary navigation collapses and product details move below the image. Include an observation only when the screenshot supports it. If the image is a viewport capture, say where the page was scrolled; if it is full-page, say so.
For a transition, pair screenshots and identify the observed boundary: “At 821 CSS px the sidebar is beside the content; at 820 CSS px it moves below.” This is a report of the example page’s behavior, not a universal tablet breakpoint. Keep screenshot naming and caption units consistent: image-file pixel dimensions are not necessarily CSS viewport dimensions.
4. Separate layout evidence from accessibility evidence
A tablet screenshot can show a responsive visual state, but it cannot alone demonstrate that the page meets WCAG reflow requirements. WCAG 2.1 Success Criterion 1.4.10 describes vertically scrolling content at a width equivalent to 320 CSS pixels and horizontally scrolling content at a height equivalent to 256 CSS pixels, subject to exceptions for content whose use or meaning requires two-dimensional layout. WAI explains that 320 CSS pixels corresponds to a 1280 CSS-pixel starting viewport at 400% zoom, while emphasizing viewport equivalence rather than physical screen resolution. See the WAI explanation of Reflow.
If the goal includes accessibility review, plan and report that evaluation separately. A set of tablet-width screenshots is useful design evidence, but it does not substitute for checking the applicable criteria, functionality, and exceptions.
5. Automate consistent captures with ScreenshotNeo
If these captures need to be regenerated for many routes or shared as a repeatable artifact, ScreenshotNeo can return a screenshot from one API request. Supply the viewport dimensions in CSS pixels; adapt the target URL and dimensions to your chosen responsive state. The ScreenshotNeo API documentation describes its request options.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://example.com/products/widget \
-d width=820 \
-d height=1180 \
-o product-detail-820x1180-portrait.webpPython:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={
"access_key": "YOUR_API_KEY",
"url": "https://example.com/products/widget",
"width": 820,
"height": 1180,
"format": "webp",
},
timeout=90,
)
r.raise_for_status()
with open("product-detail-820x1180-portrait.webp", "wb") as image:
image.write(r.content)Node.js (modern Node with built-in fetch):
const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://example.com/products/widget',
width: '820',
height: '1180',
format: 'webp',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs =>
fs.writeFile('product-detail-820x1180-portrait.webp', image)
);Or skip the browser setup
Use this one-call example and change the URL and viewport parameters to the state you need. See the API docs for option names and configuration.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -d width=820 -d height=1180 -o shot.webp- Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
- Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses identify the page verdict and billing status in headers.
- An MCP server lets AI agents such as Claude, Cursor, and other MCP clients take screenshots, get page information, and capture PDFs.
- 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Every feature is on every plan.
Create a free ScreenshotNeo account to get 1,000 screenshots per month with no card.
6. Troubleshooting and quality checks
| Symptom | Likely cause | Fix |
|---|---|---|
| The screenshot does not match the tablet someone described | “Tablet” was used as a device label without recording the CSS viewport | Record exact viewport width and height in CSS pixels; capture the target state again. |
| Two screenshots differ even though the width appears the same | Different height, zoom, DPR, browser/tool, route state, scroll position, or dynamic content | Hold those inputs constant; record any variable that cannot be fixed. |
| A screenshot misses a transition | Only one width was captured, or the selected widths were far from the actual media-query boundary | Inspect the responsive rules or resize around the observed change, then capture on both sides. |
| The image dimensions seem larger than the recorded viewport | DPR or full-page capture changes image-pixel dimensions | Distinguish CSS-pixel viewport dimensions from output image pixels; note DPR and capture mode. |
| A sticky bar or interaction looks unlike the live page | Full-page stitching, scroll position, or missing interaction state changed what was rendered | Use a viewport capture at the relevant scroll position and document the state. Compare full-page output only for whole-page flow. |
| A cloud capture shows a challenge, blank output, or an incomplete page | The destination may have served a bot check, content had not loaded, or the page failed | Inspect the returned verdict/billing headers, retry after resolving access or load conditions, and avoid treating a failed capture as layout evidence. |
| Screenshot API responds with an error | Invalid or missing credentials, malformed URL/parameters, unreachable page, or request timeout | Check the API key, URL encoding, documented parameter names, and destination availability; increase the client timeout when appropriate and handle non-success responses. |
7. Performance, reliability, and cost
Capture only the states that answer a review question. Breakpoint-adjacent screenshots usually carry more diagnostic value than many arbitrary widths. A viewport image is smaller and focused; full-page images cover more content but can be larger and may be less representative of sticky or scroll-triggered states. Keep route and page state stable so differences reflect viewport behavior rather than changing content.
For repeatable reviews, store the viewport metadata with the image or in a nearby report, use deterministic filenames, and regenerate the same cases after layout changes. Dynamic ads, personalized content, animations, and asynchronous loading can make visual comparisons noisy; note these variables and use a consistent wait/state strategy. With ScreenshotNeo, cache settings and TTL are configurable, and bulk capture supports up to 100 URLs per call. Only clean shots are billed; failed loads and cache hits are not billed. Current pricing is Free: 1,000 shots/month; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; Business: $249 for 1,000,000. Yearly billing gives two months free. All features are available on every plan.
FAQ
Is there one standard tablet screenshot width?
No. Use widths that expose your page’s actual behavior and record the CSS-pixel dimensions.
Should I capture portrait and landscape?
Capture both when orientation changes the layout or when both states matter to the report. Otherwise, document the relevant orientation and why it was selected.
Do screenshots prove the page is responsive?
They document rendered states. To explain behavior, include captures on both sides of a meaningful transition and a caption describing the change.
Do tablet captures prove WCAG reflow conformance?
No. Reflow has separate viewport-equivalent conditions, including 320 CSS pixels for vertically scrolling content and 256 CSS pixels in height for horizontally scrolling content, with defined exceptions.
