cross-browser-typography-qa

Cross-Browser Typography QA

Purpose

Use this skill when web text looks clipped, flattened, wrapped incorrectly, misaligned, or materially different between Chromium and WebKit/Safari. Treat text rendering as both a geometry problem and a visual paint problem: passing DOM bounds does not prove that every glyph is intact.

Triggers

• Lowercase descenders such as g, j, p, q, or y appear cut off.
• Gradient or transparent text looks flattened at the baseline.
• A heading fits within its element but still looks clipped.
• Safari and Chromium disagree on line height, wrapping, button labels, or heavy font weights.
• A deployed fix appears absent despite a successful upload or publish message.

Workflow

1. Reproduce the exact defect

1. Record the browser family, viewport, font family, weight, size, and exact text.
2. Use a string containing ascenders, rounded forms, punctuation, and descenders.
3. Capture a focused screenshot at the reported viewport before changing CSS.
4. Inspect the actual glyphs, not only the element rectangle.

2. Inspect layout and paint

Read computed values for:

• font-family, font-size, font-weight, and line-height;
• display, overflow, padding, transforms, and fixed heights;
• background-clip, -webkit-background-clip, and -webkit-text-fill-color;
• loaded font status and fallback-font substitution;
• the stylesheet URL/cache marker actually active in the page.

Use Range.getClientRects() for rendered-line counts and getBoundingClientRect() for containment, but never treat either as proof that glyph paint is complete.

3. Repair the cause

Choose the smallest stable repair:

• Treat a user's “is it meant to be sized like that?” reaction as a real visual-acceptance signal, not merely a request to confirm CSS intent. First verify the actual browser window bounds and distinguish normal viewport rendering from browser zoom or an accidentally narrow layout. If the viewport is normal but the display type dominates the first screen, make a bounded desktop-only scale/spacing adjustment while preserving explicit mobile overrides.
• For a hero-scale correction, adjust the heading clamp() and hero padding-block together; shrinking only the type can leave the composition oddly empty. Add an exact contract assertion before the CSS change so the intended scale is durable, prove RED, then rerun five-width Chromium and native-Safari geometry plus visual inspection.
• When the user asks to make a small, even-numbered product set “even,” prefer an equal two-column grid over editorial 7/5 nth-child spans. Encode the parity in a RED contract, remove obsolete asymmetric and breakpoint-reset rules, retain the one-column mobile override, update the stylesheet cache marker, and visually inspect paired card alignment—not only grid geometry.
• Increase the line box on the text-bearing element when font paint exceeds a tight line box.
• Remove fixed heights or hidden overflow that cut off glyphs.
• Avoid synthetic or unsupported font weights when they distort metrics.
• Rework pathological wrapping with width, balance, or explicit block structure.
• When a semantic hyphenated term breaks awkwardly, protect only that token with an inline span using white-space: nowrap; do not force the entire heading onto one line. Keep the ordinary hyphen when exact-copy tests, translation keys, or search indexing depend on the literal string.
• For background-clip: text, prefer line-height correction over outside padding; outside padding can enlarge the box without enlarging the painted glyph mask.
• If a decorative gradient remains unstable, use a solid accessible text color rather than preserving a fragile effect.
• When prose interleaves raw text with an inline emphasis element inside display: flex, wrap the entire sentence in one inline-flow child (for example, <span>Press <strong>Start Session</strong> ...</span>). Otherwise the browser can promote text fragments and the emphasis element to separate anonymous flex items, making intended spaces appear missing or incorrectly distributed. Verify the actual rendered glyph spacing in the packaged app, not only the JSX or DOM text.