CODITECT Accessibility Standard

Version: 1.0.0 Status: ACTIVE Last Updated: 2026-01-19 Compliance Target: WCAG 2.1 Level AA

Overview

All CODITECT UI components MUST meet WCAG 2.1 Level AA compliance. This standard defines the accessibility requirements, testing criteria, and implementation patterns for inclusive design.

Core Principles (POUR)

Principle	Description
Perceivable	Information must be presentable in ways users can perceive
Operable	UI components must be operable by all users
Understandable	Information and UI operation must be understandable
Robust	Content must be robust enough for assistive technologies

Color & Contrast Requirements

Contrast Ratios (WCAG 1.4.3, 1.4.11)

Element Type	Minimum Ratio	Example
Normal text (< 18pt)	4.5:1	Body text, labels
Large text (≥ 18pt or 14pt bold)	3:1	Headings
UI components & graphics	3:1	Buttons, icons, borders
Focus indicators	3:1	Focus rings

Implementation

/* ✅ CORRECT: Uses tokens with verified contrast */
.button-primary {
  background: var(--coditect-color-primary-500);
  color: var(--coditect-fg-inverse);  /* White on blue = 4.5:1+ */
}

/* ❌ WRONG: Low contrast */
.button-secondary {
  background: var(--coditect-color-neutral-100);
  color: var(--coditect-color-neutral-300);  /* 2.1:1 - FAILS */
}

Color Independence (WCAG 1.4.1)

Color MUST NOT be the only visual means of conveying information:

<!-- ✅ CORRECT: Color + icon + text -->
<span class="status status--error">
  <svg class="status__icon" aria-hidden="true"><!-- X icon --></svg>
  <span class="status__text">Error: Invalid input</span>
</span>

<!-- ❌ WRONG: Color only -->
<span class="status status--error" style="color: red;">Error</span>

Focus Order (WCAG 2.4.3)

Focus order MUST be logical and predictable:

<!-- ✅ CORRECT: Natural DOM order -->
<nav>
  <a href="/">Home</a>
  <a href="/about">About</a>
  <a href="/contact">Contact</a>
</nav>

<!-- ❌ WRONG: Manipulated order breaks expectations -->
<nav>
  <a href="/contact" tabindex="1">Contact</a>
  <a href="/" tabindex="3">Home</a>
  <a href="/about" tabindex="2">About</a>
</nav>

Focus Visibility (WCAG 2.4.7)

All interactive elements MUST have visible focus indicators:

/* Required focus styles */
:focus-visible {
  outline: 2px solid var(--coditect-border-focus);
  outline-offset: 2px;
}

/* Never remove focus entirely */
/* ❌ WRONG */
:focus { outline: none; }

/* ✅ CORRECT: Style it, don't remove it */
:focus:not(:focus-visible) {
  outline: none;
}
:focus-visible {
  outline: 2px solid var(--coditect-color-primary-500);
}

Keyboard Operability (WCAG 2.1.1)

All functionality MUST be keyboard accessible:

Component	Required Keys
Buttons	`Enter`, `Space`
Links	`Enter`
Checkboxes	`Space`
Radio buttons	`Arrow` keys
Dropdowns	`Arrow`, `Enter`, `Escape`
Modals	`Escape` to close, Tab trap
Menus	`Arrow` keys, `Home`, `End`

No Keyboard Traps (WCAG 2.1.2)

Users MUST be able to navigate away from any component:

// Modal focus trap implementation
function trapFocus(modal) {
  const focusableElements = modal.querySelectorAll(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const first = focusableElements[0];
  const last = focusableElements[focusableElements.length - 1];

  modal.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    }
    if (e.key === 'Escape') {
      closeModal(modal);  // Always provide escape
    }
  });
}

Semantic HTML & ARIA

Use Semantic Elements First

<!-- ✅ CORRECT: Semantic HTML -->
<button type="submit">Submit</button>
<nav aria-label="Main">...</nav>
<main>...</main>
<article>...</article>

<!-- ❌ WRONG: Divs with ARIA -->
<div role="button" tabindex="0" onclick="submit()">Submit</div>

ARIA Attributes

Attribute	Use Case
`aria-label`	Labels for icon-only buttons
`aria-labelledby`	Reference existing visible label
`aria-describedby`	Additional help text
`aria-expanded`	Expandable sections
`aria-hidden`	Decorative elements
`aria-live`	Dynamic content updates
`role`	Only when semantic HTML unavailable

Required ARIA Patterns

Icon Buttons:

<button aria-label="Close dialog">
  <svg aria-hidden="true"><!-- X icon --></svg>
</button>

Loading States:

<button aria-busy="true" aria-describedby="loading-text">
  <span id="loading-text" class="sr-only">Loading, please wait</span>
  <span class="spinner" aria-hidden="true"></span>
</button>

Form Errors:

<input
  id="email"
  aria-invalid="true"
  aria-describedby="email-error"
/>
<span id="email-error" role="alert">
  Please enter a valid email address
</span>

Touch Targets (WCAG 2.5.5)

Minimum Size

All interactive elements MUST meet touch target requirements:

Requirement	Size
Minimum	44×44 pixels
Recommended	48×48 pixels

/* Ensure minimum touch target */
.button {
  min-height: 44px;
  min-width: 44px;
  padding: var(--coditect-space-2) var(--coditect-space-4);
}

/* For inline links, use padding */
.link-inline {
  padding: var(--coditect-space-2);
  margin: calc(-1 * var(--coditect-space-2));
}

Spacing Between Targets

Adjacent touch targets MUST have adequate spacing:

.button-group {
  gap: var(--coditect-space-2);  /* 8px minimum */
}

/* Visually hidden but accessible */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Live Regions

Dynamic content updates MUST announce to screen readers:

<!-- For status messages -->
<div role="status" aria-live="polite" aria-atomic="true">
  Form submitted successfully
</div>

<!-- For urgent alerts -->
<div role="alert" aria-live="assertive">
  Session expired. Please log in again.
</div>

Skip Links

Pages MUST include skip navigation:

<body>
  <a href="#main-content" class="skip-link">
    Skip to main content
  </a>
  <header>...</header>
  <main id="main-content" tabindex="-1">
    ...
  </main>
</body>

.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  z-index: var(--coditect-z-tooltip);
}
.skip-link:focus {
  top: 0;
}

Forms

Labels (WCAG 1.3.1, 3.3.2)

Every form input MUST have an associated label:

<!-- ✅ CORRECT: Explicit label association -->
<label for="username">Username</label>
<input id="username" type="text" />

<!-- ✅ CORRECT: Implicit label association -->
<label>
  Username
  <input type="text" />
</label>

<!-- ❌ WRONG: No label association -->
<span>Username</span>
<input type="text" />

Error Identification (WCAG 3.3.1)

Errors MUST be clearly identified:

<div class="form-field form-field--error">
  <label for="email">Email</label>
  <input
    id="email"
    type="email"
    aria-invalid="true"
    aria-describedby="email-error"
  />
  <span id="email-error" class="form-field__error" role="alert">
    Please enter a valid email address
  </span>
</div>

Required Fields (WCAG 3.3.2)

<label for="name">
  Name
  <span aria-hidden="true">*</span>
  <span class="sr-only">(required)</span>
</label>
<input id="name" type="text" required aria-required="true" />

Images & Media

Alternative Text (WCAG 1.1.1)

Image Type	Alt Text Approach
Informative	Describe content/purpose
Decorative	`alt=""` or `aria-hidden="true"`
Functional	Describe action
Complex	Provide long description

<!-- Informative -->
<img src="chart.png" alt="Sales increased 25% from Q1 to Q2" />

<!-- Decorative -->
<img src="decoration.png" alt="" />

<!-- Functional (in button) -->
<button>
  <img src="search.svg" alt="Search" />
</button>

<!-- Icon (decorative in button with text) -->
<button>
  <svg aria-hidden="true">...</svg>
  Search
</button>

Testing Requirements

Automated Testing

Tool	Purpose
axe-core	Automated accessibility audits
Lighthouse	Performance + accessibility
WAVE	Visual accessibility checker

Manual Testing Checklist

Navigate entire UI with keyboard only
Test with screen reader (VoiceOver, NVDA)
Check color contrast ratios
Verify focus indicators visible
Test at 200% zoom
Test with reduced motion preference
Verify form error announcements
Check skip links work

Test Command

# Run accessibility quality gate
/ui-quality --gate accessibility

# Strict WCAG AAA check
/ui-quality --gate accessibility --wcag AAA

Compliance Checklist

Before any UI component is approved:

Perceivable

Color contrast meets 4.5:1 (text) / 3:1 (UI)
Color is not sole indicator
Images have alt text
Content readable at 200% zoom

Operable

All functions keyboard accessible
Focus indicators visible
No keyboard traps
Touch targets ≥ 44px

Understandable

Labels on all form inputs
Error messages clear and helpful
Consistent navigation

Robust

Valid HTML
ARIA used correctly
Works with screen readers

Related Documents:

Version: 1.0.0 Last Updated: 2026-01-19 Maintained by: AZ1.AI Inc.

Overview​

Core Principles (POUR)​

Color & Contrast Requirements​

Contrast Ratios (WCAG 1.4.3, 1.4.11)​

Implementation​

Color Independence (WCAG 1.4.1)​

Keyboard Navigation (WCAG 2.1)​

Focus Order (WCAG 2.4.3)​

Focus Visibility (WCAG 2.4.7)​

Keyboard Operability (WCAG 2.1.1)​

No Keyboard Traps (WCAG 2.1.2)​

Semantic HTML & ARIA​

Use Semantic Elements First​

ARIA Attributes​

Required ARIA Patterns​

Touch Targets (WCAG 2.5.5)​

Minimum Size​

Spacing Between Targets​

Screen Reader Support​

Screen Reader Only Text​

Live Regions​

Skip Links​

Forms​

Labels (WCAG 1.3.1, 3.3.2)​

Error Identification (WCAG 3.3.1)​

Required Fields (WCAG 3.3.2)​

Images & Media​

Alternative Text (WCAG 1.1.1)​

Testing Requirements​

Automated Testing​

Manual Testing Checklist​

Test Command​

Compliance Checklist​

Perceivable​

Operable​

Understandable​

Robust​