MTSS.ai design system

Geist across the product. One weight step per level (semibold for headings, regular for body), tight tracking on headings, relaxed leading on body. Numbers always use tabular figures so columns align. Body copy never goes below 12px.

A 4px base scale. Cards use 20px padding, sections stack at 24px, page zones at 32–48px. Radius is driven by --radius (12px): xl for cards, full for pills, lg for inputs and buttons.

Minimal palette: a slate canvas, one teal-blue primary, and semantic accents used sparingly. Tier and AI have dedicated hues so they read instantly. Every token has a dark-mode counterpart and meets WCAG AA against its paired foreground.

Status is never color-only: each badge pairs a dot with a text label so it survives color-blindness and grayscale printing. Tags are neutral metadata (domains, evidence level, skills) and can be removable.

Exactly one primary action per view — the answer to “what next?”. Secondary for supporting paths, ghost for in-card actions, destructive only behind a confirm dialog. Icon-only buttons always carry an aria-label and a 44px tap target on touch.

Lucide only, 16px inside text and controls, 20px standalone, stroke 2, currentColor. Icons are decorative by default (aria-hidden) and paired with text; when standalone they get an accessible name via IconChip.

Initials fall back when there is no photo. The ring color encodes the student's current tier, and the accessible name is always the full student name — never the initials.

card-soft is the default container: 1px border, xl radius, soft shadow, 20px padding. AI-authored content always sits in the ai tone so users can tell machine output from record-of-truth data at a glance.

Semantic table markup with a screen-reader caption and scoped headers. Surface-tinted header row, 1px row dividers, no zebra striping, numerics right-aligned and tabular. Tables scroll horizontally on mobile rather than reflowing into unreadable stacks.

Recharts styled entirely with chart-1…chart-5 tokens, so charts re-theme in dark mode automatically. Gridlines are subtle, axes are unlined, and every chart carries role='img' with a descriptive label plus a goal reference line where a decision rule exists.

The student record's spine. One rail, tone-coded dots, right-aligned dates, optional inline metadata. Used for referrals, plan changes, meetings, assessments and family contact in a single chronological stream.

Domain objects render the same everywhere: library, planner, student workspace and dashboards. An intervention always shows dosage (frequency, duration, group size), the responsible provider and fidelity. A meeting always shows when, where, who and whether AI prep is ready.

Every input has a real <label> bound by id. Hints sit under the field; errors replace the hint, use role='alert' and are announced. Required is marked with both an asterisk and the required attribute — never color alone. Prefer choosing over typing: chips, selects and AI drafts beat blank textareas.

Radix-backed: focus is trapped and restored, Escape closes, the title is the accessible name. Use dialogs for confirmation and short focused input only — multi-step work belongs in a wizard route, not a modal.

An empty state always names the next action — never a dead end. Skeletons mirror the shape of the content they replace and are aria-hidden; a polite live region announces loading for screen readers. Use skeletons for first paint, spinners only for user-triggered waits.

Dark mode is a token swap on the .dark class — no component knows about it. Surfaces lighten as they elevate (background → surface → card), borders become low-opacity white, and accent hues lift in lightness so contrast holds. Nothing pure-black or pure-white.

WCAG 2.1 AA is a build requirement, not a review step. These rules are enforced by the components above, so using the system keeps a screen compliant by default.