AI Skill Report Card
Enforcing Pixel Perfect Spacing
Enforcing Pixel-Perfect Spacing
Quick Start14 / 15
Given a design spec and implementation, check these first:
1. Base unit: Is spacing on an 4px or 8px grid? (margin: 13px → flag, should be 12px or 16px)
2. Alignment: Do edges align to a shared baseline/column? (check left/top edges across siblings)
3. Optical vs mathematical centering: Icons/text in buttons often need +1-2px offset to *look* centered
4. Consistent scale: Are gaps using the same spacing token everywhere (e.g., 8/16/24/32), not ad-hoc values?
Report deviations as: Element: expected Xpx, found Ypx (off by Z)
Recommendation▾
Add an example showing a 'good outcome' (no deviations found) to contrast with the deviation-heavy examples
Workflow14 / 15
Progress:
- Step 1: Establish the base spacing unit (4px or 8px grid — infer from most common values)
- Step 2: Extract all spacing values from design (margins, padding, gaps) into a list
- Step 3: Map each value to nearest valid token on the scale
- Step 4: Check alignment — do elements share edges/baselines where visually implied?
- Step 5: Check optical corrections — centered icons, text baselines, asymmetric padding needs
- Step 6: Compare implementation values against spec values pixel-by-pixel
- Step 7: List all deviations with exact px differences and suggested token-aligned fix
- Step 8: Verify responsive/scaled states maintain the same token system
Step 1: Determine the base grid
- Look at smallest consistent gap in the design — usually 4px or 8px
- All spacing should be a multiple of this unit
- Standard scale:
4, 8, 12, 16, 24, 32, 48, 64, 96 - If values don't fit, the design itself may need normalizing — flag this before "fixing" code
Step 4: Alignment checks
- Left edges: text, icons, and containers in a vertical stack should share an x-coordinate unless intentionally indented
- Baseline alignment: mixed font sizes in a row (e.g., label + value) should align on text baseline, not container top/bottom
- Center alignment: use
(container - content) / 2; if result isn't a whole pixel, round consistently (prefer rounding down for top/left in web, since browsers round sub-pixel values inconsistently)
Step 5: Optical corrections (common cases)
| Element | Issue | Fix |
|---|---|---|
| Play/triangle icon in circle button | Looks left-shifted when mathematically centered | Shift +1-2px right |
| Text in pill/badge | Vertical centering looks low due to font metrics | Reduce bottom padding by 1-2px vs top |
| Icon + text label | Baseline mismatch | Align icon's visual center to text x-height midpoint, not full line-height |
| Close (X) button | Asymmetric glyph | Center on the visual weight not the bounding box |
Recommendation▾
Include a brief template for a final audit report summarizing all findings across a component/page
Examples16 / 20
Example 1:
Input: Button has padding: 10px 18px and other buttons in the system use 12px 16px / 12px 24px
Output:
Deviation: Button padding (10px 18px) doesn't match spacing scale (4px grid: 4,8,12,16,24).
Fix: padding: 12px 24px (nearest valid tokens, matches primary button pattern)
Example 2:
Input: Card title and card icon are both top: 16px but icon appears visually higher
Output:
Issue: Icon's bounding box includes transparent padding (common in SVG icons).
Check: Measure icon's actual visual bounds, not SVG viewbox.
Fix: Adjust icon top to 18-19px so visual tops align with title text, OR trim icon's internal padding.
Example 3: Input: Three cards in a row have gaps of 16px, 15px, 17px Output:
Deviation: Inconsistent gaps (16/15/17px), should be uniform.
Fix: Use flexbox/grid `gap: 16px` instead of manual margins to guarantee consistency.
Recommendation▾
Consider adding guidance for how to handle conflicting specs between design tool export values and dev-rendered pixels (e.g., retina/subpixel rounding)
Best Practices
- Always infer and name the base unit before judging individual values — "off by 1px" is meaningless without a system
- Prefer layout primitives (flex
gap, CSS grid) over manual margins — they eliminate half of all spacing bugs - Distinguish mathematical center from optical center — always trust the eye for icons/glyphs, trust math for layout containers
- When auditing, measure from rendered output (DevTools box model / design tool inspect), not from code assumptions
- Group fixes by root cause (e.g., "all icon buttons need +1px offset") rather than listing symptoms element-by-element
- Respect existing design tokens/scale — don't introduce new arbitrary values even if they'd be "more accurate" to a mockup; flag the mockup as inconsistent instead
Common Pitfalls
- Don't treat every sub-pixel difference as a bug — browsers/renderers round sub-pixel values; check if the token is right, not the rendered pixel
- Don't mathematically center everything blindly — optical centering is often more correct for icons, triangles, and asymmetric glyphs
- Don't fix spacing values one-by-one without checking for a systemic pattern (e.g., component uses hardcoded px instead of the spacing scale)
- Don't ignore line-height and font metrics when measuring "gaps" around text — the visible gap is usually smaller than the box model suggests
- Don't assume the design file is the source of truth — designers make mistakes too; flag inconsistencies in the spec itself when the scale breaks