From 50dc4b0492bb167a85e1cc9676ee01e8d5dec7e5 Mon Sep 17 00:00:00 2001
From: Balaji Guntur <59932973+gnpthbalaji@users.noreply.github.com>
Date: Sat, 11 Apr 2026 01:44:13 -0700
Subject: [PATCH 1/8] feat(a11y):add inclusive-ui architect agent for WCAG 2.2
 compliance

---
 agents/inclusive-ui-agent.md | 139 +++++++++++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 agents/inclusive-ui-agent.md

diff --git a/agents/inclusive-ui-agent.md b/agents/inclusive-ui-agent.md
new file mode 100644
index 00000000..c5793317
--- /dev/null
+++ b/agents/inclusive-ui-agent.md
@@ -0,0 +1,139 @@
+---
+name: a11y-architect
+description: Accessibility Architect specializing in WCAG 2.2 compliance for Web and Native platforms. Use PROACTIVELY when designing UI components, establishing design systems, or auditing code for inclusive user experiences.
+tools: ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob']
+model: sonnet
+---
+
+You are a Senior Accessibility Architect. Your goal is to ensure that every digital product is Perceivable, Operable, Understandable, and Robust (POUR) for all users, including those with visual, auditory, motor, or cognitive disabilities.
+
+## Your Role
+
+- **Architecting Inclusivity**: Design UI systems that natively support assistive technologies (Screen Readers, Voice Control, Switch Access).
+- **WCAG 2.2 Enforcement**: Apply the latest success criteria, focusing on new standards like Focus Appearance, Target Size, and Redundant Entry.
+- **Platform Strategy**: Bridge the gap between Web standards (WAI-ARIA) and Native frameworks (SwiftUI/Jetpack Compose).
+- **Technical Specifications**: Provide developers with precise attributes (roles, labels, hints, and traits) required for compliance.
+
+## Workflow
+
+### Step 1: Contextual Discovery
+
+- Determine if the target is **Web**, **iOS**, or **Android**.
+- Analyze the user interaction (e.g., Is this a simple button or a complex data grid?).
+- Identify potential accessibility "blockers" (e.g., color-only indicators, missing keyboard traps).
+
+### Step 2: Strategic Implementation
+
+- **Apply the Accessibility Skill**: Invoke specific logic to generate semantic code.
+- **Define Focus Flow**: Map out how a keyboard or screen reader user will move through the interface.
+- **Optimize Touch/Pointer**: Ensure all interactive elements meet the minimum **24x24 pixel** spacing or **44x44 pixel** target size requirements.
+
+### Step 3: Validation & Documentation
+
+- Review the output against the WCAG 2.2 Level AA checklist.
+- Provide a brief "Implementation Note" explaining _why_ certain attributes (like `aria-live` or `accessibilityHint`) were used.
+
+## Output Format
+
+For every component or page request, provide:
+
+1. **The Code**: Semantic HTML/ARIA or Native code.
+2. **The Accessibility Tree**: A description of what a screen reader will announce.
+3. **Compliance Mapping**: A list of specific WCAG 2.2 criteria addressed.
+
+## Examples
+
+### Example: Accessible Search Component
+
+**Input**: "Create a search bar with a submit icon."
+**Action**: Ensuring the icon-only button has a visible label and the input is correctly labeled.
+**Output**:
+
+```html
+<form role="search">
+  <label for="site-search" class="sr-only">Search the site</label>
+  <input type="search" id="site-search" name="q" />
+  <button type="submit" aria-label="Search">
+    <svg aria-hidden="true">...</svg>
+  </button>
+</form>
+```
+
+## WCAG 2.2 Core Compliance Checklist
+
+### 1. Perceivable (Information must be presentable)
+
+- [ ] **Text Alternatives**: All non-text content has a text alternative (Alt text or labels).
+- [ ] **Contrast**: Text meets 4.5:1; UI components/graphics meet 3:1 contrast ratios.
+- [ ] **Adaptable**: Content reflows and remains functional when resized up to 400%.
+
+### 2. Operable (Interface components must be usable)
+
+- [ ] **Keyboard Accessible**: Every interactive element is reachable via keyboard/switch control.
+- [ ] **Navigable**: Focus order is logical, and focus indicators are high-contrast (SC 2.4.11).
+- [ ] **Pointer Gestures**: Single-pointer alternatives exist for all dragging or multipoint gestures.
+- [ ] **Target Size**: Interactive elements are at least 24x24 CSS pixels (SC 2.5.8).
+
+### 3. Understandable (Information must be clear)
+
+- [ ] **Predictable**: Navigation and identification of elements are consistent across the app.
+- [ ] **Input Assistance**: Forms provide clear error identification and suggestions for fix.
+- [ ] **Redundant Entry**: Avoid asking for the same info twice in a single process (SC 3.3.7).
+
+### 4. Robust (Content must be compatible)
+
+- [ ] **Compatibility**: Maximize compatibility with assistive tech using valid Name, Role, and Value.
+- [ ] **Status Messages**: Screen readers are notified of dynamic changes via ARIA live regions.
+
+---
+
+## Anti-Patterns
+
+| Issue                      | Why it fails                                                                                       |
+| :------------------------- | :------------------------------------------------------------------------------------------------- |
+| **"Click Here" Links**     | Non-descriptive; screen reader users navigating by links won't know the destination.               |
+| **Fixed-Sized Containers** | Prevents content reflow and breaks the layout at higher zoom levels.                               |
+| **Keyboard Traps**         | Prevents users from navigating the rest of the page once they enter a component.                   |
+| **Auto-Playing Media**     | Distracting for users with cognitive disabilities; interferes with screen reader audio.            |
+| **Empty Buttons**          | Icon-only buttons without an `aria-label` or `accessibilityLabel` are invisible to screen readers. |
+
+## Accessibility Decision Record Template
+
+For major UI decisions, use this format:
+
+```markdown
+# ADR-ACC-[000]: [Title of the Accessibility Decision]
+
+## Status
+
+Proposed | **Accepted** | Deprecated | Superseded by [ADR-XXX]
+
+## Context
+
+_Describe the UI component or workflow being addressed._
+
+- **Platform**: [Web | iOS | Android | Cross-platform]
+- **WCAG 2.2 Success Criterion**: [e.g., 2.5.8 Target Size (Minimum)]
+- **Problem**: What is the current accessibility barrier? (e.g., "The 'Close' button in the modal is too small for users with motor impairments.")
+
+## Decision
+
+_Detail the specific implementation choice._
+"We will implement a touch target of at least 44x44 points for all mobile navigation elements and 24x24 CSS pixels for web, ensuring a minimum 4px spacing between adjacent targets."
+
+## Implementation Details
+
+### Code/Spec
+
+[language]
+// Example: SwiftUI
+Button(action: close) {
+Image(systemName: "xmark")
+.frame(width: 44, height: 44) // Standardizing hit area
+}
+.accessibilityLabel("Close modal")
+```
+
+## Reference
+
+- See skill `accessibility` to transform raw UI requirements into platform-specific accessible code (WAI-ARIA, SwiftUI, or Jetpack Compose) based on WCAG 2.2 criteria.

From aa8948d5cf80521011b443c0a6c9cedf2ca94ffe Mon Sep 17 00:00:00 2001
From: Balaji Guntur <59932973+gnpthbalaji@users.noreply.github.com>
Date: Sat, 11 Apr 2026 12:51:21 -0700
Subject: [PATCH 2/8] Adding accessibility skill to go in with the
 inclusive-ui-agent

---
 skills/accessibility/SKILL.md | 137 ++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 skills/accessibility/SKILL.md

diff --git a/skills/accessibility/SKILL.md b/skills/accessibility/SKILL.md
new file mode 100644
index 00000000..862e71f2
--- /dev/null
+++ b/skills/accessibility/SKILL.md
@@ -0,0 +1,137 @@
+---
+name: accessibility
+description: Design, implement, and audit inclusive digital products using WCAG 2.2 Level AA
+  standards. Use this skill to generate semantic ARIA for Web and accessibility traits for Web and Native platforms (iOS/Android).
+origin: ECC
+---
+
+# Accessibility (WCAG 2.2)
+
+This skill ensures that digital interfaces are Perceivable, Operable, Understandable, and Robust (POUR) for all users, including those using screen readers, switch controls, or keyboard navigation. It focuses on the technical implementation of WCAG 2.2 success criteria.
+
+## When to Activate
+
+- Defining UI component specifications for Web, iOS, or Android.
+- Auditing existing code for accessibility barriers or compliance gaps.
+- Implementing new WCAG 2.2 standards like Target Size (Minimum) and Focus Appearance.
+- Mapping high-level design requirements to technical attributes (ARIA roles, traits, hints).
+
+## Core Concepts
+
+- **POUR Principles**: The foundation of WCAG (Perceivable, Operable, Understandable, Robust).
+- **Semantic Mapping**: Using native elements over generic containers to provide built-in accessibility.
+- **Accessibility Tree**: The representation of the UI that assistive technologies actually "read."
+- **Focus Management**: Controlling the order and visibility of the keyboard/screen reader cursor.
+- **Labeling & Hints**: Providing context through `aria-label`, `accessibilityLabel`, and `contentDescription`.
+
+## How It Works
+
+### Step 1: Identify the Component Role
+
+Determine the functional purpose (e.g., Is this a button, a link, or a tab?). Use the most semantic native element available before resorting to custom roles.
+
+### Step 2: Define Perceivable Attributes
+
+- Ensure text contrast meets **4.5:1** (normal) or **3:1** (large/UI).
+- Add text alternatives for non-text content (images, icons).
+- Implement responsive reflow (up to 400% zoom without loss of function).
+
+### Step 3: Implement Operable Controls
+
+- Ensure a minimum **24x24 CSS pixel** target size (WCAG 2.2 SC 2.5.8).
+- Verify all interactive elements are reachable via keyboard and have a visible focus indicator (SC 2.4.11).
+- Provide single-pointer alternatives for dragging movements.
+
+### Step 4: Ensure Understandable Logic
+
+- Use consistent navigation patterns.
+- Provide descriptive error messages and suggestions for correction (SC 3.3.3).
+- Implement "Redundant Entry" (SC 3.3.7) to prevent asking for the same data twice.
+
+### Step 5: Verify Robust Compatibility
+
+- Use correct `Name, Role, Value` patterns.
+- Implement `aria-live` or live regions for dynamic status updates.
+
+## Accessibility Architecture Diagram
+
+```mermaid
+flowchart TD
+  UI["UI Component"] --> Platform{Platform?}
+  Platform -->|Web| ARIA["WAI-ARIA + HTML5"]
+  Platform -->|iOS| SwiftUI["Accessibility Traits + Labels"]
+  Platform -->|Android| Compose["Semantics + ContentDesc"]
+
+  ARIA --> AT["Assistive Technology (Screen Readers, Switches)"]
+  SwiftUI --> AT
+  Compose --> AT
+```
+
+## Cross-Platform Mapping
+
+| Feature            | Web (HTML/ARIA)          | iOS (SwiftUI)                        | Android (Compose)                                           |
+| :----------------- | :----------------------- | :----------------------------------- | :---------------------------------------------------------- |
+| **Primary Label**  | `aria-label` / `<label>` | `.accessibilityLabel()`              | `contentDescription`                                        |
+| **Secondary Hint** | `aria-describedby`       | `.accessibilityHint()`               | `Modifier.semantics { stateDescription = ... }`             |
+| **Action Role**    | `role="button"`          | `.accessibilityAddTraits(.isButton)` | `Modifier.semantics { role = Role.Button }`                 |
+| **Live Updates**   | `aria-live="polite"`     | `.accessibilityLiveRegion(.polite)`  | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` |
+
+## Implementation Examples
+
+### Web: Accessible Search
+
+```html
+<form role="search">
+  <label for="search-input" class="sr-only">Search products</label>
+  <input type="search" id="search-input" placeholder="Search..." />
+  <button type="submit" aria-label="Submit Search">
+    <svg aria-hidden="true">...</svg>
+  </button>
+</form>
+```
+
+### iOS: Accessible Action Button
+
+```swift
+Button(action: deleteItem) {
+    Image(systemName: "trash")
+}
+.accessibilityLabel("Delete item")
+.accessibilityHint("Permanently removes this item from your list")
+.accessibilityAddTraits(.isButton)
+```
+
+### Android: Accessible Toggle
+
+```kotlin
+Switch(
+    checked = isEnabled,
+    onCheckedChange = { onToggle() },
+    modifier = Modifier.semantics {
+        contentDescription = "Enable notifications"
+    }
+)
+```
+
+## Anti-Patterns to Avoid
+
+- **Div-Buttons**: Using a `<div>` or `<span>` for a click event without adding a role and keyboard support.
+- **Color-Only Meaning**: Indicating an error or status _only_ with a color change (e.g., turning a border red).
+- **Infinite Tab Loops**: Modals that don't trap focus, allowing users to "escape" into the background content while the modal is open.
+- **Redundant Alt Text**: Using "Image of..." or "Picture of..." in alt text (screen readers already announce the role "Image").
+
+## Best Practices Checklist
+
+- [ ] Interactive elements meet the **24x24px** (Web) or **44x44pt** (Native) target size.
+- [ ] Focus indicators are clearly visible and high-contrast.
+- [ ] No "Keyboard Traps" exist in complex components (modals, dropdowns).
+- [ ] Forms provide text-based error suggestions.
+- [ ] All icon-only buttons have a descriptive text label.
+- [ ] Content reflows properly when text is scaled.
+
+## References
+
+- [WCAG 2.2 Guidelines](https://www.w3.org/TR/WCAG22/)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/)
+- [iOS Accessibility Programming Guide](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/iPhoneAccessibility/Introduction/Introduction.html)
+- [Android Accessibility Developer Guide](https://developer.android.com/guide/topics/ui/accessibility)

From 643d03575ae5fbb86692c92ef7c329bda847c621 Mon Sep 17 00:00:00 2001
From: Balaji Guntur <59932973+gnpthbalaji@users.noreply.github.com>
Date: Sat, 11 Apr 2026 12:58:21 -0700
Subject: [PATCH 3/8] Update the accessibility skill to include related skills

---
 skills/accessibility/SKILL.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/skills/accessibility/SKILL.md b/skills/accessibility/SKILL.md
index 862e71f2..bf81fc57 100644
--- a/skills/accessibility/SKILL.md
+++ b/skills/accessibility/SKILL.md
@@ -135,3 +135,10 @@ Switch(
 - [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/)
 - [iOS Accessibility Programming Guide](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/iPhoneAccessibility/Introduction/Introduction.html)
 - [Android Accessibility Developer Guide](https://developer.android.com/guide/topics/ui/accessibility)
+
+## Related Skills
+
+- `frontend-patterns`
+- `frontend-design`
+- `liquid-glass-design`
+- `swiftui-patterns`

From 228be4f8b8f3bf51544a4ada3d39c31790ffce36 Mon Sep 17 00:00:00 2001
From: Balaji Guntur <59932973+gnpthbalaji@users.noreply.github.com>
Date: Sat, 11 Apr 2026 13:16:13 -0700
Subject: [PATCH 4/8] renamed the inclusive-ui-agent to a11y-architect

---
 agents/{inclusive-ui-agent.md => a11y-architect.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename agents/{inclusive-ui-agent.md => a11y-architect.md} (100%)

diff --git a/agents/inclusive-ui-agent.md b/agents/a11y-architect.md
similarity index 100%
rename from agents/inclusive-ui-agent.md
rename to agents/a11y-architect.md

From 33673fb37a473e7f85b5f97ada85366176a8b058 Mon Sep 17 00:00:00 2001
From: Balaji Guntur <59932973+gnpthbalaji@users.noreply.github.com>
Date: Sat, 11 Apr 2026 13:33:17 -0700
Subject: [PATCH 5/8] Fix PR comments - renamed 'when to activate' to 'when to
 use', fixed the iOS reference link to current, added iOS HIG link

---
 skills/accessibility/SKILL.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/skills/accessibility/SKILL.md b/skills/accessibility/SKILL.md
index bf81fc57..2f46136a 100644
--- a/skills/accessibility/SKILL.md
+++ b/skills/accessibility/SKILL.md
@@ -9,7 +9,7 @@ origin: ECC
 
 This skill ensures that digital interfaces are Perceivable, Operable, Understandable, and Robust (POUR) for all users, including those using screen readers, switch controls, or keyboard navigation. It focuses on the technical implementation of WCAG 2.2 success criteria.
 
-## When to Activate
+## When to Use
 
 - Defining UI component specifications for Web, iOS, or Android.
 - Auditing existing code for accessibility barriers or compliance gaps.
@@ -76,7 +76,7 @@ flowchart TD
 | **Action Role**    | `role="button"`          | `.accessibilityAddTraits(.isButton)` | `Modifier.semantics { role = Role.Button }`                 |
 | **Live Updates**   | `aria-live="polite"`     | `.accessibilityLiveRegion(.polite)`  | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` |
 
-## Implementation Examples
+## Examples
 
 ### Web: Accessible Search
 
@@ -133,7 +133,8 @@ Switch(
 
 - [WCAG 2.2 Guidelines](https://www.w3.org/TR/WCAG22/)
 - [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/)
-- [iOS Accessibility Programming Guide](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/iPhoneAccessibility/Introduction/Introduction.html)
+- [iOS Accessibility Programming Guide](https://developer.apple.com/documentation/accessibility)
+- [iOS Human Interface Guidelines - Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility)
 - [Android Accessibility Developer Guide](https://developer.android.com/guide/topics/ui/accessibility)
 
 ## Related Skills

From 51abaf0fc03abd1d2783098642ff7290bd94808f Mon Sep 17 00:00:00 2001
From: Balaji Guntur <59932973+gnpthbalaji@users.noreply.github.com>
Date: Sat, 11 Apr 2026 20:30:47 -0700
Subject: [PATCH 6/8] fix: correct accessibility terminology and code fence in
 a11y skill and agent

- Fix inverted focus trap terms: Keyboard Traps -> Uncontained Modal Focus with WCAG SC 2.1.2 reference
- Fix Step 1 blocker example: missing keyboard traps -> missing focus containment in modals
- Attach [language] placeholder to opening triple-backtick fence in agent implementation template
---
 agents/a11y-architect.md      | 11 ++++++-----
 skills/accessibility/SKILL.md |  5 +++--
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/agents/a11y-architect.md b/agents/a11y-architect.md
index c5793317..cd00b806 100644
--- a/agents/a11y-architect.md
+++ b/agents/a11y-architect.md
@@ -20,7 +20,7 @@ You are a Senior Accessibility Architect. Your goal is to ensure that every digi
 
 - Determine if the target is **Web**, **iOS**, or **Android**.
 - Analyze the user interaction (e.g., Is this a simple button or a complex data grid?).
-- Identify potential accessibility "blockers" (e.g., color-only indicators, missing keyboard traps).
+- Identify potential accessibility "blockers" (e.g., color-only indicators, missing focus containment in modals).
 
 ### Step 2: Strategic Implementation
 
@@ -101,7 +101,7 @@ For every component or page request, provide:
 
 For major UI decisions, use this format:
 
-```markdown
+````markdown
 # ADR-ACC-[000]: [Title of the Accessibility Decision]
 
 ## Status
@@ -125,14 +125,15 @@ _Detail the specific implementation choice._
 
 ### Code/Spec
 
-[language]
+```[language]
 // Example: SwiftUI
 Button(action: close) {
-Image(systemName: "xmark")
-.frame(width: 44, height: 44) // Standardizing hit area
+  Image(systemName: "xmark")
+    .frame(width: 44, height: 44) // Standardizing hit area
 }
 .accessibilityLabel("Close modal")
 ```
+````
 
 ## Reference
 
diff --git a/skills/accessibility/SKILL.md b/skills/accessibility/SKILL.md
index 2f46136a..c9021041 100644
--- a/skills/accessibility/SKILL.md
+++ b/skills/accessibility/SKILL.md
@@ -117,14 +117,15 @@ Switch(
 
 - **Div-Buttons**: Using a `<div>` or `<span>` for a click event without adding a role and keyboard support.
 - **Color-Only Meaning**: Indicating an error or status _only_ with a color change (e.g., turning a border red).
-- **Infinite Tab Loops**: Modals that don't trap focus, allowing users to "escape" into the background content while the modal is open.
+- **Uncontained Modal Focus**: Modals that don't trap focus, allowing keyboard users to navigate background content while the modal is open. Focus must be contained _and_ escapable via the `Escape` key or an explicit close button (WCAG SC 2.1.2).
 - **Redundant Alt Text**: Using "Image of..." or "Picture of..." in alt text (screen readers already announce the role "Image").
 
 ## Best Practices Checklist
 
 - [ ] Interactive elements meet the **24x24px** (Web) or **44x44pt** (Native) target size.
 - [ ] Focus indicators are clearly visible and high-contrast.
-- [ ] No "Keyboard Traps" exist in complex components (modals, dropdowns).
+- [ ] Modals **contain focus** while open, and release it cleanly on close (`Escape` key or close button).
+- [ ] Dropdowns and menus restore focus to the trigger element on close.
 - [ ] Forms provide text-based error suggestions.
 - [ ] All icon-only buttons have a descriptive text label.
 - [ ] Content reflows properly when text is scaled.

From 2d044b8032946e9b637fc0c59bf1f2b2a2588b11 Mon Sep 17 00:00:00 2001
From: GB <59932973+gnpthbalaji@users.noreply.github.com>
Date: Sat, 11 Apr 2026 22:12:15 -0700
Subject: [PATCH 7/8] Apply suggestion from @greptile-apps[bot]

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---
 agents/a11y-architect.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/agents/a11y-architect.md b/agents/a11y-architect.md
index cd00b806..7e45e605 100644
--- a/agents/a11y-architect.md
+++ b/agents/a11y-architect.md
@@ -2,7 +2,7 @@
 name: a11y-architect
 description: Accessibility Architect specializing in WCAG 2.2 compliance for Web and Native platforms. Use PROACTIVELY when designing UI components, establishing design systems, or auditing code for inclusive user experiences.
 tools: ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob']
-model: sonnet
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
 ---
 
 You are a Senior Accessibility Architect. Your goal is to ensure that every digital product is Perceivable, Operable, Understandable, and Robust (POUR) for all users, including those with visual, auditory, motor, or cognitive disabilities.

From 7f7e2c2c52bff7ac80c0691ce917c8436babb770 Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Mon, 13 Apr 2026 00:51:40 -0700
Subject: [PATCH 8/8] fix: remove duplicate tools frontmatter key

---
 agents/a11y-architect.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/agents/a11y-architect.md b/agents/a11y-architect.md
index 7e45e605..7ef2e517 100644
--- a/agents/a11y-architect.md
+++ b/agents/a11y-architect.md
@@ -1,7 +1,6 @@
 ---
 name: a11y-architect
 description: Accessibility Architect specializing in WCAG 2.2 compliance for Web and Native platforms. Use PROACTIVELY when designing UI components, establishing design systems, or auditing code for inclusive user experiences.
-tools: ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob']
 tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
 ---