Severity Model

Severity and Impact Model

Unlike traditional linters (like Axe or Lighthouse) that output flat lists of errors, A11Y.md feeds a simplified, impact-based Severity Model into the AI's context.

This model is crucial because it teaches the AI how to prioritize fixes and weigh trade-offs during code generation. Instead of seeing all accessibility issues as equal violations, the AI understands them through the lens of user impact.

Level	Indicator	AI Understanding	AI Action Mandate
CRITICAL	🔴	Operational Blocker: The user cannot use the feature.	MUST FIX. No compromises.
HIGH	🟠	Perceptual Blocker: The user struggles to perceive the feature.	MUST FIX. Prioritize semantics.
MEDIUM	🟡	Efficiency Drop: The user is slowed down or confused.	SHOULD FIX.
LOW	🔵	Cosmetic Polish: Minor issues without core functional impact.	MAY FIX.

How the AI Uses the Taxonomy

The Distinction Between CRITICAL and HIGH

This is the most sophisticated design decision baked into the AI's context.

• CRITICAL (🔴) means the functionality is literally inaccessible (e.g., a keyboard trap, a <div onClick> that a keyboard user cannot reach). The AI understands this as a total failure of Task Completion.
• HIGH (🟠) means the functionality exists, but is severely degraded (e.g., text contrast is 2:1, unreadable for low vision).

Both are MUST FIX, but the AI understands that Critical is a functional blocker, while High is a perceptual blocker.

Prioritization During Code Generation

When generating a complex component, if the AI detects conflicting patterns or constraints, it uses this model to prioritize. It will fix a 🔴 CRITICAL operability issue before refining a 🔵 LOW cosmetic focus ring.

Mapping to Product Metrics

The AI is instructed that accessibility is not a compliance metric, but a product metric.

• 🔴 CRITICAL directly kills the Task Completion Rate.
• 🟠 HIGH dramatically increases the Error Rate / Abandonment Rate.
• 🟡 MEDIUM reduces the Satisfaction Score.

By embedding this model into the A11Y.md file, the AI stops acting like a blind code generator and starts making architectural decisions that prioritize the end user's ability to actually use the product.