Neo Accessibility & States

Required States per Component

Every interactive component must implement the full set of states listed below. Missing states are a blocking issue in design review.

Buttons (Primary, Secondary, Ghost)

State	Visual Treatment
Default	Standard styling as defined in component spec
Hover	Slight background lightening (Primary) or darkening (Secondary). Cursor: pointer.
Focused	3px offset focus ring in `--color-navy` (#0E172A). Visible on keyboard tab.
Active / Pressed	Background darkens slightly. Brief 100ms transition.
Disabled	Background: `--color-disabled` (#C4C4CF). Text: white (Primary) or `--color-disabled` (Secondary). Cursor: not-allowed. `aria-disabled="true"`.
Loading	Spinner icon replaces label text. Button remains same dimensions. `aria-busy="true"`.

Text Inputs

State	Visual Treatment
Default (Empty)	Placeholder text in `--color-disabled`. Border: 1px `--color-border`.
Filled	User text in `--color-navy`. Border: 1px `--color-border`.
Focused	Border: 2px `--color-purple` (#6B5EF8). Subtle box-shadow.
Error	Border: 2px `--color-destructive` (#E53835). Error message in `--type-caption` below input. `aria-invalid="true"`.
Disabled	Background: `--color-bg-light` (#F4F4F8). Text: `--color-disabled`. Border: 1px `--color-disabled`. `aria-disabled="true"`.
Read-only	Same as Filled but no cursor-text. `aria-readonly="true"`.

Toggle

State	Visual Treatment
Off	Track: `--color-border`. Knob: white, left-aligned.
On	Track: `--color-navy`. Knob: white, right-aligned.
Focused	3px focus ring around entire track in `--color-navy`.
Disabled (Off)	Track: `--color-disabled` (lighter). Knob: white. Cursor: not-allowed.
Disabled (On)	Track: `--color-disabled`. Knob: white. Cursor: not-allowed.

State	Visual Treatment
Default	`--type-label-lg`, `--color-navy` text, no background
Hover	Background: `--color-bg-light`. Text remains `--color-navy`.
Active / Selected	2px bottom border (`--color-navy` for tabs) or left border (for sidebar menu). Font weight: 600.
Focused	3px focus ring in `--color-navy` around the item.
Disabled	Text: `--color-disabled`. No hover effect. `aria-disabled="true"`.

<TabNav> (apps/web/src/components/ui/TabNav.tsx) implements two distinct ARIA patterns depending on mode:

Mode	Semantics
Route mode (items have `href`)	Plain `<nav>` + `<Link>` items. The active link gets `aria-current="page"` — no `role="tablist"`/`role="tab"`, since each item is a real page navigation rather than an in-page selection.
State mode (no `href`)	`role="tablist"` on the track, `role="tab"` + `aria-selected` on each item, `aria-controls={panelId}` pointing at the panel. Pair with a `role="tabpanel"` element carrying that same id.

Keyboard: state mode supports arrow-key roving focus (ArrowLeft / ArrowRight move and select the previous/next enabled tab, Home / End jump to the first/last enabled tab); disabled items are skipped. Route mode relies on standard link/tab-order navigation since items are <Link>s, not tabs. Touch target: items are 44px tall below the md breakpoint (h-11), meeting the minimum touch-target size on mobile. Focus ring: 3px solid rgba(107, 94, 248, 0.25) on every focusable item, in both modes.

Heading hierarchy

Exactly one <h1> per rendered route, supplied by <PageHeader> (apps/web/src/components/ui/PageHeader.tsx). Section layouts that own a PageHeader (admin, operator, settings, knowledge graph) mean their child pages must use <h2> for section headings rather than rendering a second PageHeader. <Breadcrumbs> (apps/web/src/components/layout/Breadcrumbs.tsx) renders a <nav> landmark above the page title, giving assistive tech a distinct region for hierarchical location separate from the <h1>.

Upload Cards (Document, Instagram)

State	Visual Treatment
Uploaded (Success)	Green check-circle. Border: `--color-border`.
In Progress	Animated progress bar in `--color-progress-blue`. Percentage text.
Failed	Red X-circle. Border: `--color-destructive`. Retry button visible.
Hover	Slight elevation (box-shadow) to indicate interactivity.
Focused	3px focus ring in `--color-navy` around the card.

Usage Credit Card

State	Visual Treatment
0% Used	Empty progress bar. Gray fill.
Normal (`<80%`)	`--color-progress-blue` progress bar fill.
High (80-100%)	`--color-brand-orange` progress bar. Warning text.
Overage (`>100%`)	`--color-destructive` bar exceeds track. Red OVERAGE badge. `role="alert"`.

Contrast Ratios

All text and interactive elements must meet these minimum contrast ratios against their backgrounds.

Element Type	Minimum Ratio	Standard
Normal text (`<18px` / `<14px` bold)	4.5:1	WCAG 2.1 AA
Large text (`>=18px` / `>=14px` bold)	3:1	WCAG 2.1 AA
UI components and graphical objects	3:1	WCAG 2.1 AA
Focus indicators	3:1	WCAG 2.1 AA

Token Contrast Verification

Foreground	Background	Ratio	Pass
`--color-navy` (#0E172A)	`--color-white` (#FFFFFF)	16.8:1	Yes
`--color-navy` (#0E172A)	`--color-bg-light` (#F4F4F8)	14.5:1	Yes
`--color-white` (#FFFFFF)	`--color-navy` (#0E172A)	16.8:1	Yes
`--color-purple` (#6B5EF8)	`--color-white` (#FFFFFF)	4.1:1	Borderline
`--color-destructive` (#E53835)	`--color-white` (#FFFFFF)	4.6:1	Yes
`--color-success` (#2E7D52)	`--color-white` (#FFFFFF)	5.4:1	Yes
`--color-disabled` (#C4C4CF)	`--color-white` (#FFFFFF)	2.0:1	No (decorative only)

--color-purple on white is borderline at 4.1:1. Use it only for focus rings (3:1 minimum for UI components) and large text. Never use it as small body text on white.

--color-disabled fails contrast on white. This is acceptable because disabled elements are not interactive, but always pair disabled visuals with aria-disabled so assistive technology communicates the state.

Focus Ring Specifications

Buttons (Primary, Secondary, Disconnect)

Property	Value
Style	Solid outline
Width	3px
Offset	3px (gap between button edge and ring)
Color	`--color-navy` (#0E172A)
Trigger	Keyboard focus (`:focus-visible`)

Property	Value
Style	Border change + box-shadow
Border	2px `--color-purple` (#6B5EF8)
Box-shadow	0 0 0 2px rgba(107, 94, 248, 0.2)
Trigger	Focus (`:focus`)

Toggle

Property	Value
Style	Outline around entire track
Width	3px
Offset	2px
Color	`--color-navy` (#0E172A)
Trigger	Keyboard focus (`:focus-visible`)

Use :focus-visible (not :focus) for buttons and toggles so that mouse clicks do not show the focus ring. Inputs use :focus because the ring doubles as a “currently editing” indicator.

WCAG 2.1 AA Compliance Checklist

Use this checklist when reviewing any new page or component.

Perceivable

All images have meaningful alt text or aria-hidden="true" for decorative images
Color is never the sole indicator of state (always paired with icon, text, or pattern)
Text can be resized to 200% without loss of content or functionality
Contrast ratios meet minimums listed above
Media content has captions or transcripts where applicable

Operable

All interactive elements are reachable via keyboard tab
Focus order follows a logical reading sequence (left-to-right, top-to-bottom)
Focus is visible on every interactive element (see focus ring specs above)
No keyboard traps — user can always tab out of any component
Modals trap focus within themselves until dismissed, then restore focus to trigger
No content flashes more than 3 times per second

Understandable

Form inputs have associated <label> elements or aria-label
Error messages identify the field and describe how to fix the error
Page language is set via lang attribute on <html>
Navigation is consistent across pages
Input purpose is identifiable via autocomplete attributes where applicable

Robust

HTML is valid and well-structured
ARIA roles, states, and properties are used correctly
Custom components expose correct roles (role="button", role="dialog", etc.)
Status messages use role="status" or role="alert" for live regions
Component state changes are announced to screen readers

Quick Reference

All Color Tokens

Token	Hex	Category
`--color-brand-blue`	#3B39A7	Brand
`--color-brand-orange`	#E47037	Brand
`--color-brand-salmon`	#E4AD8C	Brand
`--color-navy`	#0E172A	Core UI
`--color-purple`	#6B5EF8	Core UI
`--color-progress-blue`	#3B50E2	Core UI
`--color-destructive`	#E53835	Semantic
`--color-success`	#2E7D52	Semantic
`--color-bg-light`	#F4F4F8	Neutral
`--color-white`	#FFFFFF	Neutral
`--color-border`	#E2E2EA	Neutral
`--color-disabled`	#C4C4CF	Neutral

Key Sizes

Element	Dimension
Primary Button height	48px
Secondary Button height	37px
Text Input height	40px
Toggle track	56 x 27px
Toggle knob	21 x 21px
Icon standard	20 x 20px
Upload Card	347 x 86px
Usage Credit Card	359 x 199px

5 Key Rules

One Primary Button per view

Never place two navy 48px buttons on the same screen. Demote the less important action.

Red means destructive, always

--color-destructive is never decorative. Every red element signals danger or error.

Focus rings on everything interactive

Every button, input, toggle, link, and card that accepts interaction must show a visible focus indicator on keyboard navigation.

Never rely on color alone

Pair color with icons, text labels, or patterns. A colorblind user must be able to distinguish all states.

Confirm before destroying

Deletions, disconnections, and irreversible actions always require an explicit confirmation step.

Overview

Services

Architecture

Agent Provisioning API

Deployment

Design System (Neo)

Required States per Component

Buttons (Primary, Secondary, Ghost)

Text Inputs

Toggle

Navigation Items (Menu, Tabs)

TabNav (Sub-Navigation)

Heading hierarchy

Upload Cards (Document, Instagram)

Usage Credit Card

Contrast Ratios

Token Contrast Verification

Focus Ring Specifications

Buttons (Primary, Secondary, Disconnect)

Toggle

WCAG 2.1 AA Compliance Checklist

Quick Reference

All Color Tokens

Key Sizes

5 Key Rules

​Required States per Component

​Buttons (Primary, Secondary, Ghost)

​Text Inputs

​Toggle

​Navigation Items (Menu, Tabs)

​TabNav (Sub-Navigation)

​Heading hierarchy

​Upload Cards (Document, Instagram)

​Usage Credit Card

​Contrast Ratios

​Token Contrast Verification

​Focus Ring Specifications

​Buttons (Primary, Secondary, Disconnect)

​Inputs (Text, Dropdown, Search)

​Toggle

​WCAG 2.1 AA Compliance Checklist

​Quick Reference

​All Color Tokens

​Key Sizes

​5 Key Rules

Required States per Component

Buttons (Primary, Secondary, Ghost)

Text Inputs

Toggle

Navigation Items (Menu, Tabs)

TabNav (Sub-Navigation)

Heading hierarchy

Upload Cards (Document, Instagram)

Usage Credit Card

Contrast Ratios

Token Contrast Verification

Focus Ring Specifications

Buttons (Primary, Secondary, Disconnect)

Inputs (Text, Dropdown, Search)

Toggle

WCAG 2.1 AA Compliance Checklist

Quick Reference

All Color Tokens

Key Sizes

5 Key Rules