ui-rules
UI hard-stop rules and audit method: WCAG 2.1 AA accessibility, responsive layout and motion.
- License 许可
- MIT
- 所属仓库
- 1aGh/maude
- 最近更新
- 2026-11-13
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- ui-rules
- category
- shared
- description
- UI hard-stop rules and audit method: WCAG 2.1 AA accessibility, responsive layout and motion.
- user-invocable
- false
02 资源文件 1
- 脚本scripts/a11y-audit.sh9.3 KB
03 SKILL.md 正文
UI Rules
Follow host conventions for Claude Code or Codex.
Hard-stop rules for UI work. A violation means the agent refuses, rewrites or blocks the artifact. Web (Next.js / Vite / vanilla) and React Native (Expo) — RN equivalents in parentheses. Reads .ai/workflows.config.json; each section can be switched off with its own flag (skills.a11yRules.enabled, skills.responsiveRules.enabled, skills.motionRules.enabled = false).
Readers: a11y-auditor → Accessibility + Accessibility audit; design-system-guard → Responsive + Motion; /flow:validate --review → all.
Accessibility
Reads theme (dark | light | agnostic): dark/light validate that theme first, agnostic checks both.
- Contrast — never below 4.5:1 for normal text, 3:1 for large text (18pt+), icons and UI components; no "decorative/branding" exemption. Validate in every configured theme, against the actual rendered background. Never convey meaning by color alone (1.4.1) — pair with text or icon.
- Alt text — no
<img>withoutalt(RNaccessibilityLabel); no generic alt ("image", "photo", "icon"). Describe content or function; decorative =alt=""+aria-hidden="true"(RNaccessible={false}). Charts: the key insight; video thumbnails: what is shown. - Keyboard / focus — no focus traps without escape; modals trap focus AND close on Escape, then return focus to the trigger. Tab/Shift+Tab in logical order; custom widgets fully keyboard-operable. Command palettes / comboboxes:
role="combobox", resultsrole="listbox". - Semantics — no
<div>/<span>for interactive elements (use<button>,<a>,<input>,<select>; RN<Pressable accessibilityRole="button">), no<div onClick>. One<h1>, no skipped heading levels. Landmarks (nav,main,header,footer,aside,section,article),ul/olfor lists,tablewiththfor tabular data. - Forms — every input has
<label for>/aria-label/aria-labelledby(RNaccessibilityLabel);placeholderis never the sole label; errors linked viaaria-describedby(RNaccessibilityHint). - Icon-only buttons — require an
aria-labelnaming the action, not the icon (<Button size="icon" aria-label="Search">). - Focus indicators — never
outline-none/outline-0without a visible replacement (e.g.focus-visible:ring-2); indicator contrast ≥ 3:1. - Touch targets — ≥ 44×44 px on mobile viewports (web-mobile + RN), ≥ 8 px between adjacent targets, padding may extend small visuals. If
responsive.densityMapmaps any platform topalm-friendly→ ≥ 48×48;sideline-tool→ ≥ 56×56. - Motion — honor
prefers-reduced-motion(RNAccessibilityInfo.isReduceMotionEnabled()); no auto-playing audio/video with sound; pause/stop controls for animated content; nothing flashing > 3×/second (2.3.1). Details in Motion below. - Skip navigation — every multi-section page has a skip link:
<a href="#main-content" class="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:bg-background focus:text-foreground focus:p-2 focus:rounded">Skip to main content</a>. - Landmarks —
header role="banner",nav role="navigation" aria-label="…",main role="main" id="main-content",footer role="contentinfo". - Bilingual UI — when
ux.bilingualis non-empty (e.g.["cs","en"]): every user-visible string translated for every code; keyboard-accessible language switcher;<html lang>updates on switch; change announced viaaria-live="polite"; dates/numbers/currency use the active locale. - Live regions — live data (presence cursors, typing indicators, notifications) uses
aria-live="polite",assertiveonly for critical alerts; don't announce every keystroke (debounce/summarize); never steal focus on remote updates.
Accessibility audit
How a11y-auditor and /flow:validate --a11y audit and report. Use before deploy, after .tsx/.jsx changes, when CI reports a11y failures, or for new components.
Script (project root; needs Node and the package manager): bash <plugin>/skills/ui-rules/scripts/a11y-audit.sh [--static | --runtime | --file <path>] (default: static + runtime + checklist). Steps in order:
- Static —
eslint-plugin-jsx-a11y: missing alt, missing accessible names, invalid ARIA, missing labels, wrong roles. Verify the ESLint config includes the plugin. - Runtime —
@axe-core/playwright(+@playwright/test;<pm> add -D …if missing, otherwise skip with a warning) against key pages (landing, primary features, form-heavy pages), on a running dev server (the script tries to start one; else<pm> run dev &). Group violations by impact: critical, serious, moderate, minor. Prefer a live agent-browser axe scan when available. - Contrast — scan CSS/token theme definitions for fg/bg pairs under 4.5:1 (3:1 large text / UI).
- Manual checklist (not automatable):
- Critical: accessible names on all interactive elements; keyboard works (Tab, Enter, Escape, arrows); no unintended focus trap; nothing hidden from screen readers.
- Serious: contrast; visible focus; errors announced; labels associated.
- Moderate: ARIA correct and not redundant; heading hierarchy; alt text quality; targets ≥ 44×44.
- Minor: landmarks; skip link; live regions.
Report format — every finding carries evidence (file:line, selector, or screenshot) and severity:
=== A11y Audit Results ===
Static Analysis: ✅ / ❌ ({N} issues)
Runtime Audit: ✅ / ❌ ({N} violations) / ⚠️ skipped
Contrast Check: ✅ / ❌ ({N} potential issues)
Manual Checklist: (items)
Overall: ✅ / ❌
Reference: WCAG 2.1 AA quickref (w3.org/WAI/WCAG21/quickref), axe-core rule descriptions, eslint-plugin-jsx-a11y rules.
Responsive
Reads platforms, responsive.approach (default mobile-first), responsive.densityMap, responsive.breakpoints.
-
Direction matches
approach— withmobile-first, base styles target the smallest viewport and expand withmin-width; never desktop-first overrides down. -
No fixed-width containers — no fixed pixel widths on layout containers; use
max-width+ fluid widths (%,vw,fr,auto), e.g.width:100%; max-width:80rem; margin-inline:auto. -
Container queries for components — component-level adaptation uses
container-type: inline-size+@container; viewport media queries only for page-level layout. -
No page-body horizontal overflow at any viewport:
overflow-wrap: break-word, imagesmax-width:100%; height:auto, tables scroll in a wrapper (overflow-x:auto); intentional horizontal surfaces (timelines, kanban) live inside a container, never on<body>. -
Breakpoint tokens — no scattered raw px breakpoints; use
responsive.breakpoints(defaultsm 480, md 768, lg 1024, xl 1280, 2xl 1536); Tailwind: built-in utilities unless config overrides. -
Fluid typography —
clamp()for scaling sizes (clamp(1.5rem, 1rem + 2vw, 3rem)); no static pixel font sizes; monospace numbers/IDs also fluid. -
Breakpoint testing — never ship a layout tested at one size. Web matrix: 320, 480, 768, 1024, 1280, 1440 px. Native per
platforms:ios-phone393×852,ios-tablet820×1180,android-phonePixel 7.scenario-runnerwalks every platform inplatforms. -
Density per platform — differing density is intentional, not a parity violation;
design-system-guardchecksresponsive.densityMap(platform → preset):Preset Tap target Spacing Use command-centerhover-only tight (4/8) keyboard-first desktop cozy44×44 medium (8/12/16) default web-desktop palm-friendly48×48 generous (12/16/24) mobile, use under pressure sideline-tool56×56 extra (16/24/32) field tablets, one-handed compacthover-only very tight (2/4) admin dashboards Custom preset strings allowed.
-
Cross-platform idioms — mobile: breathing room, bottom navigation, quick actions; tablet: secondary tool, larger targets, denser than mobile; desktop: command center, keyboard-first, densest. Flag layouts that merely scale the same components instead of re-shaping per surface.
Motion
Reads motion from config; ceilings default micro 300, page 500, complex 1000 ms.
- Reduced-motion fallback — every animation has a
@media (prefers-reduced-motion: reduce)fallback (e.g.transition: none); RN:AccessibilityInfo.isReduceMotionEnabled(). - Compositor-only properties — animate
transform,opacity,filter,clip-path; neverwidth,height,top,left,margin,padding. - Duration limits — micro-interaction (button, hover, tag pulse)
motion.micro; page transition (route, tab)motion.page; complex choreography (multi-step reveal, hero)motion.complex. Never exceed without a documented justification (DDR-worthy). Prefer ≤ 200 ms; ifux.responseTargetMsis low (e.g. 100), bias tighter. - Purpose — no decorative animation; each serves feedback, orientation, focus direction, state change, or hierarchy reveal.
- No uncontrolled infinite animation —
animation-iteration-count: infiniteneeds pause/stop (stops on scroll-out, unmount, user pause). Spinners are the exception (still need reduced-motion fallback); prefer skeletons. - Motion tokens — no hardcoded durations/easings; use e.g.
transition: opacity var(--motion-duration-fast) var(--motion-ease-standard). Recommended baseline: durationsinstant 0,fast 100,normal 200,moderate 300,slow 500ms; easingsstandard cubic-bezier(0.4,0,0.2,1),enter (0,0,0.2,1),exit (0.4,0,1,1),spring (0.175,0.885,0.32,1.275). Projects may override; the reviewer flags raw values. - No flash content — nothing flashing > 3×/second (WCAG 2.3.1).
- Custom pulses — ambient loops (live indicators, breathing affordances) are exempt from page/complex ceilings when declared:
{ "motion": { "customPulses": { "liveIndicator": 1500, "skeletonShimmer": 1500 } } }. Declared pulses still need a reduced-motion fallback (solid placeholder) and a pause/stop trigger.
04 同仓库更多 Skills
workflow-state
Read and update workflow state when planning, executing, completing, pausing or resuming project work.
testing-rules
Apply test quality rules during implementation and review: meaningful assertions, isolation and coverage.
security-rules
Apply application and AI security checks to code reviews, implementation and threat-driven validation.
scenario
Author or run cross-platform UI scenarios with selectors, screenshots, platform coverage and result reports.
question-protocol
Batch necessary questions from workflow participants, collect user answers and route them to the requester.
quality-gates
Resolve project quality commands, scoped checks, gate failures and validation fallbacks from workflow config.