Design

Web Design

> Apply design-standards:design-system first (tokens, spacing, type, color, motion, states). This file adds the web Tier-1 standards and web-only rules. R-rules are PASS/FAIL/N_A, never INFO; disabling one needs a documented reason in standards.json disabled_rules[].

Standards (Tier-1, cited — universal for every web project)

• R1 Contrast (WCAG 1.4.3/1.4.11): body ≥4.5:1, large (≥18pt/14pt-bold) ≥3:1, non-text UI ≥3:1. Light and dark independent. Verify: axe-core/pa11y.
• R2 Tap targets ≥44×44 CSS px (WCAG 2.5.5 AAA; AA floor 24×24 per 2.5.8) — extend hit area with padding.
• R3 Color never the sole state signal (WCAG 1.4.1) — pair with icon/label/shape/position. Verify: grayscale screenshot.
• R4 Respect prefers-reduced-motion (WCAG 2.3.3) — drop decorative animation; functional ≤~150ms, no overshoot.
• R5 Animate only transform/opacity — layout props trigger per-frame layout/paint. Verify: DevTools paint flashing.
• R6 Focus visible via :focus-visible (WCAG 2.4.7) — never outline:none unreplaced; not bare :focus.
• R7 Body line-height ≥1.5 (WCAG 1.4.12); display 1.0–1.2.
• R8 Body measure 45–75ch (Bringhurst).
• R9 Semantic HTML (WHATWG + ARIA APG): ` actions / nav; one , no skipped levels; per control; alt present (alt="" decorative); `.
• R10 color-scheme declared — native controls/scrollbars match the theme.
• R11 forced-colors: active honored — rings/borders/icons use system colors in High Contrast.
• R12 Single source of truth — no hardcoded hex/px/ms/type literals in screen code; Tailwind arbitrary values (p-[13px]) count. Verify: grep raw literals.
• R13 Font loading without CLS — font-display: swap/optional, preload above-fold, matched fallback metrics.
• R14 tabular-nums on aligned numeric columns.
• R15 Sub-44px adjacent targets ≥24px center-to-center (WCAG 2.5.8).

Layout & responsive

• Breakpoints: 3–5 monotonic min-widths (default 375 / 768 / 1280 / 1536). Max-widths: standard 1200 / reading 720 / focused 480; constrain ≤~1920px.
• Mobile-first; no horizontal overflow at 320px. Tablet is its own layout, not a bigger mobile. Primary actions in the thumb zone on touch.
• Safe-area insets (env(safe-area-inset-*)) on fixed bars, full-bleed sections, modals. dvh not vh wherever the keyboard can open.
• gap for layout inside flex/grid, not margin.

Typography & elevation (web mechanics)

• rem for font-size; named steps only. UGC gets line-clamp. Font-loading mechanics owned by web-standards:performance (rule: R13).
• box-shadow, never filter: drop-shadow(). Default 3 levels: flat none · card 0 1px 3px rgba(0,0,0,.12) · dropdown 0 4px 16px rgba(0,0,0,.16). Dark mode: replace shadows with a 1px ~12%-white border or more alpha.

Chrome & details

• Custom focus ring via :focus-visible (R6). Custom ::selection; caret-color on inputs; styled scrollbar where visible (never hide overflow indicators); cursor:pointer on clickable non-links.
• Inline loading (in-button spinner), not full-page. Images: fixed aspect ratios, lazy-load, blur-up placeholder.

Accessibility (web specifics, beyond the R-rules)

• Modal focus trap: Tab cycles, Esc closes, focus returns to the trigger. Tab order matches visual order.
• role="status"/role="alert" on live regions. prefers-reduced-transparency honored. Color-blind safe.

Theme

• Every themeable value from a CSS variable / @theme; semantic names (--surface-muted, not --blue-500). Prefer OKLCH.
• Light and dark independently designed (see design-system) — never computed inversion.
• SSR hydration flash prevented (blocking script or cookie; next-themes + suppressHydrationWarning). color-scheme per theme class (R10).
• Audit: toggle theme, scroll every screen for untokenized backgrounds/borders/embeds.

Aesthetic coherence

• Commit to ONE aesthetic (declare standards.json features.aesthetic.active); never mix two — the #1 "assembled, not designed" tell.
• If glass: text legibility strategy (solid layer or bg-opacity ≥.5) + prefers-reduced-transparency fallback.
• Per-aesthetic numbers are Tier-3 INFO unless promoted. Spec ranges: glass blur 8–24px, bg-opacity .1–.3, hairline border · clay radius 40–60px, triple-layer shadow · bento radius 16–24, 2–4 tile sizes, per-tile hover · neumorph dual shadow, interactive-only, ruthless contrast audit · utility-brutalist mono accents, dense tables, dark-first, minimal motion · editorial ratio ≥1.5, measure 55–70ch, contrasting type pair · minimalist ≤2 brand colors, ≤3 weights, whitespace ≥40%.

Brand moments (whole-app surfaces)

404 on-brand + useful actions · 500 apologetic + retry + support · splash branded · offline branded · first-run empty state designed as a moment.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pixelcrafts-app
• Source: pixelcrafts-app/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.