ehmo/platform-design-skills/web

Name: web
Author: ehmo

Claude Code and agent skill by ehmo/platform-design-skills

Trust tier 2

community

Source check pending

Checking that the SKILL.md file is still in the repository.

Web platform design and accessibility guidelines. Use when building web interfaces, auditing accessibility, implementing responsive layouts, or reviewing web UI code. Triggers on tasks involving HTML, CSS, web components, WCAG compliance, responsive design, or web performance.

Install

npx vskill@latest install ehmo/platform-design-skills/web

SKILL.md

Web Platform Design Guidelines

Framework-agnostic rules for accessible, performant, responsive web interfaces. Based on WCAG 2.2, MDN Web Docs, and modern web platform APIs.

1. Accessibility / WCAG [CRITICAL]

Accessibility is not optional. Most rules in this section map to WCAG 2.2 success criteria at Level A or AA. A small number of best-practice rules (noted inline) target Level AAA or go beyond WCAG.

1.1 Use Semantic HTML Elements

Use elements for their intended purpose. Semantic structure provides free accessibility, SEO, and reader-mode support.

Element	Purpose
`<main>`	Primary page content (one per page)
`<nav>`	Navigation blocks
`<header>`	Introductory content or navigational aids
`<footer>`	Footer for nearest sectioning content
`<article>`	Self-contained, independently distributable content
`<section>`	Thematic grouping with a heading
`<aside>`	Tangentially related content (sidebars, callouts)
`<figure>` / `<figcaption>`	Illustrations, diagrams, code listings
`<details>` / `<summary>`	Expandable/collapsible disclosure widget
`<dialog>`	Modal or non-modal dialog boxes
`<time>`	Machine-readable dates/times
`<mark>`	Highlighted/referenced text
`<address>`	Contact information for nearest article/body

html

<!-- Good -->
<main>
  <article>
    <h1>Article Title</h1>
    <p>Content...</p>
  </article>
  <aside>Related links</aside>
</main>
 
<!-- Bad: div soup -->
<div class="main">
  <div class="article">
    <div class="title">Article Title</div>
    <div class="content">Content...</div>
  </div>
</div>

Anti-pattern: Using <div> or <span> for interactive elements. Never write <div onclick> when <button> exists.

1.2 ARIA Labels on Interactive Elements

Every interactive element must have an accessible name. Prefer visible text; use aria-label or aria-labelledby only when visible text is insufficient (SC 4.1.2).

html

<!-- Icon-only button: needs aria-label -->
<button aria-label="Close dialog">
  <svg aria-hidden="true">...</svg>
</button>
 
<!-- Linked by labelledby -->
<h2 id="section-title">Notifications</h2>
<ul aria-labelledby="section-title">...</ul>
 
<!-- Redundant: visible text is enough -->
<button>Save Changes</button> <!-- No aria-label needed -->

1.3 Keyboard Navigation

All interactive elements must be reachable and operable via keyboard (SC 2.1.1).

Use native interactive elements (<button>, <a href>, <input>, <select>) which are keyboard-accessible by default.
Custom widgets need tabindex="0" to enter tab order and keydown handlers for activation.
Never use tabindex values greater than 0.
Trap focus inside modals; return focus on close.

// Focus trap for modal
dialog.addEventListener('keydown', (e) => {
  if (e.key === 'Tab') {
    const focusable = dialog.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    const first = focusable[0];
    const last = focusable[focusable.length - 1];
    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault();
      last.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault();
      first.focus();
    }
  }
});

1.4 Visible Focus Indicators

Never remove focus outlines without providing a visible replacement (SC 2.4.7, enhanced SC 2.4.11 (AA) and SC 2.4.12 (AAA) in WCAG 2.2).

css

/* Good: custom focus indicator */
:focus-visible {
  outline: 3px solid var(--focus-color, #4A90D9);
  outline-offset: 2px;
}
 
/* Remove default only when :focus-visible is supported */
:focus:not(:focus-visible) {
  outline: none;
}
 
/* Bad: removing all focus styles */
/* *:focus { outline: none; } */

WCAG 2.2 requires focus indicators to have a minimum area of the perimeter of the component times 2px, with 3:1 contrast against adjacent colors.

1.5 Skip Navigation Links

Provide a mechanism to skip repeated blocks of content (SC 2.4.1).

html

<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>
  <nav>...</nav>
  <main id="main-content">...</main>
</body>

css

.skip-link {
  position: absolute;
  top: -100%;
  left: 0;
  z-index: 1000;
  padding: 0.75rem 1.5rem;
  background: var(--color-primary);
  color: var(--color-on-primary);
}
.skip-link:focus {
  top: 0;
}

1.6 Alt Text for Images

Every <img> must have an alt attribute (SC 1.1.1).

Informative images: describe the content and function. alt="Bar chart showing sales doubled in Q4".
Decorative images: use alt="" (empty string) so screen readers skip them.
Functional images (inside links/buttons): describe the action. alt="Search".
Complex images: use alt for short description, link to long description or use <figcaption>.

html

<img src="chart.png" alt="Revenue chart: Q1 $2M, Q2 $2.4M, Q3 $3.1M, Q4 $4.5M">
<img src="decorative-wave.svg" alt="">

1.7 Color Contrast

Maintain minimum contrast ratios (SC 1.4.3, 1.4.6, 1.4.11).

Content	Minimum Ratio
Normal text (<24px / <18.66px bold)	4.5:1
Large text (>=24px / >=18.66px bold)	3:1
UI components and graphical objects	3:1

Do not rely on color alone to convey information (SC 1.4.1). Pair color with icons, text, or patterns.

css

/* Check contrast of these tokens */
:root {
  --text-primary: #1a1a2e;    /* on white: ~16:1 */
  --text-secondary: #555770;  /* on white: ~6.5:1 */
  --text-disabled: #767693;   /* on white: ~4.5:1, borderline */
}

1.8 Form Labels

Every form input must have a programmatically associated label (SC 1.3.1, 3.3.2).

html

<!-- Explicit label (preferred) -->
<label for="email">Email address</label>
<input id="email" type="email" autocomplete="email">
 
<!-- Implicit label (acceptable) -->
<label>
  Email address
  <input type="email" autocomplete="email">
</label>
 
<!-- Never: placeholder as sole label -->
<!-- <input placeholder="Email"> -->

1.9 Error Identification

Identify and describe errors in text (SC 3.3.1). Link error messages to inputs with aria-describedby or aria-errormessage.

html

<label for="email">Email</label>
<input id="email" type="email" aria-describedby="email-error" aria-invalid="true">
<p id="email-error" role="alert">Enter a valid email address, e.g. name@example.com</p>

1.10 ARIA Live Regions

Announce dynamic content changes to screen readers (SC 4.1.3).

html

<!-- Polite: announced when user is idle -->
<div aria-live="polite" aria-atomic="true">
  3 results found
</div>
 
<!-- Assertive: interrupts current speech -->
<div role="alert">
  Your session will expire in 2 minutes.
</div>
 
<!-- Status messages -->
<div role="status">
  File uploaded successfully.
</div>

Use aria-live="polite" by default. Reserve role="alert" / aria-live="assertive" for time-sensitive warnings.

1.11 ARIA Role Quick Reference

Role	Purpose	Native Equivalent
`button`	Clickable action	`<button>`
`link`	Navigation	`<a href>`
`tab` / `tablist` / `tabpanel`	Tab interface	None
`dialog`	Modal	`<dialog>`
`alert`	Assertive live region	None
`status`	Polite live region	`<output>`
`navigation`	Nav landmark	`<nav>`
`main`	Main landmark	`<main>`
`complementary`	Aside landmark	`<aside>`
`search`	Search landmark	`<search>` (HTML5)
`img`	Image	`<img>`
`list` / `listitem`	List	`<ul>/<li>`
`heading`	Heading (with `aria-level`)	`<h1>`-`<h6>`
`menu` / `menuitem`	Menu widget	None
`tree` / `treeitem`	Tree view	None
`grid` / `row` / `gridcell`	Data grid	`<table>`
`progressbar`	Progress	`<progress>`
`slider`	Range input	`<input type="range">`
`switch`	Toggle	`<input type="checkbox">`

Rule: Prefer native HTML over ARIA. Use ARIA only when no native element exists for the pattern.

1.12 Label in Name (WCAG 2.5.3 Level A)

When an interactive element has visible text, its accessible name must contain that visible text as a substring (SC 2.5.3). Voice control users (Dragon NaturallySpeaking, macOS Voice Control) speak the visible label to activate controls. If aria-label replaces or contradicts the visible text, voice commands fail.

html

<!-- Correct: aria-label contains visible text as substring -->
<button aria-label="Delete item from cart">Delete</button>
 
<!-- Correct: no aria-label needed — visible text is the accessible name -->
<button>Save Changes</button>
 
<!-- Correct: icon button — no visible text, aria-label is fine -->
<button aria-label="Close dialog">
  <svg aria-hidden="true">...</svg>
</button>

html

<!-- Incorrect: aria-label overrides visible text with different text -->
<button aria-label="Remove">Delete</button>
 
<!-- Incorrect: aria-label does not contain visible "Submit" -->
<button aria-label="Proceed to next step">Submit</button>

Rule: When visible text is present, aria-label must include that visible text (verbatim, case-insensitively). Prefer no aria-label at all when visible text is sufficient.

2. Responsive Design [CRITICAL]

2.1 Mobile-First Approach

Write base styles for the smallest viewport. Layer complexity with min-width media queries.

css

/* Base: mobile */
.grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: 1rem;
}
 
/* Tablet */
@media (min-width: 48rem) {
  .grid {
    grid-template-columns: repeat(2, 1fr);
  }
}
 
/* Desktop */
@media (min-width: 64rem) {
  .grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

2.2 Fluid Layouts with Modern CSS Functions

Use clamp(), min(), and max() for fluid sizing without breakpoints.

css

/* Fluid typography */
h1 {
  font-size: clamp(1.75rem, 1.2rem + 2vw, 3rem);
}
 
/* Fluid spacing */
.section {
  padding: clamp(1.5rem, 4vw, 4rem);
}
 
/* Fluid container */
.container {
  width: min(90%, 72rem);
  margin-inline: auto;
}

2.3 Container Queries

Size components based on their container, not the viewport.

css

.card-container {
  container-type: inline-size;
  container-name: card;
}
 
@container card (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 200px 1fr;
  }
}
 
@container card (min-width: 700px) {
  .card {
    grid-template-columns: 300px 1fr;
    gap: 2rem;
  }
}

2.4 Content-Based Breakpoints

Set breakpoints where your content breaks, not at device widths. Common starting points:

css

/* Content-based, not "iPhone" or "iPad" */
@media (min-width: 30rem)  { /* ~480px: single column gets cramped */ }
@media (min-width: 48rem)  { /* ~768px: room for 2 columns */ }
@media (min-width: 64rem)  { /* ~1024px: room for sidebar + content */ }
@media (min-width: 80rem)  { /* ~1280px: wide multi-column */ }

2.5 Touch Targets

Minimum 44x44 CSS pixels for touch targets (WCAG SC 2.5.5 AAA; SC 2.5.8 requires only 24x24px at AA). Provide at least 24px spacing between adjacent targets.

css

button, a, input, select, textarea {
  min-height: 44px;
  min-width: 44px;
}
 
/* Enlarge tap area without changing visual size */
.icon-button {
  position: relative;
  width: 24px;
  height: 24px;
}
.icon-button::after {
  content: "";
  position: absolute;
  inset: -10px; /* expands clickable area */
}

2.6 Viewport Meta Tag

Always include in the document <head>:

html

<meta name="viewport" content="width=device-width, initial-scale=1">

Never use maximum-scale=1 or user-scalable=no -- these break pinch-to-zoom accessibility (SC 1.4.4).

2.7 No Horizontal Scrolling

Content must reflow at 320px width without horizontal scrolling (SC 1.4.10).

css

/* Prevent overflow */
img, video, iframe, svg {
  max-width: 100%;
  height: auto;
}

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 100 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/web/SKILL.md

Popularity

Repository stars: 362
Repository forks: 22
7-day trend score: 29

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 3 Apr 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/ehmo/platform-design-skills/web/badge)](https://verified-skill.com/skills/ehmo/platform-design-skills/web)

Something wrong with this skill or its page? Tell us.