Making the digital world accessible for 1.3 billion people with disabilities
Web accessibility is one of the most overlooked challenges in software development today:
- 96.3% of the top 1 million homepages have detectable WCAG accessibility failures (WebAIM 2025 report)
- 1.3 billion people worldwide -- roughly 16% of the global population -- live with some form of disability that affects how they interact with digital content
- Enterprise documents such as PDFs, internal reports, HR policies, and training materials are almost never checked for accessibility before distribution
- Existing accessibility tools are reactive: they scan a finished page and produce a list of violations for developers to manually fix. There is no tool that proactively analyzes, reasons about, and automatically transforms content into accessible formats
The result is that billions of documents, web pages, and digital resources remain inaccessible to people who use screen readers, have low vision, cognitive disabilities, or motor impairments.
AccessMind is an AI-powered multi-agent system that takes any document, webpage, or text content and automatically:
- Analyzes it for accessibility issues across four dimensions -- visual, cognitive, structural, and compliance
- Identifies specific WCAG 2.2 violations with citations to the exact guideline criteria
- Transforms the content into an accessible version -- fixing contrast, simplifying language, correcting heading hierarchies, adding missing ARIA attributes and alt text
- Scores the content on a 0-100 compliance scale with a detailed breakdown by category
- Requires human approval before any export -- a critical safety guardrail that ensures AI-generated transforms are reviewed by a human before being published
- Exports the accessible version in multiple formats (HTML, Markdown, JSON compliance report, clipboard)
All accessibility recommendations are grounded in WCAG 2.2 guidelines retrieved from Microsoft Foundry IQ, which means every suggestion comes with a citation to the specific standard -- reducing hallucination and ensuring reliability.
| Input Type | How It Works |
|---|---|
| PDF files | Extracted via PyMuPDF -- text content, metadata, and structure are parsed and analyzed |
| HTML files | Parsed with BeautifulSoup -- full DOM analysis including headings, images, links, ARIA roles, semantic elements |
| URLs | Fetched via httpx -- the remote page HTML is downloaded and analyzed like a local HTML file |
| Plain text | Directly analyzed for reading level, cognitive complexity, and structure |
AccessMind uses 5 specialized AI agents that each focus on a different dimension of accessibility. They work in parallel under a supervisor, and their findings are merged and validated before being presented to the user.
The orchestrator. It receives the uploaded content, determines its type (PDF, HTML, URL, or text), routes it to the appropriate parser, then dispatches the parsed content to all three specialist agents simultaneously using asyncio.gather. Once all specialists return their findings, the Supervisor merges the results -- deduplicating overlapping issues, resolving conflicts, and building a unified issue list. It then sends everything to the Judge for final validation. If the compliance score falls below 85%, the Supervisor can trigger a refinement cycle, asking agents to re-analyze with additional context. Every step is recorded in an audit trail with timestamps.
Focuses on how content looks to users with visual impairments. It performs:
- Color contrast checking against WCAG 1.4.3 (AA minimum 4.5:1 ratio) and WCAG 1.4.6 (AAA enhanced 7:1 ratio) using a custom luminance calculator
- Font size analysis -- flags text smaller than 16px body or 12px minimum
- Image alt-text audit -- detects images without
altattributes, images with empty alt text, and decorative images that should havealt="" - Touch target sizing -- ensures interactive elements meet the 44x44px minimum target size
- Visual hierarchy assessment -- checks whether the visual structure matches the semantic structure
Focuses on making content understandable for users with cognitive disabilities, learning disabilities, or limited literacy. It performs:
- Reading level analysis -- calculates the Flesch-Kincaid grade level of the content and flags anything above an 8th-grade reading level (WCAG 3.1.5 Level AAA)
- Sentence complexity scoring -- identifies sentences longer than 25 words, nested clauses, and passive voice constructions
- Jargon detection -- flags technical terms, acronyms, and domain-specific language that should be defined or simplified
- Text rewriting -- uses Azure OpenAI GPT-4o to rewrite complex paragraphs into plain language while preserving meaning
- Summary generation -- creates a brief summary of the document for users who need a quick overview
Focuses on the document structure and markup that assistive technologies (screen readers, braille displays) rely on. It performs 11 specific checks:
- Heading hierarchy -- ensures headings follow a logical order (h1 > h2 > h3) with no skipped levels
- ARIA landmarks -- checks for
role="main",role="navigation",role="banner",role="contentinfo" - Semantic HTML -- flags
<div>and<span>elements used where semantic elements (<nav>,<article>,<section>,<aside>) should be used - Skip navigation links -- checks for a "skip to main content" link at the top of the page (WCAG 2.4.1)
- Page title -- verifies the
<title>element exists and is descriptive (WCAG 2.4.2) - Language attribute -- checks for
langattribute on the<html>element (WCAG 3.1.1) - Link text quality -- flags generic link text like "click here" or "read more" that provides no context for screen reader users
- Form labels -- ensures all form inputs have associated
<label>elements (WCAG 3.3.2) - Table markup -- checks for
<th>headers,scopeattributes, and<caption>elements in data tables - Reading order -- verifies that the DOM order matches the visual reading order
- List structure -- ensures lists use proper
<ul>,<ol>, and<li>elements
The final validator. After all specialist agents have reported their findings, the Judge:
- Cross-validates every reported issue against WCAG 2.2 success criteria to confirm it is a real violation (not a false positive)
- Queries Foundry IQ to retrieve the exact guideline text, sufficient techniques, and common failure patterns for each cited criterion
- Calculates a weighted compliance score (0-100) using category weights: Visual (30%), Cognitive (20%), Structure (30%), Compliance (20%)
- Assigns severity levels to each issue: Critical (must fix, blocks accessibility), Major (should fix, degrades experience), Minor (nice to fix, improves experience)
- Generates an ordered remediation plan -- prioritized list of fixes from most impactful to least
- Produces the final audit report with all citations, scores, and the transformed content
This is how AccessMind demonstrates multi-step reasoning -- the core requirement of the Reasoning Agents track:
Step 1: PARSE Content uploaded -> type detected -> parsed into structured data
(PDF -> PyMuPDF, HTML -> BeautifulSoup, URL -> httpx + BS4)
|
Step 2: FAN-OUT Supervisor dispatches to 3 specialists IN PARALLEL
(asyncio.gather for concurrent execution)
|
+-------------------+-------------------+
| | |
Step 3: ANALYZE Visual checks Cognitive analysis Structure audit
contrast ratios reading level heading hierarchy
alt-text audit simplification ARIA landmarks
font sizes jargon detection semantic HTML
touch targets summary generation link text quality
| | |
+-------------------+-------------------+
|
Step 4: MERGE Supervisor merges all findings
deduplicates overlapping issues
resolves conflicting recommendations
|
Step 5: GROUND Foundry IQ retrieves WCAG 2.2 guidance
for each identified issue with citations
|
Step 6: JUDGE Compliance Judge validates all issues
assigns severity (critical/major/minor)
calculates weighted compliance score
generates prioritized remediation plan
|
Step 7: REFINE? If score < 85%, Supervisor triggers
a refinement cycle with additional context
(max 1 refinement cycle)
|
Step 8: PRESENT Results displayed in the UI
score gauge, issue cards, before/after view
|
Step 9: APPROVE Human-in-the-loop approval required
user reviews transforms before export
|
Step 10: EXPORT Accessible HTML, Markdown, JSON report,
or copy summary to clipboard
AccessMind integrates Foundry IQ as its knowledge retrieval layer. Foundry IQ is Microsoft's agentic knowledge service that connects enterprise data sources, enforces permissions, and delivers grounded answers with citations.
In AccessMind, Foundry IQ is used to:
- Retrieve WCAG 2.2 guideline text for any specific criterion (e.g., querying "WCAG 1.4.3" returns the full success criterion text, sufficient techniques, and common failure patterns)
- Ground every recommendation in the actual standard -- so when AccessMind tells you "this color combination fails contrast requirements," it cites the exact WCAG criterion and the required ratio
- Reduce hallucination -- instead of relying on the LLM's training data about accessibility standards (which may be outdated or incorrect), AccessMind retrieves the authoritative text from the knowledge base
- Provide best practices by category -- querying "visual accessibility best practices" returns curated guidance specific to that domain
When Azure credentials are not available, the system falls back to a local knowledge base containing bundled WCAG 2.2 guidelines (backend/knowledge/wcag_data/), ensuring the system works in demo mode without any external dependencies.
AccessMind integrates with Foundry IQ using the azure-ai-projects SDK. The integration follows the official Agent + AzureAISearchTool + Thread/Run pattern:
# 1. Initialize the project client from connection string
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import AzureAISearchTool
from azure.identity import DefaultAzureCredential
client = AIProjectClient.from_connection_string(
conn_str=os.environ["PROJECT_CONNECTION_STRING"],
credential=DefaultAzureCredential(),
)
# 2. Configure AzureAISearchTool pointing at the WCAG knowledge index
search_tool = AzureAISearchTool(
index_connection_id=os.environ["FOUNDRY_KB_ID"],
index_name="wcag22-knowledge-index",
)
# 3. Create a short-lived agent with the search tool attached
agent = client.agents.create_agent(
model="gpt-4o",
name="accessmind-wcag-retriever",
instructions="You are an accessibility expert. Use the provided knowledge base...",
tools=[search_tool.definitions[0]],
)
# 4. Create a thread, send a message, and execute the run
thread = client.agents.create_thread()
client.agents.create_message(
thread_id=thread.id, role="user",
content="What does WCAG 2.2 say about color contrast?"
)
run = client.agents.create_and_process_run(
thread_id=thread.id, agent_id=agent.id
)
# 5. Retrieve grounded response with citations
messages = client.agents.list_messages(thread_id=thread.id)
# -> Returns WCAG-cited guidance with specific criterion references
# 6. Cleanup
client.agents.delete_agent(agent.id)The full implementation is in foundry_client.py. When Azure is unavailable, it falls back to local keyword search across bundled WCAG 2.2 markdown files.
flowchart TD
UI["AccessMind Web UI\nFluent 2 Dark Theme"]
API["FastAPI REST API\nbackend/main.py"]
SUP["Supervisor Agent\nOrchestrator - MAF 1.6"]
VIS["Visual Accessibility\nAgent"]
COG["Cognitive Simplifier\nAgent"]
STR["Structure Analyzer\nAgent"]
JDG["Compliance Judge\nAgent"]
FIQ["Foundry IQ\nWCAG 2.2 Knowledge Base"]
EXP["Export Engine\nHTML / MD / JSON"]
UI -->|REST API| API
API --> SUP
SUP -->|parallel dispatch| VIS
SUP -->|parallel dispatch| COG
SUP -->|parallel dispatch| STR
VIS -->|findings| SUP
COG -->|findings| SUP
STR -->|findings| SUP
SUP -->|merged results| JDG
JDG -->|query guidance| FIQ
FIQ -->|cited WCAG text| JDG
JDG -->|scored report| SUP
SUP -->|final analysis| API
API -->|approved export| EXP
style UI fill:#1a1a2e,stroke:#0078D4,color:#fff
style SUP fill:#2d1b69,stroke:#9B59B6,color:#fff
style VIS fill:#1b3a4b,stroke:#3498DB,color:#fff
style COG fill:#1b3a4b,stroke:#2ECC71,color:#fff
style STR fill:#1b3a4b,stroke:#E67E22,color:#fff
style JDG fill:#3b1929,stroke:#E74C3C,color:#fff
style FIQ fill:#0d3b66,stroke:#0078D4,color:#fff
style API fill:#1a1a2e,stroke:#00BCF2,color:#fff
style EXP fill:#1a1a2e,stroke:#00BCF2,color:#fff
sequenceDiagram
participant U as User
participant API as FastAPI
participant S as Supervisor
participant V as Visual Agent
participant C as Cognitive Agent
participant T as Structure Agent
participant J as Judge Agent
participant F as Foundry IQ
U->>API: POST /api/analyze (file/URL/text)
API->>S: Parse content, detect type
par Parallel Analysis
S->>V: Analyze visual accessibility
S->>C: Analyze cognitive complexity
S->>T: Analyze document structure
end
V-->>S: Visual findings
C-->>S: Cognitive findings
T-->>S: Structure findings
S->>S: Merge and deduplicate
S->>J: Validate all findings
J->>F: Query WCAG 2.2 guidance
F-->>J: Cited guidelines
J-->>S: Scored compliance report
alt Score < 85%
S->>S: Trigger refinement cycle
end
S-->>API: Final analysis result
API-->>U: Display results in UI
U->>API: POST /api/approve/{id}
U->>API: POST /api/export/{id}
API-->>U: Accessible HTML/MD/JSON
- Python 3.12 with FastAPI -- High-performance async API with automatic OpenAPI docs
- Microsoft Agent Framework (MAF) 1.6.0 -- Multi-agent orchestration (successor to AutoGen)
- Azure AI Foundry SDK (
azure-ai-projects2.1.0) -- Foundry IQ knowledge retrieval - Azure OpenAI (GPT-4o) -- LLM reasoning engine for cognitive simplification
- Semantic Kernel 1.43.0 -- AI orchestration foundation layer
- Pydantic -- Type-safe request/response models and validation
- BeautifulSoup + lxml -- HTML parsing and DOM analysis
- PyMuPDF -- PDF text and metadata extraction
- Pillow -- Image analysis for alt-text detection
- Vanilla HTML/CSS/JS -- Zero build step, instant loading, no framework overhead
- Microsoft Fluent 2 Design System -- 52KB stylesheet with exact Microsoft design tokens
- Dark theme with Copilot gradient accents (blue, green, purple, orange)
- Segoe UI Variable typography -- Microsoft's latest variable-weight system font
- Accessible by design -- Skip links, ARIA roles, keyboard navigation, live regions, screen reader support
- Real-time agent status panel -- Animated cards showing each agent's progress
- Score gauge -- Animated circular progress indicator (0-100)
- Before/after comparison -- Split-pane view of original vs. transformed content
- 4 export formats -- HTML, Markdown, JSON compliance report, clipboard
- Foundry IQ -- Knowledge base of WCAG 2.2 guidelines for grounded, cited recommendations
- Local fallback -- Bundled WCAG 2.2 data (guidelines, best practices, common failures) for offline/demo mode
- Python 3.11+
- Azure subscription (optional -- demo mode works without it)
# Clone the repository
git clone https://github.com/ashutosh0x/accessmind.git
cd accessmind
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure environment (optional -- demo mode works without Azure)
cp .env.example .env
# Edit .env with your Azure credentials for full functionality
# Run the application
uvicorn backend.main:app --reload --port 8000
# Open http://localhost:8000 in your browser# Build and run
docker compose up --build
# Or without Docker Compose
docker build -t accessmind .
docker run -p 8000:8000 accessmindThe app includes a full demo mode that works without any Azure credentials. When the server starts, it automatically checks for the AZURE_OPENAI_API_KEY and PROJECT_CONNECTION_STRING environment variables. If either is missing, it activates demo mode with a MockSupervisorAgent that returns realistic analysis results -- including issues, scores, transformed content, and a complete audit trail. This allows judges, reviewers, and developers to experience the full workflow without needing an Azure subscription.
# Run without any Azure setup -- demo mode activates automatically
uvicorn backend.main:app --reload --port 8000
# Open http://localhost:8000Demo video: (to be recorded before submission deadline -- June 14, 2026)
- Open AccessMind at
http://localhost:8000 - Click "Try Demo" to see the full analysis flow
- Watch the 5 AI agents activate and analyze content in real-time
- Review the accessibility score (0-100) and issue breakdown by severity
- Explore the before/after comparison view showing original vs. transformed content
- Approve the changes (human-in-the-loop safety check)
- Export as HTML, Markdown, JSON compliance report, or copy summary to clipboard
# Install test dependencies (included in requirements.txt)
pip install pytest pytest-asyncio
# Run all 26 tests
pytest tests/ -v
# Run with short traceback
pytest tests/ -v --tb=shortThe test suite covers:
- Import tests -- All 10 modules importable without errors
- Configuration -- Default settings, CORS origins
- Foundry IQ client -- Local fallback, WCAG queries, criterion extraction, level inference
- Contrast utilities -- Color contrast ratio calculations (black/white = 21:1, same color = 1:1)
- Mock supervisor -- Demo pipeline end-to-end, score ranges, agent statuses
- Pydantic schemas -- AccessibilityIssue and AgentResult model validation
- HTML parser -- Basic HTML parsing and structure extraction
| Guardrail | Description |
|---|---|
| Human-in-the-loop | All AI-generated transforms must be explicitly approved by the user before they can be exported. The export API returns HTTP 403 if approval has not been granted. |
| Audit trail | Every agent action, decision, and human interaction is logged with timestamps and agent identifiers. The full trail is included in JSON exports. |
| Input validation | File uploads are limited to 25MB. Only PDF, HTML, and text content types are accepted. All inputs are sanitized before processing. |
| Content filtering | Azure AI content safety filtering is enabled on all OpenAI calls to prevent generation of harmful content. |
| Graceful degradation | If any individual agent fails (timeout, error, malformed response), the Supervisor catches the error, logs it, and returns partial results from the agents that succeeded. |
| Demo mode isolation | When Azure credentials are absent, the system operates in a fully isolated demo mode with zero external API calls. |
| No confidential data | This project contains no confidential, proprietary, or personal information per the hackathon disclaimer requirements. |
AccessMind checks against these WCAG 2.2 success criteria:
| Criterion | Level | Category | What It Checks |
|---|---|---|---|
| 1.1.1 | A | Visual | Non-text Content -- images must have alt text |
| 1.3.1 | A | Structure | Info and Relationships -- semantic markup must convey structure |
| 1.3.2 | A | Structure | Meaningful Sequence -- reading order must be logical |
| 1.4.3 | AA | Visual | Contrast (Minimum) -- 4.5:1 ratio for normal text |
| 1.4.6 | AAA | Visual | Contrast (Enhanced) -- 7:1 ratio for enhanced compliance |
| 2.4.1 | A | Structure | Bypass Blocks -- skip navigation links must be present |
| 2.4.2 | A | Structure | Page Titled -- page must have a descriptive title |
| 2.4.6 | AA | Structure | Headings and Labels -- headings must be descriptive |
| 3.1.1 | A | Structure | Language of Page -- html lang attribute must be set |
| 3.1.5 | AAA | Cognitive | Reading Level -- content should be at 8th grade level or below |
| 3.3.2 | A | Structure | Labels or Instructions -- form inputs need labels |
| 4.1.2 | A | Structure | Name, Role, Value -- UI components must expose accessibility info |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/health |
Health check -- returns status, version, demo mode flag, and agent readiness |
GET |
/api/agents/status |
Current status of all 5 agents (idle, analyzing, complete, error) |
POST |
/api/analyze |
Upload content for analysis -- accepts file upload, URL, or text via form data |
GET |
/api/analysis/{id} |
Retrieve stored analysis results by ID |
POST |
/api/approve/{id} |
Human-in-the-loop approval -- marks analysis as approved or rejected with optional feedback |
POST |
/api/export/{id} |
Export in requested format (html, markdown, json) -- requires prior approval (HTTP 403 otherwise) |
Full interactive API documentation is available at /api/docs (Swagger UI) and /api/redoc (ReDoc) when the server is running.
graph LR
subgraph root["accessmind/"]
subgraph backend["backend/"]
subgraph agents["agents/"]
sup["supervisor.py\n33KB - Orchestrator"]
vis["visual_agent.py\n19KB - Contrast, Alt-text"]
cog["cognitive_agent.py\n19KB - Readability"]
str2["structure_agent.py\n30KB - ARIA, Headings"]
jdg["judge_agent.py\n19KB - WCAG Scoring"]
end
subgraph knowledge["knowledge/"]
fc["foundry_client.py\n16KB - Foundry IQ"]
wd["wcag_data/\nGuidelines, Practices"]
end
subgraph models["models/"]
sc["schemas.py\nPydantic Models"]
end
subgraph parsers["parsers/"]
hp["html_parser.py - 15KB"]
pp["pdf_parser.py - 9KB"]
ia["image_analyzer.py - 10KB"]
end
subgraph utils["utils/"]
ct["contrast.py - 6KB"]
sr["scoring.py - 6KB"]
end
cfg["config.py - 3KB"]
mn["main.py - 15KB\nFastAPI Routes"]
end
subgraph frontend["frontend/"]
idx["index.html - 25KB\nSingle Page App"]
css["css/styles.css - 52KB\nFluent 2 Dark Theme"]
app["js/app.js - 32KB"]
ag["js/agents.js - 10KB"]
cmp["js/comparison.js - 8KB"]
exp["js/export.js - 15KB"]
end
subgraph tests["tests/"]
tst["test_accessmind.py\n26 Tests"]
end
dk["Dockerfile"]
dc["docker-compose.yml"]
rq["requirements.txt"]
ar["ARCHITECTURE.md"]
se["SECURITY.md"]
co["CONTRIBUTING.md"]
li["LICENSE - MIT"]
end
style backend fill:#1a1a2e,stroke:#0078D4,color:#fff
style frontend fill:#1a1a2e,stroke:#00BCF2,color:#fff
style agents fill:#2d1b69,stroke:#9B59B6,color:#fff
style knowledge fill:#0d3b66,stroke:#0078D4,color:#fff
style tests fill:#1b3a4b,stroke:#2ECC71,color:#fff
This project is submitted for the Microsoft Agents League Hackathon @ AISF 2026:
| Award | Why AccessMind Qualifies |
|---|---|
| Best Reasoning Agent | 5-agent pipeline with parallel analysis, cross-agent synthesis, iterative refinement, and 10-step reasoning flow |
| Best Use of IQ Tools | Deep Foundry IQ integration for grounded WCAG 2.2 knowledge retrieval with citations |
| Accessibility Award | The entire project is dedicated to making digital content accessible for people with disabilities |
| Hack for Good | Direct social impact for 1.3 billion people worldwide who live with disabilities |
MIT License -- See LICENSE for details.
- Microsoft Foundry IQ for grounded knowledge retrieval
- WCAG 2.2 guidelines by W3C Web Accessibility Initiative
- Microsoft Fluent 2 design system for UI tokens and components
- Microsoft Agents League Hackathon at AISF 2026
Built for accessibility at the Agents League Hackathon @ AISF 2026