Web Design Guidelines

Web Interface Guidelines

When to Load

• Trigger: UI audit, accessibility checks, responsive design review, UX best practices evaluation
• Skip: Backend-only work with no UI components

Self-contained guidelines for reviewing web interfaces. Apply these rules when auditing UI code.

Output Format

Report findings as: file:line — [RULE_ID] description

Example: src/Button.tsx:12 — [A11Y-01] Missing aria-label on icon button

1. Accessibility (A11Y)

A11Y-01: Semantic HTML

• Use ` for actions, for navigation, ` for data entry
• Never use ` or ` for interactive elements
• Use `, , , , ` for landmarks

A11Y-02: ARIA Labels

• All interactive elements need accessible names
• Icon-only buttons MUST have aria-label
• Form inputs MUST have associated ` or aria-label`
• Images need alt text (decorative images: alt="")

A11Y-03: Keyboard Navigation

• All interactive elements must be reachable via Tab
• Custom components need proper role, tabIndex, and key handlers
• Focus must be visible (never outline: none without replacement)
• Modal/dialog must trap focus and return focus on close

A11Y-04: Color & Contrast

• Text contrast ratio: 4.5:1 minimum (3:1 for large text)
• Never use color alone to convey meaning (add icons, text, patterns)
• Ensure UI is usable at 200% zoom

A11Y-05: Screen Readers

• Dynamic content changes need aria-live regions
• Loading states need aria-busy="true"
• Error messages linked to inputs via aria-describedby

2. Performance (PERF)

PERF-01: Image Optimization

• Use next/image or responsive images with srcset
• Specify width and height to prevent layout shift
• Lazy load below-fold images: loading="lazy"
• Use WebP/AVIF with fallback

PERF-02: Bundle Size

• No full library imports: import { Button } from 'lib' not import lib
• Tree-shake CSS: use CSS modules or Tailwind purge
• Lazy load routes and heavy components: React.lazy() or dynamic imports

PERF-03: Rendering

• Avoid layout thrashing: don't read then write DOM in loops
• Use will-change sparingly (only for known animations)
• Prefer CSS animations over JS animations
• Use transform and opacity for 60fps animations (compositor-only)

PERF-04: Core Web Vitals

• LCP spinner)
• Disable interactive elements during loading
• Set aria-busy="true" on loading containers

CP-03: Error States

• Always show actionable error messages ("Try again" button, not just "Error")
• Don't show technical errors to users (log internally, show friendly message)
• Error boundaries for React component trees
• Retry logic for network failures

CP-04: Empty States

• Never show blank pages — provide helpful empty states
• Include call-to-action: "No items yet. Create your first item."
• Use illustrations sparingly (they add bundle weight)

CP-05: Modals & Dialogs

• Use ` element or proper role="dialog"`
• Trap focus within modal
• Close on Escape key and backdrop click
• Return focus to trigger element on close
• Prevent body scroll while open

5. CSS Practices (CSS)

CSS-01: Specificity

• Prefer class selectors over ID or element selectors
• Avoid !important (use specificity or cascade layers)
• Use CSS custom properties for theming
• One direction for spacing: prefer margin-bottom over margin-top

CSS-02: Layout

• Use Flexbox for 1D layout, Grid for 2D layout
• Avoid position: absolute for layout (use for overlays only)
• Use gap over margins between flex/grid children
• Use min-height: 100dvh (not 100vh) for full-height layouts

CSS-03: Dark Mode

• Use prefers-color-scheme media query
• Define all colors as CSS custom properties
• Test both modes — check contrast in both
• Don't just invert colors — design intentionally for dark mode

6. Security (SEC)

SEC-01: Content Security

• Never use dangerouslySetInnerHTML without sanitization
• Sanitize user-generated content before rendering
• Use rel="noopener noreferrer" on external links with target="_blank"

SEC-02: Forms & Input

• CSRF protection on all forms
• Rate limit form submissions
• Validate on both client AND server

7. Internationalization (I18N)

I18N-01: Text

• Don't hardcode strings — use i18n library or constants
• Support RTL layouts: use logical properties (margin-inline-start over margin-left)
• Don't truncate text — designs must accommodate 40% text expansion
• Use lang attribute on `` tag

Review Checklist

When auditing a file, check in this order (CRITICAL first):

1. CRITICAL: A11Y-01, A11Y-02, SEC-01 — Semantic HTML, ARIA, XSS prevention
2. HIGH: PERF-04, A11Y-03, CP-01 — Core Web Vitals, keyboard, forms
3. MEDIUM: RD-01, CSS-02, CP-02, CP-03 — Responsive, layout, loading/errors
4. LOW: CSS-03, I18N-01, CP-04 — Dark mode, i18n, empty states

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CloudAI-X
• Source: CloudAI-X/claude-workflow-v2
• License: MIT

Install and usage instructions live in the source repository linked above.