diff --git a/.claude/skills/critique/scripts/detect-antipatterns-browser.js b/.claude/skills/critique/scripts/detect-antipatterns-browser.js
index c35dcff9d..662166638 100644
--- a/.claude/skills/critique/scripts/detect-antipatterns-browser.js
+++ b/.claude/skills/critique/scripts/detect-antipatterns-browser.js
@@ -151,6 +151,60 @@ const ANTIPATTERNS = [
description:
'Dark backgrounds with colored box-shadow glows are the default "cool" look of AI-generated UIs. Use subtle, purposeful lighting instead — or skip the dark theme entirely.',
},
+ {
+ id: 'line-length',
+ name: 'Line length too long',
+ description:
+ 'Text lines wider than ~80 characters are hard to read. The eye loses its place tracking back to the start of the next line. Add a max-width (65ch to 75ch) to text containers.',
+ },
+ {
+ id: 'cramped-padding',
+ name: 'Cramped padding',
+ description:
+ 'Text is too close to the edge of its container. Add at least 8px (ideally 12-16px) of padding inside bordered or colored containers.',
+ },
+ {
+ id: 'tight-leading',
+ name: 'Tight line height',
+ description:
+ 'Line height below 1.3x the font size makes multi-line text hard to read. Use 1.5 to 1.7 for body text so lines have room to breathe.',
+ },
+ {
+ id: 'small-target',
+ name: 'Small touch target',
+ description:
+ 'Interactive elements should be at least 44x44px to be comfortably tappable. Small targets cause misclicks and frustrate users, especially on touch devices.',
+ },
+ {
+ id: 'skipped-heading',
+ name: 'Skipped heading level',
+ description:
+ 'Heading levels should not skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation. Skipping levels breaks the document outline.',
+ },
+ {
+ id: 'justified-text',
+ name: 'Justified text',
+ description:
+ 'Justified text without hyphenation creates uneven word spacing ("rivers of white"). Use text-align: left for body text, or enable hyphens: auto if you must justify.',
+ },
+ {
+ id: 'tiny-text',
+ name: 'Tiny body text',
+ description:
+ 'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
+ },
+ {
+ id: 'all-caps-body',
+ name: 'All-caps body text',
+ description:
+ 'Long passages in uppercase are hard to read. We recognize words by shape (ascenders and descenders), which all-caps removes. Reserve uppercase for short labels and headings.',
+ },
+ {
+ id: 'wide-tracking',
+ name: 'Wide letter spacing on body text',
+ description:
+ 'Letter spacing above 0.05em on body text disrupts natural character groupings and slows reading. Reserve wide tracking for short uppercase labels only.',
+ },
];
// ─── Section 2: Color Utilities ─────────────────────────────────────────────
@@ -711,6 +765,128 @@ function checkElementAIPaletteDOM(el) {
return findings;
}
+const QUALITY_TEXT_TAGS = new Set(['p', 'li', 'td', 'th', 'dd', 'blockquote', 'figcaption']);
+const QUALITY_INTERACTIVE_TAGS = new Set(['button', 'a', 'input', 'select', 'textarea']);
+
+function checkElementQualityDOM(el) {
+ const tag = el.tagName.toLowerCase();
+ const style = getComputedStyle(el);
+ const findings = [];
+
+ const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 10);
+ const textLen = el.textContent?.trim().length || 0;
+ const fontSize = parseFloat(style.fontSize) || 16;
+ const rect = el.getBoundingClientRect();
+
+ // --- Line length too long ---
+ // Only flag if text is long enough to actually fill the line (>80 chars)
+ if (hasDirectText && QUALITY_TEXT_TAGS.has(tag) && rect.width > 0 && textLen > 80) {
+ const charsPerLine = rect.width / (fontSize * 0.5);
+ if (charsPerLine > 85) {
+ findings.push({ id: 'line-length', snippet: `~${Math.round(charsPerLine)} chars/line (aim for <80)` });
+ }
+ }
+
+ // --- Cramped padding ---
+ if (hasDirectText && textLen > 10) {
+ const borders = {
+ top: parseFloat(style.borderTopWidth) || 0,
+ right: parseFloat(style.borderRightWidth) || 0,
+ bottom: parseFloat(style.borderBottomWidth) || 0,
+ left: parseFloat(style.borderLeftWidth) || 0,
+ };
+ // Need at least 2 borders (a container), or a non-transparent background
+ const borderCount = Object.values(borders).filter(w => w > 0).length;
+ const hasBg = style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)';
+ if (borderCount >= 2 || hasBg) {
+ // Only check padding on sides that have borders or where bg creates containment
+ const paddings = [];
+ if (hasBg || borders.top > 0) paddings.push(parseFloat(style.paddingTop) || 0);
+ if (hasBg || borders.right > 0) paddings.push(parseFloat(style.paddingRight) || 0);
+ if (hasBg || borders.bottom > 0) paddings.push(parseFloat(style.paddingBottom) || 0);
+ if (hasBg || borders.left > 0) paddings.push(parseFloat(style.paddingLeft) || 0);
+ if (paddings.length > 0) {
+ const minPad = Math.min(...paddings);
+ if (minPad < 8) {
+ findings.push({ id: 'cramped-padding', snippet: `${minPad}px padding (need >=8px)` });
+ }
+ }
+ }
+ }
+
+ // --- Tight line height ---
+ if (hasDirectText && textLen > 50 && !['h1','h2','h3','h4','h5','h6'].includes(tag)) {
+ const lineHeight = parseFloat(style.lineHeight);
+ if (lineHeight && lineHeight !== NaN) {
+ const ratio = lineHeight / fontSize;
+ if (ratio < 1.3 && ratio > 0) {
+ findings.push({ id: 'tight-leading', snippet: `line-height ${ratio.toFixed(2)}x (need >=1.3)` });
+ }
+ }
+ }
+
+ // --- Small touch targets ---
+ if (QUALITY_INTERACTIVE_TAGS.has(tag) || el.hasAttribute('tabindex') || el.getAttribute('role') === 'button') {
+ if (rect.width > 0 && rect.height > 0 && (rect.width < 44 || rect.height < 44)) {
+ if (style.display !== 'none' && style.visibility !== 'hidden') {
+ findings.push({ id: 'small-target', snippet: `${Math.round(rect.width)}x${Math.round(rect.height)}px (need 44x44)` });
+ }
+ }
+ }
+
+ // --- Justified text (without hyphens) ---
+ if (hasDirectText && style.textAlign === 'justify') {
+ const hyphens = style.hyphens || style.webkitHyphens || '';
+ if (hyphens !== 'auto') {
+ findings.push({ id: 'justified-text', snippet: 'text-align: justify without hyphens: auto' });
+ }
+ }
+
+ // --- Tiny body text ---
+ if (hasDirectText && textLen > 20 && fontSize < 12) {
+ if (!['sub', 'sup', 'code', 'kbd', 'samp', 'var'].includes(tag)) {
+ findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
+ }
+ }
+
+ // --- All-caps body text ---
+ if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
+ if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
+ findings.push({ id: 'all-caps-body', snippet: `text-transform: uppercase on ${textLen} chars of body text` });
+ }
+ }
+
+ // --- Wide letter spacing on body text ---
+ if (hasDirectText && textLen > 20) {
+ const tracking = parseFloat(style.letterSpacing);
+ if (tracking > 0 && style.textTransform !== 'uppercase') {
+ const trackingEm = tracking / fontSize;
+ if (trackingEm > 0.05) {
+ findings.push({ id: 'wide-tracking', snippet: `letter-spacing: ${trackingEm.toFixed(2)}em on body text` });
+ }
+ }
+ }
+
+ return findings;
+}
+
+function checkPageQualityDOM() {
+ const findings = [];
+
+ // --- Skipped heading levels ---
+ const headings = document.querySelectorAll('h1, h2, h3, h4, h5, h6');
+ let prevLevel = 0;
+ for (const h of headings) {
+ const level = parseInt(h.tagName[1]);
+ if (prevLevel > 0 && level > prevLevel + 1) {
+ findings.push({ type: 'skipped-heading', detail: `h${prevLevel} followed by h${level} (missing h${prevLevel + 1})` });
+ }
+ prevLevel = level;
+ }
+
+ return findings;
+}
+
// Node adapters — take pre-extracted jsdom computed style
function checkElementBorders(tag, style) {
@@ -1042,6 +1218,18 @@ if (IS_BROWSER) {
const LABEL_BG = 'oklch(55% 0.25 350)';
const OUTLINE_COLOR = 'oklch(60% 0.25 350)';
+ // Inject hover styles via CSS (more reliable than JS event listeners)
+ const styleEl = document.createElement('style');
+ styleEl.textContent = `
+ .impeccable-overlay { pointer-events: auto; }
+ .impeccable-overlay .impeccable-tooltip { display: none; }
+ .impeccable-overlay .impeccable-label { display: block; }
+ .impeccable-overlay:hover { border-color: transparent !important; }
+ .impeccable-overlay:hover .impeccable-tooltip { display: block; }
+ .impeccable-overlay:hover .impeccable-label { display: none; }
+ `;
+ (document.head || document.documentElement).appendChild(styleEl);
+
const overlays = [];
const TYPE_LABELS = {};
for (const ap of ANTIPATTERNS) {
@@ -1057,14 +1245,14 @@ if (IS_BROWSER) {
top: `${rect.top + scrollY - 2}px`, left: `${rect.left + scrollX - 2}px`,
width: `${rect.width + 4}px`, height: `${rect.height + 4}px`,
border: `2px solid ${OUTLINE_COLOR}`, borderRadius: '4px',
- pointerEvents: 'none', zIndex: '99999', boxSizing: 'border-box',
+ zIndex: '99999', boxSizing: 'border-box',
});
const label = document.createElement('div');
label.className = 'impeccable-label';
label.textContent = findings.map(f => TYPE_LABELS[f.type || f.id] || f.type || f.id).join(', ');
Object.assign(label.style, {
- position: 'absolute', top: '-20px', left: '0',
+ position: 'absolute', top: '-22px', left: '0',
background: LABEL_BG, color: 'white',
fontSize: '11px', fontFamily: 'system-ui, sans-serif', fontWeight: '600',
padding: '2px 8px', borderRadius: '3px', whiteSpace: 'nowrap',
@@ -1076,25 +1264,14 @@ if (IS_BROWSER) {
tooltip.className = 'impeccable-tooltip';
tooltip.innerHTML = findings.map(f => f.detail || f.snippet).join('General Design Quality Issues That Should Be Flagged
+
+
+
+ Design Quality Issues: Should Flag
+ Every example on this page has a common design quality problem.
+
+
+ 1. Line Length Too Long
+
+
This paragraph has no max-width constraint at all, which means on a wide monitor or ultrawide display, each line of text can stretch to 150 or even 200 characters wide. Research consistently shows that line lengths beyond 75 characters significantly reduce reading speed and comprehension. The eye has to travel too far to find the beginning of the next line, causing readers to lose their place. This is one of the most common and easily fixable typographic issues on the web, yet it persists because developers test on narrow browser windows and never see the problem. A simple max-width of 65ch to 75ch on the paragraph or its container would fix this entirely. But without that constraint, this text will just keep going and going across the full width of whatever viewport or container it finds itself in, making it genuinely unpleasant to read.
+
2. Cramped Padding
+
+
This text is crammed against the border with only 4px padding. It feels claustrophobic and hard to read.
+
+
Cramped background padding
+
+
Zero padding on a bordered element. The text is literally touching the border.
+
3. Tiny Body Text
+
+
This body text is only 10px. While this might be fine for a disclaimer or legal footnote, it's too small for primary content that users need to actually read. Accessibility guidelines generally recommend a minimum of 16px for body text, with 12px as an absolute floor.
+
+
This is 11px body text. Still too small for comfortable reading, especially on high-DPI screens where the physical size is even smaller than the pixel count suggests.
+
4. Tight Line Height
+
+
This paragraph has a line-height of 1.0, which means the lines are touching. Multi-line body text needs breathing room between lines for readability. A line-height of 1.5 to 1.7 is generally recommended for body text.
+
+
This paragraph uses line-height: 16px with font-size: 16px, giving an effective ratio of 1.0. Same problem expressed differently.
+
5. Justified Text
+
+
This paragraph uses text-align: justify, which forces each line to stretch to fill the full width. Without hyphenation support, this creates uneven gaps between words known as "rivers of white space" that flow vertically through the text. These rivers make the text harder to read because the inconsistent spacing disrupts the reading rhythm. Left-aligned text with a ragged right edge is almost always more readable on the web.
+
6. Missing Focus Styles
+
+ outline: none (try tabbing)
+ outline: 0 (try tabbing)
+
+
+
+ 7. Small Touch Targets
+
+
+
+ 8. Skipped Heading Levels
+
+
This H3 follows the H2 above (OK)
+
But this H5 skips H4 entirely (bad for accessibility and document structure)
+
Screen readers use heading levels to build a document outline. Skipping levels breaks that navigation.
+
9. Z-Index Abuse
+
+
z-index: 99999 (why?)
+
z-index: 2147483647 (the maximum 32-bit integer)
+
10. Fixed Pixel Widths
+
+
This element has width: 800px. On any screen narrower than 800px, it will overflow and cause horizontal scrolling.
+
11. All-Caps Body Text
+
+
This entire paragraph is in uppercase via text-transform. While all-caps works for short labels, headings, or navigation items, longer body text in uppercase is significantly harder to read because we lose the word shape cues that come from ascenders and descenders in mixed-case text.
+
12. !important Overuse
+
+
This element has 5 !important declarations. It's a sign of specificity wars and unmaintainable CSS.
+
13. Inconsistent Border Radius
+
+
+
2px radius
+
8px radius
+
16px radius
+
pill
+
+
14. Wide Letter Spacing
+
+
This body text has letter-spacing: 0.15em applied to it. While subtle tracking adjustments can improve readability for headings or all-caps text, adding significant letter spacing to body text actually makes it harder to read by disrupting natural character groupings.
+
Good Design Quality Patterns That Should Pass
+
+
+
+ Design Quality: Should Pass
+ None of these should trigger quality warnings.
+
+ Good Line Length
+
+
This paragraph has a max-width of 65ch, keeping the line length comfortable for reading. The eye can easily track from the end of one line to the beginning of the next.
+
Good Padding
+
+
This container has 16px padding, giving the text room to breathe within its border.
+
Good Text Sizes
+
+
This is 16px body text with 1.6 line-height. Comfortable to read.
+
This is a 12px caption. Small but appropriate for its purpose.
+
Good Touch Targets
+
+ Properly Sized Button
+
+
+ Proper Heading Hierarchy
+
+
This H3 follows H2 correctly
+
No skipped levels.
+
Short Labels in Caps (OK)
+
+ Category Label
+
+
+ Custom Focus Style
+
+ Custom focus ring
+
+
+ Consistent Border Radius
+
+
+
Card A
+
Card B
+
Card C
+
+
Reasonable Z-Index
+
+
+ Responsive Width
+
+
max-width: 800px, width: 100%. Adapts to any screen.
+