oborchers/craftsmanship-polish

Craftsmanship Is the Multiplier — A Simple Design Flawlessly Executed Beats a Brilliant Design Sloppily Built

Craftsmanship is the strongest single correlate with perceived visual quality in the VisAWI model (Moshagen & Thielsch, 2010). Users cannot articulate why a polished interface feels trustworthy, but they punish sloppiness instantly. Every blurry image, inconsistent radius, and missing hover state erodes credibility.

Pixel-Perfect Alignment

Enforce the >90% grid alignment rule from the layout-spatial-structure skill. Misalignment of even 1px between adjacent elements is visible at retina resolution.

Debug technique: Add outline: 1px solid rgba(255,0,0,0.3) to all elements temporarily. Misaligned edges become obvious.

Image Quality

| Rule | Requirement | |------|-------------| | Resolution | All images must be >=2x rendered resolution (e.g., 800px image for a 400px container) | | Format priority | AVIF > WebP > JPEG (use <picture> with fallbacks) | | Hero image budget | <=300KB after compression | | Lazy loading | All images below the fold use loading="lazy" | | Aspect ratio | Always specify width and height attributes to prevent CLS |

Shadow Elevation System

Use layered box-shadows for realistic depth. Single-layer shadows look flat and artificial. Define exactly 5 levels and use them consistently.

| Level | Name | Use Case | Box-Shadow | |-------|------|----------|-----------| | 0 | Flat | Inline elements, flush cards | none | | 1 | Card | Cards, tiles, raised surfaces | 0 1px 2px rgba(0,0,0,0.06), 0 1px 3px rgba(0,0,0,0.1) | | 2 | Dropdown | Dropdowns, popovers, tooltips | 0 4px 6px rgba(0,0,0,0.07), 0 2px 4px rgba(0,0,0,0.06) | | 3 | Modal | Modals, dialogs, drawers | 0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05) | | 4 | Popover | Floating toolbars, command palettes | 0 20px 25px rgba(0,0,0,0.1), 0 8px 10px rgba(0,0,0,0.04) |

Rule: Higher elevation = larger offset + larger blur + lower opacity. Never use a single heavy shadow.

Border-Radius System

Define 3-4 radius values. Use them everywhere. Never invent ad-hoc values.

| Token | Value | Use | |-------|-------|-----| | --radius-sm | 4px | Badges, tags, inline code | | --radius-md | 8px | Cards, inputs, buttons | | --radius-lg | 12px | Modals, large containers | | --radius-full | 9999px | Avatars, pills, toggles |

Nested radius rule: When an element with border-radius contains a child with border-radius, the inner radius = outer radius - padding. A card with border-radius: 12px and padding: 8px gives children border-radius: 4px.

Interactive States

Every interactive element must have visible hover, focus, and active states.

| State | Implementation | |-------|----------------| | Hover | Color shift, subtle scale, or shadow lift | | Focus | Visible focus ring (2px solid, offset 2px) — see accessibility-inclusive-design for full focus rules | | Active | Slight scale-down (transform: scale(0.98)) for tactile feedback |

For transition timing, easing, and prefers-reduced-motion rules, see the visual-interest-expression skill which owns motion design guidelines.

Icon Consistency

Use a single icon library per project. Mix outlined and filled icons deliberately: outlined for navigation, filled for active/selected states. Maintain consistent stroke weight (1.5px or 2px) and size (20px or 24px grid). Never mix icon sets from different libraries.

Loading, Empty, and Error States

Skeleton screens beat spinners for loads of 1.5-10 seconds. Match the skeleton to actual content shape. Use a left-to-right shimmer animation at a 1.5s cycle (Bill Chung research: perceived as faster than pulsing).

Empty states must include: illustration or icon + heading + description + primary CTA. Never show a blank page.

Error states must include: what went wrong + what the user can do + a retry action.

Cumulative Layout Shift (CLS)

Target CLS < 0.1 (Google Core Web Vitals "good" threshold).

| Cause | Fix | |-------|-----| | Images without dimensions | Always set width and height attributes | | Web fonts causing FOUT | Apply font-display strategy (see typography skill for web font loading rules) | | Dynamic content injected above fold | Reserve space with min-height or use content-visibility: auto | | Ads or embeds without reserved space | Set explicit container dimensions before content loads |

Anti-Patterns

| Anti-Pattern | Why It Fails | Fix | |-------------|-------------|-----| | Pixelated or blurry images | Signals amateur quality | Serve >=2x resolution in AVIF/WebP | | Single heavy box-shadow | Looks like a drop shadow from 2010 | Use layered shadows with multiple values | | Inconsistent border-radius (4px here, 6px there, 10px elsewhere) | Subtle discord that feels "off" | Define 3-4 tokens, use them everywhere | | No hover or focus states | Interactive elements feel dead | Add transition on every clickable element | | Flash of unstyled text (FOUT) | Layout jumps, text reflows | Apply web font loading rules (see typography skill) | | Spinners for everything | No spatial context during loading | Use skeleton screens matching content shape |

Cross-Media Notes

• Presentations: Use sharp, high-resolution images only. Maintain consistent shape treatments (all rounded or all square, never mixed). Align all elements to a slide grid.
• CVs/Resumes: Alignment precision matters more than decoration. Ensure consistent margins, bullet alignment, and font sizing. A well-aligned minimal CV beats a decorated misaligned one.
• Documents: Consistent formatting (heading sizes, paragraph spacing, list indentation) is the document equivalent of UI craftsmanship. Define styles once, apply everywhere.

Examples

Working implementations in examples/:

• examples/shadow-system-and-states.md — Complete elevation system with layered shadows, skeleton screen implementation, and empty state component in CSS/Tailwind/React

Review Checklist

When reviewing or building for craftsmanship:

• [ ] Grid alignment passes >90% rule (see layout-spatial-structure skill)
• [ ] All images are >=2x rendered resolution and served in AVIF/WebP with JPEG fallback
• [ ] Hero images are <=300KB after compression
• [ ] All images have explicit width and height attributes
• [ ] Shadow system uses exactly 5 levels with layered (multi-value) box-shadows
• [ ] Border-radius uses 3-4 defined tokens only — no ad-hoc values
• [ ] Nested border-radius follows the outer - padding rule
• [ ] All interactive elements have hover, focus, and active states
• [ ] Transition rules applied (see visual-interest-expression skill for timing and easing)
• [ ] Icons come from a single library with consistent stroke weight and size
• [ ] Loading states use skeleton screens matching content shape (not generic spinners)
• [ ] Empty states include illustration + heading + description + CTA
• [ ] CLS < 0.1: no images without dimensions, no dynamic injection above fold
• [ ] Web font loading follows typography skill rules (font-display, preloading)