frontend-errors-units-rendering-viewport

name	frontend-errors-units-rendering-viewport
description	Use when a mobile hero section overflows because of `100vh`, deciding between the small (`svh`), large (`lvh`), and dynamic (`dvh`) viewport-unit families, picking between `em` and `rem` for font-size or component spacing, reasoning about CSS px versus device px on a HiDPI / Retina display, sizing a `<canvas>` backing store to match `devicePixelRatio`, handling iPhone notch / Dynamic Island safe areas with `env(safe-area-inset-*)`, configuring the `<meta name="viewport">` tag with `viewport-fit=cover`, debugging unexpected font-size compounding three levels deep, or migrating off the legacy `--vh` JavaScript workaround for the mobile-chrome viewport bug. Prevents the most common 2026 unit and viewport regressions : a `100vh` hero that gets covered by the mobile browser chrome on first load and shows empty whitespace once the chrome retracts, nested `1.5em` font-size declarations that compound to 3 375x at three levels deep, `100vw` that includes the desktop scrollbar gutter and overflows the body, `env(safe-area-inset-*)` that silently returns 0 because `viewport-fit=cover` was never added to the viewport meta, hardcoded `font-size: 14px` that blocks the user's browser zoom and font-size preference, `0.5px` hairline borders that render as 0 on DPR 1 displays and full pixel on DPR 2 displays, blurry `<canvas>` output because the backing store was sized in CSS pixels instead of device pixels, and the assumption that `1in = 96px` is a physical inch on screens. Covers absolute units (`px`, `pt`, `pc`, `in`, `cm`, `mm`, `Q` and the reference-pixel anchor `1px = 1in / 96`), the font-relative family (`em`, `rem`, `ex`, `cap`, `ch`, `ic`, `lh`, `rlh` plus the root-relative `rcap`, `rch`, `rex`, `ric`, `rlh`), the viewport-percentage families (default `v*`, small `sv*`, large `lv*`, dynamic `dv*`) across all six axes (`w`, `h`, `min`, `max`, `i` inline, `b` block), the rule that default `vh` currently resolves to `lvh` per MDN, the dvh-update-throttling rule (UA may step instead of animating during chrome transitions), the `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">` baseline, the four `env(safe-area-inset-*)` variables plus `safe-area-max-inset-*` and `keyboard-inset-*`, the foldable-device `env(viewport-segment-*)` family, `devicePixelRatio` and the canvas backing-store pattern, and the rule that 100vw does not include scrollbar width on classic-scrollbar systems. Keywords: px, em, rem, vw, vh, dvh, svh, lvh, dvw, svw, lvw, dvmin, dvmax, dvi, dvb, lvi, lvb, svi, svb, vi, vb, vmin, vmax, ch, ex, cap, ic, lh, rlh, rcap, rch, rex, ric, in, cm, mm, pt, pc, Q, devicePixelRatio, DPR, Retina, HiDPI, env, safe-area-inset, safe-area-inset-top, safe-area-inset-bottom, viewport-fit, cover, meta viewport, keyboard-inset, viewport-segment, scrollbar-gutter, 100vh wrong on mobile, em compound, font too big nested, hero cut off mobile, browser chrome covers content, retina image blurry, viewport jumps when URL bar appears, notch overlapping content, font-size keeps growing, layout broken in iOS PWA, hairline border not visible, why is 100vh wrong, what is dvh, what is svh, what is lvh, em vs rem, fix 100vh mobile, safe area iPhone notch, retina images, how to handle notch, what viewport units to use mobile, why does my font keep growing
license	MIT
compatibility	Designed for Claude Code. Requires Frontend Design evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Frontend Errors : Units, Rendering, Viewport

This skill is the operational reference for CSS length units, viewport-percentage units, font-relative units, the CSS pixel versus device pixel distinction, and the env(safe-area-inset-*) + viewport-fit=cover pairing for notch and Dynamic Island handling. It is an errors-class skill : every section is anchored to a real-world failure mode, with the spec citation that explains it. The skill does NOT cover container-query units (cqw, cqh, cqi, cqb, cqmin, cqmax ; see [[frontend-syntax-css-container-queries]]), clamp() typography (see [[frontend-impl-typography-system]]), or animation jank (see [[frontend-errors-animation-jank]]).

Quick Reference

Floor rules

• ALWAYS use 100dvh (or 100svh for guaranteed-fit) for full-height mobile heroes. NEVER use 100vh ; per MDN it currently resolves to 100lvh, so the hero overflows when mobile chrome is visible.
• ALWAYS use rem (or %) for font-size. NEVER use em for font-size in nested contexts ; it compounds (1 5 × 1 5 × 1 5 = 3 375 at three levels deep).
• ALWAYS use em for properties that should scale WITH the local font-size : button padding, line-height multipliers, icon sizing inside a text element. NEVER use rem for those ; the relationship to the local text breaks.
• ALWAYS include viewport-fit=cover in <meta name="viewport"> AND pair every edge-touching surface with env(safe-area-inset-*). NEVER use env(safe-area-inset-*) alone ; without viewport-fit=cover the values are 0 on iOS.
• ALWAYS multiply <canvas> backing-store width and height by devicePixelRatio and call ctx.scale(dpr, dpr). NEVER set canvas.width = canvas.style.width ; the result is blurry on Retina.
• ALWAYS prefer 100% over 100vw for full-bleed sections that are children of <body>. NEVER use 100vw without considering classic-scrollbar systems where overflows by the scrollbar width.