AGENT SKILL

web-standards

Use when writing or reviewing HTML, CSS, or browser JavaScript — covers semantic markup, native platform features over libraries, Baseline browser support, accessibility and APCA contrast, and optional validation with vnu, axe, and Lighthouse

License 许可
MIT
所属仓库
kejadlen/dotfiles
最近更新
2026-11-14
Stars
★ 10
Forks
0

01 前言 Front Matter

name
web-standards
description
Use when writing or reviewing HTML, CSS, or browser JavaScript — covers semantic markup, native platform features over libraries, Baseline browser support, accessibility and APCA contrast, and optional validation with vnu, axe, and Lighthouse

03 SKILL.md 正文

Web standards

Build on what the platform already does, and check claims about it against a primary source rather than memory. Browser support moves faster than training data, so a feature remembered as unsupported may have shipped everywhere since.

For visual design, fluid type, and Alpine.js, use web-design. For alt text and inclusive language, use writing-for-accessibility.

Semantic HTML

Lead with semantic HTML. Reach for meaningful elements — main, article, nav, kbd, details, dl/dt — before wrapping content in generic divs. Semantic markup gives the CSS something to target and carries accessibility along with it.

Native before JavaScript

Before adding a library or hand-rolling behavior, check whether the platform has a built-in. The following replace common dependencies:

Need Platform feature
Modals <dialog> with showModal()
Menus, tooltips, toasts popover attribute
Disclosure, accordions <details> and <summary>, grouped with name
Form validation Constraint validation: required, pattern, :user-invalid
Parent and state selectors :has()
Component-level responsiveness Container queries
Preprocessor nesting Native CSS nesting
Page and state transitions View transitions
Positioning relative to another element Anchor positioning
Date, number, and list formatting Intl.*
URL parsing and query strings URL, URLSearchParams
Cancellable requests fetch with AbortController
Deep copies structuredClone()

Some of these are newer than others. Check support before relying on one, as described in the next section.

Browser support

Default to Baseline "widely available": features that have worked in every major browser for at least 30 months. Use "newly available" features only as progressive enhancement, behind @supports or feature detection, so the page still works without them.

Look up the current status on Baseline or caniuse instead of recalling it. MDN pages also show a Baseline badge near the top.

Progressive enhancement

Forms submit and links navigate without JavaScript. JavaScript layers behavior on top of working HTML, not in place of it. Keep state worth sharing — filters, tabs, search terms — in the URL so it survives a reload and a copied link.

Accessibility

Target WCAG 2.2 level AA. It's the current W3C Recommendation, and the regulations that cite WCAG 2.1 AA are satisfied by 2.2 AA too. WCAG 3 is still a Working Draft; don't target it.

Follow the first rule of ARIA: when a native element has the semantics and behavior you need, use it instead of adding role and aria-* to a div. A <button> is focusable, activates on Enter and Space, and announces itself as a button for free.

Keep focus visible and in a logical order. When a <dialog> or popover closes, focus returns to whatever opened it. Respect prefers-reduced-motion for animation and prefers-color-scheme for theming.

Color contrast

Pass WCAG 2.2 AA (4.5:1 for body text, 3:1 for large text and UI components), then check APCA as a perceptual floor. APCA handles dark mode and thin fonts better than the WCAG 2 ratio, which overstates contrast for light text on dark backgrounds. APCA is a candidate for WCAG 3, not a standard, so it supplements WCAG 2.2 and doesn't replace it.

APCA reports a lightness contrast (Lc) value that's negative for light text on dark backgrounds; compare its absolute value against the following thresholds:

Lc Use
90 Preferred for body text
75 Minimum for body text (18px/400, 16px/500, 14px/700)
60 Minimum for other content text (24px/400, 16px/700)
45 Headlines (36px/400, 24px/700)
30 Minimum for any other text, and non-text elements
15 Minimum for non-semantic elements that must stay visible

With fluid type, check the smallest size in each clamp() range.

Primary sources

Cite specs and references, not blog summaries or recollection:

Validating

These checks are optional. Run one when it's cheap and the change touches markup, styles, or color. If a tool isn't available, say which check you skipped instead of installing something to get around it.

Check Command Needs
HTML conformance vnu --errors-only page.html vnu (Homebrew) or npx vnu-jar, plus a JDK
CSS conformance vnu --css --errors-only style.css Same as above
Accessibility rules npx @axe-core/cli <url> Chrome
Accessibility audit npx lighthouse <url> --only-categories=accessibility Chrome
APCA contrast The APCA calculator, or apca-w3 in a script Nothing, or Node

Automated checks catch only a fraction of accessibility problems; a clean axe run doesn't mean the page is accessible. For interactive changes, also tab through the page and confirm focus stays visible and moves in order.


This is a self-improving skill. If you used it and it came up short — a missing command, flag, gotcha, or workflow — invoke the self-improving-skills skill and follow it before you finish.

04 同仓库更多 Skills