diff options
| author | Arshita Jaryal <186042954+jaryalarshita@users.noreply.github.com> | 2026-10-29 17:18:30 +0530 |
|---|---|---|
| committer | Arshita Jaryal <186042954+jaryalarshita@users.noreply.github.com> | 2026-11-09 21:28:21 +0530 |
| commit | f766b64a952cd9bd5595c8d00f56cdb5c0b61ae2 (patch) | |
| tree | b5dc6bb40978c221bffa8cecdfc465587ddc2674 | |
| parent | 1a2c79d4e6c4a2283dc2c614b6538cbe1ed5ca62 (diff) | |
fix(web-design-guidelines): bundle pinned guidelines instead of fetching from main
| -rw-r--r-- | skills/web-design-guidelines/SKILL.md | 31 | ||||
| -rw-r--r-- | skills/web-design-guidelines/references/command.md | 191 |
2 files changed, 212 insertions, 10 deletions
diff --git a/skills/web-design-guidelines/SKILL.md b/skills/web-design-guidelines/SKILL.md index ceae92a..ee7db72 100644 --- a/skills/web-design-guidelines/SKILL.md +++ b/skills/web-design-guidelines/SKILL.md @@ -3,7 +3,7 @@ name: web-design-guidelines description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices". metadata: author: vercel - version: "1.0.0" + version: "1.1.0" argument-hint: <file-or-pattern> --- @@ -13,27 +13,38 @@ Review files for compliance with Web Interface Guidelines. ## How It Works -1. Fetch the latest guidelines from the source URL below +1. Read the bundled guidelines at [references/command.md](references/command.md) 2. Read the specified files (or prompt user for files/pattern) -3. Check against all rules in the fetched guidelines +3. Check against all rules in the guidelines 4. Output findings in the terse `file:line` format ## Guidelines Source -Fetch fresh guidelines before each review: +The rules are bundled with this skill in the [references/command.md](references/command.md) file. Read that file before each review. Do not fetch rules from the network. -``` -https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md -``` +The snapshot is pinned to a specific upstream commit: -Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions. +Source: https://github.com/vercel-labs/web-interface-guidelines/blob/434b7f91364665f2f733b310ec54809bf8f37937/command.md + +SHA-256: `d246b026f4f29b5823a9cc857f9edf3d2507002e055e32040cadeaf3b38e0234` + +The file contains all the rules and output format instructions. +Where it says `$ARGUMENTS`, use the files or pattern the user asked to review. + +## Updating the Guidelines + +To update the snapshot to a newer upstream version: + +1. Get the latest commit SHA: `gh api repos/vercel-labs/web-interface-guidelines/commits/main --jq .sha` +2. Download it: `curl -fsSL https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/<SHA>/command.md -o references/command.md` +3. Review the changes, then update the Source URL and SHA-256 above (`shasum -a 256 references/command.md`) ## Usage When a user provides a file or pattern argument: -1. Fetch guidelines from the source URL above +1. Read [references/command.md](references/command.md) 2. Read the specified files -3. Apply all rules from the fetched guidelines +3. Apply all rules from the guidelines 4. Output findings using the format specified in the guidelines If no files specified, ask the user which files to review. diff --git a/skills/web-design-guidelines/references/command.md b/skills/web-design-guidelines/references/command.md new file mode 100644 index 0000000..3eb3a21 --- /dev/null +++ b/skills/web-design-guidelines/references/command.md @@ -0,0 +1,191 @@ +--- +description: Review UI code for Vercel Web Interface Guidelines compliance +argument-hint: <file-or-pattern> +--- + +# Web Interface Guidelines + +Review these files for compliance: $ARGUMENTS + +Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise. + +## Rules + +### Accessibility + +- Icon-only buttons need `aria-label` +- Form controls need `<label>` or `aria-label` +- Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`) +- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`) +- Images need `alt` (or `alt=""` if decorative) +- Decorative icons need `aria-hidden="true"` +- Async updates (toasts, validation) need `aria-live="polite"` +- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA +- Headings hierarchical `<h1>`–`<h6>`; include skip link for main content +- `scroll-margin-top` on heading anchors +- Meaningful media needs captions, transcripts, or descriptions as applicable +- Media controls need keyboard support; decorative media needs assistive-tech hiding + +### Focus States + +- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent +- Never `outline-none` / `outline: none` without focus replacement +- Use `:focus-visible` over `:focus` (avoid focus ring on click) +- Group focus with `:focus-within` for compound controls +- Sticky headers/footers/overlays must not cover the focused element + +### Forms + +- Inputs need `autocomplete` and meaningful `name` +- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode` +- Never block paste (`onPaste` + `preventDefault`) +- Labels clickable (`htmlFor` or wrapping control) +- Disable spellcheck on emails, codes, usernames (`spellCheck={false}`) +- Checkboxes/radios: label + control share single hit target (no dead zones) +- Submit button stays enabled until request starts; spinner during request +- Errors inline next to fields; focus first error on submit +- Placeholders end with `…` and show example pattern +- `autocomplete="off"` on non-auth fields to avoid password manager triggers +- Warn before navigation with unsaved changes (`beforeunload` or router guard) + +### Animation + +- Honor `prefers-reduced-motion` (provide reduced variant or disable) +- Animate `transform`/`opacity` only (compositor-friendly) +- Never `transition: all`—list properties explicitly +- Set correct `transform-origin` +- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center` +- Animations interruptible—respond to user input mid-animation +- Autoplay motion >5 seconds alongside other content needs pause, stop, or hide controls +- Muted decorative loops must stop under `prefers-reduced-motion` + +### Typography + +- `…` not `...` +- Curly quotes `“` `”` not straight `"` +- Non-breaking spaces: `10 MB`, `⌘ K`, brand names +- Loading states end with `…`: `"Loading…"`, `"Saving…"` +- `font-variant-numeric: tabular-nums` for number columns/comparisons +- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows) + +### Content Handling + +- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words` +- Flex children need `min-w-0` to allow text truncation +- Handle empty states—don't render broken UI for empty strings/arrays +- User-generated content: anticipate short, average, and very long inputs + +### Images + +- `<img>` needs explicit `width` and `height` (prevents CLS) +- Below-fold images: `loading="lazy"` +- Above-fold critical images: `priority` or `fetchpriority="high"` + +### Performance + +- Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`) +- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`) +- Batch DOM reads/writes; avoid interleaving +- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke +- Add `<link rel="preconnect">` for CDN/asset domains +- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap` +- Prefer `<video autoplay muted loop playsinline>` over animated GIF; provide a still alternative +- Short non-essential loops: Safari H.264 MP4 `<picture>` source, `prefers-reduced-motion` media condition, and still fallback + +### Navigation & State + +- URL reflects state—filters, tabs, pagination, expanded panels in query params +- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support) +- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar) +- Destructive actions need confirmation modal or undo window—never immediate + +### Touch & Interaction + +- `touch-action: manipulation` (prevents double-tap zoom delay) +- `-webkit-tap-highlight-color` set intentionally +- `overscroll-behavior: contain` in modals/drawers/sheets +- Page rubber-band suppression: `overscroll-behavior: none` on `<html>` inside `@media (pointer: fine)`; keep coarse-pointer page defaults for pull-to-refresh. Test hybrid touch devices: `pointer` describes the primary input, and `none` also disables scroll chaining and native swipe navigation +- During drag: disable text selection, `inert` on dragged elements +- Drag/swipe/pinch/path gestures need tap/click and keyboard alternatives unless essential +- `autoFocus` sparingly—desktop only, single primary input; avoid on mobile + +### Safe Areas & Layout + +- Full-bleed layouts need `env(safe-area-inset-*)` for notches +- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow +- Flex/grid over JS measurement for layout + +### Dark Mode & Theming + +- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs) +- `<meta name="theme-color">` matches page background +- Native `<select>`: explicit `background-color` and `color` (Windows dark mode) + +### Locale & i18n + +- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats +- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats +- Detect language via `Accept-Language` / `navigator.languages`, not IP +- Brand names, code tokens, identifiers: wrap with `translate="no"` to prevent garbled auto-translation + +### Hydration Safety + +- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled) +- Date/time rendering: guard against hydration mismatch (server vs client) +- `suppressHydrationWarning` only where truly needed + +### Hover & Interactive States + +- Buttons/links need `hover:` state (visual feedback) +- Interactive states increase contrast: hover/active/focus more prominent than rest + +### Content & Copy + +- Active voice: "Install the CLI" not "The CLI will be installed" +- Title Case for headings/buttons (Chicago style) +- Numerals for counts: "8 deployments" not "eight" +- Specific button labels: "Save API Key" not "Continue" +- Error messages include fix/next step, not just problem +- Second person; avoid first person +- `&` over "and" where space-constrained + +### Anti-patterns (flag these) + +- `user-scalable=no` or `maximum-scale=1` disabling zoom +- `onPaste` with `preventDefault` +- `transition: all` +- `outline-none` without focus-visible replacement +- Inline `onClick` navigation without `<a>` +- `<div>` or `<span>` with click handlers (should be `<button>`) +- Images without dimensions +- Large arrays `.map()` without virtualization +- Form inputs without labels +- Icon buttons without `aria-label` +- Hardcoded date/number formats (use `Intl.*`) +- `autoFocus` without clear justification +- Animated GIF when compressed video is suitable +- Gesture-only action without tap/click and keyboard alternative + +## Output Format + +Group by file. Use `file:line` format (VS Code clickable). Terse findings. + +```text +## src/Button.tsx + +src/Button.tsx:42 - icon button missing aria-label +src/Button.tsx:18 - input lacks label +src/Button.tsx:55 - animation missing prefers-reduced-motion +src/Button.tsx:67 - transition: all → list properties + +## src/Modal.tsx + +src/Modal.tsx:12 - missing overscroll-behavior: contain +src/Modal.tsx:34 - "..." → "…" + +## src/Card.tsx + +✓ pass +``` + +State issue + location. Skip explanation unless fix non-obvious. No preamble. |
