Zero-tolerance alignment verification protocol. Alignment is binary - elements are either in line or they're not. Report exact measurements, no tolerances, no "close enough."
apm install @majiayu000/alignment-verification
[](https://apm-p1ls2dz87-atlamors-projects.vercel.app/packages/@majiayu000/alignment-verification)---
name: alignment-verification
description: >
Zero-tolerance alignment verification protocol. Alignment is binary -
elements are either in line or they're not. Report exact measurements,
no tolerances, no "close enough."
---
# Alignment Verification Skill
RULE: Alignment is BINARY. In line or not. Zero tolerances.
## Core Principle
Alignment verification has exactly two outcomes:
- **Delta = 0px** --> ALIGNED: YES
- **Delta > 0px** --> ALIGNED: NO (report exact deviation)
There are NO tolerances. A 2px deviation in a row of chips is visible. A 1px misalignment between form labels is noticeable. "Close enough" does not exist.
When you claim something is aligned, you MUST prove it with pixel measurements.
## Mental Model
Alignment is a RELATIONSHIP between elements, not a property of a single element.
Every alignment check requires:
1. **Target Element(s)** - What you are checking
2. **Reference Element** - What you are aligning TO (parent, sibling, baseline)
3. **Alignment Type** - How they should relate (center, edge, spacing)
4. **Container Space** - For alignment to work, there must be space to align within
Example mental model:
```
"Button should be horizontally centered in its parent"
- Target: the button
- Reference: the parent container
- Type: horizontal center
- Container: parent must be wider than button for centering to be meaningful
```
## Verification Protocol
### Step 1: Identify What Should Align
Before measuring, explicitly state:
- Which elements are being checked
- What type of alignment is expected
- What the reference point is
### Step 2: Extract Exact Pixel Values
Use Puppeteer's evaluate to get precise measurements:
```javascript
// Get element bounding box via puppeteer_evaluate
puppeteer_evaluate({
script: `
const el = document.querySelector('[selector]');
const box = el.getBoundingClientRect();
JSON.stringify({ x: box.x, y: box.y, width: box.width, height: box.height });
`
})
// Returns: { x, y, width, height }
```
Extract ALL values needed for your alignment type.
### Step 3: Calculate Exact Deviations
Calculate with full precision. DO NOT round. DO NOT apply tolerances.
```javascript
// For horizontal centering in parent
const parentBox = await page.locator('[parent]').boundingBox();
const childBox = await page.locator('[child]').boundingBox();
const parentCenter = parentBox.x + (parentBox.width / 2);
const childCenter = childBox.x + (childBox.width / 2);
const deviation = Math.abs(parentCenter - childCenter);
// Report: deviation === 0 ? "ALIGNED: YES" : `ALIGNED: NO (${deviation}px off)`
```
### Step 4: Output ALIGNMENT_CHECK Block
Every alignment verification MUST produce this output:
```
ALIGNMENT_CHECK:
- Task: [alignment goal in plain language]
- Type: [horizontal_center|vertical_center|left_edge|right_edge|top_edge|bottom_edge|spacing]
- Elements measured:
- [selector]: [value]px
- [selector]: [value]px
- ALIGNED: YES/NO
- Max deviation: Xpx
- Deviations: [list if multiple elements]
```
## Alignment Types with Code
### Center Horizontally in Parent
```javascript
// Measure
const parent = await page.locator('.parent').boundingBox();
const child = await page.locator('.child').boundingBox();
// Calculate
const parentCenterX = parent.x + (parent.width / 2);
const childCenterX = child.x + (child.width / 2);
const deviation = Math.abs(parentCenterX - childCenterX);
// Report
console.log(`Parent center: ${parentCenterX}px`);
console.log(`Child center: ${childCenterX}px`);
console.log(`Deviation: ${deviation}px`);
console.log(`ALIGNED: ${deviation === 0 ? 'YES' : 'NO'}`);
```
### Center Vertically in Parent
```javascript
// Measure
const parent = await page.locator('.parent').boundingBox();
const child = await page.locator('.child').boundingBox();
// Calculate
const parentCenterY = parent.y + (parent.height / 2);
const childCenterY = child.y + (child.height / 2);
const deviation = Math.abs(parentCenterY - childCenterY);
// Report
console.log(`Parent center Y: ${parentCenterY}px`);
console.log(`Child center Y: ${childCenterY}px`);
console.log(`Deviation: ${deviation}px`);
console.log(`ALIGNED: ${deviation === 0 ? 'YES' : 'NO'}`);
```
### Left Edge Alignment (Multiple Elements)
```javascript
// Measure all elements
const elements = await page.locator('.item').all();
const leftEdges = [];
for (const el of elements) {
const box = await el.boundingBox();
leftEdges.push(box.x);
}
// Calculate deviations from first element
const reference = leftEdges[0];
const deviations = leftEdges.map((x, i) => ({
index: i,
value: x,
deviation: Math.abs(x - reference)
}));
// Report
const maxDeviation = Math.max(...deviations.map(d => d.deviation));
console.log(`Reference left edge: ${reference}px`);
deviations.forEach(d => {
console.log(`Element ${d.index}: ${d.value}px (deviation: ${d.deviation}px)`);
});
console.log(`Max deviation: ${maxDeviation}px`);
console.log(`ALIGNED: ${maxDeviation === 0 ? 'YES' : 'NO'}`);
```
### Right Edge Alignment
```javascript
// Measure
const elements = await page.locator('.item').all();
const rightEdges = [];
for (const el of elements) {
const box = await el.boundingBox();
rightEdges.push(box.x + box.width);
}
// Calculate deviations from first element
const reference = rightEdges[0];
const deviations = rightEdges.map((r, i) => ({
index: i,
value: r,
deviation: Math.abs(r - reference)
}));
// Report
const maxDeviation = Math.max(...deviations.map(d => d.deviation));
console.log(`ALIGNED: ${maxDeviation === 0 ? 'YES' : 'NO'}`);
```
### Top Edge Alignment
```javascript
// Measure
const elements = await page.locator('.item').all();
const topEdges = [];
for (const el of elements) {
const box = await el.boundingBox();
topEdges.push(box.y);
}
// Calculate deviations from first element
const reference = topEdges[0];
const maxDeviation = Math.max(...topEdges.map(y => Math.abs(y - reference)));
// Report
console.log(`ALIGNED: ${maxDeviation === 0 ? 'YES' : 'NO'}`);
console.log(`Max deviation: ${maxDeviation}px`);
```
### Equal Spacing Between Elements
```javascript
// Measure
const elements = await page.locator('.item').all();
const boxes = [];
for (const el of elements) {
boxes.push(await el.boundingBox());
}
// Calculate gaps between consecutive elements
const gaps = [];
for (let i = 1; i < boxes.length; i++) {
const gap = boxes[i].x - (boxes[i-1].x + boxes[i-1].width);
gaps.push(gap);
}
// Calculate deviations from first gap
const referenceGap = gaps[0];
const deviations = gaps.map((g, i) => ({
index: i,
value: g,
deviation: Math.abs(g - referenceGap)
}));
// Report
const maxDeviation = Math.max(...deviations.map(d => d.deviation));
console.log(`Reference gap: ${referenceGap}px`);
deviations.forEach(d => {
console.log(`Gap ${d.index}: ${d.value}px (deviation: ${d.deviation}px)`);
});
console.log(`ALIGNED: ${maxDeviation === 0 ? 'YES' : 'NO'}`);
```
## Common Pitfalls
### CSS: margin: auto needs flex/grid parent
```css
/* WRONG - margin auto alone does nothing in block layout */
.child {
margin: 0 auto;
}
/* RIGHT - parent must be flex or block with defined width */
.parent {
display: flex;
justify-content: center;
}
/* OR */
.child {
width: 200px; /* must have explicit width */
margin: 0 auto;
}
```
### SwiftUI: .center needs frame larger than content
```swift
// WRONG - no frame means content hugs, nothing to center within
Text("Hello")
.frame(alignment: .center)
// RIGHT - explicit frame provides space to center within
Text("Hello")
.frame(maxWidth: .infinity, alignment: .center)
```
### Transforms affect visual but not bounding box
getBoundingClientRect() returns the ORIGINAL position before CSS transforms. If you use `transform: translateX()` or similar, the visual position differs from the measured position.
```javascript
// Element visually at 100px but boundingBox shows 0px due to transform
// Solution: account for transforms or use offsetLeft/getBoundingClientRect
```
### Asymmetric content (icon in button)
A button with an icon on one side may APPEAR off-center even when the button IS centered, because the visual weight is asymmetric.
```
[ Icon Text ] <-- Button is centered but looks left-heavy
Solution: Either accept true center or adjust with padding to achieve
optical center (but document this explicitly).
```
## Anti-Patterns (FORBIDDEN Language)
The following phrases are REJECTED in alignment verification:
| Phrase | Why Rejected |
|--------|--------------|
| "within tolerance" | There is no tolerance. 0px or report deviation. |
| "close enough" | Not a measurement. What is the actual deviation? |
| "approximately aligned" | Approximate is not aligned. Give the number. |
| "looks aligned" | Visual assertion without ALIGNMENT_CHECK block. |
| "alignment seems fine" | "Seems" is not measurement. Prove it. |
| "roughly centered" | "Roughly" is not a pixel value. |
### How to Fix
WRONG:
```
"The chips look aligned to me."
```
RIGHT:
```
ALIGNMENT_CHECK:
- Task: Verify horizontal alignment of chip row
- Type: top_edge
- Elements measured:
- chip[0]: y=142px
- chip[1]: y=142px
- chip[2]: y=142px
- chip[3]: y=144px
- ALIGNED: NO
- Max deviation: 2px
- Deviations: chip[3] is 2px below reference
```
## Complete Verification Example
Task: "Center the modal horizontally in the viewport"
```javascript
// Step 1: Identify
// - Target: .modal
// - Reference: viewport
// - Type: horizontal_center
// Step 2: Measure
const viewport = await page.viewportSize();
const modal = await page.locator('.modal').boundingBox();
// Step 3: Calculate
const viewportCenterX = viewport.width / 2;
const modalCenterX = modal.x + (modal.width / 2);
const deviation = Math.abs(viewportCenterX - modalCenterX);
// Step 4: Output
console.log(`
ALIGNMENT_CHECK:
- Task: Center modal horizontally in viewport
- Type: horizontal_center
- Elements measured:
- viewport center: ${viewportCenterX}px
- modal center: ${modalCenterX}px
- ALIGNED: ${deviation === 0 ? 'YES' : 'NO'}
- Max deviation: ${deviation}px
`);
```
## Integration with Other Skills
- **debugging-first**: Use alignment verification AFTER confirming elements render
- **design-qa-skill**: Alignment checks are one component of full design QA
- **lovable-pitfalls**: Avoid premature "looks good" claims by measuring
## When to Apply This Skill
ALWAYS apply when:
- User says "center this"
- User says "align these"
- User says "make them line up"
- Reviewing spacing consistency
- Verifying layout implementation
SKIP when:
- No alignment requirements mentioned
- Working on non-visual code (APIs, logic)
- User explicitly says "don't worry about exact alignment"