aiRA Design System First Edition

The First Edition is organised around atomic design — Atoms → Molecules → Organisms → Templates — so every element maps cleanly onto a Figma library. The product has one assistant voice (aiRA), one set of avatars, 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.

About this file

This single HTML file contains every part of the aiRA Design System First Edition — 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. Open it in any browser; no build step, no external assets.

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      # First Edition 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 does double duty as the app logo, the launcher icon, and the streaming / AI-generated indicator in product surfaces.

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

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

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

Every icon used in the system lives here. 20 px nominal · stroke 1.5 · slate-600 default. Inherit colour from currentColor; never bake a colour into the SVG.

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

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. Users learn the taxonomy once.

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 — "₹14.2L" beats "₹1,421,540" in a dashboard.
• Symbols on the value, not the axis — "₹" prefix on each tile, not on every gridline.
• Round consistently. Don't show 8.234% next to 12% in the same column.

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 8% of men 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

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

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)

Filled square inside a coloured circle. Indicates active generation; clicking it stops aiRA.

Do / don't

Input

36 px default. Ten states.

Do / don't

Textarea

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

Do / don't

Chip

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

Do / don't

Tag

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

Do / don't

Badge

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

Do / don't

Pill (status)

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

Properties

Do / don't

Avatar

Two variants only — User initials and the aiRA mark. Both use the canonical aiRA gradient (--avatar-grad). No per-agent avatars: the product has one assistant voice.

User avatar — initials

aiRA avatar — sparkle mark

Do / don't

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

Tooltip

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

Do / don't

Keyboard (kbd)

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

Divider

1 px horizontal rule using --border-default.

Spinner

Indeterminate progress. 14 px default.

Skeleton

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

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.

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

Checkbox

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

Do / don't

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

Toggle

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

Do / don't

Stepper

Ordered multi-step flow.

Progress bar

Determinate progress for known durations.

Feedback control

Two bare icon buttons — thumbs-up / thumbs-down — sitting inline with the action row. No pill, no container, no divider. The selected thumb fills with the link colour. An optional reason picker pops below on Not helpful.

Do / don't

Action row

Inline actions under an aiRA reply — Copy · Support · Feedback (thumbs-up / thumbs-down). Keyboard focus uses the global :focus-visible ring; no per-action override.

Tabs

Local navigation between views of the same data.

Breadcrumb

Hierarchical location indicator. Useful inside multi-step configurators.

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

Toast

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

Do / don't

Banner

Inline page-level message. Persistent until dismissed.

Do / don't

Nudge card

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

Do / don't

Selection card

Disambiguation step. Keyboard-first, escape-to-skip, free-type fallback. Option rows and the "Something else" row use visually distinct hover treatments so the two never look like the same target.

Default

Interaction matrix

Option rows and "Something else" use different hover surfaces so they read as separate affordances.

Properties

Do / don't

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

Chat message

Three message types. aiRA's reply free-flows — anchored by the aiRA avatar at the start of the message. No agent label, no badge, no chip.

Variants

Anatomy

• Thread — role="log" aria-live="polite"; new messages announce.
• User message — grey pill, end-aligned, max 80% width.
• aiRA reply — aiRA avatar (sm) + free-flowing body. 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

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

The Send button stays disabled until the user types. Disabled uses the neutral disabled surface; 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

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. 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). Reject and Edit remain reachable. Same compact primary-button size as routine Accept — 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.

Multi-brand override path

The status pill colours and the lifecycle states (Draft → Awaiting → Upcoming → Approved → Live → Rejected) are wired to Capillary's Connect+ workflow. White-label / reseller deployments need a --approval-state-* token layer that maps tenant lifecycle names to the system's six-state machine. Tracked under Deferred · Multi-brand theming hooks; flagged here so the override surface is designed in, not bolted on later.

Do / don't

Code block

First-class output for SQL and scripts. Language badge, Copy / Explain actions.

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

Inline diff

Add / remove / context lines. Used inside Approval cards and the Change-log feed.

Do / don't

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

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

• thinking → streaming happens on the first content token. Never an empty streaming UI.
• If thinking exceeds 10 s without a token, append "Still working — taking longer than usual" to the activity row. Do not auto-cancel.
• error is reachable from thinking, streaming, aborted. The retry path rewinds to user-sent with the original prompt.
• aborted is reachable only from streaming (Stop) or thinking (Cancel) — never from done.
• done, aborted, and error all loop back to user-sent when the user composes a follow-up.
• During streaming, the composer Send icon swaps to the Stop icon. Clicking it triggers streaming → aborted.
• Composer is never disabled by the assistant state. Read-only treatment is reserved for locked conversations (shared sessions, audit views).

Modal / Dialog

For confirmation, destructive actions, 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.

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

Bottom sheet

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

Do / don't

List row

Chat history rail — a narrow sidebar pinned to the left of the chat surface listing previous sessions (ChatGPT / Gemini 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

• 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

Data table

Every column header carries the same sort icon — chevrons-up-down. 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

Card

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

Do / don't

Form

Standard composition — field stack + actions footer.

Do / don't

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

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

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 a leading aiRA avatar, the config name, and a status pill.

Mobile preview

Desktop is the primary surface; mobile honours safe-area tokens for sheets and bottom CTAs.

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.

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+ as the floor. Contrast verified token-by-token, light + dark.

Verified contrast — light mode

Verified 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

Cmd+K · slash commands

aiRA is a B2B power-user tool. Cmd+K 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 Cmd+K UI per team — the design will fragment. Tracked under Deferred.

Until the React library ships

The React component library is correctly deferred. Until then:

• Markup source of truth — this index.html. Copy demo HTML verbatim; replace inline values with your data binding.
• Tokens source of truth — tokens.css. Import once at app root. Never redefine a token locally.
• Behaviour source of truth — the data-ds-* hooks inline at the bottom of this file (Tabs, Dropdown, sidebar search).

When the React library lands, the migration is a class-rename pass + a token resolver swap — not a rewrite.

Component status

System-wide parity. Figma means a 1:1 Figma library component exists. HTML means a live reference renders in this file. A11y means keyboard, ARIA, and contrast have been audited in light + dark for the latest spec.

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 First Edition \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 v2",
  "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", "showCopyExplain"]
    },
    {
      "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 the First Edition. Each item has a trigger condition for re-opening.