Index of every page on this site: llms.txt
All skills
asyrafhussin avatar

/web-design-guidelines

@1aa0ff7
Run it yourself

UI/UX best practices and accessibility audit. Use when reviewing UI code, checking accessibility, running accessibility audits, auditing forms, or ensuring web interface best practices. Triggers on "audit accessibility", "check WCAG", "review UI", "check accessibility", "audit design", "review UX", or "check best practices".

Use this Skill: https://skilld.dev/gh/asyrafhussin/agent-skills/web-design-guidelines

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈87 tokens for metadata: the name and description. ≈1.8k when used: this file. ≈67k more on demand in 28 files.

Description uses 4.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈350 characters, or 4.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Web Design Guidelines

WCAG accessibility, semantic HTML, keyboard navigation, forms, and performance patterns for inclusive web interfaces. Contains 23 rules across 4 categories. Supports both coding reference and audit mode.

Metadata

  • Version: 2.1.0
  • Rule Count: 23 rules across 4 categories
  • License: MIT

How to Audit

When the user asks to "audit accessibility", "check WCAG compliance", or "review accessibility" — run the checklist below against their codebase.

Step 1: Determine Scope

  • If arguments provided ($ARGUMENTS): audit only those files or components
  • If no arguments: audit all UI components and pages in the codebase

Step 2: Detect Stack

Check the project for:

  • .tsx/.jsx files → React
  • .vue files → Vue
  • .blade.php files → Laravel Blade
  • .html files → Static HTML

Step 3: Run Accessibility Checklist

Work through every item below. For each, output:

  • PASS — brief confirmation of what was verified
  • FAIL — exact file:line, description of the issue, and fix recommendation
  • N/A — if the check does not apply to this project
Semantic HTML & Structure
  • Pages use semantic elements (<header>, <main>, <nav>, <footer>, <article>, <section>) — not <div> soup
  • Heading hierarchy is sequential (h1 → h2 → h3) — no skipped levels
  • One <h1> per page
  • Skip link exists to bypass navigation (<a href="#main-content">Skip to content</a>)
  • Landmark regions are labelled when duplicated (aria-label on multiple <nav> elements)
Keyboard Navigation
  • All interactive elements are reachable via Tab key
  • Focus order follows visual order (no positive tabindex values)
  • Focus indicator is visible on all focusable elements (not removed with outline: none without replacement)
  • Modal dialogs trap focus and return focus on close
  • Custom components (dropdowns, tabs, accordions) support expected keyboard patterns (Arrow keys, Escape, Enter)
Images & Media
  • All <img> elements have alt attributes — descriptive for content images, empty (alt="") for decorative
  • Complex images (charts, diagrams) have extended descriptions
  • Video content has captions or transcripts
Color & Contrast
  • Text meets WCAG AA contrast ratio (4.5:1 for normal text, 3:1 for large text)
  • Information is not conveyed by color alone (e.g., error states use icons + text, not just red)
  • UI components and focus indicators meet 3:1 contrast ratio against background
Forms
  • Every input has an associated <label> (not just placeholder text)
  • Required fields indicated with both visual cue and aria-required="true"
  • Error messages linked to inputs via aria-describedby
  • Error messages use role="alert" or aria-live="assertive" for screen reader announcement
  • Correct type attributes on inputs (email, tel, url, number)
  • autocomplete attributes present on common fields (name, email, address, credit card)
ARIA & Screen Readers
  • ARIA labels on icon-only buttons (aria-label="Close")
  • Dynamic content updates use aria-live regions
  • Loading states announced to screen readers (aria-busy="true", status messages)
  • Decorative elements hidden from screen readers (aria-hidden="true")
Motion & Animation
  • prefers-reduced-motion respected — animations disabled or reduced
  • No auto-playing video or audio without user control
  • No content that flashes more than 3 times per second

Step 4: Summary

End the audit with:

## Accessibility Audit Summary
- **PASS**: X checks
- **FAIL**: X checks
- **N/A**: X checks
- **WCAG Level**: AA / Partial AA / Below AA
- **Top Priority Fixes**: (list the 3 most impactful FAIL items)

When to Apply

Reference these guidelines when:

  • Running an accessibility audit on a codebase
  • Reviewing UI code for accessibility (WCAG compliance)
  • Implementing forms and interactions
  • Ensuring keyboard navigation works
  • Adding ARIA labels and live regions
  • Optimizing image loading and layout stability

Rule Categories by Priority

Priority Category Impact Prefix
1 Accessibility CRITICAL a11y-
2 Forms HIGH form-
3 Animation & Motion CRITICAL motion-
4 Performance & UX MEDIUM perf-

Quick Reference

1. Accessibility (CRITICAL)

  • a11y-semantic-html - Use semantic HTML elements
  • a11y-heading-hierarchy - Maintain proper heading hierarchy
  • a11y-screen-reader - Optimize for screen reader compatibility
  • a11y-skip-links - Provide skip links for navigation
  • a11y-keyboard-nav - Ensure full keyboard navigation
  • a11y-focus-management - Manage keyboard focus properly
  • a11y-aria-labels - Add ARIA labels to interactive elements
  • a11y-color-contrast - Ensure sufficient color contrast (WCAG AA)
  • a11y-alt-text - Provide meaningful alt text for images
  • a11y-error-messages - Make error messages accessible
  • a11y-form-labels - Associate labels with form inputs
  • a11y-live-regions - Announce dynamic content to screen readers

2. Forms (HIGH)

  • form-autocomplete - Use autocomplete attributes
  • form-input-types - Use correct input types
  • form-error-display - Display form errors clearly
  • form-validation-ux - Design user-friendly validation
  • form-inline-validation - Implement smart inline validation
  • form-multi-step - Design effective multi-step forms
  • form-placeholder-usage - Use placeholders appropriately
  • form-submit-feedback - Provide clear submission feedback

3. Animation & Motion (CRITICAL)

  • motion-reduced - Respect prefers-reduced-motion (WCAG AAA)

4. Performance & UX (MEDIUM)

  • perf-image-loading - Optimize image loading for UX
  • perf-layout-stability - Prevent cumulative layout shift

Essential Guidelines

Semantic HTML

// ❌ Div soup
<div className="header"><div className="nav"><div onClick={handleClick}>Home</div></div></div>

// ✅ Semantic HTML
<header><nav aria-label="Main"><a href="/">Home</a></nav></header>
<main><article><h1>Title</h1><p>Content</p></article></main>

Form Accessibility

<label htmlFor="email">Email <span aria-hidden="true">*</span></label>
<input id="email" type="email" required aria-required="true" aria-describedby="email-error" autoComplete="email" />
{error && <p id="email-error" role="alert">{error}</p>}

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

How to Use

Read individual rule files for detailed explanations:

rules/a11y-semantic-html.md
rules/form-autocomplete.md
rules/motion-reduced.md
rules/perf-image-loading.md

References

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    The skill provides comprehensive guidelines for accessibility and web design audits. It processes user-provided code files to generate compliance reports, which introduces a minor risk of indirect prompt injection if the audited files contain malicious instructions. No evidence of data exfiltration, obfuscation, or unauthorized command execution was found.

  • Socket2mo

    2 alerts: gptAnomaly

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer9mo

    26/27 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 1aa0ff7. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago
metadata
{
  "author": "agent-skills",
  "version": "2.1.0"
}

README badge

README badge for asyrafhussin/agent-skills/web-design-guidelines