Ecocee Skills Web Design Guidelines

Web Interface Guidelines Reviewer

A comprehensive UI code review skill that audits frontend files against established Web Interface Guidelines. Covers accessibility, performance, typography, animation, forms, theming, and interaction patterns.

Compatible with: Claude, Claude Code, VS Code agent extensions, Cursor, Windsurf, and any agent that supports the Agent Skills standard.

Behaviour

1. If the user provides a file path or glob pattern, begin the review immediately.
2. If no files are specified, ask: "Which files or patterns would you like me to review?"
3. Fetch the latest guidelines from the source URL before every review — never use a cached version.
4. Read and parse all matched files.
5. Check every file against all rule categories below.
6. Output findings in the file:line format defined in the Output Format section.
7. If a file passes all checks, output ✓ pass — never skip it silently.

Guidelines Source

Always fetch the authoritative, up-to-date rules before reviewing:

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

Use a WebFetch or equivalent tool to retrieve this file fresh on every invocation. The fetched content is the source of truth. Rules below are a local reference and may lag behind the canonical source.

Rule Categories (Local Reference)

Accessibility

• Icon-only buttons require aria-label
• Form controls require <label> or aria-label
• Interactive elements require keyboard handlers (onKeyDown / onKeyUp)
• Use <button> for actions, <a> / <Link> for navigation — not <div onClick>
• Images require alt; decorative images use alt=""
• Decorative icons require aria-hidden="true"
• Async updates (toasts, validation messages) require aria-live="polite"
• Prefer semantic HTML over ARIA where a native element exists
• Headings must be hierarchical <h1>–<h6>; include a skip link for main content
• Heading anchors need scroll-margin-top

Focus States

• All interactive elements need a visible focus indicator (focus-visible:ring-* or equivalent)
• Never use outline-none / outline: none without a replacement focus style
• Use :focus-visible over :focus to avoid showing ring on mouse click
• Use :focus-within for compound controls

Forms

• Inputs need autocomplete and a meaningful name attribute
• Use correct type (email, tel, url, number) and inputmode
• Never block paste (onPaste + preventDefault)
• Labels must be clickable via htmlFor or by wrapping the control
• Disable spellcheck on emails, codes, and usernames (spellCheck={false})
• Checkbox and radio label + control share a single hit target — no dead zones
• Submit button stays enabled until the request starts; show spinner during request
• Inline errors displayed next to the relevant field; focus first error on submit
• Placeholders end with … and show an example pattern
• Use autocomplete="off" on non-auth fields to avoid password manager conflicts
• Warn before navigation when unsaved changes exist (beforeunload or router guard)

Animation

• Respect prefers-reduced-motion — provide a reduced variant or disable animation entirely
• Only animate transform and opacity (compositor-friendly properties)
• Never use transition: all — list properties explicitly
• Set transform-origin correctly
• SVG: apply transforms on a <g> wrapper with transform-box: fill-box; transform-origin: center
• Animations must be interruptible — respond to user input mid-animation

Typography

• Use … (ellipsis character), not three periods ...
• Use curly quotes " ", not straight quotes "
• Non-breaking spaces for units and key combos: 10 MB, ⌘ K, brand names
• Loading states end with …: "Loading…", "Saving…"
• Apply font-variant-numeric: tabular-nums to number columns and comparisons
• Use text-wrap: balance or text-pretty on headings to prevent widows

Content Handling

• Text containers must handle long content: truncate, line-clamp-*, or break-words
• Flex children need min-w-0 to allow text truncation
• Handle empty states explicitly — never render broken UI for empty strings or arrays
• User-generated content: test with short, average, and very long inputs

Images

• <img> requires explicit width and height to prevent Cumulative Layout Shift (CLS)
• Below-fold images: loading="lazy"
• Above-fold critical images: priority or fetchpriority="high"

Performance

• Lists with more than 50 items must be virtualized (virtua, content-visibility: auto)
• No layout reads during render (getBoundingClientRect, offsetHeight, offsetWidth, scrollTop)
• Batch DOM reads and writes; never interleave them
• Prefer uncontrolled inputs; controlled inputs must execute cheaply per keystroke
• Add <link rel="preconnect"> for CDN and asset domains
• Critical fonts: <link rel="preload" as="font"> with font-display: swap

Navigation and State

• URL must reflect application state — filters, tabs, pagination, and expanded panels belong in query params
• Links must use <a> / <Link> to support Cmd/Ctrl+click and middle-click
• Deep-link all stateful UI — if a value uses useState, consider URL sync via nuqs or similar
• Destructive actions require a confirmation modal or undo window — never execute immediately

Touch and Interaction

• Set touch-action: manipulation to prevent double-tap zoom delay
• Set -webkit-tap-highlight-color intentionally
• Set overscroll-behavior: contain in modals, drawers, and sheets
• During drag: disable text selection; apply inert on dragged elements
• Use autoFocus sparingly — desktop only, single primary input; avoid on mobile

Safe Areas and Layout

• Full-bleed layouts need env(safe-area-inset-*) for notch/island handling
• Prevent unwanted scrollbars: overflow-x-hidden on containers; fix content overflow
• Use Flexbox or Grid for layout instead of JS measurement

Dark Mode and Theming

• Apply color-scheme: dark to <html> for dark themes (fixes scrollbars and native inputs)
• <meta name="theme-color"> must match the page background colour
• Native <select>: set explicit background-color and color (required for Windows dark mode)

Locale and i18n

• Dates and times: use Intl.DateTimeFormat — no hardcoded format strings
• Numbers and currency: use Intl.NumberFormat — no hardcoded format strings
• Detect language via Accept-Language / navigator.languages, not by IP address

Hydration Safety

• Controlled inputs with value require onChange (or use defaultValue for uncontrolled)
• Date and time rendering: guard against server/client hydration mismatch
• Use suppressHydrationWarning only where it is genuinely necessary and document why

Hover and Interactive States

• Buttons and links need a hover: state for visual feedback
• Hover, active, and focus states must be more visually prominent than the resting state

Content and Copy

• Use active voice: "Install the CLI" not "The CLI will be installed"
• Title Case for headings and button labels (Chicago Manual of Style)
• Use numerals for counts: "8 deployments" not "eight deployments"
• Button labels must be specific: "Save API Key" not "Continue"
• Error messages must include a fix or next step — not just the problem
• Use second person; avoid first person ("you" not "I" or "we")
• Use & over "and" where space is constrained

Anti-Patterns (Always Flag)

Output Format

Group findings by file. Use file:line format (clickable in VS Code and compatible editors). Be terse — state the issue and location. Skip explanation unless the fix is non-obvious. No preamble. No summary paragraph. Start directly with the first file heading.

## src/components/Button.tsx

src/components/Button.tsx:42  icon button missing aria-label
src/components/Button.tsx:18  input lacks label association
src/components/Button.tsx:55  animation missing prefers-reduced-motion guard
src/components/Button.tsx:67  transition: all → list properties explicitly

## src/components/Modal.tsx

src/components/Modal.tsx:12   missing overscroll-behavior: contain
src/components/Modal.tsx:34   "..." → "…" (ellipsis character)
src/components/Modal.tsx:89   <div onClick> → <button>

## src/components/Card.tsx

✓ pass

Examples

Example 1: Single file review

User: "Review src/components/LoginForm.tsx" Agent: Fetches guidelines, reads the file, outputs findings grouped under ## src/components/LoginForm.tsx.

Example 2: Glob pattern review

User: "Audit all components in src/components/" Agent: Fetches guidelines, reads all matched files, outputs findings grouped by file.

Example 3: Focused accessibility audit

User: "Check my UI for accessibility issues only" Agent: Asks for the file or pattern, fetches guidelines, then applies only the Accessibility and Focus States rule categories.

Example 4: No files provided

User: "Review my UI" Agent: Responds — "Which files or patterns would you like me to review? For example: src/components/*.tsx or src/app/page.tsx"

Notes

• This skill is agent-agnostic and works in Claude, Claude Code, VS Code, Cursor, Windsurf, Antigravity, and any environment supporting the Agent Skills standard.
• Always fetch the guidelines source URL before reviewing — never rely solely on the local reference above.
• If the fetch fails, inform the user and proceed using the local reference rules as a fallback, noting that the review may not reflect the latest guidelines.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.