Pi/skills/web-design-excellence/SKILL.md

name, description

name	description
web-design-excellence	Create elegant, usable, world-class web interfaces; apply when designing or implementing UI/UX, layouts, landing pages, dashboards, forms, or components.

Web design excellence

When to use

This skill must be used whenever the coding agent is asked to perform web development tasks which include front-end creativity.

Rules

• Design for clarity first: the user must understand what the page is, what matters, and what to do next within 5 seconds.
• Start with content hierarchy: define the primary action, secondary actions, supporting content, and remove everything else.
• Use a strong visual hierarchy: size, weight, spacing, contrast, and position should make importance obvious.
• Prefer fewer elements, better arranged. Avoid visual noise, decorative clutter, and competing focal points.
• Use generous whitespace. Crowded interfaces feel cheap, confusing, and harder to trust.
• Align everything intentionally. Use a grid, consistent margins, and shared edges.
• Use consistent spacing based on a scale, e.g. 4/8/12/16/24/32/48/64.
• Limit typography: usually 1–2 typefaces, 3–5 sizes, and clear line-height.
• Body text must be readable: 16px minimum, comfortable line height, sensible measure, high contrast.
• Use color sparingly. Start in grayscale, then add one accent color for action or meaning.
• Never rely on color alone to communicate state; pair it with text, icons, shape, or motion.
• Make CTAs obvious: action-oriented labels, strong contrast, clear placement, no ambiguity.
• Every screen needs one dominant next step unless the product intentionally supports exploration.
• Use familiar patterns before inventing new ones: cards, tabs, breadcrumbs, modals, drawers, filters, steppers.
• Respect platform conventions. Do not surprise users with custom controls that behave differently.
• Forms should be forgiving: clear labels, helpful defaults, inline validation, visible errors, and sane input types.
• Labels belong outside fields unless space is extremely constrained. Placeholders are examples, not labels.
• Error messages must say what happened, why it matters, and how to fix it.
• Design empty, loading, error, success, and disabled states; they are part of the interface, not edge cases.
• Make navigation predictable: clear current location, obvious links, no hidden critical actions.
• Use progressive disclosure: show essential information first, reveal advanced details only when needed.
• Prefer direct manipulation and immediate feedback. Every interaction should visibly respond.
• Motion should clarify, not decorate. Keep animations fast, subtle, and purposeful.
• Images must support the message. Avoid generic stock visuals unless used as placeholders.
• Icons must be recognizable, consistently styled, and accompanied by text when meaning is not universal.
• Use real-looking content during design; lorem ipsum hides layout and hierarchy problems.
• Optimize for mobile first, then scale up. Touch targets should be at least 44px.
• Design responsive layouts deliberately; do not just let elements wrap accidentally.
• Accessibility is non-negotiable: semantic HTML, keyboard support, focus states, contrast, labels, alt text.
• Do not remove outlines unless replacing them with an equally visible focus indicator.
• Use semantic HTML before ARIA. ARIA fixes gaps; it does not replace correct markup.
• Performance affects design quality: minimize layout shift, heavy assets, blocking scripts, and unnecessary effects.
• Prefer CSS layout primitives: flex, grid, container queries, clamp, aspect-ratio.
• Use design tokens for color, spacing, typography, radius, shadows, and breakpoints.
• Shadows should be subtle and consistent; avoid muddy, excessive elevation.
• Border radius should be consistent. Do not mix many unrelated radii.
• Avoid common pitfalls: centered everything, weak contrast, tiny text, vague CTAs, inconsistent spacing, fake depth, over-animation.
• Avoid “dashboard soup”: group related data, highlight insights, and reduce chart junk.
• For landing pages: hero must state value clearly, prove credibility, show work, handle objections, and end with a CTA.
• For SaaS/product UI: prioritize task completion, clear status, recoverability, and fast scanning.
• For portfolios/agencies: let work breathe, use excellent typography, strong imagery, concise copy, and confident restraint.
• Before finalizing, audit: hierarchy, alignment, spacing, contrast, responsiveness, accessibility, states, copy, and performance.
• Golden rule: make it obvious, make it usable, make it beautiful only after those two are true.