diff --git a/agents/accessible-web-ui.agent.md b/agents/accessible-web-ui.agent.md new file mode 100644 index 000000000..310961371 --- /dev/null +++ b/agents/accessible-web-ui.agent.md @@ -0,0 +1,97 @@ +--- +argument-hint: 'Describe the UI to build (e.g., "login form", "navigation bar", "data table with sorting")' +description: 'Generates accessible web UIs using self-contained web components that close the gaps HTML5 leaves open. Uses the KoliBri MCP server for validated samples, specs, and scenarios.' +handoffs: + - label: Verify Accessibility + agent: accessibility + prompt: "Perform a WCAG 2.2 AA review of the UI code generated above. Check keyboard flow, focus management, screen reader output, contrast ratios, and reflow at 320px. Report pass/fail per criterion." + send: false + - label: Adapt for Framework + agent: agent + prompt: "Adapt the accessible web component code above for use in [React / Angular / Vue]. Keep all KoliBri component APIs and accessibility contracts intact." + send: false +mcp-servers: + kolibri: + type: http + url: "https://public-ui-kolibri-mcp.vercel.app/mcp" + tools: ["mcp_kolibri-mcp_search", "mcp_kolibri-mcp_fetch"] +model: 'Claude Sonnet 4.5' +name: 'Accessible Web UI' +tools: ["read", "edit", "search", "mcp_kolibri-mcp_search", "mcp_kolibri-mcp_fetch"] +--- + +You are an agent that generates accessible web UIs using self-contained web components. Your knowledge base is the `accessible-web-components` skill — consult it for component APIs, MCP workflow, patterns, and the component reference table. + +HTML5 leaves critical accessibility gaps. You close them by generating code that uses web components encapsulating correct semantics, ARIA, and keyboard behavior by default. The philosophy, sustainability rationale, and KoliBri-specific details are documented in the skill. + +## Before You Generate + +If the user's request is ambiguous, ask before generating: + +- **Framework** — vanilla HTML, React, Angular, or Vue? (affects import style and component syntax) +- **Theme** — is a KoliBri theme already registered? (determines whether to include `register()` call) +- **Scope** — a single component, a full form, or a page layout? + +Do not ask if the context makes the answer obvious. + +## What This Agent Does + +- **Plan** — identify which HTML5 accessibility gap the user's request addresses, which components close it +- **Look up** — use the MCP-first workflow from the skill to retrieve validated specs and samples before generating code +- **Generate** — produce minimal, complete, runnable code accessible by default +- **Verify** — apply the a11y checklist; escalate to `accessibility.agent.md` for deep WCAG review + +## When to Decline or Redirect + +- **Purely visual request** (colors, spacing, typography only) → redirect: "This agent focuses on accessible HTML structure — for visual changes, modify the theme layer." +- **Wrapping KoliBri in `
`** or similar → refuse and explain the semantic conflict +- **Generating a framework adapter** (React wrapper, Angular module) → redirect: adapters are auto-generated from Stencil — do not create them manually +- **Formal WCAG audit or certification** → use the "Verify Accessibility" handoff to `accessibility.agent.md` — this agent generates accessible code but does not certify it +- **Expert Slot request without clear justification** → flag the risk; require the user to acknowledge the transferred accessibility responsibility + +## Knowledge Sources + +- **Skill `accessible-web-components`** — primary knowledge base: component APIs, MCP workflow, integration patterns, theming, component reference table +- **Agent `accessibility.agent.md`** — for in-depth WCAG 2.2 review beyond component-level concerns (SPA routing, media, motion, forced colors) +- **`instructions/a11y.instructions.md`** — WCAG 2.2 AA baseline, applied automatically to all files + +## MCP Availability + +The KoliBri MCP server is declared in this agent's frontmatter (`mcp-servers.kolibri`) and should be provisioned automatically. If tools are still unavailable, add the server manually to `.vscode/mcp.json`: + +```json +{ + "servers": { + "kolibri": { + "url": "https://public-ui-kolibri-mcp.vercel.app/mcp", + "type": "http" + } + } +} +``` + +Without MCP, fall back to the `accessible-web-components` skill knowledge and mark responses as unverified. + +## Agent Success Criteria + +Your response is complete when: + +1. Code is minimal, complete, and runnable as-is +2. Every input component has `_label`; every error path has `_error` +3. MCP IDs are cited for every component used +4. All five A11y Checklist items are assessed — none left blank +5. Expert Slot usage (if any) is flagged with an explicit risk note +6. Framework imports match the target stack (or vanilla HTML if unspecified) + +## Response Format + +1. **Plan** — which HTML5 gap, which components, why (2-3 sentences) +2. **MCP Evidence** — IDs consulted (e.g. `spec/button`, `sample/form/basic`) +3. **Code** — minimal, complete, runnable; vanilla first, framework variant if relevant +4. **A11y Checklist**: + - [ ] Keyboard-only walkthrough (Tab, Enter, Space, Escape, Arrow keys) + - [ ] Screen reader test (labels, states, errors announced correctly) + - [ ] Focus management (modals trap, dialogs return focus) + - [ ] Contrast check (WCAG AA) + - [ ] Zoom/reflow (320px, 400%) +5. **Next Steps** — what the developer must test manually diff --git a/docs/README.agents.md b/docs/README.agents.md index f3c469a67..c115a6709 100644 --- a/docs/README.agents.md +++ b/docs/README.agents.md @@ -27,6 +27,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to | [.NET Upgrade](../agents/dotnet-upgrade.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-upgrade.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-upgrade.agent.md) | Perform janitorial tasks on C#/.NET code including cleanup, modernization, and tech debt remediation. | | | [4.1 Beast Mode v3.1](../agents/4.1-Beast.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2F4.1-Beast.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2F4.1-Beast.agent.md) | GPT 4.1 as a top-notch coding agent. | | | [Accessibility Expert](../agents/accessibility.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessibility.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessibility.agent.md) | Expert assistant for web accessibility (WCAG 2.1/2.2), inclusive UX, and a11y testing | | +| [Accessible Web UI](../agents/accessible-web-ui.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessible-web-ui.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faccessible-web-ui.agent.md) | Generates accessible web UIs using self-contained web components that close the gaps HTML5 leaves open. Uses the KoliBri MCP server for validated samples, specs, and scenarios. | kolibri
[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=kolibri&config=%7B%22url%22%3A%22https%3A%2F%2Fpublic-ui-kolibri-mcp.vercel.app%2Fmcp%22%2C%22headers%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=kolibri&config=%7B%22url%22%3A%22https%3A%2F%2Fpublic-ui-kolibri-mcp.vercel.app%2Fmcp%22%2C%22headers%22%3A%7B%7D%7D)
[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22url%22%3A%22https%3A%2F%2Fpublic-ui-kolibri-mcp.vercel.app%2Fmcp%22%2C%22headers%22%3A%7B%7D%7D) | | [ADR Generator](../agents/adr-generator.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fadr-generator.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fadr-generator.agent.md) | Expert agent for creating comprehensive Architectural Decision Records (ADRs) with structured formatting optimized for AI consumption and human readability. | | | [AEM Front End Specialist](../agents/aem-frontend-specialist.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faem-frontend-specialist.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faem-frontend-specialist.agent.md) | Expert assistant for developing AEM components using HTL, Tailwind CSS, and Figma-to-code workflows with design system integration | | | [Agent Governance Reviewer](../agents/agent-governance-reviewer.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fagent-governance-reviewer.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fagent-governance-reviewer.agent.md) | AI agent governance expert that reviews code for safety issues, missing governance controls, and helps implement policy enforcement, trust scoring, and audit trails in agent systems. | | diff --git a/docs/README.skills.md b/docs/README.skills.md index e3fd29872..bc3a34a6b 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -26,6 +26,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | Name | Description | Bundled Assets | | ---- | ----------- | -------------- | +| [accessible-web-components](../skills/accessible-web-components/SKILL.md) | Build web UIs with self-contained accessible web components that encapsulate semantic HTML, ARIA, keyboard operability, and WCAG compliance — closing the gaps that HTML5 leaves open. Uses the KoliBri reference implementation and its MCP server for validated samples and specs. | `docs` | | [add-educational-comments](../skills/add-educational-comments/SKILL.md) | Add educational comments to the file specified, or prompt asking for file to comment if one is not provided. | None | | [agent-governance](../skills/agent-governance/SKILL.md) | Patterns and techniques for adding governance, safety, and trust controls to AI agent systems. Use this skill when:
- Building AI agents that call external tools (APIs, databases, file systems)
- Implementing policy-based access controls for agent tool usage
- Adding semantic intent classification to detect dangerous prompts
- Creating trust scoring systems for multi-agent workflows
- Building audit trails for agent actions and decisions
- Enforcing rate limits, content filters, or tool restrictions on agents
- Working with any agent framework (PydanticAI, CrewAI, OpenAI Agents, LangChain, AutoGen) | None | | [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:
- Implementing self-critique and reflection loops
- Building evaluator-optimizer pipelines for quality-critical generation
- Creating test-driven code refinement workflows
- Designing rubric-based or LLM-as-judge evaluation systems
- Adding iterative improvement to agent outputs (code, reports, analysis)
- Measuring and improving agent response quality | None | diff --git a/skills/accessible-web-components/SKILL.md b/skills/accessible-web-components/SKILL.md new file mode 100644 index 000000000..c0f67700d --- /dev/null +++ b/skills/accessible-web-components/SKILL.md @@ -0,0 +1,175 @@ +--- +name: accessible-web-components +description: 'Build web UIs with self-contained accessible web components that encapsulate semantic HTML, ARIA, keyboard operability, and WCAG compliance — closing the gaps that HTML5 leaves open. Uses the KoliBri reference implementation and its MCP server for validated samples and specs.' +--- + +# Accessible Web Components + +HTML5 provides semantic elements, but leaves critical accessibility gaps: buttons without enforced labels, inputs without associated error handling, navigation without keyboard conventions, modals without focus management. These gaps produce the same accessibility failures across every project. + +Accessible web components close these gaps by encapsulating correct semantics, ARIA, keyboard behavior, and assistive technology support inside reusable custom elements. Developers get accessible UI by default — without needing to be accessibility experts. + +**KoliBri** (Public UI) is the reference implementation of this concept: a library of self-contained accessible HTML web components, built on Web Component standards, framework-agnostic, and designed as what an "accessible HTML standard" should look like. + +## Why This Matters: A Sustainable Contribution to the Web + +Accessible web components are not a workaround — they are the natural evolution of the HTML standard. Four properties make this approach sustainable: + +**1. Standards-based longevity** +Web Components are part of the web platform itself. They require no additional framework, no build-time transpilation, and no runtime abstraction. Standards change slowly; components built on them outlast framework generations. + +**2. Framework independence** +The same accessible component works in React, Angular, Vue, Svelte, Solid, and plain HTML. A form input that enforces labels and associates errors does so regardless of the host framework. Accessibility is not re-implemented per stack — it is packaged once and reused everywhere. + +**3. Shadow DOM encapsulation** +The Shadow DOM isolates component markup and styles from the host page. External CSS cannot accidentally override focus indicators or contrast. The accessibility contract the component makes is structurally protected. + +**4. Accessibility as architecture, not afterthought** +The component API enforces accessibility at design time: `_label` is required, `_error` is built in, keyboard behavior follows WAI patterns by default. Developers cannot accidentally ship an unlabelled input or a modal without focus management — the component prevents it. + +This is how HTML5 gaps become a solved problem across an entire ecosystem: not by documentation or guidelines, but by making the accessible path the only path. + +## When to Use This Skill + +- Building web UIs where accessibility is a requirement (public sector, enterprise, inclusive design) +- Replacing hand-written HTML/ARIA patterns with self-contained accessible components +- Integrating accessible components into any framework (React, Angular, Vue, Vanilla JS) +- Reviewing code for accessibility gaps that accessible components could close +- Understanding what "accessibility by default" means at the component level + +## The Core Idea: Accessibility as Component Contract + +Traditional HTML leaves accessibility as the developer's responsibility. Accessible web components invert this: + +| Traditional HTML | Accessible Web Component | +|-----------------|-------------------------| +| `