> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainstormer.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Neo Accessibility & States
> Required component states, contrast ratios, focus ring specifications, and WCAG 2.1 AA compliance checklist for the Neo design system.
## 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. |
### Navigation Items (Menu, Tabs)
| 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"`. |
### 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`) |
### Inputs (Text, Dropdown, Search)
| 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.
* 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
* 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
* Form inputs have associated `
* 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
Never place two navy 48px buttons on the same screen. Demote the less important action.
`--color-destructive` is never decorative. Every red element signals danger or error.
Every button, input, toggle, link, and card that accepts interaction must show a visible focus indicator on keyboard navigation.
Pair color with icons, text labels, or patterns. A colorblind user must be able to distinguish all states.
Deletions, disconnections, and irreversible actions always require an explicit confirmation step.