Skip to content

🧠 Accessibility Engineer Agent Specification

🎯 Purpose

The Accessibility Engineer Agent (AEA) ensures that every frontend UI component generated by the ConnectSoft AI Software Factory is:

  • ✅ Compliant with accessibility standards (e.g. WCAG 2.1 AA)
  • ✅ Usable by all users, including those relying on assistive technologies
  • ✅ Auditable through reports and trace-linked annotations
  • ✅ Enhanced with accessibility-first markup and design overlays

It does not merely lint code — it actively collaborates to build inclusive user experiences from the very first generation step.

🧭 Strategic Position in the Platform

The agent operates in both:

  • 🔍 Verification Mode: Audits templates for compliance, flags violations, and blocks merges or releases if needed.
  • 🛠 Implementation Mode: Injects ARIA roles, semantic structure, and keyboard navigation improvements — modifying UI artifacts or suggesting fixes.

🧠 Dual Mode Model: Verifier + Implementer

Mode Capabilities
✅ Verifier Runs a11y linting, contrast checks, keyboard tab sequence validation, emits a11y-lint-results.json, and blocks critical issues.
🧠 Implementer Injects roles, restructures HTML, enhances templates with accessible variants, and co-generates improved outputs with Frontend Developer Agent.

🧩 Role in the Factory Flow

flowchart TD
    T[UI Template Generator] --> F[Frontend Developer Agent]
    F --> A[Accessibility Engineer Agent]
    A --> F
    A --> QA
    A --> Studio

    click F "agents/detailed-agent-specifications/frontend-developer-agent.md"
Hold "Alt" / "Option" to enable pan & zoom
  • 🧱 UI is generated
  • 🧪 AEA validates it
  • 🛠 If needed, AEA fixes or enhances the markup
  • 🧩 QA and Studio receive trace-linked reports and feedback

🔁 Trigger Points

AEA is activated:

  • Automatically after UI templates are generated
  • When a pull request is created involving frontend components
  • On Studio request (“Check accessibility”)
  • Before production release if a11yRequired: true

🧬 Example Mission Statement

“Given a generated UI component, the Accessibility Engineer Agent evaluates its structure against WCAG 2.1 AA guidelines, improves semantic clarity, and ensures it can be used with screen readers, keyboard-only navigation, and high-contrast themes. It outputs annotated files, Studio reports, and optionally replaces the original markup with an a11y-enhanced version.”

✅ Summary

The Accessibility Engineer Agent is both:

  • 🧠 A guardrail against inaccessible UI
  • 🛠 A builder of inclusive experiences
  • 🤝 A collaborator with UI and QA agents
  • 📘 A documentation-aware contributor that makes accessibility visible in trace reports and Studio

📋 Responsibilities

The Accessibility Engineer Agent (AEA) is responsible for both validating and enhancing accessibility in all frontend outputs generated by the factory. It operates under two execution modes — Verifier and Implementer — and produces actionable outputs for Studio, QA, and Frontend agents.

✅ Verifier Responsibilities

Task Description
🔍 Run a11y Lint Checks Execute accessibility checkers (e.g., axe-core, WCAG validators) on HTML, Blazor, Angular templates.
🧾 Emit Violation Reports Output structured artifacts like a11y-lint-results.json, violations.md, and inline annotations.
📊 Assess Compliance Level Calculate total violations, WCAG compliance tier, contrast ratios, ARIA role coverage.
🧠 Annotate Trace Write accessibility status and summaries to trace metadata.
🛑 Block Merge or Release if Critical Signal Release Manager or Studio gate if blocking a11y issues are detected.

🧠 Implementer Responsibilities

Task Description
🛠 Refactor Components for Accessibility Modify templates to add ARIA roles, semantic tags, keyboard navigation enhancements.
🎨 Apply Contrast Tokens Replace color tokens or inline styles with high-contrast compliant variants.
↔️ Collaborate with FEA Request component regeneration or suggest enhancements if semantic clarity is missing.
🔁 Generate Accessible Variants Store corrected or enhanced templates as accessible versions in shared libraries.
⚙️ Autofix or Suggest Fixes Use skills like InjectSkipLinks, FixTabOrder, ImproveLabeling to programmatically improve markup.

📘 Shared Deliverables

Output Purpose
a11y-lint-results.json Machine-readable audit of violations per component.
violations.md Developer-readable summary with suggestions and WCAG mapping.
AccessibleComponent.html Enhanced UI template post-rewrite.
a11y-score.json Summary rating per module (A, AA, AAA compliance levels).
accessibility-annotations.yaml Traceable memory file for Studio display and approval logic.

🧩 Inter-Agent Collaboration Responsibilities

Target Agent Responsibility
Frontend Developer Agent Collaborate on semantic enhancements or regenerated variants.
QA Agents Feed violation data into visual test automation and usability validation.
Release Manager Agent Emit blocking signal if critical a11y rules are broken.
Studio Trace UI Provide inline annotations and allow Studio users to view, override, or accept fixes.

🧠 Example Trigger + Output Chain

Trigger: PullRequestCreated (with UI templates)

→ AEA runs `RunA11yAudit`
→ Violations found: 3 missing labels, 1 contrast failure
→ Generates: `a11y-lint-results.json`, `AccessibleHeader.html`
→ Annotates: Studio timeline and blocks trace merge
→ Suggests: FEA regenerate layout with `<nav>` + ARIA role

✅ Summary

The Accessibility Engineer Agent ensures ConnectSoft’s frontend UIs:

  • ✅ Meet required accessibility standards
  • ✅ Automatically fix common WCAG and ARIA issues
  • ✅ Collaborate with generation agents to improve output
  • ✅ Block regressions and support inclusion by default

📥 Inputs

The Accessibility Engineer Agent (AEA) ingests a rich set of inputs across markup artifacts, trace metadata, and design constraints. These inputs enable it to verify, enhance, and trace accessibility across UI components for all tenants and environments.

📦 Primary Input Types

Input Type Description
🧱 Generated UI Component Files HTML, Razor, Blazor, or Angular templates representing the current UI being evaluated.
📘 Trace Context Metadata traceId, moduleId, environment, tenantId, UI type, and execution context (e.g., PR vs Release).
📐 Design Token Libraries Access to color palettes, spacing, contrast definitions, and theme variables used in the component.
🧠 Template Generator Output Structural blueprint used to generate the current component (for diffing or re-templating).
🔁 Previous a11y Results (optional) Past run’s a11y-lint-results.json for delta comparisons, regression detection.
📥 User Action Trigger (optional) Studio command: “Run a11y check,” or CLI-based request to validate template manually.

🔎 Input File Examples

1. HTML Template Input (raw)

<header class="site-header">
  <h1>Welcome</h1>
  <nav>
    <ul><li><a href="/">Home</a></li></ul>
  </nav>
</header>

2. Trace Context

traceId: trace-2025-05-23-1181
moduleId: site-header
environment: staging
tenantId: vetclinic-001
uiType: Blazor
mode: verifier

3. Design Token Map

{
  "primaryColor": "#FFFFFF",
  "secondaryColor": "#0A0A0A",
  "fontSize": "16px",
  "contrastThreshold": 4.5
}

📘 Optional Enrichments

Input Use
StudioUserNotes.md Human feedback about previous UI accessibility concerns
ComponentUsageStats.json Prioritize validation if high user exposure (e.g., homepage, login)
ApprovedExceptions.yaml Mark known violations (e.g., legacy overrides) as suppressed but traceable

⚠️ Validation Trigger Scenarios

Trigger Input Pattern
Post-code generation Receives new *.html, *.razor, or *.component.ts file with traceId
Pull Request created PR contains changes to files under templates/ui/
Studio manual request Trace state: "manualValidationRequested: true"
Production release request AEA is required to validate before ReleaseApproved can emit

✅ Summary

AEA is activated by a combination of file-level changes, trace context, Studio interactions, and lifecycle state. Its inputs provide the foundation for:

  • Linting
  • Template rewrites
  • Accessibility scoring
  • Studio annotations

All of which ensure inclusive, accessible, and compliant UIs are always part of the delivery flow.

📤 Outputs

The Accessibility Engineer Agent (AEA) generates outputs that serve multiple audiences:

  • 🧪 Developers: detailed feedback and auto-fixed variants
  • 📘 Studio: trace annotations and merge gating signals
  • 🛡 QA/Compliance: audit-ready a11y summaries
  • 🔁 Other Agents: collaboration signals for FEA, Release Manager, or QA cluster

Outputs are trace-linked, structured, and support both human review and machine gating.

📄 Core Output Artifacts

Output File Description
a11y-lint-results.json Full JSON audit of detected accessibility violations with severity, location, and suggestions.
violations.md Human-readable report for Studio or PR comment summarizing issues, compliance level, and suggested actions.
AccessibleComponent.html (or .razor, .ts) Auto-fixed or enhanced version of the input file, rewritten with better ARIA, tab order, roles, or contrast fixes.
a11y-score.json Summary score per component/module, including total violations, severity distribution, pass/fail status.
accessibility-annotations.yaml Trace-linked feedback block for Studio display (timeline item, block merge button, etc.).
AccessibilityFixPlan.yaml (optional) Structured instructions to Frontend Developer Agent when human regeneration is preferred over direct injection.

📘 Example: a11y-lint-results.json

{
  "traceId": "trace-2025-05-23-0012",
  "moduleId": "appointment-form",
  "violations": [
    {
      "ruleId": "label-visibility",
      "selector": "input#email",
      "severity": "critical",
      "message": "Form input must have visible label."
    },
    {
      "ruleId": "contrast-ratio",
      "selector": ".text-muted",
      "severity": "moderate",
      "contrastRatio": 2.8,
      "requiredRatio": 4.5
    }
  ]
}

📘 Example: violations.md

## Accessibility Violations – appointment-form

🔴 Critical: Missing visible label on `#email`
🟡 Moderate: Low contrast (2.8:1) on `.text-muted` – expected ≥ 4.5:1

**WCAG Tier:** Fails WCAG 2.1 AA

🛠 Suggested Fix:
- Add `<label for="email">Email</label>`
- Replace `#999999` with higher-contrast token

📄 Example: AccessibleComponent.html

<label for="email" class="sr-only">Email</label>
<input id="email" name="email" aria-required="true" />

Automatically rewritten or augmented component, optionally written to shared template repo.

🧠 Trace Memory Annotations

AEA annotates the trace with a block like:

traceId: trace-2025-05-23-0012
component: appointment-form
a11yStatus: blocked
violations: 2
score: 68
autoFixable: true
studioSummary: "2 issues found (1 critical), fix applied to input field"

This drives Studio merge/release gating and timeline updates.

🚦 Signal Emissions (Internal)

Signal Consumer Description
AccessibilityCheckPassed Release Manager Agent All checks passed or justified, safe to continue
AccessibilityCheckFailed Studio UI, QA Agent Merge/release must be paused; issues reported
FixPlanIssued Frontend Developer Agent Regeneration required to solve layout or structure-level violations

✅ Summary

The Accessibility Engineer Agent emits:

  • ⚙️ Structured reports
  • 🛠 Auto-corrected components
  • 📘 Studio annotations
  • 🚦 Policy enforcement signals

This ensures accessibility isn’t just scanned — it’s corrected, traceable, and embedded into the delivery lifecycle.

📚 Knowledge Base

The Accessibility Engineer Agent (AEA) is powered by a deep and structured internal knowledge base designed to:

  • Apply WCAG 2.1 AA compliance rigor
  • Evaluate ARIA roles, semantic markup, tab order, and contrast
  • Inject fixes and enhancements based on a11y heuristics and reusable templates
  • Recommend best practices for accessible frontend development

This knowledge is both rule-driven and template-aware, supporting deterministic validation and auto-repair workflows.

🧠 Embedded Rule Engines

Rule Set Description
WCAG 2.1 AA Full checklist of accessibility guidelines including contrast ratio, focus order, labeling, landmark regions, alt attributes.
ARIA Practices Pattern-based roles and attributes for regions, controls, inputs, dialogs, navigation, and screen reader compatibility.
Keyboard Navigation Patterns Expected behavior for tab/arrow keys, skip links, focus management.
Contrast Ratio Calculations Color token diff engine that uses luminance calculations to ensure contrast thresholds.
Landmark Semantics Recognition and validation of <nav>, <header>, <main>, <aside>, and expected roles for structure clarity.

📘 Agent Heuristics and Recommendations

Pattern AEA Behavior
input without <label> Insert <label for="...">, recommend aria-label fallback if label can't be visible
Low-contrast span or class Replace with --a11y-contrast-token, suggest a mapped semantic tone
Non-interactive div with onclick Refactor to button or add role="button" and tabindex="0"
Missing heading levels (e.g., skipping h1 → h3) Insert heading scaffolding or report heading structure violations
Empty alt="" on functional images Flag unless decorative; suggest descriptive alt text
Missing skip links in page template Inject <a href="#main" class="skip-link">Skip to content</a> in AccessibleComponent.html

🔖 Design Token Compatibility

Data Source Description
contrast-tokens.json Pre-calculated WCAG-compliant design token pairs
theme-mapping.yaml Token → color → contrast mapping
a11y-token-aliases.json Overrides or substitutions used during auto-correction

This allows AEA to rewrite styles or classes without breaking visual design fidelity.

🧠 Knowledge of Studio and Developer Expectations

Behavior Reason
Markdown report formatting Makes violation summaries friendly for pull request comments and Studio views
Justification annotations Adds rule reference (WCAG-2.1.1.3) to every reported violation
Trace memory summaries Maps a11y results to merge/release blocks using compliance tiering (pass/warn/block)

🧠 Shared Libraries

Asset Purpose
AccessibleTemplateVariants/ Prefabricated components with ARIA and keyboard enhancements
FixSnippets.json Common rule → fix patterns (e.g., “missing label” → label-for injection)
AutoFixPriorities.yaml Config for when to fix, when to defer, and when to escalate

✅ Summary

The Accessibility Engineer Agent draws from a rich, structured knowledge base that includes:

  • 📘 WCAG and ARIA specifications
  • 🧩 Semantic heuristics and fix patterns
  • 🎨 Contrast rules and token mappings
  • 📂 Prefabricated accessible component templates

This ensures AEA can understand, validate, explain, and repair UI accessibility gaps with precision and consistency.

🔍 Process Flow – Validation Mode

In Validation Mode, the Accessibility Engineer Agent (AEA) acts as a gatekeeper, ensuring that all frontend components meet minimum accessibility standards. It analyzes UI structure, detects violations, annotates results, and triggers Studio/QA feedback or blocks further delivery if needed.

🔁 High-Level Execution Flow (Verifier)

flowchart TD
    A[📥 Receive UI Template + Trace Context] --> B[🧪 Run a11y Linter (axe-core, WCAG rules)]
    B --> C[🧠 Analyze Violations by Severity]
    C --> D[📝 Generate Reports (JSON, Markdown)]
    D --> E{🚦 Block Required?}
    E -- Yes --> F[❌ Emit AccessibilityCheckFailed]
    E -- No --> G[✅ Emit AccessibilityCheckPassed]
    F --> H[📄 Write Violation Annotations to Memory]
    G --> H
    H --> I[📘 Annotate Studio Timeline + Feedback Pane]
Hold "Alt" / "Option" to enable pan & zoom

🔬 Detailed Step Breakdown

Step Description
A. Receive Input Reads UI markup (*.html, .razor, .ts) and traceId, moduleId, uiType.
B. Run Linter Applies automated validators like axe-core, HTMLCodeSniffer, WCAG.js, and custom rules.
C. Analyze Violations Classifies issues as critical, moderate, low, and maps to WCAG/ARIA rule IDs.
D. Generate Reports Produces a11y-lint-results.json, violations.md, a11y-score.json.
E. Check Gate Logic If critical violations exist, triggers AccessibilityCheckFailed; otherwise, emits AccessibilityCheckPassed.
F/G. Emit Result Event These signals are picked up by Release Manager Agent, QA agents, and Studio.
H. Write Memory Files All reports stored under /memory/trace-{id}/a11y/.
I. Update Studio Trace View Studio displays pass/fail banner, highlights critical selectors, and shows diff-based fixes (if available).

🧠 Sample Trigger → Result Chain

Trigger: PullRequestCreated → UI component file detected in diff Actions:

  • AEA invoked in Validation Mode
  • Runs validator suite
  • Finds missing label and contrast failure
  • Outputs:
    • ✅ a11y-lint-results.json
    • 📝 violations.md
    • 🚦 AccessibilityCheckFailed (blocks Release FSM)
    • 🧠 Writes to accessibility-annotations.yaml
    • 📘 Studio shows red a11y badge

⚠️ Validation Decision Logic

Criteria Decision
≥ 1 Critical issue Block release or merge
Only Warnings Pass, but emit violations.md and notify QA
No issues Pass silently, optional Studio log

✅ Summary

The Validation Mode ensures that:

  • Accessibility issues are caught early
  • Compliance is enforced consistently across tenants
  • Developers and Studio users see clear, structured feedback
  • Delivery is blocked or delayed until accessibility is brought up to standard

It makes AEA a first-class gatekeeper of inclusiveness and usability.

🛠 Process Flow (Implementation Mode)

In Implementation Mode, the Accessibility Engineer Agent (AEA) goes beyond validation — it actively enhances UI components by:

  • Injecting semantic ARIA roles
  • Rewriting markup for screen readers
  • Refactoring structure for keyboard/tab navigation
  • Replacing low-contrast elements with compliant design tokens

AEA becomes a co-creator alongside the Frontend Developer Agent (FEA), building accessible-by-default components.

🔁 High-Level Execution Flow (Implementer)

flowchart TD
    A[📥 Receive UI Template + Trace Context] --> B[🧪 Run Validation First]
    B --> C{⚠️ Fixes Needed?}
    C -- No --> Z[✅ Exit – Already Compliant]
    C -- Yes --> D[📐 Parse Semantic Structure]
    D --> E[🧠 Apply A11y Enhancements]
    E --> F[✏️ Rewrite Template]
    F --> G[💾 Save Accessible Variant (memory/shared library)]
    G --> H[📘 Annotate Studio + Notify FEA]
Hold "Alt" / "Option" to enable pan & zoom

🔬 Step-by-Step Breakdown

Step Description
A. Input UI component markup + traceId, moduleId, uiType, and fix mode flag
B. Initial Validation Uses RunAccessibilityAudit to determine if rewriting is necessary
C. Decision If no violations found → exit; otherwise → enhance
D. Semantic Parsing Uses DOM traversal + pattern matching to detect landmarks, controls, and tab-index flow
E. Enhancement Application Adds ARIA attributes, skip links, contrast tokens, keyboard accessibility features
F. Template Rewrite Generates AccessibleComponent.html or updated .razor or .ts component
G. Output Write Saves enhanced template to memory + optionally updates the shared component template library
H. Feedback Loop Notifies Frontend Developer Agent (FEA) via FixPlanIssued, annotates Studio view with before/after diff

🧩 Example Transformation

Before (insecure contrast + missing ARIA):

<button style="color:#aaa">Checkout</button>

After:

<button style="color:#000" role="button" aria-label="Proceed to Checkout">Checkout</button>

🛠 Skills Used in This Mode

  • InjectAriaAttributes
  • RefactorTabOrder
  • ReplaceLowContrastTokens
  • GenerateAccessibleVariant
  • FixHeadingStructure
  • SuggestLabelOverlays

🧠 Sample Memory Output

AccessibleComponent.html: true
violationsResolved: 3
componentRefactored: appointment-form
fixMode: auto
originalIssues: [missing-label, low-contrast, unstructured-nav]
savedAt: 2025-05-23T11:02:12Z

🤝 Collaboration Hooks

  • 🔄 Optionally writes FixPlan.yaml for FEA to regenerate instead of auto-rewrite
  • 🧠 Studio displays before/after diff
  • ✅ Release Manager Agent receives updated a11y-lint-results.json after rewrite
  • QA Agents retest enhanced templates via test generators

✅ Summary

In Implementation Mode, AEA:

  • Doesn’t just point at problems — it solves them
  • Co-builds inclusive templates with reusable improvements
  • Ensures accessible design is embedded at the source
  • Enhances developer efficiency and product usability at scale

It elevates the AI Factory’s accessibility from “passive compliance” to proactive, inclusive design.

🤝 Collaboration Interfaces

The Accessibility Engineer Agent (AEA) does not operate in isolation. It’s deeply embedded in the UI generation, review, QA, and release pipeline. Its value multiplies when it talks to other agents, especially the:

  • 🎨 Frontend Developer Agent (FEA)
  • 🔁 UI Template Generator Agent
  • 🧪 QA Validation Agents
  • 📘 Studio Feedback View
  • 🛡 Release Manager Agent

This cycle defines AEA’s interface boundaries, signals, and feedback paths across agents and human touchpoints.

🔄 Collaboration Diagram

flowchart TD
    T[UI Template Generator Agent] --> F[Frontend Developer Agent]
    F --> A[Accessibility Engineer Agent]
    A --> F
    A --> Studio
    A --> QA[QA Cluster]
    A --> RM[Release Manager Agent]
    A --> TemplateLib[Shared Template Library]

    click F "agents/detailed-agent-specifications/frontend-developer-agent.md"
    click RM "agents/detailed-agent-specifications/release-manager-agent.md"
Hold "Alt" / "Option" to enable pan & zoom

🤝 Agent Interfaces

Target Agent Interaction Type Purpose
Frontend Developer Agent 🔁 Bidirectional Receives accessibility issues or enhancement requests; can receive enhanced templates or fix plans
UI Template Generator Agent 🔍 Passive AEA reads base templates to understand variant structure; optionally injects accessibility overlays
QA Agents 📡 Unidirectional QA cluster receives a11y violation results to influence visual test paths or usability simulations
Release Manager Agent ✅ Critical Gate AEA sends pass/fail signal (AccessibilityCheckPassed or Failed) that can block merge or deployment
Studio UI / Trace View 🖥 Human Interface Studio renders: timeline annotations, issue summaries, fix diffs, compliance scores
Shared Template Library 📁 Write Access AEA contributes accessible variants of templates that are reused across modules/tenants

🧠 Collaboration Events

Event Sender Receiver Description
AccessibilityCheckFailed AEA Studio, Release Manager Block merge or release, display feedback
FixPlanIssued AEA FEA Suggest regeneration for unfixable markup
AccessibleComponentSaved AEA Template Library Share fixed template for reuse
A11yLintResultsGenerated AEA QA Cluster QA can prioritize visual tests around a11y violations
StudioFeedbackAnnotated AEA Studio UI Annotated UI preview with failure locations and fixes shown in trace timeline

🧩 Collaboration Format Examples

Fix Plan to FEA

moduleId: booking-form
violations: ["missing-label", "tab-order", "low-contrast"]
preferredFixMode: regenerate
recommendation: "Use FormWithLabels.v2"

Release Approval Hook

{
  "traceId": "trace-2025-05-23-0192",
  "a11yStatus": "blocked",
  "violations": 4,
  "approved": false
}

🧬 Diff & Review Cycle

If AEA rewrites a template:

  • ✅ Studio user can preview diff
  • 🔁 FEA can comment, reject, or accept the fix plan
  • 🧪 QA reruns snapshot and screen reader tests with enhanced variant
  • 🛑 Release Manager only approves if critical violations are cleared

✅ Summary

The Accessibility Engineer Agent is:

  • A collaborative enforcer with FEA
  • A signal generator for QA, Studio, and release agents
  • A co-creator of accessibility-first UI libraries
  • A Studio-integrated assistant with before/after previews, justification flows, and merge-blocking authority

This makes AEA a connective agent — not a silo — in delivering inclusive software.

⚙️ Skills and Kernel Functions

The Accessibility Engineer Agent (AEA) is not a monolithic validator — it is composed of modular, reusable, and prompt-driven skills that allow it to:

  • Validate templates at scale
  • Modify markup with precision
  • Collaborate using structured plans
  • Generate reports and Studio annotations

This cycle defines the Semantic Kernel skills and functions that power AEA’s internal logic.

🧩 Core Kernel Skills

Skill Name Description
RunAccessibilityAudit Executes full WCAG 2.1 AA audit on HTML/Blazor/Angular markup using axe-core or equivalent
GenerateA11yReport Converts audit results into a11y-lint-results.json, violations.md, and a11y-score.json
InjectAriaAttributes Adds missing ARIA roles and aria-* properties to enhance screen reader compatibility
FixHeadingStructure Corrects broken or skipped heading levels (e.g., H1 → H3), generates a semantic heading tree
RefactorTabOrder Adds or reorders tabindex, ensures navigation consistency
ReplaceLowContrastTokens Substitutes non-compliant color styles with approved contrast tokens
EnhanceFormInputs Adds labels, descriptions, and required state for form elements
InjectSkipLinks Adds keyboard-accessible skip links to main regions
GenerateAccessibleVariant Builds a rewritten template version using all other enhancement skills
EmitFixPlanToFEA Formats fix suggestion YAML and sends to Frontend Developer Agent
EmitStudioAnnotations Prepares Markdown + trace-linked annotations for timeline and feedback view

🛠 Example: Skill Composition – Fixing Form Field

Composite Skill Flow:

RunAccessibilityAudit
→ if [missing-label]
→ EnhanceFormInputs
→ InjectAriaAttributes
→ GenerateAccessibleVariant
→ EmitStudioAnnotations

💡 Skill Prompt Templates

InjectAriaAttributes

Given this HTML:
<input id="email" type="text" />

Enhance it to be screen-reader accessible using proper ARIA roles and attributes.

Output:

<input id="email" type="text" aria-label="Email address" role="textbox" />

ReplaceLowContrastTokens

{
  "element": ".footer-text",
  "color": "#999999",
  "contrastWith": "#FFFFFF",
  "requiredRatio": 4.5
}

Output:

.footer-text {
  color: var(--a11y-neutral-contrast-700);
}

🔌 Skill Hosting + Execution Context

Host Purpose
Semantic Kernel Invocation engine + context memory
Azure Functions (optional) Long-running audits, queued fix plans
MCP (Model Context Protocol) Structured agent orchestration with UI pipeline trace

AEA skills are idempotent, composable, and trace-aware — so they can run in pipelines, on CLI triggers, or via Studio interactions.

✅ Summary

AEA’s skill set allows it to:

  • Validate, fix, and communicate accessibility issues modularly
  • Operate autonomously but collaborate contextually
  • Produce consistent, prompt-based a11y outcomes that scale across thousands of components

These kernel functions give AEA the agility to be both fast and compliant — across any UI framework, at any scale.

⚙️ Technology Stack

The Accessibility Engineer Agent (AEA) is built on a hybrid stack of accessibility tooling, AI-driven enhancement engines, trace orchestration infrastructure, and cloud-native execution environments. It integrates smoothly with the ConnectSoft platform using Semantic Kernel and MCP-based orchestration.

🧠 Core Platforms and Frameworks

Layer Technology Purpose
💡 AI Kernel Semantic Kernel Orchestrates skills, enables prompt chaining, integrates memory
🔍 Accessibility Engine axe-core, HTMLCodeSniffer, WCAG.js Perform WCAG 2.1 AA audits and rule-based validation
🌐 Markup Parsing Cheerio (Node), AngleSharp (.NET) Safely parse and traverse HTML/Razor for analysis and rewrite
🎨 Design Token Validator Custom contrast checker + design system token resolver Validates and replaces styles for contrast compliance
📘 Studio API Trace timeline, violation feedback, diff view Annotates Studio UI and enables merge gating
📂 Trace File Memory Azure Blob Storage Stores a11y-lint-results.json, violations.md, accessible template variants
🧭 Orchestration Layer MCP servers (https://github.com/modelcontextprotocol/servers) Handles trace state, agent registration, and event-based coordination
⏱ Event System Azure Event Grid, OpenTelemetry For triggering skills and logging metrics in response to trace/PR actions
🔧 Execution Context .NET 8 + Node.js dual-hosted runtime Supports C#-based skill execution with Node-powered a11y audit wrappers

💻 Programming Languages

Language Role
C# (.NET 8) Main agent implementation, skill wrappers, Semantic Kernel integration
TypeScript / Node.js axe-core, DOM parsing, contrast validation scripts
HTML/Blazor/Angular Input formats handled by the agent
YAML/Markdown/JSON Report generation and Studio feedback formats

📘 Memory Structure & File Outputs

Memory Type Storage Description
Trace memory Azure Blob per traceId Stores lint results, diffs, accessibility-enhanced variants
Studio annotations Azure DevOps APIs / Trace Memory Timeline events, merge blocker status, user feedback
Shared template library Blob-backed or Git-based Common accessible components injected by AEA into future generations

🔒 Security + Compliance Considerations

Feature Implementation
Role-restricted memory access Trace + tenant scoping on all file reads/writes
Signature-based report validation Signed a11y-score.json for audit trail integrity
Compliance metadata embedded in release memory Accessible compliance logs link to ReleaseManagerAgent workflows

🧠 Future Stack Enhancements

Capability Technology
Screen reader simulation testing NVDA CLI bindings, ChromeVox emulator
Mobile accessibility testing Lighthouse + Android TalkBack integration
Voice accessibility validation Integration with conversational UI heuristics

✅ Summary

The Accessibility Engineer Agent combines:

  • ✅ Proven a11y tooling (axe-core, WCAG rulesets)
  • ✅ Advanced prompt-driven skill execution (Semantic Kernel)
  • ✅ Trace-aware observability and file-backed memory
  • ✅ Cross-agent orchestration using MCP and Azure-native event infra

This technology stack enables AEA to deliver auditable, automated, and adaptive accessibility compliance at scale.

🧩 System Prompt

The System Prompt serves as the initial definition of identity, goals, constraints, and behavior for the Accessibility Engineer Agent (AEA). It establishes the agent’s operating boundaries and injects domain-specific context so that all skills and prompt-based executions are aligned to ConnectSoft standards.

This prompt is loaded once at bootstrap and governs how the agent operates in both Verifier and Implementer modes.

🧠 System Prompt — Full Text

You are the Accessibility Engineer Agent in the ConnectSoft AI Software Factory.

Your mission is to ensure that all user interfaces generated by the platform are inclusive and compliant with WCAG 2.1 AA standards.

You operate in two modes:
- Verifier: Validate accessibility rules across HTML, Razor, Angular templates.
- Implementer: Repair or enhance templates using accessibility heuristics and best practices.

You must:
- Enforce semantic structure (headers, landmarks, roles).
- Ensure proper ARIA attributes, labels, skip links, and tab navigation.
- Analyze color contrast and enforce tokenized design compliance.
- Generate audit-ready reports for trace-linked memory.
- Collaborate with the Frontend Developer Agent on regeneration or enhancement tasks.
- Annotate Studio UI timelines with violations, diffs, and compliance summaries.
- Respect trace boundaries, tenant-specific policies, and release gates.

You must never approve or emit success unless:
- All critical violations are fixed.
- All templates meet minimum compliance scoring.
- All memory and Studio annotations are correctly updated.

Do not guess. Use known patterns from accessible template variants and reuse from shared libraries when applicable.

When in doubt, escalate via Studio feedback or FixPlan to the Frontend Developer Agent.

🔎 Key Instruction Segments

Section Purpose
🎯 "Your mission..." Establishes agent's identity and domain role
⚙️ Mode-specific goals Split logic for Verifier and Implementer execution
📏 Constraint rules Prevents success outputs unless WCAG criteria are fully met
🤝 Collaboration hooks Describes required integration with Studio and FEA
♻️ Memory and trace enforcement Ensures scoped behavior and file structure compliance
🚫 Escalation clause Ensures safe fallback if uncertainty or policy violation arises

📘 Prompt Injection Context

This system prompt is injected at:

  • 🧠 Semantic Kernel Agent Bootstrap (/config/agents/a11y-engineer.yaml)
  • 📦 Loaded into ContextVariables along with traceId, moduleId, uiType, and config overlays
  • 🔁 Reused across validator and rewrite skills as persistent meta-guidance

✅ Summary

The System Prompt ensures the Accessibility Engineer Agent:

  • Understands its identity and dual-mode role
  • Operates within the rules of the ConnectSoft Factory
  • Uses deterministic, compliant, and collaborative behaviors
  • Embeds governance, responsibility, and trace integrity at its core

📥 Input Prompt Template

Input prompt templates define how the Accessibility Engineer Agent (AEA) is invoked — providing it with:

  • The UI markup or component to analyze or enhance
  • The execution context (e.g., mode, trace, module, environment)
  • Optional flags for auto-fix behavior, diff output, or collaboration mode

These templates serve both manual Studio-initiated runs and automated trace-based invocations.

🧾 Template: Verifier Mode (Check-only)

mode: verifier
traceId: {{traceId}}
moduleId: {{moduleId}}
environment: {{environment}}
uiType: {{uiType}}  # e.g. HTML, Razor, Angular
templateFilePath: {{pathToComponentFile}}

instructions: |
  Analyze the provided UI template for accessibility compliance.

  - Validate against WCAG 2.1 AA.
  - Use axe-core or equivalent rule engine.
  - Check for: semantic tags, ARIA attributes, heading structure, form labeling, contrast.
  - Emit violations in JSON and Markdown format.
  - Annotate severity levels and provide suggestions.
  - Do not modify the original file.

outputs:
  - a11y-lint-results.json
  - violations.md
  - a11y-score.json
  - accessibility-annotations.yaml

🛠 Template: Implementer Mode (Auto-enhance)

mode: implementer
traceId: {{traceId}}
moduleId: {{moduleId}}
uiType: {{uiType}}  # HTML | Razor | Angular
templateFileContent: |
  {{componentMarkup}}

options:
  autoFix: true
  collaborationMode: "fe-support"  # [fe-support | auto | suggest-only]
  writeEnhancedVariant: true
  useSharedTokens: true

instructions: |
  Enhance the template to meet WCAG 2.1 AA compliance.

  - Add missing ARIA roles, labels, tab order.
  - Replace non-compliant colors with design tokens.
  - Add skip links and improve heading structure.
  - Rewrite the template to an enhanced variant.
  - Optionally write to the shared component library.

outputs:
  - AccessibleComponent.html (or .razor/.ts)
  - FixPlan.yaml (if collaborationMode = "fe-support")
  - Updated a11y-lint-results.json
  - Studio diff annotation

🧠 Optional Prompt Add-ons

Field Purpose
diffAgainst: originalTemplate Allows diff engine to show Studio before/after view
previousViolations: [ruleIds] Used for delta analysis or regression flagging
contextScoreOverride Boosts fix priority if component is high-traffic or high-visibility

🧬 Example: Injected Prompt Values

traceId: trace-2025-05-23-0012
moduleId: login-form
uiType: HTML
templateFilePath: memory/trace-0012/ui/login-form.html
mode: verifier

✅ Summary

Input Prompt Templates enable AEA to:

  • Operate consistently across invocations
  • Switch modes contextually (validate vs. enhance)
  • Maintain trace-scoped, reproducible behavior
  • Support flexible fix strategies (auto, suggest, collaborate)

These templates standardize the interface between orchestration and AI-based a11y operations.

🎯 Output Expectations

Output expectations define the contract of what the Accessibility Engineer Agent (AEA) must return after execution. These outputs serve as:

  • ✅ Studio-visible feedback
  • 🛠 Actionable diffs or rewritten files
  • 📄 Reports for QA and audit agents
  • 🚦 Signals for merge/release gating

AEA’s outputs are structured, trace-aware, and automation-ready.

📘 Expected Output Artifacts (Verifier Mode)

File Format Description
a11y-lint-results.json JSON Full rule-based violation log: ruleId, severity, selector, message
violations.md Markdown Human-readable summary: critical + moderate issues, WCAG mapping
a11y-score.json JSON Summary rating: numeric score, WCAG level (AA, AAA), fixability ratio
accessibility-annotations.yaml YAML Trace metadata for Studio timeline + gating decisions

🛠 Expected Output Artifacts (Implementer Mode)

File Format Description
AccessibleComponent.html / .razor HTML/Razor Rewritten template with ARIA roles, fixed labels, contrast-safe tokens
FixPlan.yaml (optional) YAML Sent to FEA for structural or generation-based refactoring
accessibility-enhancement-diff.md Markdown Side-by-side diff for Studio and developer review

📁 Output Directory Layout (Memory)

/memory/trace-2025-05-23-0012/
└── accessibility/
    ├── a11y-lint-results.json
    ├── a11y-score.json
    ├── violations.md
    ├── accessibility-annotations.yaml
    ├── AccessibleComponent.html
    └── FixPlan.yaml

📊 Output Format Examples

a11y-score.json

{
  "traceId": "trace-2025-05-23-0012",
  "moduleId": "appointment-form",
  "score": 72,
  "wcagLevel": "AA",
  "critical": 2,
  "moderate": 3,
  "low": 1,
  "autoFixable": 4
}

accessibility-annotations.yaml

traceId: trace-2025-05-23-0012
moduleId: appointment-form
status: blocked
studioMessage: "2 critical violations found. Fixes available. Review diff."
studioView: accessibility-enhancement-diff.md
gating: true

FixPlan.yaml

moduleId: appointment-form
fixStrategy: suggest-regeneration
recommendedTemplate: FormWithLabels.v2
reason: Structural nav missing, tab order not fixable in-place
feAgentAction: regenerateComponent

🔁 When Outputs Are Considered Complete

Condition Required?
Reports generated ✅ Always
At least 1 enhancement written or suggested ✅ If violations exist
Studio diff or annotation created ✅ Always (unless explicitly skipped)
Signal emitted to Release Manager or QA ✅ Required if blocking

✅ Summary

AEA output expectations guarantee:

  • 🔍 Accurate and human/machine-readable reporting
  • ✍️ Corrected markup for fixable templates
  • 📘 Studio and QA collaboration hooks
  • 🚦 Trace-safe delivery of accessibility status and gating logic

This ensures accessibility is not just validated — but resolved, reviewed, and ready to ship.

💾 Memory (Short + Long Term)

The Accessibility Engineer Agent (AEA) relies on both short-term execution memory and long-term trace memory to:

  • Maintain accessibility context across trace cycles
  • Store audit artifacts and fixed components
  • Feed trace compliance data into Studio, QA, and Release Manager Agent
  • Reuse fixed components and design patterns across modules and tenants

Memory also enables diff generation, regression detection, and auditable history of fixes.

🧠 Short-Term Memory (In-Context Execution)

Type Purpose
🧠 Prompt context variables Carries traceId, moduleId, uiType, violation summary, execution mode
📝 Lint result cache Stores violations from current audit for real-time scoring or fix decision
✍️ Fix plan draft Holds suggestions, rewrites, or refactor commands before writing final output

Short-term memory lives within the Semantic Kernel context window during the agent's invocation cycle.

🗂 Long-Term Memory (Trace Memory Files)

AEA writes structured outputs to trace-scoped directories under memory/trace-{id}/accessibility/.

📁 Folder Structure

/memory/
└── trace-2025-05-23-0012/
    └── accessibility/
        ├── a11y-lint-results.json
        ├── a11y-score.json
        ├── violations.md
        ├── FixPlan.yaml
        ├── accessibility-annotations.yaml
        └── AccessibleComponent.html

These files are:

  • Used by Studio for annotations and UI feedback
  • Read by Release Manager to allow/block merges
  • Archived for compliance audit post-deploy
  • Referenced by QA Agent for regression or test augmentation

📘 Cross-Trace Memory (Longitudinal)

AEA optionally writes or reads from shared, multi-trace memory:

Path Purpose
shared/a11y-template-variants/ Common accessible UI snippets for component reuse
shared/a11y-token-aliases.json Approved high-contrast token mappings
shared/a11y-rule-exceptions.yaml Global whitelist of known suppressed violations (must be justified and trace-linked)

🔁 Memory Lifecycle

Phase Action
On validation Write violations, summary, annotations
On enhancement Write AccessibleComponent.html or enhanced variant
On fix suggestion Emit FixPlan.yaml
On Studio approval Archive results into release memory bucket
On retry Read from previous a11y-lint-results.json to compare deltas or detect regression

📦 Memory Retention Policy

Type Retained For
a11y-lint-results.json Until trace is archived (same as pipeline logs)
AccessibleComponent.html 90 days minimum or until overridden
FixPlan.yaml Cleared after acceptance or regeneration
Shared templates Permanent unless version-bumped or deprecated

✅ Summary

AEA’s memory model enables:

  • 🔁 Repeatability: retrace the same output deterministically
  • 🔎 Traceability: link every fix, failure, and override to a trace and user
  • ♻️ Reusability: apply fixes and templates across modules, tenants, and editions

It forms the knowledge spine of inclusive UI delivery at scale.

✅ Validation Strategy

The Validation Strategy governs how the Accessibility Engineer Agent (AEA) determines:

  • If a component passes or fails accessibility evaluation
  • What constitutes a critical, blocking violation
  • When a merge or release must be halted
  • Whether the component can be autofixed, enhanced, or requires regeneration

It is essential for consistent enforcement of accessibility across all generated UIs in the ConnectSoft Factory.

✅ Pass/Fail Logic

AEA determines result status based on:

Level Criteria Result
✅ Pass No critical violations; WCAG 2.1 AA met; contrast thresholds ≥ 4.5:1 AccessibilityCheckPassed
⚠️ Warn Only moderate or low-severity violations; no regression AccessibilityCheckPassed with Studio warning
❌ Fail One or more critical violations (e.g., unlabeled input, missing landmark, tab trap) AccessibilityCheckFailed (merge/release blocked)

🔎 Violation Severity Levels

Severity Examples Result
🔴 Critical Missing <label>, contrast < 3:1, non-interactive control with role missing, unreachable content, no skip link Always blocks
🟡 Moderate Skipped heading levels, missing landmarks, nested roles Annotated, optional fix
🔵 Low ARIA best practices, verbose labeling, redundant roles Optional warning only

AEA tags each rule with severity metadata in a11y-lint-results.json.

⚙️ Threshold Config (Override Capable)

validationRules:
  blockOn:
    - severity: critical
    - wcagLevel: AA
  warnOn:
    - severity: moderate
  ignore:
    - role: presentation
      selector: .icon-decorator
  minimumScore: 80

This allows tenant-specific, environment-specific, or component-specific policy adjustments.

🧠 Fixability Classification

Type Example Agent Behavior
✅ Auto-fixable Color token replacement, add ARIA label, tab order adjustment Fix immediately, write enhanced variant
🛠 Regenerable Layout lacking structure (e.g., non-semantic nesting) Emit FixPlan.yaml to FEA
❌ Unfixable Intentional violation (e.g., branding requirement), requires human justification Log and require manual override in Studio

🚦 Merge/Release Gate Behavior

Phase AEA Signal Outcome
Pull Request AccessibilityCheckFailed Studio blocks PR merge until resolved
Pre-release AccessibilityCheckPassed Release Manager Agent proceeds
Production a11y-score < threshold Can be escalated to compliance reviewer, triggers audit warning

📘 Studio Feedback Status Mapping

Status Shown in Studio
Pass ✅ “Accessibility checks passed (WCAG AA)”
Warn ⚠️ “Moderate issues found — auto-fixed or advisory only”
Block ❌ “Critical accessibility violations detected — merge blocked”

✅ Summary

The Accessibility Engineer Agent uses a tiered validation model to:

  • Classify issues precisely
  • Enforce blocking rules for critical failures
  • Guide fixes through autofix or collaboration
  • Ensure accessibility is measurable, explainable, and enforceable

This strategy ensures that ConnectSoft's delivery system is inclusive by policy — not just by intent.

🔁 Retry/Correction Flow

Accessibility validation may surface issues that:

  • Can be auto-fixed immediately
  • Require regeneration or human refinement
  • Cause retries across multiple trace executions (e.g., PR → enhancement → re-validate)

The Retry and Correction Flow ensures the Accessibility Engineer Agent (AEA) can:

  • Recover from failures
  • Improve upon failed states
  • Collaborate when needed
  • Avoid repeated or circular failures

🔄 Correction Flow Overview

flowchart TD
    A[Run a11y Audit] --> B{Violations Found?}
    B -- No --> Z[✅ Emit AccessibilityCheckPassed]
    B -- Yes --> C{Auto-Fixable?}
    C -- Yes --> D[Apply Fixes → Generate Enhanced Variant]
    D --> E[Revalidate Template]
    E --> F{Still Violations?}
    F -- No --> Z
    F -- Yes --> G[Emit FixPlan to FEA]

    C -- No --> G
    G --> H[Studio or FEA Confirms Regeneration]
    H --> A  %% Retry after new template arrives
Hold "Alt" / "Option" to enable pan & zoom

📘 Retry Logic Scenarios

Scenario Action
🔁 Re-validation after autofix Agent re-executes validation on AccessibleComponent.html
🔁 Retry after FEA regeneration Triggered via FixPlanAccepted → ComponentUpdated
🔁 Retry on Studio override User marks "Ignore and retry" in Studio, agent revalidates with allowOverride = true
🚫 Retry limit reached Logs as non-compliant, trace flagged for manual review

🛠 Auto-Fix Retry Cycle

Step Detail
1. Audit → violation: missing label Severity = critical
2. Auto-fix inserts <label for=...> and aria-label
3. Writes new AccessibleComponent.html
4. Runs validation again
5. Pass → ✅ Release can proceed

🧾 Fix Plan Collaboration Cycle

Step Description
1. FixPlan.yaml emitted with regeneration request
2. FEA receives plan and regenerates template
3. Studio timeline updates: “Template updated based on AEA FixPlan”
4. Retry triggered automatically
5. If resolved, merge allowed; else further action suggested

🧠 Retry Metadata Tracking

AEA tracks retry state using:

traceId: trace-2025-05-23-0012
retryCount: 2
lastAttemptStatus: failed
lastFixMode: auto
nextAction: escalate-to-human

Used to prevent loops and inform orchestrators.

⛔ Retry Boundaries and Escalation

Rule Action
More than 3 failed attempts Escalate to Studio with block message
Violation not fixable or exception listed Mark trace as requiresOverride
Retry loop from regenerated output Flag FixPlanLoopDetected and lock merge/release until reviewed

✅ Summary

The AEA’s correction flow supports:

  • ✅ Fast remediation via auto-fix
  • ✅ Structured collaboration via FixPlan
  • ✅ Safe retries and controlled fallback
  • ✅ Studio-guided resolution if needed

This ensures the a11y validation process is robust, non-blocking, and recovery-friendly — without compromising compliance.

📡 Observability Hooks

To ensure trust, traceability, and audit readiness, the Accessibility Engineer Agent (AEA) must emit structured observability data across:

  • Validation attempts
  • Auto-fix executions
  • Failures, retries, and overrides
  • Violations and fix counts
  • Merge/release gating status

This allows the factory, Studio, and developers to track accessibility health per trace, component, and environment.

🧭 Observability Dimensions

Type Description
📊 Metrics Prometheus counters/gauges to track accessibility status trends
📡 OTEL Spans Structured spans with traceId, a11y_score, violations_count, duration
📝 Logs JSON logs for debugging, audit, and validation workflows
📘 Studio UI Updates Visual timeline blocks, badges, and diff annotations
📂 Memory Snapshots Stored outputs in trace memory for human review and historical analysis

📈 Metrics Emitted (Prometheus)

Metric Labels Description
a11y_violations_total traceId, moduleId, severity Count of violations found
a11y_auto_fixes_total traceId, fixType Count of automatic fixes applied
a11y_blocked_traces_total environment, tenantId Number of trace executions blocked due to a11y
a11y_score_gauge moduleId Score from 0–100 indicating compliance level
a11y_retry_count traceId Retry count on a given component
a11y_fix_plan_issued_total reason, severity Tracks when FixPlan collaboration triggered

🕵️ OTEL Spans Example

{
  "traceId": "trace-2025-05-23-0012",
  "agentId": "accessibility-engineer",
  "moduleId": "login-form",
  "status": "passed",
  "a11yScore": 95,
  "durationMs": 2381,
  "violations": 1,
  "autoFixApplied": true,
  "fixMode": "auto"
}

📝 Structured Log Event Example

{
  "event": "AccessibilityCheckCompleted",
  "traceId": "trace-2025-05-23-0012",
  "moduleId": "appointment-form",
  "status": "failed",
  "criticalIssues": 2,
  "autoFixes": 1,
  "retry": false,
  "nextAction": "EmitFixPlan"
}

📘 Studio UI Hooks

UI Element Source
🟡 A11y Warning Banner from a11y-score.json or accessibility-annotations.yaml
❌ Block Merge Button from AccessibilityCheckFailed signal
✅ Fix Accepted Indicator triggered after re-validation of auto-fix or FEA regeneration
📄 Diff View generated via accessibility-enhancement-diff.md
📊 A11y Panel Graphical summary: score, status, violations by rule/severity

📂 Memory Snapshots

Stored in:

/memory/trace-2025-05-23-0012/accessibility/
    ├── a11y-lint-results.json
    ├── a11y-score.json
    ├── accessibility-annotations.yaml
    ├── violations.md
    ├── FixPlan.yaml
    └── AccessibleComponent.html

Used for Studio diffs, QA integrations, and long-term audit trails.

✅ Summary

AEA observability provides:

  • 🔍 Real-time insight into accessibility quality
  • 📊 Metrics for release readiness and compliance dashboards
  • 🛠 Feedback into retry and fix loops
  • 🖥 Visibility across Studio and orchestrator logs

This ensures that accessibility isn't just checked — it's measured, explained, and monitored throughout the factory lifecycle.

👥 Human Intervention Hooks

While the Accessibility Engineer Agent (AEA) automates validation and remediation, some situations require human decision-making:

  • ❗ Ambiguous or conflicting WCAG interpretations
  • ⛔ Business-justified exceptions (e.g., branding restrictions on contrast)
  • 🔄 Rejected auto-fixes that change layout/UX
  • 🧾 Legal/compliance overrides requiring documentation
  • 🔁 Confirmation of FixPlan regeneration from the Frontend Developer Agent (FEA)

This cycle defines when, how, and where human input is accepted or required.

🛑 Trigger Points for Human Involvement

Trigger Condition Description
Critical violation, not fixable No programmatic fix is available (e.g., structure too broken)
Branding conflict Color/contrast fix rejected by design lead or Studio user
FixPlan escalation FEA is asked to regenerate, Studio user must approve
Violation override attempt Studio user attempts to bypass failure gate
Manual Retry Request Developer triggers a new validation cycle after manual edits

📘 Studio Integration Points

UI Element Purpose
⚠️ Violation Banner Shows blocking issues with “Explain” and “Override” buttons
📝 Fix Review Diff Shows before/after markup with “Accept Fix”, “Request Re-gen”, or “Ignore”
🔁 Retry Button Manually re-runs validation if template has been updated
🧾 Override Justification Panel Required to unblock critical violations with a written reason
📄 Approval Switch (Admin only) Overrides gating logic in non-production or demo traces

🧾 Justification Format Example

overrideBy: jane.doe
role: ProductOwner
reason: "Brand team requires this visual contrast"
date: 2025-05-23T10:33:11Z
scope: "login-form"
riskAccepted: true
linkedIssue: STUDIO-1782

Stored in ApprovalRecords.yaml or accessibility-override-justifications.yaml and surfaced in Studio.

🔄 Human Review Loop

flowchart TD
    A[AEA Finds Violation] --> B[Suggest Fix or Generate FixPlan]
    B --> C{Fix Accepted?}
    C -- Yes --> D[Apply Fix → Revalidate]
    C -- No --> E[Studio User Reviews]
    E --> F{Override or Request Re-gen}
    F -- Override --> G[Log Justification → Allow Merge]
    F -- Re-gen --> H[Send to FEA → Retry AEA]
Hold "Alt" / "Option" to enable pan & zoom

✅ Escalation Rules

Condition Result
Production release blocked due to a11y failure Escalate to Studio Admin + ProductOwner
Same violation repeated across traces Trigger Studio-wide alert for shared template regression
Overridden violation in regulated tenant Send copy to Release Manager and Compliance Gatekeeper Agent (future)

📁 Memory Write: Justification Snapshot

traceId: trace-2025-05-23-0199
status: override
reason: "Intentional exception approved by lead"
reviewedBy: alice.jones
approvedAt: 2025-05-23T11:01Z

✅ Summary

Human intervention hooks ensure that:

  • 🧠 Automated enforcement remains context-aware
  • 🔍 Design and compliance teams can document exceptions
  • 🔁 Developers can retry, regenerate, or correct manually
  • 📘 Studio becomes the collaborative decision layer for inclusive UI delivery

Together, this safeguards accessibility without sacrificing flexibility or product realism.

🧭 Agent Position in Factory Flow

The Accessibility Engineer Agent (AEA) operates in the UI generation and validation lifecycle between:

  • Frontend generation (by the Frontend Developer Agent and Template Generator Agent)
  • Studio interaction and QA validation
  • Release approval by the Release Manager Agent

It acts as both a filter and a co-creator, enabling proactive accessibility validation before merge, before release, or on developer request.

🔁 Factory Placement Diagram

flowchart TD
    TG[🧱 Template Generator Agent] --> FEA[🎨 Frontend Developer Agent]
    FEA --> AEA[♿ Accessibility Engineer Agent]
    AEA --> FEA
    AEA --> QA[🧪 QA Agents]
    AEA --> Studio[📘 Studio Timeline + UI]
    AEA --> RMA[🛡 Release Manager Agent]

    click FEA "agents/detailed-agent-specifications/frontend-developer-agent.md"
    click RMA "agents/detailed-agent-specifications/release-manager-agent.md"
Hold "Alt" / "Option" to enable pan & zoom

🔁 Lifecycle Integration Points

Phase AEA Role
After UI generated Invoked to validate markup for WCAG 2.1 AA
On PR creation Scans changed templates and annotates Studio if violations found
Pre-release Blocks release if accessibility violations remain
Studio-triggered User can manually validate or override results
QA feedback Feeds violation data into visual/behavioral test plans
Fix collaboration Suggests or generates enhanced markup, notifies FEA if regeneration is better

🧠 Event Interfaces Summary

Input Trigger Output
PullRequestCreated AccessibilityCheckPassed / AccessibilityCheckFailed
ComponentGenerated FixPlan.yaml or AccessibleComponent.html
ManualValidationRequested a11y-lint-results.json, violations.md, Studio annotation
FixPlanAccepted Re-run validation with new markup
ReleaseIntentDeclared Gated release approval if a11y issues unresolved

📘 Studio Flow Contribution

  • A11y Badge in PR trace view
  • Diff Overlay: enhanced vs. original markup
  • Timeline Event: “Accessibility Validation Passed/Blocked”
  • Approval Override UI: tied to accessibility-annotations.yaml
  • Audit Trail: accessible compliance status and justification logs

🔁 Role in Cross-Agent Feedback Loops

Collaborates With Reason
FEA Improve or regenerate inaccessible components
QA Agent Suggest test coverage for interactive and visual a11y issues
Release Manager Agent Enforce accessibility as a gating constraint
Studio Users Approve, justify, or override accessibility results

✅ Summary

The Accessibility Engineer Agent sits at a critical midpoint in the ConnectSoft Factory:

  • 🧱 After UI is built
  • 📘 Before Studio merges or releases
  • ♻️ Collaborating with QA, Dev, and Compliance flows

This ensures that accessibility is embedded, visible, and enforceable across the full lifecycle of every component.

✅ Summary & Future Extensions

The Accessibility Engineer Agent (AEA) plays a dual role in the ConnectSoft AI Software Factory:

  • 🔍 Verifier: Automatically audits all frontend outputs for WCAG 2.1 AA compliance.
  • 🛠 Implementer: Repairs, rewrites, and enhances UI templates for screen readers, keyboard navigation, semantic structure, and contrast safety.

It ensures accessibility is:

  • 📘 Trace-validated
  • 🧠 Built-in by design
  • 🔁 Corrected through collaboration
  • 🛡 Enforced by policy and gating
  • ✅ Visible to humans and machines

🧩 Core Capabilities Recap

Area Responsibilities
📥 Inputs Component HTML/Razor/Angular, trace metadata, token themes
📤 Outputs Lint results, markdown reports, Studio diffs, enhanced templates
🧠 Knowledge WCAG 2.1, ARIA spec, contrast math, semantic heuristics
🔁 Skills Auto-fix labeling, tab order, landmark roles, color token enhancement
💾 Memory Per-trace results + reusable shared accessible variants
🧭 Observability Metrics, spans, logs, trace annotations, merge/release gating
👥 Collaboration Frontend Developer Agent, QA, Studio users, Release Manager Agent
🔄 Recovery Retry logic, FixPlan emission, override justification logging

🚀 Future Extensions

1. 🎧 Screen Reader Simulation Agent Integration

  • Run NVDA, VoiceOver, or ChromeVox emulation in CI
  • Validate focus order, live region announcements, and verbosity

2. 🌍 Multi-Language A11y Testing

  • Validate screen reader experience in RTL, Hebrew, Arabic, Japanese
  • Verify translated label and ARIA attribute correctness

3. 🔐 Compliance Mode: ADA, EN 301 549

  • Support strict regulatory profiles (legal-grade)
  • Signed justification records, encrypted audit trail

4. 🖱️ Interaction Heuristics

  • Detect mouse-only interactions with no keyboard fallback
  • Simulate keyboard tab flow with visual overlays

5. 📊 Accessibility Heatmaps

  • Visualize which components, tenants, or pages fail most
  • Drive proactive improvements in shared templates

6. 🤖 AI-Guided Remediation

  • Large model-assisted suggestions for component rewrites
  • Lint-and-correct in natural language (e.g., “make this login form accessible”)

📘 Final Statement

The Accessibility Engineer Agent transforms accessibility from an afterthought into an engineered, enforceable outcome. It makes inclusive design scalable, reportable, and repeatable — ensuring every product built by the ConnectSoft AI Software Factory is accessible by default.