Aira Design System v1.1

Aira Design System v1.1 is organised around atomic design — Atoms → Molecules → Organisms → Templates — so every element is structured to map onto a Figma library. The product has one assistant voice (aiRA, shown only as the sparkle brand mark — no avatar), user avatars (initials), and custom-rendered form controls throughout.

Open this file in a browser. No build step. Toggle Light/Dark and LTR/RTL via the top bar.

AI fluency fixes

Recurring copy fixes that keep aiRA's language fluent, honest, and on-voice. Pairs with Voice rules and Refusal grammar.

Principles

• Can't / can / next. Every refusal names what it can't do, what it can, and the next step.
• One aiRA. No "the AI", no per-agent personas, no coder agent.
• Plain over precise-sounding. No jargon or error codes in user-facing copy.

Tokens & MCP

How design tokens reach code, and how aiRA reads the system to stay on-brand.

Token pipeline

• tokens/tokens.json (DTCG 2025.10) is the source. scripts/generate.js emits css/variables.css — CSS custom properties for light and dark.
• Prefix. Every custom property is emitted with the --aira-* prefix (e.g. --aira-bg-surface, --aira-sp-3) so the tokens coexist with Ant Design v3 variables in the same app without clashing. Components use the matching Aira* PascalCase prefix.
• Tailwind reads the same tokens as its theme, so utilities like bg-surface, text-secondary, rounded-md resolve to token values — components never hard-code hex, spacing, or radius.
• The same tokens.json publishes to Figma variables via Tokens Studio (see Figma bundle), so design, code, and Figma stay one source of truth.

Model Context Protocol (MCP)

An MCP server exposes the tokens, the component map, and Code Connect to aiRA. When the assistant drafts or edits UI, it can reference real component names (AiraButton, AiraDataTable…), token values, and usage examples — so generated output stays on-system instead of inventing one-off styles.

• Tokens resource — the resolved light/dark token set.
• Component map — AiraX names → props, variants, and the library each is built with.
• Code Connect — Figma node → React source, so Dev Mode and aiRA point at the same implementation.

About this file

This documents every part of the Aira Design System v1.1 — markup, tokens, behaviour, README, changelog, the Figma bundle (tokens.json in DTCG 2025.10, component map, Code Connect), and the system-wide Component status table. The source is now split into the tokens, css, and html/components folders; see the README for the build and serve steps.

Stack & sync

The designer reference (this file) and the developer reference (the Storybook React library) are one system in two surfaces. In code, components are named AiraX and built with:

• Primitives & a11y — @base-ui/react
• Variants & className — class-variance-authority · clsx · tailwind-merge
• Styling & motion — Tailwind CSS (tokens as theme + CSS variables) · tailwindcss-animate
• Icons — lucide-react
• State — xstate · @xstate/react (conversation, approval, streaming)
• Tables & lists — @tanstack/react-table · @tanstack/react-virtual
• Charts — recharts · d3
• Dates — date-fns

Each component section carries an Engineering handoff block with its AiraX name, the libraries it uses, and a React/Tailwind snippet. The full engineering contract is in Conventions.

Non-goals

• Not a runtime — this document ships no React; it's the spec the @aira/react library implements.
• No agent-identity fiction (one aiRA; no per-agent themes) and no coder agent.
• No design-only multi-brand constructs ahead of the developed v1 contract.

How to contribute

• Change a value in tokens/tokens.json, then run node scripts/generate.js && node scripts/bundle.js.
• Add or edit a component in html/components/<id>.html; keep its AiraX name and Engineering-handoff block in step with the Storybook.
• When the design and the developed reference diverge, the developed reference wins for naming and terminology.

README

open aira-design-system/index.html

aira-design-system/
  index.html        # full design system page   tokens.css        # all design tokens (light + dark)   CHANGELOG.md      # v1.1 release notes   README.md         # this file   assets/           # logo + fonts   figma/            # tokens.json, figma-components.md, code-connect.json 

Atoms       Button · Icon button · Input · Textarea · Chip · Tag · Badge · Pill
            Avatar · Citation chip · Tooltip · Kbd · Divider · Spinner · Skeleton
Molecules   Field · Dropdown (single · multi · searchable × sm · md · lg)             Checkbox · Radio (incl. disabled) · Toggle · Stepper · Progress             Feedback control · Action row · Tabs · Breadcrumb · Popover             Toast · Banner · Nudge card · Selection card
Organisms   Chat message · Composer · Approval card (with Type-to-confirm)             Code block · Inline diff · Agent activity (animated single-step +             todo-style multi-step) · Conversation state machine · Modal · Sheet             List row · Data table (column filters) · Card · Form · Change-log feed
Templates   Empty · Loading · Errors · My Configs · Mobile · Email × 4 

Logo & marks

The aiRA mark is a cluster of three four-pointed sparkles filled with the brand gradient (indigo-400 → sky-400). It is the app logo, launcher icon, and email/marketing brand mark — a logo element, not a conversational avatar or per-message speaking indicator.

Logomark

The gradient is decorative

Sizes

The mark scales from 12 px (inline meta) to 64 px (marketing hero). Keep the sparkle on a single stroke weight; do not redraw at small sizes.

Clearspace

Reserve at least 25% of the mark's height as clearspace around all four sides. Nothing intrudes — no text, no other glyphs.

Treatments

Construction

• Geometry. A cluster of three four-pointed sparkles — one large in the centre, two smaller ones anchored top-right and bottom-right. Proportions are fixed; never re-balance the cluster.
• Gradient. Linear, 0°, indigo-400 (#6268FF) → sky-400 (#3BA7FF), drawn across the bounding box of all three sparkles together. On dark surfaces, shift to the lighter pair: indigo-300 (#8E97FF) → sky-300 (#5EA8FF).
• Fill only. No stroke, no shadow, no outer glow, no container chip. The gradient fills the path directly.
• One artwork. The same SVG geometry renders at every size — never redraw, simplify, or thin the small sparkles for tiny renders.
• Minimum size. 12 px square. Below that, fall back to a single sparkle glyph from the icon set.

Logomark do / don't

Wordmark

Mixed case — lowercase "ai" leading, uppercase "RA" trailing — locked as one token: aiRA. Set in Roboto Medium. Never reorder the case; never spell it "AIRA". The wordmark is live type, not artwork — it is set in the running font, never traced or outlined.

Construction

• Case is locked. Lowercase ai, uppercase RA — together, one token. Never AIRA, Aira, or aira.
• Font. Roboto Medium (--fw-medium, weight 500). Letter-spacing -0.015em, line-height 1.
• Colour. Solid only. --text-primary on light; #FFFFFF on dark or on gradient. No gradient fill, no stroke, no shadow.
• Minimum size. 18 px font-size (≈ 14 px cap-height). Below that, use the sparkle alone.

Sizes

Set the wordmark at 18, 24, 32, 48 or 64 px font-size. Use the smallest size that remains comfortably legible on the surface.

Clearspace

Reserve clearspace equal to the cap-height of the "R" on all four sides of the wordmark. Nothing intrudes — no body copy, no buttons, no other glyphs.

Wordmark do / don't

Combination mark

The horizontal lockup pairs the sparkle and the wordmark into a single asset (aira-lockup.svg). It is the default presentation in product chrome — top bar, sign-in, email headers.

Construction

• Order. Sparkle always on the leading side (left in LTR, right in RTL). The wordmark never leads.
• Proportions. Sparkle square dimension = wordmark font-size in pixels. 24 px wordmark → 24×24 sparkle; 64 px wordmark → 64×64 sparkle.
• Gap. --sp-2 (8 px) at wordmark sizes ≥ 24 px. --sp-1 (4 px) below.
• Alignment. Optical centre to the x-height of the wordmark — not the cap-height.
• Treat it as one asset. Do not re-space, re-stack, recolour, or re-order the two elements independently. Ship as aira-lockup.svg.
• Minimum size. 20 px sparkle + 20 px wordmark. Below 20 px, drop the wordmark and use the sparkle alone.

Lockup do / don't

Engineering handoff

import { AiraLockup, AiraMark, AiraWordmark } from "@aira/react";

<AiraMark size={28} />        {/* sparkle only */}
<AiraLockup size={32} />      {/* mark + wordmark */}
<AiraWordmark />

Color

Two-tier system: raw primitives at the base, semantic tokens on top. Product code references semantic tokens only.

Slate · neutrals

Indigo · primary brand

indigo-600 (#3438C9) is the primary action colour — the fill used on every primary button across the system. Flagged below.

Sky · gradient end-stop

Status accents

aiRA gradient

Semantic chips

Surfaces & on-surface text

The backgrounds and the text colours that sit on them across the product shell — chat panel, artifact panel, cards, left rail, top bar and selected rows — in light and dark. Every value here is pixel-sampled from the product (light + dark) and mapped to a named semantic token; product code references the token, never the raw hex.

Surface map

On-surface text · contrast

Measured on the card surface (#FFFFFF / #131B2C) where this text actually sits. WCAG AA needs 4.5:1 for normal text; AAA needs 7:1.

On the bare canvas (#F6F8FA) text-tertiary dips to ~4.3:1 — keep tertiary on cards, or step up to text-secondary for muted text placed directly on the canvas. text-placeholder stays an intentional sub-AA hint (see Accessibility).

Developer semantic tokens

The full semantic set as it ships in the developer's Storybook, grouped the same way — Background, Text, Border — so design and code read off one list. These resolve to the primitives above; product code references the token, never the raw hex. The Surfaces & on-surface text block above is the curated in-app view of these same tokens.

Background

bg-default is the chat / app base — white in light, canvas-dark in dark (it's what --aira-surface-chat-bg resolves to). bg-elevated is the raised card surface (aliases the internal bg-surface, same value).

Text

Contrast for primary/secondary/tertiary is in the On-surface text · contrast table above. On bg-default (verified): text-link 8.2, text-success 8.0, text-danger 6.8, text-warning 6.2 (light) — all clear AA. text-inverse is for inverse surfaces only — it flips opposite the text-on-* tokens, so don't substitute one for the other. text-disabled is an intentionally low-contrast, WCAG-exempt disabled state — never use it for active text.

Border

border-brand is for brand-emphasis edges — it is not the focus ring (--aira-border-focus, indigo-300 in dark).

Do / don't

Color fidelity

Colors are authored in sRGB. Reference rendering is on a display calibrated to sRGB IEC61966-2.1, white point D65, gamma 2.2, at roughly 120 cd/m².

Why colors vary across machines

On uncalibrated panels — most Windows laptops, many external monitors — variation is expected in both light and dark mode. In light mode, panel white points drift cooler than D65, saturated mid-tones lose punch on sRGB-only panels, and hairline borders either vanish or harden. In dark mode, backlight bleed lifts near-black values into muddy grey-blue on IPS LCD while OLED renders them as nearly-off pixels. Four factors stack: display gamut (Mac displays cover P3; most Windows panels cover only sRGB), gamma curves, backlight characteristics, and browser color management (Safari respects the system ICC profile; Chrome and Edge on Windows are inconsistent).

What the system does

• Brand gradients use OKLCH interpolation so the midpoint stays vibrant across display gamuts.
• The dark canvas sits at #0E1424 — lifted slightly from true black so panels with backlight bleed render it as clearly dark rather than muddy grey-blue.
• Brand surfaces opt out of Windows forced-color overrides so the indigo primary stays indigo in High Contrast Mode.
• Light-mode rendering can't be hardware-corrected via CSS. Uncalibrated Windows panels with cool white points will render light surfaces with a faint blue cast that no code change resolves.

What product teams can do

• Review on a calibrated display when possible. A software calibration via OS settings gets most of the way.
• Spot-check on the cheapest Windows laptop common in your deployment — that's the floor.
• Trust the tokens. Don't tweak hex values to compensate for what you see on your own machine.

What can't be fixed in code

Ambient lighting, blue-light filters, panel hardware, OS calibration, and browser color-management quirks are outside the system's reach. Aim for consistency within the variance envelope each panel allows.

Typography

Roboto, Regular (400) + Medium (500) + Semibold (600). One ramp, used consistently.

Spacing

4 px base grid. Use the scale; no 10 px, 13 px, 22 px.

Radius & elevation

Radii

Elevation

Motion

Three durations. prefers-reduced-motion halts animation — does not speed it up.

Iconography

Icons are re-exported from lucide-react under aiRADS names via src/lib/icons.js. Defaults: size 20, strokeWidth 1.5, currentColor. Use the aiRADS name (e.g. Send, Regenerate, Workbook) — not the underlying Lucide name. AiraSparkle is the one custom mark (not in Lucide); the inline SVGs here are reference renders.

Interactive states

Every icon, when wrapped in an Icon button (or any interactive target), supports four states. The matrix below shows the contract on a representative icon — the same treatment applies to every icon in the grid above.

Do / don't

Engineering handoff

// re-exported from lucide-react under aiRADS names
import { Send, Regenerate, Workbook } from "@/lib/icons";

<Send />   {/* defaults: size 20 · strokeWidth 1.5 · currentColor */}
// use the aiRADS name (Send, Regenerate, Workbook), not the Lucide name

Data viz

Five guidelines, the right encoding for every data relationship, and a gallery of every chart format aiRA produces. Based on Cleveland & McGill's perceptual rankings and Schwabish's Better Data Visualizations.

Five guidelines

1. Show the data. Strip ornament. If the reader can't see the pattern you're communicating, simplify until they can.
2. Reduce the clutter. No 3D, no gradients on chart marks, no heavy gridlines. Every non-data element earns its place.
3. Integrate graphics and text. The title is the takeaway, not the topic. Annotate moments directly on the chart.
4. Avoid the spaghetti chart. Past four-to-six series, highlight-and-gray or break into small multiples.
5. Start with gray. Add colour only where it carries meaning. Forces intentional choices and creates visual hierarchy.

Perceptual ranking

Encodings ranked by how accurately the eye reads them (Cleveland & McGill). Use higher-ranked encodings when precision matters.

Choosing the chart — by data relationship

Bar chart · vertical

The workhorse. Length on a common baseline reads accurately. Always start the value axis at zero. Sort by value unless a natural order exists.

Bar chart · horizontal

Use horizontal when labels are long. Sort descending by default.

Paired bar chart

Two values per category, side by side. Limit to two groups; beyond that, switch to a slope chart or dot plot.

Stacked bar chart

Total + composition. Only the bottom segment shares a baseline — put the most important there. Limit to three to five segments.

Diverging bar chart

Bars extend in two directions from a central baseline. Use for data with a natural midpoint — satisfaction, sentiment, percent change.

Dot plot · dumbbell

Two dots per row, connected by a line. Shows the gap between two values across many categories — clearer than paired bars when the values are similar.

Heatmap

Grid of cells coloured by value. Two categorical axes, one quantitative measure. Sequential palette for a single measure; diverging when there's a midpoint.

Waffle chart

10×10 grid of squares. Each square is one percent. More tangible than a pie for a single statistic — "23 of every 100 members".

Line chart

The default for time series. Limit to four-to-six lines; beyond that, highlight-and-gray or small multiples.

Line chart · highlight-and-gray

When showing many series, color only the lines that carry the story. Everything else stays neutral.

Area chart

Line chart with filled area below. Emphasises magnitude. Don't stack more than four-to-five series.

Slope chart

Two vertical axes connected by lines. Shows direction and magnitude of change across many categories at once.

Sparkline

Tiny inline chart — no axes, no labels. Used in tables and KPI tiles to add trend context to a single number.

Histogram

Bars showing frequency per bin. Bars touch — gaps are reserved for categorical bar charts.

Box-and-whisker plot

Median, IQR, and outliers in compact form. Requires statistical literacy — annotate parts for general audiences.

Scatterplot

Dots on two continuous axes — the go-to for showing correlation. Use transparency when dots overlap; label outliers directly.

Treemap

Nested rectangles, area encodes value. For hierarchical data. Area is imprecise — use for broad patterns, not lookup.

Pie chart · use sparingly

Only for two-to-three slices when the approximate proportion is the point. Never 3D, never exploded. With more slices, switch to a stacked bar or waffle.

Donut chart · use sparingly

Same constraints as a pie — two to three segments, single insight. The hole in the centre is a natural place to surface the headline number. Preferred over a pie when the dataset has a clear total worth calling out.

Categorical · 6 series

Unordered groups. Distinct, equally vivid hues. Limit to six.

Channel · locked taxonomy

WhatsApp is always green; Push is always indigo; Email is always teal. Users learn the taxonomy once. Push and Email use clearly different hues (indigo vs teal) — not two neighbouring blues — so they stay easy to tell apart, including under colour-vision deficiency.

Sequential · single hue

For ordered data (low → high). Single hue varying in lightness.

Diverging · with midpoint

For data with a natural neutral midpoint — sentiment, percent change. Two hues diverging from neutral.

Delta semantics

Green for positive change · orange for negative change. Red is reserved for errors and destructive actions — never the default for "down" deltas in a chart.

Data table · with sparklines

Tables are visualisations too. Right-align numbers, light horizontal rules only where needed, sparklines for trend context.

Table design — ten rules

1. Remove or minimise borders and fills — let whitespace organise.
2. Light, thin horizontal rules only where needed.
3. Remove vertical rules entirely.
4. Right-align numbers, left-align text.
5. Consistent precision within a column.
6. Guide the eye with alignment, not lines.
7. Highlight key values with weight, colour, or background.
8. Add sparklines or inline bars for trend context.
9. Limit columns — past fifteen, split or chart.
10. The title states the finding, not "Table 1".

Numeric formatting

• Use tabular numerals so digits line up vertically in tables.
• Match precision to what the reader needs — a compact "14.2L" / "1.4M" beats "1,421,540" in a dashboard.
• Put the unit on the value, not on every gridline.
• Round consistently. Don't show 8.234% next to 12% in the same column.
• No hard-coded prefixes. The currency symbol, digit grouping (1,23,456 vs 123,456), and decimal style are resolved dynamically from the brand's locale and currency at render time — never baked into the component. The same chart renders ₹, $, or € purely from brand config.

Active titles

The title is the takeaway. "Active members grew 14% over six months" beats "Active members over time".

Accessibility

• Never rely on colour alone — pair with shape, pattern, label, or direct annotation.
• About 1 in 20 people have a colour-vision deficiency. Avoid red-green as the only distinction.
• Charts must remain readable in grayscale.
• Provide an accessible name on every chart SVG.

Implementation checklist

• Title states the insight, not just the topic.
• Non-data elements (gridlines, borders, fills) are minimal.
• Colour is intentional, not decorative.
• Chart type matches the data relationship.
• Bar charts start at zero.
• No 3D, no gradient fills on chart marks.
• Series labelled directly where practical — not just a legend.
• Chart works in grayscale.
• Key findings called out by annotation.
• Data source is credited in a subtitle or footnote.

Do / don't

Engineering handoff

import { AiraBarChart, AiraMetricTile } from "@aira/react/charts";

<AiraBarChart data={data} xKey="store" yKey="sales" />
<AiraMetricTile label="Active members" value={12481} delta={+4.2} />
// 17 chart components wrap recharts; scales/axes/interpolation from d3

Approval status tokens

Six lifecycle states with paired surfaces.

• Draft — not yet submitted.
• Awaiting approval — submitted, with a reviewer.
• Upcoming — approved and scheduled, not yet live.
• Approved — signed off, no schedule required.
• Live — currently active in production.
• Rejected — declined; reason persisted on the card.

Code & syntax tokens

Single-tone palette; no carnival-coloured highlighting. Tokens used in Code block.

Safe area

Honour the device notch and home indicator on mobile surfaces (sheets, app bars).

Tokens

On Android WebView (Chrome 88+), env(safe-area-inset-*) resolves once the app sets WindowCompat.setDecorFitsSystemWindows(window, false) and the manifest declares android:windowLayoutInDisplayCutoutMode="shortEdges". The CSS contract is identical to iOS — write tokens, not platform branches.

Do / don't

Responsive

Same tokens, retuned for touch. Scale up the hit targets, drop the density, and keep the visual rhythm consistent across Windows, macOS, iPadOS, and Android.

Breakpoints

Mobile-first. Layouts collapse top-down.

Hit targets

Minimum tappable area per surface. Always pass the largest constraint that applies.

Type-scale tweaks

Headings step down one notch on sm; body stays.

Platform consistency · Windows ↔ macOS ↔ iOS ↔ Android

Tokens are platform-agnostic. The only platform-aware pieces are scrollbar width, native focus-ring colour, and font-smoothing — all handled by the design system shell.

Layout adaptation

How the aiRA chat surface restructures across breakpoints.

Do / don't

Voice rules

Voice is part of the design. Nine hard rules.

1. Sentence case. Titles, buttons, labels — all sentence case. Avoid Title Case unless it's a proper noun.
2. Active voice. "aiRA created the promotion" not "The promotion was created."
3. One exclamation per first session. No exclamation marks elsewhere.
4. No marketing language. "Set up the campaign" not "Unleash your campaign magic."
5. Don't apologise reflexively. If aiRA can't do something, say what it can, then what's next.
6. Don't anthropomorphise. aiRA does not "think", "feel", or "hope". It does work.
7. Numbers in numerals, even for one-digit. "5 items left." Easier to scan.
8. Plain verbs in activity rows. "Querying analytics" not "Executing query_engine_v3".
9. Refusal grammar follows the can't / can / next template. See below.

Do / don't

Refusal grammar — can't / can / next

When aiRA can't fulfil a request, the response has three parts: what it can't do, what it can, and what to do next.

Button

Four variants, three sizes. Primary indigo-600 fill. The single canonical button atom — no per-context one-offs.

Variants

Sizes

Properties

Do / don't

Engineering handoff

import { AiraButton } from "@aira/react";

<AiraButton variant="primary" size="md">Save</AiraButton>
<AiraButton variant="secondary">Cancel</AiraButton>
// variant/size resolved by class-variance-authority; classes merged with tailwind-merge

Icon button

Single-icon affordances. 32 px default; 44 px touch. Use the Stop icon only for halting an in-flight aiRA generation.

Sizes & states

Stop icon (Generating state)

The same Stop icon as the default state — a circle with a filled square, on the neutral icon-button surface. Indicates active generation; clicking it stops aiRA. No indigo fill: the generating state must not look like a primary action.

Do / don't

Engineering handoff

import { AiraIconButton } from "@aira/react";
import { Upload } from "lucide-react";

<AiraIconButton aria-label="Upload" size="md"><Upload /></AiraIconButton>

Input

36 px default. Ten states.

Do / don't

Engineering handoff

<AiraInput value={v} onValueChange={setV} placeholder="aiRA" invalid={!!error} />

Textarea

Multi-line input. Resizable on the Y axis only.

Do / don't

Engineering handoff

<AiraTextarea rows={3} value={v} onValueChange={setV} />

Chip

Neutral metadata tag, removable. Carries an optional dot for status semantics.

Do / don't

Engineering handoff

<AiraChip tone="success">Live</AiraChip>

Tag

Categorical label. Larger surface than a chip; no dot.

Do / don't

Engineering handoff

<AiraTag>Beta</AiraTag>

Badge

Count or numeric indicator. Sits on top of a parent surface.

Do / don't

Engineering handoff

<AiraBadge count={3} />

Pill (status)

Lifecycle states across approvals, scheduled jobs, and content. Six variants.

Properties

Do / don't

Engineering handoff

<AiraPill status="upcoming">Upcoming</AiraPill>

Avatar

Avatars are for the human user only — initials on the canonical gradient (--avatar-grad). aiRA has no avatar: its visual identity is the sparkle brand mark (see Logo & marks) — a logo element, never a per-message speaking avatar or profile image.

User avatar — initials

Do / don't

Engineering handoff

<AiraAvatar name="Punya Shetty" size="sm" />
{/* user avatars only — aiRA has no avatar; use <AiraMark /> for the brand mark */}

Citation chip

RAG provenance. Real <a href> links. Hover lifts the border + text to brand.

Inline

Hover & focus

Hover or keyboard-focus brightens the border (--citation-border-hover) and shifts the text to brand colour (--citation-text-hover).

Appended list

Do / don't

Engineering handoff

<AiraCitationChip index={1} href="#source-1">Proposal #4421</AiraCitationChip>

Tooltip

Short explainer on hover/focus. Surface is --tooltip-bg (slate-700 — softer than near-black) with white text at about 10 : 1 contrast.

Do / don't

Engineering handoff

<AiraTooltip content="Copy">
  <AiraIconButton aria-label="Copy"><Copy /></AiraIconButton>
</AiraTooltip>
// wraps @base-ui/react Tooltip; enter/exit via tailwindcss-animate

Keyboard (kbd)

Visualises a key in a shortcut. Use sparingly — inline help, command palette docs, the Selection card keyboard hint.

Shortcuts — Mac & Windows

Always document both platforms. Mac uses ⌘ (Command) and ⌥ (Option); Windows uses Ctrl and Alt. Detect the user's OS and show the matching row at runtime; list both in docs.

Engineering handoff

<AiraKbd>⌘</AiraKbd> <AiraKbd>K</AiraKbd>

Divider

1 px horizontal rule using --border-default.

Engineering handoff

<AiraDivider />   {/* @base-ui/react Separator */}

Spinner

Indeterminate progress. 14 px default.

Engineering handoff

<AiraSpinner size="sm" />   {/* animate-spin */}

Skeleton

Placeholder for loading content. Hide from assistive tech (aria-hidden).

Engineering handoff

<AiraSkeleton className="h-4 w-40" />   {/* shimmer */}

Field

Composed label + control + helper + error. The shape every form control uses.

Accessibility

• Pair label[for] ↔ input[id].
• Use aria-describedby to associate the helper with the input.
• Error message: announce via aria-describedby in addition to the visual border colour.

Engineering handoff

<AiraField label="Email" hint="Work address" error={error}>
  <AiraInput name="email" />
</AiraField>
// @base-ui/react Field wires label, description & validity

Dropdown

The canonical custom-rendered form-select molecule. Three variants (single · multi · searchable) × three sizes (sm · md · lg) — maps directly onto a Figma 3 × 3 variant matrix. Never use the native <select>; behaviour is fully controlled in CSS and JS.

Variant · single

Single-choice selection. Caret on the right; menu opens below.

Variant · multi

Checkbox rows inside the menu; trigger shows a count chip. Closing commits the selection.

Variant · searchable (combobox)

Input-driven; type to filter. The menu shows a search input above results when the option set is large.

States — loading & empty

Stacking & overflow

Open menus sit at z-index: 40 over sibling content. Max-height is 280 px; longer lists scroll internally. Menus never push the section below off-screen, and they always render above later content — fixing the v2 combobox overlap bug.

Properties

Accessibility

• Trigger: aria-haspopup="listbox" + aria-expanded.
• Menu: role="listbox" with aria-multiselectable on multi.
• Each option: role="option" with aria-selected.
• Esc closes; ↑/↓ navigate; Enter selects (and closes single, keeps menu open for multi).

Do / don't

Engineering handoff

<AiraDropdown items={members} value={id} onValueChange={setId} searchable />
// @base-ui/react Select/Combobox; long lists virtualized with @tanstack/react-virtual

Checkbox

Multi-select within a group. Wrap with <fieldset> + <legend>.

Do / don't

Engineering handoff

<AiraCheckbox checked={on} onCheckedChange={setOn}>Email me</AiraCheckbox>

Radio

Exclusive selection. Always wrap in <fieldset> + <legend>. The disabled state is documented explicitly.

States

• Default — empty circle.
• Selected — filled brand dot inside the circle.
• Disabled — greyed, cursor not-allowed.
• Disabled-selected — selected and locked. Used when policy pins a value.

Do / don't

Engineering handoff

<AiraRadioGroup value={v} onValueChange={setV}>
  <AiraRadio value="gold">Gold tier</AiraRadio>
</AiraRadioGroup>

Toggle

Binary on/off that takes effect immediately. For settings that need an explicit Save, use a Checkbox in a form.

Do / don't

Engineering handoff

<AiraToggle checked={on} onCheckedChange={setOn} />   {/* @base-ui/react Switch */}

Stepper

Ordered multi-step flow.

Engineering handoff

<AiraStepper value={n} min={0} max={10} onValueChange={setN} />

Progress bar

Determinate progress for known durations.

Engineering handoff

<AiraProgress value={62} />   {/* @base-ui/react Progress */}

Feedback control

Two bare icon buttons — thumbs-up means like, thumbs-down means dislike — sitting inline with the action row. No pill, no container, no divider. The selected thumb fills with the link colour. The signal is recorded inline on click; thumbs-down does not open a reason picker.

Do / don't

Engineering handoff

import { ThumbsUp, ThumbsDown } from "lucide-react";

<AiraFeedback value={vote} onValueChange={setVote} />
// thumbs = like / dislike; dislike records inline, no reason picker

Action row

Inline actions under an aiRA reply — Copy · Support · Feedback (thumbs-up = like, thumbs-down = dislike). Support opens help; thumbs-down records the signal inline and does not open a reason picker. Keyboard focus uses the global :focus-visible ring; no per-action override.

Engineering handoff

<AiraActionRow onCopy={copy} onSupport={openHelp} value={vote} onVoteChange={setVote} />
// Copy · Support · Feedback — icon-only (lucide-react)

Tabs

Local navigation between views of the same data.

Engineering handoff

<AiraTabs value={tab} onValueChange={setTab}
  items={[{ id: "result", label: "Result" }, { id: "sql", label: "SQL" }]} />
// @base-ui/react Tabs (roving focus, aria-controls)

Breadcrumb

Hierarchical location indicator. Useful inside multi-step configurators.

Engineering handoff

<AiraBreadcrumb items={[{ label: "Home", href: "/" }, { label: "Loyalty" }]} />

Popover

Rich content with actions. Footer buttons are right-aligned; primary on the far right.

Rule

Popover footer actions are right-aligned. Primary action sits on the far right. Tertiary or destructive actions sit to its left.

Do / don't

Engineering handoff

<AiraPopover trigger={<AiraButton>Filters</AiraButton>}>…</AiraPopover>
// @base-ui/react Popover; positioned with its anchor

Toast

Transient notification. Auto-dismisses; reserves for non-critical confirmations.

Do / don't

Engineering handoff

const { toast } = useAiraToast();
toast({ title: "Promotion created", tone: "success" });
// @base-ui/react Toast provider

Banner

Inline page-level message. Persistent until dismissed.

Do / don't

Engineering handoff

<AiraBanner tone="warning">Multi-brand mode is on.</AiraBanner>

Nudge card

Suggestion or prompt presented next to the chat surface. Blue left-border accent.

Do / don't

Engineering handoff

<AiraNudgeCard title="38% of top customers spend on Saturdays" onDismiss={hide} />

Selection card

Disambiguation step. Keyboard-first, escape-to-skip, and — when the listed options don't fit — a free-text composer the user can open and type a full paragraph into. Option rows and the "Something else" row use visually distinct hover treatments so the two never look like the same target.

Default — pick one

2–5 numbered interpretations. Click a row, press 1–5, or arrow + Enter. "Something else" opens the free-text box below — it never forces a listed answer.

Free text — type a paragraph

When the user picks "Something else," the card swaps the list for a composer. It opens at two lines and auto-grows as they type, up to ~7 lines, then scrolls internally — so a one-liner and a full paragraph both fit without the card jumping. Click in and type; Send enables once there's text.

Free text — filled (paragraph)

The same composer holding a multi-line paragraph. It has grown to fit the content; past ~7 lines it caps and scrolls inside the field, and Send is enabled because there's non-empty text. Edit it freely — it re-flows as you go.

Open-ended — no preset options

When aiRA can't enumerate sensible choices, skip the list entirely and lead with the composer. Same control, no numbered rows — for "describe it in your words" moments.

Variants

Interaction matrix

Option rows and "Something else" use different hover surfaces so they read as separate affordances; the free-text field is a real, focusable input.

Properties

Do / don't

Engineering handoff

<AiraSelectionCard
  title={question}
  options={options}                  {/* omit for open-ended */}
  value={choice} onValueChange={setChoice}
  allowFreeText freeTextValue={text} onFreeTextChange={setText}
  maxRows={7} submitOnEnter
  onSubmitText={handleSubmit} onSkip={handleSkip}
/>

To-do list

Interactive checklist with check-off. Items strike through and fade once complete. Used in onboarding, multi-step setup flows, and anywhere a small set of discrete tasks needs visual progress.

Default

Anatomy

• Item — checkbox + label. Whole row is clickable. Hover lifts background to hover surface.
• Done state — checkbox fills with brand colour; label strikes through and shifts to tertiary text.
• Progress line — "X of N done", live-region-polite so screen readers announce updates.

Interactions

• Mouse — click anywhere on the row to toggle.
• Keyboard — Tab moves between items; Space toggles. Each item is a real input[type="checkbox"].
• Transition — 200 ms fade + strike-through (reduced-motion replaces with an instant snap).

Do / don't

Engineering handoff

<AiraTodoList items={items} onToggle={toggle} />
// progress label derived from checked count

Chat message

Three message types. aiRA's reply free-flows as plain text — no avatar, no aiRA sparkle mark, no agent label, no badge, no chip anchoring the start of the message.

Variants

Anatomy

• Thread — role="log" aria-live="polite"; new messages announce.
• User message — grey pill, end-aligned, max 80% width.
• aiRA reply — free-flowing body with no avatar and no badge above the prose. Body wraps in role="status" aria-live="polite".
• System — single quiet line in tertiary text. Metadata, not announced.
• Error — inline alert block with role="alert".

Do / don't

Engineering handoff

<AiraChatMessage role="user">Show last month’s sales by store.</AiraChatMessage>
<AiraChatMessage role="ai">{markdown}</AiraChatMessage>
// roles: user · ai · system · error. aiRA reply free-flows (no avatar). Times via date-fns

Composer

Input area with attach, voice, send. While aiRA is generating, the send icon swaps for the Stop icon — clicking it interrupts generation and keeps the partial output. Agents are never disabled; they're stopped.

Default · empty (idle)

This is the conversation's idle state: the input is auto-focused with the caret blinking, so the user can start typing immediately — no click needed. The input itself is the live region. The Send button stays disabled until the user types; disabled uses the neutral disabled surface, and the gradient never lives on this control.

Default · with text

Once the input has content, Send enables and renders in the primary action colour (indigo-600). No gradient — gradients are reserved for the aiRA mark.

Generating state

The send icon is replaced by the enabled Stop icon. Placeholder reads "Generating…". Clicking Stop transitions the conversation state to aborted; partial output is preserved.

Read-only (conversation locked)

For historical or shared sessions where the user can read but not send.

Do / don't

Engineering handoff

<AiraComposer
  state={state.value}      // idle | thinking | streaming
  onSend={text => send({ type: "SEND", text })}
  onStop={() => send({ type: "STOP" })}
/>
// Send swaps to Stop while streaming (driven by the conversation machine)

Approval card

aiRA proposal awaiting human review. Header is the proposal title only — no agent badge. High-risk variants use the Type-to-confirm pattern.

Default

Status variants

Six lifecycle states — these status variants are mainly for configurations. Status pill on the left of the footer; primary action shifts per state.

High-risk · Type-to-confirm

Production-affecting, irreversible, security-relevant, or financial changes require a secondary confirmation. On Accept click, the footer Accept button swaps in place for a slim input (placeholder "Type APPROVE to confirm") + a Confirm button — both disabled until the input matches APPROVE (case-insensitive). Edit remains reachable. The Confirm button uses the primary indigo colour — not red — at the same compact size as a routine primary action; no giant outsized button.

Diff overflow behaviour

Risk flagging rules

• Production-affecting — any change whose audience or schedule expands. Surface a risk pill in the header.
• Irreversible — deletions, archival, schema changes. Require Type-to-confirm.
• Security-relevant — RBAC, audience PII filters, data-source connections. Approval shows the reviewer's name + timestamp; an audit-log entry is written.
• Financial — multipliers, coupon values, payout caps. Require Type-to-confirm + restate the financial impact in plain language.

Do / don't

Engineering handoff

<AiraApprovalCard
  proposal={proposal}
  riskLevel="high"        // swaps Create for type-to-confirm
  onEdit={edit} onCreate={create}
/>
// lifecycle (draft→awaiting→upcoming→approved→live) via xstate; dates via date-fns

Code block

First-class output for SQL and scripts. Language badge and a Copy action.

function normaliseRow(row) {
  // Drop fields not in target schema
  const { id, amount, currency } = row;
  return { id, amount: Number(amount), currency: currency || 'INR' };
}

Engineering handoff

<AiraCodeBlock lang="javascript" showCopy>{code}</AiraCodeBlock>

Inline diff

A line-by-line before → after view of a change aiRA proposes, so a reviewer can see exactly what moves before approving. Red lines marked − are being removed; green lines marked + are being added; plain lines are unchanged context. Used inside Approval cards and the Change-log feed.

How to read it

• A red line followed by a green line on the same line number is one edit. Here, line 3 changes points_multiplier from 1.5 to 2.0 — read it top-to-bottom as old → new.
• A lone green + line is brand-new. Line 4 adds free_shipping; nothing was removed.
• Sign and colour always travel together (−/red, +/green), so the diff still reads in greyscale and for colour-vision deficiency — never colour alone.
• Context lines stay so you can see where the change lands in the surrounding config.

Do / don't

Engineering handoff

<AiraInlineDiff before={oldYaml} after={newYaml} />
// line diff (d3-array); +/− paired with colour for grayscale & CVD

Agent activity

Streaming disclosure of what aiRA is doing. Use the single-step row for one task; the multi-step list when several steps run in sequence.

Single-step

One row: spinner + step verb + optional detail. Use plain verbs — no internal job IDs.

Multi-step · todo list

Each step starts empty; the indicator fills on activation and locks to a check mark when complete. Completed rows strike through with faded text, like ticking items off a list.

Do / don't

Engineering handoff

<AiraAgentActivity steps={steps} current={i} />
// reflects thinking / streaming states from the conversation machine

Conversation state machine

An AI turn has seven stops. The table below maps every state to its visible UI, user affordance, and live-region behaviour.

Transition rules

Each transition is driven by exactly one trigger. Read every row as: from this state, this trigger moves the turn to the next state.

Two rules hold across every transition:

• No empty streaming. thinking → streaming fires only on the first real content token. If thinking runs past 10 s with no token, append "Still working — taking longer than usual" to the activity row; never auto-cancel.
• aiRA's state never disables the composer. While streaming, the Send icon swaps to the Stop icon (Stop, don't disable). Read-only treatment is reserved for locked conversations — shared sessions and audit views.

Engineering handoff

import { useMachine } from "@xstate/react";
import { conversationMachine } from "@aira/react/machines";

const [state, send] = useMachine(conversationMachine);
// states: idle → userSent → thinking → streaming → done | aborted | error
// transitions are the single source of truth for composer + activity + chat

Modal / Dialog

For confirmation, destructive actions, validation prompts, and short forms.

Warning · destructive action

Use when the user is about to do something destructive, irreversible, or financially material. Icon-led headline, plain-language consequence, danger primary action.

Validation · confirm navigation

Use when leaving a step would change or discard work already entered elsewhere. State the consequence plainly and let the user choose to stay or go back.

Validation · fix before continuing

Use when the user tries to advance with missing or invalid fields. Name exactly what needs attention; one primary action takes them back to fix it. Nothing is discarded.

Accessibility — warning modal

• Role is alertdialog (not dialog) so assistive tech announces it as a warning.
• Title and warning icon are both visible; never rely on the icon alone.
• Primary action is the danger variant. Cancel sits to its left.
• Esc dismisses. Focus traps within; on close, focus returns to the trigger.

Do / don't

Engineering handoff

<AiraModal open={open} onOpenChange={setOpen} title="Send for approval?">…</AiraModal>
// @base-ui/react Dialog; role="alertdialog" for destructive / validation

Bottom sheet

Mobile escalation of Modal. Honours --safe-bottom.

Do / don't

Engineering handoff

<AiraBottomSheet open={open} onOpenChange={setOpen}>…</AiraBottomSheet>
// @base-ui/react Dialog (bottom placement); honours safe-area insets

List row

Chat history rail — a narrow sidebar pinned to the left of the chat surface listing previous sessions (a common chat-history convention). Each row is a single click target. An export marker on the right shows how many times the session was exported (FTP push, CSS download, or workbook download).

Anatomy

• New chat button. The + in the "Sessions" header starts a new chat. On hover it shows a clear background and a "New chat" tooltip; on click it opens a fresh session — a new active row is prepended to the top of the list and the previously active row is deselected. (The demo above is live — try it.)
• Width. 260 px on desktop. The rail is narrow on purpose so the chat surface owns the viewport.
• Row. One title (max two lines, ellipsis after), one timestamp, and an optional export marker on the trailing edge.
• Selected state. Active session uses --bg-selected with a 3 px --border-focus leading border.
• Export marker. Up to three distinct icon pips (FTP / workbook / CSS) followed by a total count. Repeats of the same type collapse into the single pip — the count carries the multiplicity.

Do / don't

Engineering handoff

<AiraListRail>
  {sessions.map(s => (
    <AiraListRow key={s.id} title={s.title} time={s.time} active={s.id === current} />
  ))}
</AiraListRail>
// AiraListRail virtualizes long histories with @tanstack/react-virtual

Data table

Every column header carries the same sort icon — two opposing arrows (one down, one up). A click cycles ascending → descending → unsorted. The icon never changes shape; only its colour reflects state (slate-500 idle, indigo-600 active). aria-sort on the header carries the order for assistive tech. No filter icons in headers.

Default · sortable

Sort states

One icon, three states. Shape stays the same on every header; colour and aria-sort carry the meaning.

Do / don't

Engineering handoff

import { AiraDataTable } from "@aira/react";

<AiraDataTable columns={columns} data={rows} />
// sorting/columns via @tanstack/react-table; rows virtualized with @tanstack/react-virtual

Card

Generic container. Use only when the content needs visual elevation; otherwise prefer a plain section.

Do / don't

Engineering handoff

<AiraCard title="Weekend boost" footer={<AiraButton>Open</AiraButton>}>…</AiraCard>

Form

Standard composition — field stack + actions footer.

Do / don't

Engineering handoff

<form onSubmit={onSubmit}>
  <AiraField label="Program name"><AiraInput name="name" /></AiraField>
  <AiraButton type="submit">Save</AiraButton>
</form>
// validation surfaced through @base-ui/react Field

Change-log feed

A product UI pattern for visualising change history inside aiRA — e.g. a loyalty-program edit timeline, a Config audit trail, or "What changed since you last looked." Vertical timeline with grouped entries.

Anatomy

• Filter strip — change-type multi-select + date range.
• Day group — header label above an entries cluster.
• Entry — actor avatar · name · change-type tag · timestamp · summary · optional diff or citation.
• Timeline — vertical gutter with a small dot per entry.
• Empty state — "No changes in this period" with a "Clear filters" CTA.

Change-type tags

Do / don't

Engineering handoff

<AiraChangeLogFeed entries={entries} groupBy="day" />
// relative timestamps via date-fns; long feeds virtualized with @tanstack/react-virtual

Empty states

Specific copy that names what's missing and offers a next step. Never a generic "No results".

Loading & streaming

Three loading patterns. Choose by the work being done.

Spinner — single short task

Skeleton — content shell

Agent activity

Engineering handoff

// streaming is a state machine, not a boolean
const [state] = useMachine(conversationMachine);
{state.matches("thinking") && <AiraAgentActivity … />}
{state.matches("streaming") && <StreamedTokens … />}

Error handling

Errors are first-class UI. Plain-language reason, then what to do next. Never a stack trace.

My Configs

A list of saved configurations the user can reuse — list-row organism with the config name and a status pill.

Mobile preview

Desktop is the primary surface; mobile honours safe-area tokens for sheets and bottom CTAs. The mobile composer keeps the full attach · voice input · send affordances — voice input is first-class on mobile, not desktop-only.

Engineering handoff

<AiraBottomSheet open={open} onOpenChange={setOpen}>…</AiraBottomSheet>
<AiraComposer voiceInput />   {/* mic affordance is first-class on mobile */}

In context

Tokens applied to the aiRA surface. The same theme switch flips every element below — sidebar, header, tabs, metric cards, alert — with no layout shift and no contrast loss. Toggle the Dark button in the top bar and watch the cascade.

Every surface above is composed from semantic tokens — --bg-surface, --bg-surface-alt, --bg-selected, --border-default, --text-primary, --text-tertiary, --text-link, --delta-positive, --delta-negative. Toggling the theme on the top bar re-resolves every one of those — no per-component override needed.

Engineering handoff

<div className="grid grid-cols-2 gap-4">
  <AiraMetricTile label="Tier 1 spend" value="₹14.2L" delta={+12} />
  <AiraSparkline data={trend} />
</div>

Email templates

Four transactional templates aiRA sends. Shared rules apply to all four — listed once below.

Shared rules

• Hardcoded hex values. Email clients strip CSS variables. Copy resolved values from tokens.css at build time.
• Table-based layout for any structural layout that must survive Outlook 2016+ on Windows. Flex and grid are not safe.
• One CTA. Never two primary buttons of equal weight.
• Width 560 px max. Wider templates clip on mobile clients.
• No gradients in email. Solid colours only.
• No tracking pixels. Use Capillary's transactional pipeline only.
• Reply-to a routable address if the email surfaces reply-based affordances.

Template · Share session

Sent when a user shares a chat session with a colleague.

Template · Approval request

Sent when a reviewer is asked to approve an aiRA proposal.

Template · Scheduled-run result

Sent when a scheduled aiRA job completes (daily / weekly digest).

Template · Daily digest

A morning summary of pending items the user owns.

Do / don't

Accessibility

WCAG 2.2 AA is the floor for text and interactive elements. Key pairings are checked in light and dark below (ratios rounded). Placeholder text is the one intentional exception — it sits below AA as a supplementary hint, and every field carries a persistent visible label that meets the requirement.

Checked contrast — light mode

Checked contrast — dark mode

Hard rules

• Hit area ≥ 44 × 44 px (touch) / ≥ 32 × 32 px (mouse-only desktop).
• focus-visible on every interactive element.
• Status communicated by colour AND text/icon — never colour alone.
• prefers-reduced-motion halts animation (sparkle, todo strike-through, shimmer).
• Form labels connected via for/id or aria-labelledby; errors via aria-describedby.
• Avatars without a visible name carry aria-label.

Feedback routing

Five surfaces for telling the user something. Pick by urgency and persistence.

Conventions worth raising

Command palette · slash commands

A command palette (⌘ K on Mac, Ctrl + K on Windows) and slash commands are expected conventions. The system doesn't ship a palette component yet because the underlying command surface isn't designed. Until that's decided, do not ship a command-palette UI per team — the design will fragment. Tracked under Deferred.

Developer alignment · multi-brand

For multi-brand work, the developer-facing contract — token names, component names, and the override path — aligns strictly with the first iteration of the shared developed (Aira) design system. The design system follows the developed system's naming so the two never drift; don't introduce design-only multi-brand constructs ahead of that v1 contract. Multi-brand theming hooks stay Deferred until the first reseller deployment commits.

The React library

Components ship as a published React library — the developer Storybook is the live reference. This document is the design source of truth; the table below maps each concern to the library the build uses.

File shape

• One component per file, named AiraX (PascalCase). Co-locate its cva variant definition and exported prop types.
• forwardRef to the root element and spread …props so consumers can pass DOM attributes.
• Behaviour with more than two states (composer, approval card, conversation) lives in an xstate machine — not in ad-hoc component state.

Prop conventions

• Variants — variant / size / tone resolved by class-variance-authority; the consumer's className is merged last with tailwind-merge, so overrides win without specificity fights.
• Controlled value — value + onValueChange (the @base-ui/react convention), not onChange with raw events.
• Composition — asChild (Base UI) renders as a different element instead of wrapping.
• Icon-only controls require an aria-label. Icons are lucide-react glyphs, sized with Tailwind (size-*) and coloured by currentColor.

Imports & tokens

• Import components from @aira/react and charts from @aira/react/charts.
• Tokens are consumed as the Tailwind theme + CSS variables — never hard-code a hex, spacing, or radius. Every custom property is --aira-*-prefixed (antd v3 coexistence). Numeric/currency formatting is dynamic per brand locale (never a hard-coded prefix).

Time & virtualization

• All timestamps and relative times go through date-fns — no hand-rolled date math.
• Any list that can exceed ~50 rows — chat history (AiraListRail), the change-log feed, dropdown options, data tables — is virtualized with @tanstack/react-virtual.

Accessibility checklist

• A keyboard path for every interaction; the global :focus-visible ring (no per-component override).
• aria-* wiring comes from @base-ui/react primitives — don't re-implement roles by hand.
• WCAG AA contrast in both themes; touch targets ≥ 44 px; never colour alone (pair with shape or label).

Component status

System-wide status. Figma means a 1:1 component spec exists in the Figma bundle — the Figma file itself isn't built yet. HTML means a live reference renders in this file. A11y means keyboard, ARIA, and contrast were checked in light and dark.

Reading the table

• Stable — passed full review · safe to consume in product · changes are additive only.
• Beta — visual and interaction spec is settled but a11y or cross-product review is still pending. Safe to consume; expect minor refinements before the next edition.
• Experimental — exploratory · no consumer expectation · may be removed.
• Deprecated — scheduled for removal; do not consume.
• Partial in A11y means the audit ran but at least one note is open. Linked from the component's metadata strip.

Figma bundle

The Figma library mirrors the atomic IA. Tokens published as Figma variables from tokens.json in DTCG 2025.10 format.

tokens.json · DTCG 2025.10

{
  "$themes": [
    {
      "id": "light",
      "name": "Light",
      "selectedTokenSets": {
        "global": "enabled",
        "primitives": "source",
        "semantic-light": "enabled",
        "additions-light": "enabled"
      }
    },
    {
      "id": "dark",
      "name": "Dark",
      "selectedTokenSets": {
        "global": "enabled",
        "primitives": "source",
        "semantic-dark": "enabled",
        "additions-dark": "enabled"
      }
    }
  ],
  "$metadata": {
    "tokenSetOrder": [
      "primitives",
      "semantic-light",
      "semantic-dark",
      "additions-light",
      "additions-dark",
      "global"
    ]
  },
  "primitives": {
    "slate": {
      "25": {
        "$value": "#FBFCFD",
        "$type": "color"
      },
      "50": {
        "$value": "#F6F8FA",
        "$type": "color"
      },
      "100": {
        "$value": "#EEF1F4",
        "$type": "color"
      },
      "200": {
        "$value": "#E2E6EB",
        "$type": "color"
      },
      "300": {
        "$value": "#C9D0D9",
        "$type": "color"
      },
      "400": {
        "$value": "#9AA4B2",
        "$type": "color"
      },
      "500": {
        "$value": "#6B7785",
        "$type": "color"
      },
      "600": {
        "$value": "#4D5867",
        "$type": "color"
      },
      "700": {
        "$value": "#364152",
        "$type": "color"
      },
      "800": {
        "$value": "#1F2937",
        "$type": "color"
      },
      "900": {
        "$value": "#111827",
        "$type": "color"
      },
      "950": {
        "$value": "#0A0F1A",
        "$type": "color"
      }
    },
    "indigo": {
      "50": {
        "$value": "#EEF0FF",
        "$type": "color"
      },
      "100": {
        "$value": "#DDE0FF",
        "$type": "color"
      },
      "200": {
        "$value": "#BAC1FF",
        "$type": "color"
      },
      "300": {
        "$value": "#8E97FF",
        "$type": "color"
      },
      "400": {
        "$value": "#6268FF",
        "$type": "color"
      },
      "500": {
        "$value": "#4A50EF",
        "$type": "color"
      },
      "600": {
        "$value": "#3438C9",
        "$type": "color"
      },
      "700": {
        "$value": "#252AA0",
        "$type": "color"
      },
      "800": {
        "$value": "#1B2078",
        "$type": "color"
      },
      "900": {
        "$value": "#121757",
        "$type": "color"
      }
    },
    "violet": {
      "50": {
        "$value": "#F4EEFF",
        "$type": "color"
      },
      "100": {
        "$value": "#E6DAFF",
        "$type": "color"
      },
      "200": {
        "$value": "#CDB5FF",
        "$type": "color"
      },
      "300": {
        "$value": "#B08CFF",
        "$type": "color"
      },
      "400": {
        "$value": "#8E61F2",
        "$type": "color"
      },
      "500": {
        "$value": "#6E40D9",
        "$type": "color"
      },
      "600": {
        "$value": "#5A2FB8",
        "$type": "color"
      },
      "700": {
        "$value": "#46248F",
        "$type": "color"
      }
    },
    "sky": {
      "50": {
        "$value": "#E6F1FF",
        "$type": "color"
      },
      "100": {
        "$value": "#C7E1FF",
        "$type": "color"
      },
      "200": {
        "$value": "#8EC1FF",
        "$type": "color"
      },
      "300": {
        "$value": "#5EA8FF",
        "$type": "color"
      },
      "400": {
        "$value": "#3BA7FF",
        "$type": "color"
      },
      "500": {
        "$value": "#1564CC",
        "$type": "color"
      },
      "600": {
        "$value": "#114DA0",
        "$type": "color"
      },
      "700": {
        "$value": "#0D3C7E",
        "$type": "color"
      }
    },
    "green": {
      "50": {
        "$value": "#E7F6EC",
        "$type": "color"
      },
      "100": {
        "$value": "#C6EAD2",
        "$type": "color"
      },
      "200": {
        "$value": "#8FD7A6",
        "$type": "color"
      },
      "300": {
        "$value": "#4FBE76",
        "$type": "color"
      },
      "400": {
        "$value": "#2A9D55",
        "$type": "color"
      },
      "500": {
        "$value": "#1F7A42",
        "$type": "color"
      },
      "600": {
        "$value": "#185C32",
        "$type": "color"
      },
      "700": {
        "$value": "#103E22",
        "$type": "color"
      }
    },
    "amber": {
      "50": {
        "$value": "#FFF6E0",
        "$type": "color"
      },
      "100": {
        "$value": "#FFE5A8",
        "$type": "color"
      },
      "200": {
        "$value": "#FFCB60",
        "$type": "color"
      },
      "300": {
        "$value": "#E89B1A",
        "$type": "color"
      },
      "400": {
        "$value": "#B97300",
        "$type": "color"
      },
      "500": {
        "$value": "#8A5500",
        "$type": "color"
      },
      "600": {
        "$value": "#5C3800",
        "$type": "color"
      }
    },
    "red": {
      "50": {
        "$value": "#FFECEC",
        "$type": "color"
      },
      "100": {
        "$value": "#FFCFCF",
        "$type": "color"
      },
      "200": {
        "$value": "#FF9C9C",
        "$type": "color"
      },
      "300": {
        "$value": "#F55959",
        "$type": "color"
      },
      "400": {
        "$value": "#D92D2D",
        "$type": "color"
      },
      "500": {
        "$value": "#B11E1E",
        "$type": "color"
      },
      "600": {
        "$value": "#8A1414",
        "$type": "color"
      }
    }
  },
  "semantic-light": {
    "bg": {
      "canvas": {
        "$value": "{primitives.slate.50}",
        "$type": "color"
      },
      "surface": {
        "$value": "#FFFFFF",
        "$type": "color"
      },
      "surfaceAlt": {
        "$value": "{primitives.slate.25}",
        "$type": "color"
      },
      "sunken": {
        "$value": "{primitives.slate.100}",
        "$type": "color"
      },
      "brand": {
        "$value": "{primitives.indigo.600}",
        "$type": "color"
      },
      "brandSubtle": {
        "$value": "{primitives.indigo.50}",
        "$type": "color"
      },
      "selected": {
        "$value": "{primitives.indigo.50}",
        "$type": "color"
      }
    },
    "text": {
      "primary": {
        "$value": "{primitives.slate.900}",
        "$type": "color"
      },
      "secondary": {
        "$value": "{primitives.slate.700}",
        "$type": "color"
      },
      "tertiary": {
        "$value": "{primitives.slate.500}",
        "$type": "color"
      },
      "onBrand": {
        "$value": "#FFFFFF",
        "$type": "color"
      },
      "link": {
        "$value": "{primitives.indigo.600}",
        "$type": "color"
      }
    },
    "border": {
      "subtle": {
        "$value": "{primitives.slate.100}",
        "$type": "color"
      },
      "default": {
        "$value": "{primitives.slate.200}",
        "$type": "color"
      },
      "strong": {
        "$value": "{primitives.slate.300}",
        "$type": "color"
      },
      "focus": {
        "$value": "{primitives.indigo.600}",
        "$type": "color"
      },
      "danger": {
        "$value": "{primitives.red.400}",
        "$type": "color"
      }
    }
  },
  "semantic-dark": {
    "bg": {
      "canvas": {
        "$value": "#0E1424",
        "$type": "color"
      },
      "surface": {
        "$value": "#131B2C",
        "$type": "color"
      },
      "surfaceAlt": {
        "$value": "#182135",
        "$type": "color"
      },
      "sunken": {
        "$value": "#0A101C",
        "$type": "color"
      },
      "brand": {
        "$value": "{primitives.indigo.400}",
        "$type": "color"
      },
      "brandSubtle": {
        "$value": "#1F2A55",
        "$type": "color"
      },
      "selected": {
        "$value": "#1F2A55",
        "$type": "color"
      }
    },
    "text": {
      "primary": {
        "$value": "#F4F6FA",
        "$type": "color"
      },
      "secondary": {
        "$value": "#C8CFDB",
        "$type": "color"
      },
      "tertiary": {
        "$value": "#94A0B4",
        "$type": "color"
      },
      "onBrand": {
        "$value": "#0A0F1A",
        "$type": "color"
      },
      "link": {
        "$value": "{primitives.indigo.300}",
        "$type": "color"
      }
    },
    "border": {
      "subtle": {
        "$value": "#1F2940",
        "$type": "color"
      },
      "default": {
        "$value": "#2A3654",
        "$type": "color"
      },
      "strong": {
        "$value": "#3A4870",
        "$type": "color"
      },
      "focus": {
        "$value": "{primitives.indigo.300}",
        "$type": "color"
      },
      "danger": {
        "$value": "{primitives.red.300}",
        "$type": "color"
      }
    }
  },
  "global": {
    "type": {
      "displayLg": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "40px",
          "lineHeight": "48px",
          "fontWeight": "600",
          "letterSpacing": "-0.02em"
        },
        "$type": "typography"
      },
      "displayMd": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "32px",
          "lineHeight": "40px",
          "fontWeight": "600",
          "letterSpacing": "-0.015em"
        },
        "$type": "typography"
      },
      "h1": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "28px",
          "lineHeight": "36px",
          "fontWeight": "600",
          "letterSpacing": "-0.01em"
        },
        "$type": "typography"
      },
      "h2": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "22px",
          "lineHeight": "30px",
          "fontWeight": "600",
          "letterSpacing": "-0.005em"
        },
        "$type": "typography"
      },
      "h3": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "18px",
          "lineHeight": "26px",
          "fontWeight": "600"
        },
        "$type": "typography"
      },
      "h4": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "16px",
          "lineHeight": "24px",
          "fontWeight": "600"
        },
        "$type": "typography"
      },
      "bodyLg": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "16px",
          "lineHeight": "26px",
          "fontWeight": "400"
        },
        "$type": "typography"
      },
      "bodyMd": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "14px",
          "lineHeight": "22px",
          "fontWeight": "400"
        },
        "$type": "typography"
      },
      "bodySm": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "13px",
          "lineHeight": "20px",
          "fontWeight": "400"
        },
        "$type": "typography"
      },
      "labelLg": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "15px",
          "lineHeight": "22px",
          "fontWeight": "500"
        },
        "$type": "typography"
      },
      "labelMd": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "14px",
          "lineHeight": "20px",
          "fontWeight": "500"
        },
        "$type": "typography"
      },
      "labelSm": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "12px",
          "lineHeight": "16px",
          "fontWeight": "500"
        },
        "$type": "typography"
      },
      "caption": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "12px",
          "lineHeight": "16px",
          "fontWeight": "400"
        },
        "$type": "typography"
      },
      "overline": {
        "$value": {
          "fontFamily": "Roboto",
          "fontSize": "11px",
          "lineHeight": "16px",
          "fontWeight": "500",
          "letterSpacing": "0.08em"
        },
        "$type": "typography"
      },
      "code": {
        "$value": {
          "fontFamily": "SF Mono",
          "fontSize": "13px",
          "lineHeight": "20px",
          "fontWeight": "400"
        },
        "$type": "typography"
      }
    },
    "spacing": {
      "0": {
        "$value": "0px",
        "$type": "dimension"
      },
      "1": {
        "$value": "4px",
        "$type": "dimension"
      },
      "2": {
        "$value": "8px",
        "$type": "dimension"
      },
      "3": {
        "$value": "12px",
        "$type": "dimension"
      },
      "4": {
        "$value": "16px",
        "$type": "dimension"
      },
      "5": {
        "$value": "20px",
        "$type": "dimension"
      },
      "6": {
        "$value": "24px",
        "$type": "dimension"
      },
      "8": {
        "$value": "32px",
        "$type": "dimension"
      },
      "10": {
        "$value": "40px",
        "$type": "dimension"
      },
      "12": {
        "$value": "48px",
        "$type": "dimension"
      },
      "16": {
        "$value": "64px",
        "$type": "dimension"
      },
      "20": {
        "$value": "80px",
        "$type": "dimension"
      }
    },
    "radius": {
      "xs": {
        "$value": "4px",
        "$type": "dimension"
      },
      "sm": {
        "$value": "6px",
        "$type": "dimension"
      },
      "md": {
        "$value": "8px",
        "$type": "dimension"
      },
      "lg": {
        "$value": "12px",
        "$type": "dimension"
      },
      "xl": {
        "$value": "16px",
        "$type": "dimension"
      },
      "2xl": {
        "$value": "20px",
        "$type": "dimension"
      },
      "pill": {
        "$value": "999px",
        "$type": "dimension"
      },
      "circle": {
        "$value": "9999px",
        "$type": "dimension"
      }
    },
    "elevation": {
      "xs": {
        "$value": {
          "color": "rgba(17,24,39,0.06)",
          "offsetX": "0px",
          "offsetY": "1px",
          "blur": "2px",
          "spread": "0px"
        },
        "$type": "shadow"
      },
      "sm": {
        "$value": {
          "color": "rgba(17,24,39,0.08)",
          "offsetX": "0px",
          "offsetY": "1px",
          "blur": "3px",
          "spread": "0px"
        },
        "$type": "shadow"
      },
      "md": {
        "$value": {
          "color": "rgba(17,24,39,0.10)",
          "offsetX": "0px",
          "offsetY": "4px",
          "blur": "8px",
          "spread": "-2px"
        },
        "$type": "shadow"
      },
      "lg": {
        "$value": {
          "color": "rgba(17,24,39,0.14)",
          "offsetX": "0px",
          "offsetY": "12px",
          "blur": "24px",
          "spread": "-6px"
        },
        "$type": "shadow"
      },
      "focus": {
        "$value": {
          "color": "rgba(52,56,201,0.32)",
          "offsetX": "0px",
          "offsetY": "0px",
          "blur": "0px",
          "spread": "3px"
        },
        "$type": "shadow"
      }
    },
    "motion": {
      "fast": {
        "$value": "120ms cubic-bezier(0.4,0,0.2,1)",
        "$type": "duration"
      },
      "base": {
        "$value": "200ms cubic-bezier(0.4,0,0.2,1)",
        "$type": "duration"
      },
      "slow": {
        "$value": "320ms cubic-bezier(0.4,0,0.2,1)",
        "$type": "duration"
      }
    }
  },
  "additions-light": {
    "ai": {
      "accent": {
        "$value": "{primitives.violet.600}",
        "$type": "color"
      },
      "accentSurface": {
        "$value": "{primitives.violet.50}",
        "$type": "color"
      },
      "accentBorder": {
        "$value": "{primitives.violet.200}",
        "$type": "color"
      },
      "onAccent": {
        "$value": "#FFFFFF",
        "$type": "color"
      }
    },
    "citation": {
      "bg": {
        "$value": "{primitives.slate.50}",
        "$type": "color"
      },
      "bgHover": {
        "$value": "{primitives.slate.100}",
        "$type": "color"
      },
      "border": {
        "$value": "{primitives.slate.200}",
        "$type": "color"
      },
      "text": {
        "$value": "{primitives.slate.700}",
        "$type": "color"
      },
      "icon": {
        "$value": "{primitives.slate.500}",
        "$type": "color"
      }
    },
    "diff": {
      "addBg": {
        "$value": "#E7F6EC",
        "$type": "color"
      },
      "addFg": {
        "$value": "{primitives.green.600}",
        "$type": "color"
      },
      "addMarker": {
        "$value": "{primitives.green.400}",
        "$type": "color"
      },
      "removeBg": {
        "$value": "#FFECEC",
        "$type": "color"
      },
      "removeFg": {
        "$value": "{primitives.red.500}",
        "$type": "color"
      },
      "removeMarker": {
        "$value": "{primitives.red.400}",
        "$type": "color"
      },
      "contextBg": {
        "$value": "#FFFFFF",
        "$type": "color"
      },
      "contextFg": {
        "$value": "{primitives.slate.700}",
        "$type": "color"
      },
      "gutterBg": {
        "$value": "{primitives.slate.50}",
        "$type": "color"
      },
      "gutterFg": {
        "$value": "{primitives.slate.500}",
        "$type": "color"
      }
    },
    "code": {
      "bg": {
        "$value": "{primitives.slate.50}",
        "$type": "color"
      },
      "bgInline": {
        "$value": "{primitives.slate.100}",
        "$type": "color"
      },
      "border": {
        "$value": "{primitives.slate.200}",
        "$type": "color"
      },
      "fg": {
        "$value": "{primitives.slate.900}",
        "$type": "color"
      }
    },
    "syntax": {
      "keyword": {
        "$value": "{primitives.indigo.700}",
        "$type": "color"
      },
      "string": {
        "$value": "{primitives.green.600}",
        "$type": "color"
      },
      "number": {
        "$value": "{primitives.amber.500}",
        "$type": "color"
      },
      "comment": {
        "$value": "{primitives.slate.500}",
        "$type": "color"
      },
      "operator": {
        "$value": "{primitives.slate.700}",
        "$type": "color"
      },
      "function": {
        "$value": "{primitives.violet.600}",
        "$type": "color"
      },
      "punctuation": {
        "$value": "{primitives.slate.600}",
        "$type": "color"
      }
    },
    "approval": {
      "draftBg": {
        "$value": "{primitives.slate.100}",
        "$type": "color"
      },
      "draftText": {
        "$value": "{primitives.slate.700}",
        "$type": "color"
      },
      "awaitingBg": {
        "$value": "{primitives.amber.50}",
        "$type": "color"
      },
      "awaitingText": {
        "$value": "{primitives.amber.500}",
        "$type": "color"
      },
      "approvedBg": {
        "$value": "{primitives.green.50}",
        "$type": "color"
      },
      "approvedText": {
        "$value": "{primitives.green.600}",
        "$type": "color"
      },
      "liveBg": {
        "$value": "{primitives.indigo.50}",
        "$type": "color"
      },
      "liveText": {
        "$value": "{primitives.indigo.700}",
        "$type": "color"
      },
      "rejectedBg": {
        "$value": "{primitives.red.50}",
        "$type": "color"
      },
      "rejectedText": {
        "$value": "{primitives.red.500}",
        "$type": "color"
      }
    }
  },
  "additions-dark": {
    "ai": {
      "accent": {
        "$value": "{primitives.violet.200}",
        "$type": "color"
      },
      "accentSurface": {
        "$value": "#2A1A4D",
        "$type": "color"
      },
      "accentBorder": {
        "$value": "{primitives.violet.400}",
        "$type": "color"
      },
      "onAccent": {
        "$value": "#0A0F1A",
        "$type": "color"
      }
    },
    "citation": {
      "bg": {
        "$value": "#182135",
        "$type": "color"
      },
      "bgHover": {
        "$value": "#1C2640",
        "$type": "color"
      },
      "border": {
        "$value": "#2A3654",
        "$type": "color"
      },
      "text": {
        "$value": "#C8CFDB",
        "$type": "color"
      },
      "icon": {
        "$value": "{primitives.slate.400}",
        "$type": "color"
      }
    },
    "diff": {
      "addBg": {
        "$value": "#0E2E1B",
        "$type": "color"
      },
      "addFg": {
        "$value": "#6FD995",
        "$type": "color"
      },
      "addMarker": {
        "$value": "{primitives.green.300}",
        "$type": "color"
      },
      "removeBg": {
        "$value": "#2E1010",
        "$type": "color"
      },
      "removeFg": {
        "$value": "#F58B8B",
        "$type": "color"
      },
      "removeMarker": {
        "$value": "{primitives.red.300}",
        "$type": "color"
      },
      "contextBg": {
        "$value": "#131B2C",
        "$type": "color"
      },
      "contextFg": {
        "$value": "#C8CFDB",
        "$type": "color"
      },
      "gutterBg": {
        "$value": "#0A101C",
        "$type": "color"
      },
      "gutterFg": {
        "$value": "{primitives.slate.400}",
        "$type": "color"
      }
    },
    "code": {
      "bg": {
        "$value": "#0A101C",
        "$type": "color"
      },
      "bgInline": {
        "$value": "#182135",
        "$type": "color"
      },
      "border": {
        "$value": "#2A3654",
        "$type": "color"
      },
      "fg": {
        "$value": "#F4F6FA",
        "$type": "color"
      }
    },
    "syntax": {
      "keyword": {
        "$value": "{primitives.indigo.200}",
        "$type": "color"
      },
      "string": {
        "$value": "#6FD995",
        "$type": "color"
      },
      "number": {
        "$value": "#F0B95B",
        "$type": "color"
      },
      "comment": {
        "$value": "{primitives.slate.400}",
        "$type": "color"
      },
      "operator": {
        "$value": "#C8CFDB",
        "$type": "color"
      },
      "function": {
        "$value": "{primitives.violet.200}",
        "$type": "color"
      },
      "punctuation": {
        "$value": "{primitives.slate.300}",
        "$type": "color"
      }
    },
    "approval": {
      "draftBg": {
        "$value": "#1C2640",
        "$type": "color"
      },
      "draftText": {
        "$value": "#C8CFDB",
        "$type": "color"
      },
      "awaitingBg": {
        "$value": "#2E2310",
        "$type": "color"
      },
      "awaitingText": {
        "$value": "#F0B95B",
        "$type": "color"
      },
      "approvedBg": {
        "$value": "#0E2E1B",
        "$type": "color"
      },
      "approvedText": {
        "$value": "#6FD995",
        "$type": "color"
      },
      "liveBg": {
        "$value": "#1F2A55",
        "$type": "color"
      },
      "liveText": {
        "$value": "#BCC4FF",
        "$type": "color"
      },
      "rejectedBg": {
        "$value": "#2E1010",
        "$type": "color"
      },
      "rejectedText": {
        "$value": "#F58B8B",
        "$type": "color"
      }
    }
  },
  "$schema": "https://design-tokens.github.io/community-group/format/2025-10/",
  "$description": "Aira Design System v1.1 \u2014 DTCG 2025.10 format. Agent identity tokens removed (rule: one aiRA)."
}

figma-components.md

code-connect.json

{
  "$schema": "https://schemas.figma.com/code-connect/v1/code-connect.schema.json",
  "version": "1.0.0",
  "designSystem": "Aira Design System v1.0",
  "sourceRoot": "../",
  "components": [
    {
      "figmaName": "chat/Bubble",
      "source": "index.html#chat-bubble",
      "selector": ".msg",
      "variants": ["role", "agent", "state", "density"],
      "props": ["text", "showMeta", "showActions", "timestamp"]
    },
    {
      "figmaName": "ai/Label",
      "source": "index.html#ai-label",
      "selector": ".ai-label",
      "variants": ["size"]
    },
    {
      "figmaName": "approval/Card",
      "source": "index.html#approval-card",
      "selector": ".approval",
      "variants": ["status", "risk"],
      "props": ["title", "agent", "previewSlot"]
    },
    {
      "figmaName": "citation/Chip",
      "source": "index.html#citation",
      "selector": ".citation",
      "variants": ["mode", "state"],
      "props": ["number", "title", "showSnippetOnHover"]
    },
    {
      "figmaName": "code/Block",
      "source": "index.html#code-block",
      "selector": ".code-block",
      "variants": ["lang", "state", "aiLabelled"],
      "props": ["code", "lang", "showCopy"]
    },
    {
      "figmaName": "diff/Inline",
      "source": "index.html#diff",
      "selector": ".diff",
      "variants": ["density", "showLineNumbers"]
    },
    {
      "figmaName": "activity/Row",
      "source": "index.html#activity",
      "selector": ".activity",
      "variants": ["state"]
    },
    {
      "figmaName": "activity/List",
      "source": "index.html#activity",
      "selector": ".activity-list",
      "variants": ["itemState"]
    },
    {
      "figmaName": "feedback/Control",
      "source": "index.html#feedback",
      "selector": ".feedback",
      "variants": ["state", "size"]
    },
    {
      "figmaName": "overlay/Modal",
      "source": "index.html#modal",
      "selector": ".modal",
      "variants": ["intent", "size"],
      "props": ["title", "bodySlot", "primaryCta", "secondaryCta"]
    },
    {
      "figmaName": "overlay/BottomSheet",
      "source": "index.html#bottom-sheet",
      "selector": ".sheet",
      "variants": ["size", "dismissible"]
    },
    {
      "figmaName": "nav/Tabs",
      "source": "index.html#tabs",
      "selector": ".tabs",
      "variants": ["size", "style"]
    },
    {
      "figmaName": "form/Select",
      "source": "index.html#select",
      "selector": ".field select",
      "variants": ["state"]
    },
    {
      "figmaName": "form/Combobox",
      "source": "index.html#combobox",
      "selector": ".combo",
      "variants": ["state"]
    },
    {
      "figmaName": "form/Toggle",
      "source": "index.html#toggle",
      "selector": ".toggle",
      "variants": ["state"]
    },
    {
      "figmaName": "form/Checkbox",
      "source": "index.html#checkbox",
      "selector": ".opt input[type=checkbox]",
      "variants": ["state"]
    },
    {
      "figmaName": "form/RadioGroup",
      "source": "index.html#radio",
      "selector": "fieldset",
      "variants": ["optionState"]
    },
    {
      "figmaName": "overlay/Tooltip",
      "source": "index.html#tooltip",
      "selector": ".tip"
    },
    {
      "figmaName": "overlay/Popover",
      "source": "index.html#tooltip",
      "selector": ".popover"
    },
    {
      "figmaName": "avatar/Avatar",
      "source": "index.html#avatar",
      "selector": ".avatar",
      "variants": ["size", "kind"]
    },
    {
      "figmaName": "list/Row",
      "source": "index.html#list-row",
      "selector": ".list-row",
      "variants": ["density", "state"]
    },
    {
      "figmaName": "data/Table",
      "source": "index.html#data-table",
      "selector": ".dt",
      "variants": ["cellAlign", "cellType"]
    },
    {
      "figmaName": "progress/Stepper",
      "source": "index.html#stepper",
      "selector": ".stepper",
      "variants": ["stepState"]
    },
    {
      "figmaName": "progress/Bar",
      "source": "index.html#stepper",
      "selector": ".progress"
    },
    {
      "figmaName": "loading/Skeleton",
      "source": "index.html#skeleton",
      "selector": ".skeleton",
      "variants": ["shape"]
    }
  ],
  "tokens": {
    "format": "tokens-studio",
    "source": "tokens.json",
    "css": "../tokens.css"
  },
  "notes": [
    "Import tokens.json via the Tokens Studio Figma plugin to materialize variables/styles.",
    "Each figmaName above must be created as a Figma Component with the listed variants.",
    "After creating the components, run Figma → Plugins → Code Connect → Sync to bind them to this file.",
    "The figmaName slashes ('chat/Bubble') create Figma's nested-component menu structure."
  ]
}

Deferred

Work consciously left out of Aira Design System v1.1. Each item has a trigger condition for re-opening.

Risk register

• Base UI pre-1.0 churn. @base-ui/react APIs may still shift; pin the version and isolate changes behind the AiraX wrappers.
• Chart performance. recharts (SVG) degrades past a few thousand points; drop to a d3 + canvas renderer for high-cardinality series.
• Virtualization vs. a11y. @tanstack/react-virtual removes off-screen rows from the DOM; keep aria-rowcount/aria-setsize accurate so assistive tech still reads totals.
• Token drift. Hard-coded values bypass the Tailwind theme; the lint rules below are the guardrail.

Lint rules

• Tokens only — no raw hex, spacing, or radius literals; values must resolve from the Tailwind theme / CSS variables.
• Controlled props — use value + onValueChange, not bare onChange handlers.
• Icon labels — an icon-only control without an aria-label fails lint.
• Dates via date-fns — no new Date() math or hand-built format strings in components.
• Virtualize long lists — a scrollable list rendering > 50 rows without @tanstack/react-virtual fails lint.

Language strategy

• Sentence case everywhere; one aiRA voice; refusal grammar is "can't / can / next".
• No concatenated strings — full ICU messages with named variables, so translators get whole sentences.
• Locale-aware dates and numbers via date-fns locales; currency/grouping resolve from the brand locale (never a hard-coded prefix).
• RTL via dir + CSS logical properties (the system already ships LTR/RTL); no left/right hard-coding.

Changelog

Version history for the Aira Design System itself — tokens, components, voice rules, documentation. Every entry is dated and tagged so you can tell at a glance whether something was added, changed, removed, or fixed between releases. For the in-product change-log pattern (audit trails, edit timelines), see Change-log feed.