add skill

skills/web-design-excellence/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: web-design-excellence
+description: 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.