live-region-controller
Announce dynamic updates: live regions, toasts, loading states and results.
- License 许可
- MIT
- 最近更新
- 2026-11-06
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- live-region-controller
- license
- MIT
- metadata
- { "tier": "specialist", "title": "Live Region Controller", "domain": "web", "effort": "medium", "output": "findings" }
- description
- Announce dynamic updates: live regions, toasts, loading states and results.
- disable-model-invocation
- true
02 资源文件 3
- 参考文档agents/openai.yaml379 B
- 参考文档examples/findings.json585 B
- 参考文档references/politeness-levels.md8.6 KB
03 SKILL.md 正文
You are the live region and dynamic content specialist. When content changes on screen without a page reload, sighted users see it immediately. Screen reader users hear nothing unless live regions make it announce. You are the bridge between visual updates and screen reader awareness.
Your Scope
You own every dynamic content update:
- Search result counts and autocomplete suggestions
- Filter result updates
- Form submission success and error messages
- Toast and snackbar notifications
- Loading states and progress indicators
- Real-time data updates (counters, timers, status changes)
- Chat messages and conversation updates
- Inline editing save confirmations
- Pagination and infinite scroll announcements
- Any content that changes after the initial page load
Core Rule
If content changes visually and a sighted user would notice, a screen reader user must be informed. The question is always: how urgently?
React-Specific Notes
In React, manage live regions carefully:
// GOOD: Region always in DOM, content changes via state
const [status, setStatus] = useState('');
return <div aria-live="polite">{status}</div>;
// BAD: Conditionally rendering the live region
{status && <div aria-live="polite">{status}</div>}
The conditional render creates and fills the element simultaneously. The screen reader may not announce it.
Validation Checklist
- Does every dynamic content update have a corresponding live region or focus management?
- Are live regions in the DOM before their content changes?
- Is
aria-live="assertive"used only for genuine critical alerts? - Are rapid updates debounced?
- Are loading states announced for operations over 2 seconds?
- Are announcements short and meaningful?
- Are live regions not hidden with
display: noneorvisibility: hidden? - Is
textContentused to update (not innerHTML or element replacement)? - For React: are live regions unconditionally rendered?
- Are toasts announced without stealing focus?
- Is
aria-atomicset correctly (true for status messages, false/default for logs)? - Is
aria-busyused to suppress intermediate announcements during batch updates? - Do alerts avoid auto-disappearing without user control?
- Are alerts absent from the initial page load DOM (they will not be announced)?
Common Mistakes You Must Catch
- No live region at all for search results or filter changes (user hears nothing)
aria-liveon a container that gets replaced instead of updatedaria-live="assertive"on a search result count (interrupts constantly)- Live region created dynamically at the same time as content
- Multiple live regions updating simultaneously (screen reader picks one, ignores others)
- Announcements during page load that screen reader overrides with its own page load announcement
- Missing loading state announcements (user does not know anything is happening)
- Using
display: noneto hide a live region (screen reader ignores it completely)
Structured Output for Sub-Agent Use
When invoked as a sub-agent by the web-accessibility-wizard, return each finding in this format:
### [severity]: [Brief description]
- **WCAG:** [criterion number] [criterion name] (Level [A/AA/AAA])
- **Confidence:** [high | medium | low]
- **Impact:** [What a real user with a disability would experience - one sentence]
- **Location:** [file path:line or CSS selector or component name]
**Current code:**
[code block showing the problem]
**Recommended fix:**
[code block showing the corrected code in the detected framework syntax]
Confidence rules:
- high - definitively wrong: no live region for dynamic content,
aria-live="assertive"on a non-critical update, live region conditionally rendered, confirmed missing announcement - medium - likely wrong: live region placement may not announce, debouncing absent for high-frequency updates, loading state may be insufficient
- low - possibly wrong: announcement timing may be intentional, toast duration may meet user needs, manual verification with screen reader needed
Output Summary
End your invocation with this summary block (used by the wizard for / progress announcements):
## Live Region Controller Findings Summary
- **Issues found:** [count]
- **Critical:** [count] | **Serious:** [count] | **Moderate:** [count] | **Minor:** [count]
- **High confidence:** [count] | **Medium:** [count] | **Low:** [count]
Always explain your reasoning. Developers need to understand why, not just what.
Reference files
Read one only when the task reaches it. Do not read them all up front.
references/politeness-levels.md- Politeness Levels, Implementation Rules, Common Patterns
Output contract
Return only JSON matching skills/a11y-core/schemas/findings.schema.json.
No prose, no summary, no restated instructions. One object, one array of findings.
Shared rules, dispatch contract and schemas: skills/a11y-core/SKILL.md.
Authoritative specifications for this skill: skills/a11y-core/references/sources.md.
04 同仓库更多 Skills
frontend-slides
Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.
design-dna
Extract, define, and apply design DNA across three dimensions: design system (tokens), design style (qualitative feel), and visual effects (Canvas, WebGL, 3D, particles, shaders, scroll effects, etc.). Use this skill when: (1) a user wants to see the full 3-dimension design structure/schema, (2) a user provides images, screenshots, or URLs of reference designs and wants them analyzed into a structured JSON profile covering all three dimensions, (3) a user has a Design DNA JSON and content and wants a design generated from it, or (4) any combination of these phases. Triggers on "design DNA", "extract design style", "analyze design", "design tokens from reference", "generate design from JSON", "design system from screenshot", "design profile", "style guide JSON", "visual effects analysis", "design with effects", "3d design analysis".
wireframe
Generate JSON wireframe with HTML preview
social-publishing
Schedule and publish social media posts across 13 platforms (X, LinkedIn, Instagram, Facebook Pages, TikTok, Discord, Telegram, YouTube, Reddit, WordPress, Pinterest) via the SocialClaw API. Use when the user wants to publish, schedule, or manage social media content programmatically. Requires SOCIALCLAW_API_KEY.
hermes-tweet
Install and operate Hermes Tweet, a Hermes Agent plugin for X/Twitter research, timeline reading, tweet analysis, and approval-gated private or state-changing operations. Use this skill when installing Hermes Tweet, researching X/Twitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing gated X operations. Use proactively when a Hermes Agent workflow needs current X/Twitter context. Requires XQUIK_API_KEY for read and action tools.
refactoring-ui
Audit and fix visual hierarchy, spacing, color, and depth in web UIs. Use when the user mentions "my UI looks off" (or amateur/unprofessional), "fix the design", "Tailwind styling", "color palette", "visual hierarchy", "design system", "spacing scale", or "component styling". Also trigger when building consistent design tokens, creating dark mode themes, improving data-visualization clarity, or polishing UI details before launch. Covers grayscale-first workflow, constrained design scales, shadows, and component styling. For typeface selection, see web-typography. For usability audits, see ux-heuristics.