Tokens, components, icons, motion, and voice reference for every ArcGrid surface. The single source of truth for how the platform looks and behaves.
Mark & Wordmark
The mark is a node-network graph - two clusters of nodes connected across a midline, representing arc and grid as two halves of one system.
Mark sizes
Wordmark
Set in IBM Plex Mono. "arc" at weight 700, color #F2F3F5. "grid" at weight 400, color #80848E. Always lowercase. Never use the old SVG wordmark - always compose from the mark + styled text.
Don'ts
Three-Theme System
Surface ships three themes that share the same token structure and teal accent hue. The theme is set via data-theme on the root element. Use the D / M / L toggle in the nav to preview each theme live.
Identity colors (shared across all themes in dark / medium)
These eight colors are used for user identity chips, project tags, and avatar borders. Light theme uses desaturated equivalents for accessibility on white backgrounds.
Palette
The swatches below reflect the active theme - use the D / M / L toggle in the nav to switch. The page background is always sunken; cards sit on base; interactive surfaces raise to raised or overlay.
Surface layers
Borders
Text
Accent
Semantic
Cycle statuses
Brand colors (external, fixed)
These values are theme-invariant. Use only for third-party brand identity contexts (settings, connections, integrations).
Type System
IBM Plex Sans for UI text. IBM Plex Mono for code, token names, and the wordmark. Both ship as open-source weights from Google Fonts or self-hosted.
Space & Shape
Base unit is 4px. All spacing is a multiple. Never use arbitrary pixel values - stay on the scale.
Spacing scale
Border radius
Grid & Breakpoints
Two width containers govern all content. .wrap is the site-wide rail; .page-wrap is for narrower editorial content. Both center with auto margins and horizontal padding.
Content containers
Breakpoints
| Max-width | Token | What changes |
|---|---|---|
| 860px | - | Mobile nav: burger appears, main nav collapses to dropdown |
| 700px | - | Theme comparison grid stacks from 3-col to single column |
| 680px | - | .grid-3 and .grid-4 collapse to 2-column |
| 420px | - | All .grid-* helpers collapse to single column |
Grid helpers
.grid-2
.grid-3
.grid-4
Responsive Shell
Surface is an application, not a website. It uses width ranges at the page level and container queries at the component level. Never build per device — build for ranges and test against named real devices.
Page-level width ranges
Minimum supported width: 320px. Nothing may scroll horizontally at the page level at any width from 320 up.
| Token | Range (CSS px) | Typical devices | Shell layout |
|---|---|---|---|
| xs | 0 – 479 | Most phones portrait (360–440) | Single column. Bottom tab bar or drawer nav. Sheets instead of dialogs. |
| sm | 480 – 767 | Large phones landscape, foldable inner screens, small tablets | Single column, wider gutters. Drawer nav. |
| md | 768 – 1023 | iPad portrait, iPad mini | Collapsible rail nav (icons only). One primary pane; detail opens as overlay or push. |
| lg | 1024 – 1279 | iPad landscape, iPad Pro portrait, small laptops | Rail nav. List + detail split where the page has one. |
| xl | 1280 – 1599 | 13–14″ laptops, MacBooks at default scaling | Full sidebar. Split panes. |
| 2xl | 1600 – 1919 | 15–16″ laptops, 1080p at 100–125% | Full sidebar. Optional third context pane. |
| 3xl | 1920 – 2559 | 1080p and 1440p desktop monitors | Three panes available. Content width caps apply. |
| 4xl | 2560+ | 1440p at 100%, 21:9 and 32:9 ultrawides, 4K | Three or four panes. Caps and pane rules are mandatory. |
Widescreen rules
Extra width is used for more information, never for stretched content.
| Rule | Requirement |
|---|---|
| W-01 | Reading content (text, forms, settings) caps at ~80 characters. Forms cap near 640px. |
| W-02 | Extra width adds panes in order: list → detail → context (activity, properties, agent chat) → optional pinned secondary view. |
| W-03 | Tables may use full width but columns have min and max widths. Beyond max, extra space goes to a details pane, not wider columns. |
| W-04 | Dashboards increase column count (4, 8, 12, 16) with width rather than scaling cards up. |
| W-05 | Panes are user-resizable and collapsible at xl and above. Widths are persisted per user. |
| W-06 | Nothing important sits at the far right edge of a 32:9 display without also being reachable from the left or center. |
Container queries
Components respond to the width of their container, not the viewport. A table in a narrow side pane on an ultrawide should behave like a table on a tablet. Every component in the Surface Application section documents its own container breakpoints — for example, Table becomes DataList below 560px container width.
Input modality
Width does not tell you how the user is interacting. An iPad with a keyboard is a pointer device; a touchscreen laptop may be touch.
- Use
@media (pointer: coarse)and(hover: none)to enlarge targets, reveal actions that would otherwise be hover-only, and increase spacing. - Never hide a required action behind hover alone.
- Keyboard: every action must be reachable. Focus-visible is always shown. Shortcuts are documented in the command palette.
Mobile specifics
- Use
dvh/svhunits, never raw100vh, so browser chrome does not clip content. - Respect safe areas with
env(safe-area-inset-*)andviewport-fit=cover(notches, Dynamic Island, home indicator, Android gesture bar). - Inputs at 16px minimum to prevent iOS focus zoom.
- Bottom sheets for menus and pickers at xs and sm.
- Fixed bottom actions sit above the safe area inset and the on-screen keyboard.
- Foldables: test both cover and inner screens, and the transition between them without losing state.
Orientation and resizing
- State survives rotation, window resizing, and fold changes.
- Desktop windows can be any size (split screen, Stage Manager). The shell must work at every width, not just maximized.
Text scaling and zoom
- Layouts survive 200% browser zoom and OS text scaling up to 200% without clipping or overlap.
- Use
remfor type and spacing tokens so user font settings apply.
Device Test Targets
Canonical test targets — CSS pixel sizes (width × height), portrait unless noted. Priority Tier 1 devices are tested on every build. All sizes are as reported by the browser, not physical pixels.
Browsers: Chromium · WebKit (Safari and all iOS browsers) · Firefox
Priority Tier 1
iOS phones
| Device | Size (CSS px) | Range |
|---|---|---|
| iPhone SE (3rd gen) | 375 × 667 | xs |
| iPhone 13 mini | 375 × 812 | xs |
| iPhone 15 / 16 | 393 × 852 | xs |
| iPhone 16 Plus / 15 Pro Max | 430 × 932 | xs |
| iPhone 16 Pro Max | 440 × 956 | xs |
| Current flagship lineup (2026) | verify | xs |
| Minimum supported | 320 × 640 | xs |
Android phones
| Device | Size (CSS px) | Range |
|---|---|---|
| Galaxy S-series base | 360 × 780 | xs |
| Galaxy A-series | 360 × 800 | xs |
| Pixel 8 / 9 | 412 × 915 | xs |
| Galaxy S Ultra | 412 × 915 | xs |
| Galaxy Z Fold (cover) | 344 × 882 | xs |
| Galaxy Z Fold (inner) | 673 × 841 | sm |
Phones landscape
| Device | Size (CSS px) | Range | Note |
|---|---|---|---|
| iPhone 16 landscape | 852 × 393 | md | Short height — test sticky headers and sheets |
| Pixel landscape | 915 × 412 | md |
Tablets
| Device | Size (CSS px) | Range |
|---|---|---|
| iPad mini | 744 × 1133 | sm |
| iPad 10th gen / iPad Air 11 | 820 × 1180 | md |
| iPad Pro 11 | 834 × 1210 | md |
| iPad Air 13 | 1024 × 1366 | lg |
| iPad Pro 13 (M4) | 1032 × 1376 | lg |
| iPad 10th gen landscape | 1180 × 820 | lg |
| iPad Pro 13 landscape | 1376 × 1032 | xl |
| Galaxy Tab S9 | 800 × 1280 | md |
Laptops
| Device | Size (CSS px) | Range |
|---|---|---|
| Small Windows laptop | 1366 × 768 | xl |
| MacBook Air 13 default | 1470 × 956 | xl |
| MacBook Pro 14 default | 1512 × 982 | xl |
| 1080p laptop at 125% | 1536 × 864 | xl |
| MacBook Pro 16 default | 1728 × 1117 | 2xl |
Desktops and ultrawides
| Device | Size (CSS px) | Range |
|---|---|---|
| 1080p monitor | 1920 × 1080 | 3xl |
| 1440p monitor | 2560 × 1440 | 4xl |
| 4K at 150% | 2560 × 1440 | 4xl |
| 4K at 100% | 3840 × 2160 | 4xl |
| 21:9 1440p ultrawide | 3440 × 1440 | 4xl |
| 32:9 super ultrawide | 5120 × 1440 | 4xl |
Windowed (split screen)
| Context | Size (CSS px) | Range | Note |
|---|---|---|---|
| Half of 1440p | 1280 × 1440 | xl | Split screen |
| Half of 1080p | 960 × 1080 | md | Split screen — desktop pointer at tablet width |
Modality overrides
| Context | Base device | Pointer | Hover |
|---|---|---|---|
| iPad with keyboard and trackpad | iPad Pro 13 | fine | hover |
| Touchscreen laptop | 1080p laptop at 125% | coarse | hover |
Zoom and text scaling
| Test | Base device |
|---|---|
| 200% browser zoom | MacBook Pro 14 default |
| Large OS text (1.5×) | iPhone 15 / 16 |
Timing & Easing
Motion is for orientation, not decoration. Use the fastest duration that doesn't feel abrupt. Always respect prefers-reduced-motion.
Live demo
Click a duration to fire a panel entrance at that speed. All use --ease.
UI Components
These are the canonical component forms. Copy tokens and structure exactly - variants must stay within this vocabulary.
Orchestration layer for the sovereign agent fleet.
Work platform for the team - tasks, time, clients.
Component Library
Full anatomy, states, keyboard behavior, and ARIA contract for every component Surface uses. All components use semantic tokens only - never raw values.
IconButton
Square button containing a single icon. Used where space is constrained and the action is understood from context. Always paired with a visible or aria label.
Anatomy
- Root -
<button>, enforces square aspect ratio viapadding: equal - Icon - Lucide icon, 20px default, 16px sm, 24px lg
- Tooltip - required for accessibility (see Tooltip entry)
States
| State | Visual |
|---|---|
| Default | Transparent background, --text-tertiary icon |
| Hover | Background --overlay, icon --text-primary |
| Focus-visible | 2px offset outline --accent |
| Active | Background darkens one step; transform scale(0.95) |
| Disabled | opacity 0.45; pointer-events none; aria-disabled="true" |
Keyboard
| Key | Behavior |
|---|---|
| Enter / Space | Triggers action |
| Tab | Advances focus |
ARIA
- Role:
button(native) aria-labelrequired - describes the action, not the iconaria-disabled="true"when disabled (do not rely on HTMLdisabledalone)
Swatch
Link
Inline navigation or action element. Renders as an <a> tag when navigating, <button> when triggering an action.
Anatomy
- Root -
<a href>or<button> - Underline - appears on hover via
text-decoration - External icon - optional Lucide
ExternalLinkat 12px for new-tab links
States
| State | Visual |
|---|---|
| Default | --accent color, no underline |
| Hover | Underline appears; opacity 0.85 |
| Focus-visible | 2px offset outline --accent |
| Visited | Muted - --text-tertiary (navigation links only) |
| Disabled | opacity 0.45; pointer-events none |
Keyboard
| Key | Behavior |
|---|---|
| Enter | Follows link or triggers action |
| Tab | Advances focus |
ARIA
- Role:
link(native<a>) orbutton(action trigger) target="_blank"links addrel="noopener"and visually indicate new-tab behavioraria-current="page"on active nav links
Swatch
Textarea
Multi-line text input. Supports auto-grow (height tracks content) and an optional character count.
Anatomy
- Label - above the field,
--text-secondary - Field -
<textarea>, min 3 rows, grows with content - Character count - optional, right-aligned below the field
- Helper text - optional, left-aligned below the field
States
| State | Visual |
|---|---|
| Default | Border --border-default, background --sunken |
| Focus | Border --accent, box-shadow --accent-glow |
| Error | Border --red, helper text --red |
| Disabled | opacity 0.45; cursor not-allowed |
| Read-only | No focus ring; background --raised |
Keyboard
| Key | Behavior |
|---|---|
| Tab | Moves focus in/out of field |
| Enter | Inserts newline (not form submit) |
| Ctrl+Enter | Submit form (when configured) |
ARIA
- Role:
textboxwitharia-multiline="true"(native) aria-describedbylinks to helper text and/or character countaria-invalid="true"in error state
Swatch
Select
Single-value picker rendered as a styled native <select>. Clearable via an inline X button when a value is chosen.
Anatomy
- Label - above the control
- Trigger - shows selected value or placeholder
- Chevron icon - Lucide
ChevronDown, right-aligned - Clear button - replaces chevron when value is set (clearable only)
States
| State | Visual |
|---|---|
| Default | Border --border-default, placeholder --text-tertiary |
| Focus | Border --accent, glow |
| Open | Chevron rotates 180deg; dropdown visible |
| Disabled | opacity 0.45; cursor not-allowed |
| Error | Border --red |
Keyboard
| Key | Behavior |
|---|---|
| Space / Enter | Opens dropdown |
| Arrow Up/Down | Navigates options |
| Enter | Selects focused option |
| Escape | Closes without change |
| Tab | Closes and moves focus |
ARIA
- Role:
comboboxwitharia-expandedandaria-haspopup="listbox" - Listbox: role
listbox, options roleoption aria-selected="true"on the active option
Swatch
Combobox
Searchable select with autocomplete. Supports single and multi-select. The input filters the dropdown list in real time.
Anatomy
- Input - text field with search icon; shows selected value(s) or placeholder
- Dropdown - filtered list in a
--raisedpanel - Option row - label + optional description; checkmark when selected
- Tags strip - multi-select shows selected items as removable tags above the input
- Empty state - "No results" when filter returns nothing
States
| State | Visual |
|---|---|
| Closed | Shows placeholder or selected value; chevron down |
| Open | Dropdown visible; input editable; chevron rotated |
| Loading | Spinner in dropdown while options fetch |
| Disabled | opacity 0.45; cursor not-allowed |
Keyboard
| Key | Behavior |
|---|---|
| Arrow Down | Opens dropdown or moves focus to next option |
| Arrow Up | Moves focus to previous option |
| Enter | Selects focused option; closes if single-select |
| Escape | Closes; restores previous value |
| Backspace | Multi-select: removes last tag when input is empty |
ARIA
- Input:
role="combobox",aria-autocomplete="list",aria-controlspoints to listbox - Listbox:
role="listbox", optionsrole="option" aria-selected="true"on selected options in multi-select
Swatch
Checkbox
Binary selection control. Supports an indeterminate state for "select all" patterns. Label can be positioned before or after.
Anatomy
- Box - 16x16px, border-radius
--rx-xs - Check mark - Lucide
Checkpath,--accentcolor - Label - inline text, clickable
States
| State | Visual |
|---|---|
| Unchecked | Border --border-strong, transparent fill |
| Checked | Fill --accent, white check, no border |
| Indeterminate | Fill --accent-dim, horizontal dash |
| Focus-visible | 2px offset outline --accent |
| Disabled | opacity 0.45; cursor not-allowed |
| Error | Border --red |
Keyboard
| Key | Behavior |
|---|---|
| Space | Toggles checked state |
| Tab | Advances focus |
ARIA
- Role:
checkbox(native<input type="checkbox">) aria-checked="mixed"for indeterminate statearia-labelledbyor visible<label>
Swatch
Radio
Mutually exclusive option within a role="radiogroup". Always used in groups of two or more.
Anatomy
- Circle - 16x16px, full radius
- Dot - 6x6px filled dot when selected,
--accent - Label - inline text, clickable
States
| State | Visual |
|---|---|
| Unselected | Border --border-strong, transparent center |
| Selected | Border --accent, filled --accent dot |
| Focus-visible | 2px offset outline --accent |
| Disabled | opacity 0.45; cursor not-allowed |
Keyboard
| Key | Behavior |
|---|---|
| Arrow Up/Down/Left/Right | Moves selection within group |
| Space | Selects focused radio |
ARIA
- Group:
role="radiogroup"witharia-labelledby - Individual:
role="radio",aria-checked
Swatch
Switch
Binary on/off toggle. Semantically a checkbox with toggle styling. Label can be before or after the control.
Anatomy
- Track - 32x18px pill,
--border-defaultoff /--accenton - Thumb - 14x14px white circle, translates 14px on activation
- Label - optional text
States
| State | Visual |
|---|---|
| Off | Track --overlay, thumb left |
| On | Track --accent, thumb right |
| Focus-visible | 2px offset outline on track |
| Disabled | opacity 0.45; cursor not-allowed |
Keyboard
| Key | Behavior |
|---|---|
| Space | Toggles state |
| Tab | Advances focus |
ARIA
- Role:
switch,aria-checked="true|false" - Implemented as
<input type="checkbox" role="switch">
Swatch
DatePicker
Text input that opens a calendar popover on focus or icon click. Supports single date and date range selection.
Anatomy
- Input - shows formatted date string
- Calendar icon - right-side trigger (Lucide
Calendar) - Popover - calendar grid, month/year navigation
- Day cell - 32x32px button; selected =
--accentfill; in-range =--accent-dim
States
| State | Visual |
|---|---|
| Closed | Input shows placeholder or formatted date |
| Open | Calendar popover visible below input |
| Date selected | Day cell filled --accent |
| Range | Start/end = --accent; in-between = --accent-dim |
| Disabled | Input disabled; specific dates greyed out |
Keyboard
| Key | Behavior |
|---|---|
| Enter / Space | Opens/closes calendar; selects focused day |
| Arrow keys | Navigates days within calendar grid |
| Page Up/Down | Navigates months |
| Home / End | Moves to first/last day of week |
| Escape | Closes without change |
ARIA
- Input:
role="combobox",aria-haspopup="dialog" - Calendar:
role="dialog",aria-label="Calendar" - Grid:
role="grid"; cells:role="gridcell"
Swatch
Tabs
Horizontal strip that shows one panel at a time. Keyboard-navigable per ARIA authoring practices. Overflows with horizontal scroll at narrow widths.
Anatomy
- Tab list - horizontal row of tab triggers
- Tab trigger - button with label; active tab has bottom border
--accent - Panel - content area shown for the active tab
States
| State | Visual |
|---|---|
| Default | Color --text-tertiary |
| Active | Color --accent; 2px bottom border --accent |
| Hover | Color --text-secondary |
| Focus-visible | 2px offset outline |
| Disabled | opacity 0.4; pointer-events none |
Keyboard
| Key | Behavior |
|---|---|
| Arrow Left/Right | Moves focus through tab triggers |
| Home / End | First / last tab |
| Enter / Space | Activates focused tab |
| Tab | Moves focus into the active panel |
ARIA
- Tab list:
role="tablist" - Tabs:
role="tab",aria-selected,aria-controlspoints to panel - Panels:
role="tabpanel",aria-labelledbypoints to tab
Swatch
SegmentedControl
Compact inline button group acting as a single-select. Used for switching between two or more views or modes, typically 2-5 options.
Anatomy
- Track - pill container with
--sunkenbackground - Segment - button per option; active has
--raisedbackground
States
| State | Visual |
|---|---|
| Unselected | Transparent background, --text-tertiary |
| Selected | --raised background, --text-primary |
| Focus-visible | Outline on active segment |
| Disabled | opacity 0.45 |
Keyboard
| Key | Behavior |
|---|---|
| Arrow Left/Right | Moves selection |
| Home / End | First / last segment |
ARIA
- Container:
role="radiogroup" - Segments:
role="radio",aria-checked
Swatch
Tag
Removable label chip. Variants: default (neutral), status-colored, identity-colored. Used for multi-value selection, filters, and labeling.
Anatomy
- Label - text, 12px
- Remove button - Lucide
Xat 12px, appears on hover or always - Dot - optional 6px indicator for status variants
States
| State | Visual |
|---|---|
| Default | Background --overlay, border --border-default |
| Hover | Remove button becomes visible / more opaque |
| Focus-visible | 2px outline on remove button |
| Status variant | Matches --status-* color family |
Keyboard
| Key | Behavior |
|---|---|
| Backspace / Delete | Removes tag when tag itself is focused |
| Enter / Space | Activates remove button when focused |
ARIA
- Tag:
role="option"within arole="listbox" - Remove button:
aria-label="Remove [tag label]"
Swatch
Avatar
Circular user representation. Shows image if available; falls back to initials on an identity-color background. Stacked group variant overlaps multiple avatars.
Anatomy
- Circle - xs 20px, sm 24px, md 32px, lg 40px
- Image - fills circle; object-fit cover
- Initials fallback - 1-2 chars on identity-color background
- Status ring - optional 2px border in
--status-*color - Overflow chip - stacked group shows +N for extras
States
| State | Visual |
|---|---|
| Default | No ring |
| Online | 2px --green ring |
| Away | 2px --yellow ring |
| Busy | 2px --red ring |
ARIA
aria-label="[Name]'s avatar"oralton the image- Decorative-only avatars:
aria-hidden="true" - Stack:
aria-label="[A], [B], and 3 more"
Swatch
Tooltip
Non-interactive label that appears on hover or focus after a 300ms delay. Four placements: top, right, bottom, left. Never contains interactive elements.
Anatomy
- Trigger - any focusable element
- Bubble -
--overlaybackground, 1px border, 4px radius - Arrow - 5px CSS triangle pointing to trigger
States
| State | Visual |
|---|---|
| Hidden | opacity 0, pointer-events none |
| Visible | opacity 1, translateY(0); 300ms open delay |
| Reduced motion | No animation; instant appear/hide |
ARIA
- Bubble:
role="tooltip" - Trigger:
aria-describedbypoints to tooltip id - Never receives keyboard focus
Swatch
Popover
Interactive floating panel anchored to a trigger. Unlike Tooltip, it can contain interactive elements. Dismissed by Escape, click outside, or an explicit close button.
Anatomy
- Trigger - button or control that opens the popover
- Panel -
--raisedcard with 1px border and--rx-lg - Close button - top-right X button (optional)
- Content zone - unconstrained; can contain any interactive content
States
| State | Visual |
|---|---|
| Closed | Panel not rendered in DOM |
| Open | Panel visible; focus moves to first focusable element inside |
Keyboard
| Key | Behavior |
|---|---|
| Enter / Space | Opens popover from trigger |
| Escape | Closes; returns focus to trigger |
| Tab | Cycles through interactive elements inside |
ARIA
- Trigger:
aria-haspopup="dialog",aria-expanded,aria-controls - Panel:
role="dialog"orrole="region",aria-label
Swatch
Dialog
Modal overlay blocking interaction with the page behind. Three width tiers: sm 360px, md 480px, lg 600px. Always has a dismiss path.
Anatomy
- Backdrop - full-viewport semi-transparent overlay
- Panel - centered card with header, body, footer zones
- Header - title + optional close button
- Body - scrollable if content overflows
- Footer - right-aligned actions
States
| State | Visual |
|---|---|
| Opening | Backdrop fades in; panel scales from 0.96 to 1 + fades |
| Closing | Reverse; --dur-fast |
| Destructive | Primary action uses btn-destructive |
Keyboard
| Key | Behavior |
|---|---|
| Escape | Closes dialog |
| Tab | Cycles within dialog (focus trap) |
| Shift+Tab | Cycles backward within dialog |
ARIA
- Panel:
role="dialog",aria-modal="true",aria-labelledbypoints to title - Focus trap active while open; restored to trigger on close
Swatch
Drawer
Side panel that slides in from the right or left edge. Two behaviors: overlay (backdrop blocks page) and push (content shifts).
Anatomy
- Backdrop - overlay variant only; semi-transparent
- Panel - slides from edge; default width 320px (right), 240px (left nav)
- Header - title + close button
- Body - scrollable content
States
| State | Visual |
|---|---|
| Closed | Panel offscreen (translateX ±100%) |
| Opening | Slides in over --dur-normal |
| Open | Panel on screen; focus moved to header |
Keyboard
| Key | Behavior |
|---|---|
| Escape | Closes drawer |
| Tab | Cycles within drawer (focus trap when overlay) |
ARIA
- Panel:
role="dialog",aria-modal="true"for overlay;role="complementary"for push aria-labelledbypoints to drawer title
Swatch
Sheet
Responsive side/bottom panel. Renders as a bottom sheet on viewports under 640px, as a right-edge drawer on wider viewports.
Anatomy
- Handle - 4x32px drag indicator at top of bottom sheet
- Panel - bottom: full width, max-height 75vh; side: same as Drawer
- Snap points - optional: 25%, 50%, 100% for swipe-to-expand
States
| State | Visual |
|---|---|
| Mobile (bottom) | Slides up from bottom edge |
| Desktop (side) | Slides in from right edge |
| Snap expanded | Height extends to next snap point on swipe/drag |
Keyboard
| Key | Behavior |
|---|---|
| Escape | Closes sheet |
| Tab | Cycles through contents |
ARIA
- Role:
dialog,aria-modal="true" - Handle:
role="separator",aria-orientation="horizontal"
Swatch
Toast
Transient notification anchored to the bottom of the viewport. Auto-dismisses after 4000ms. Four semantic variants: info, success, warning, error.
Anatomy
- Icon - Lucide icon for variant (optional)
- Message - single-line label, max 60 chars
- Action - optional single text link (e.g. "Undo")
- Dismiss - X button
States
| State | Visual |
|---|---|
| Entering | Slides up from bottom + fade in |
| Visible | Fully opaque; progress bar optionally shows time remaining |
| Exiting | Fades out + slides down |
ARIA
- Container:
role="status"for info/success;role="alert"for warning/error aria-live="polite"(info/success) oraria-live="assertive"(error)- Dismiss button:
aria-label="Dismiss"
Swatch
Banner
Persistent inline alert bar. Unlike Toast, it stays until dismissed or the condition clears. Placed at the top of a section or page.
Anatomy
- Icon - Lucide variant icon
- Message - can be multi-line; may contain a link
- Dismiss button - right-aligned X (when dismissible)
States
| State | Visual |
|---|---|
| Info | --info accent, rgba(88,101,242,0.1) background |
| Success | --green accent, --green-dim background |
| Warning | --yellow accent, --yellow-dim background |
| Error | --red accent, --red-dim background |
ARIA
- Role:
alertfor error/warning;statusfor info/success - Dismiss button:
aria-label="Dismiss"
Swatch
Table
Sortable data table with row selection, sticky header, empty state, and loading skeleton. Used for client lists, task tables, and log views.
Anatomy
- Header row - sticky; sortable columns show sort chevron
- Data row - 40px default height; 32px dense mode
- Selection cell - checkbox in first column (optional)
- Actions cell - icon buttons in last column (optional)
- Pagination - below the table; page size selector
States
| State | Visual |
|---|---|
| Row hover | Background --raised |
| Row selected | Background --accent-dim, left border --accent |
| Loading | Skeleton rows replace data rows |
| Empty | EmptyState component centered in table body |
| Sorted asc/desc | Column header shows Lucide ChevronUp/Down |
Keyboard
| Key | Behavior |
|---|---|
| Tab | Moves focus through interactive cells |
| Space | Toggles row selection |
| Enter | Opens row detail or activates primary action |
ARIA
- Role:
table(orgridfor interactive cells) - Sortable header:
aria-sort="ascending|descending|none" - Selected row:
aria-selected="true"
Swatch
| Name | Status | Owner |
|---|---|---|
| Project Alpha | Active | Charles B. |
| Design System | Done | Sarah A. |
| API Migration | In Review | Charles B. |
DataList
Key-value pair display. Two layouts: horizontal (label left, value right) and vertical (label above value). Used in settings panels, detail sidebars, and record views.
Anatomy
- Row - label + value pair
- Label -
--text-tertiary, 12px, uppercase tracking - Value -
--text-primary, 14px; can contain inline components - Divider - 1px
--border-subtlebetween rows
ARIA
- Rendered as
<dl>with<dt>(label) and<dd>(value) pairs
Swatch
EmptyState
Zero-state placeholder shown when a list or view has no content. Provides context and an optional call-to-action.
Anatomy
- Icon container - 48x48px rounded square,
--overlaybackground - Title - 15px semibold,
--text-primary - Body - 13px,
--text-tertiary, max-width 280px - CTA - optional primary or ghost button
ARIA
- No special role required; content is static
- CTA button follows standard button ARIA
Swatch
Skeleton
Loading placeholder that matches the shape of the content it replaces. Uses a pulse animation; respects prefers-reduced-motion.
Anatomy
- Block - rounded rectangle at the exact dimensions of expected content
- Circle - for avatars and icons
- Animation - opacity pulse 1.5s infinite; static when reduced-motion
ARIA
- Container:
aria-busy="true",aria-label="Loading" - Individual skeleton blocks:
aria-hidden="true"
Swatch
Spinner
Inline loading indicator for indeterminate progress. Color inherits currentColor. Three sizes: sm 16px, md 20px, lg 24px.
Anatomy
- Track - full circle border,
--border-default - Arc - one quadrant colored; rotates 360deg in 800ms linear infinite
ARIA
- Role:
status,aria-label="Loading" - Wrap with
aria-live="polite"container to announce completion - Respects
prefers-reduced-motion(reduce opacity, no spin)
Swatch
PageHeader
Top-of-page title zone. Contains breadcrumb, title, subtitle, and an actions slot. Used on every major page in Surface.
Anatomy
- Breadcrumb - optional; Lucide
ChevronRightseparators - Title - h1, 22px semibold
- Subtitle - optional, 13px
--text-tertiary - Actions slot - right-aligned buttons and controls
ARIA
- Breadcrumb nav:
aria-label="Breadcrumb" - Current page breadcrumb:
aria-current="page" - Title:
<h1>(one per page)
Swatch
Projects
3 active projects
Toolbar
Horizontal action strip with grouped icon buttons and controls. Groups are separated by dividers. Overflows into a "More" menu at narrow widths.
Anatomy
- Group - set of logically related controls
- Divider - 1px vertical separator between groups
- Overflow menu - "..." button that captures items that don't fit
Keyboard
| Key | Behavior |
|---|---|
| Arrow Left/Right | Moves focus through toolbar items |
| Home / End | First / last toolbar item |
| Tab | Exits toolbar to next focusable element |
ARIA
- Container:
role="toolbar",aria-label - Roving tabindex pattern within the toolbar
Swatch
Sidebar
Vertical navigation panel. Collapsible to rail mode at narrow breakpoints or on user toggle. Width range: 200-280px expanded, 48px collapsed.
Anatomy
- Header - brand/logo and workspace switcher
- Nav section - labeled group of nav items
- Nav item - icon + label; active state; badge for counts
- Footer - account, settings, collapse toggle
States
| State | Visual |
|---|---|
| Expanded | Full width; icon + label visible |
| Collapsed (rail) | 48px; icons only; labels appear as tooltips |
| Active item | Background --overlay, --text-primary |
| Badge | Numeric badge on right side of item |
ARIA
- Nav:
role="navigation",aria-label="Main navigation" - Collapse toggle:
aria-expanded,aria-controls - Active item:
aria-current="page"
Swatch
Rail
Icon-only collapsed navigation. 48px wide. Each item shows a Tooltip on hover/focus. Used as the collapsed state of Sidebar and as a persistent primary nav on wide screens.
Anatomy
- Column - 48px fixed width, full height
- Item - 36x36px centered icon button;
--rx-sm - Active indicator -
--accent-dimbackground,--accenticon - Tooltip - label appears on right on hover/focus
Keyboard
| Key | Behavior |
|---|---|
| Arrow Up/Down | Moves focus through rail items |
| Enter / Space | Navigates to item |
ARIA
- Nav:
role="navigation",aria-label="Primary navigation" - Items:
role="link"orbutton,aria-labelwith section name - Active:
aria-current="page"
Swatch
SplitPane
Resizable two-pane layout with a draggable divider. Supports horizontal (side-by-side) and vertical (stacked) splits. Enforces min/max size constraints on each pane.
Anatomy
- Pane A - primary pane; often list or nav
- Divider - 4px hit area, 1px visual; drag handle cursor
- Pane B - secondary pane; often detail or editor
- Collapse trigger - optional double-click or button to snap pane
States
| State | Visual |
|---|---|
| Default | Divider at configured default position |
| Dragging | Cursor changes to resize; divider highlights |
| Snapped | One pane at min-width; other fills space |
Keyboard
| Key | Behavior |
|---|---|
| Arrow Left/Right (on divider) | Moves divider 10px per press |
| Home / End | Snaps to min or max |
ARIA
- Divider:
role="separator",aria-valuenow(percent),aria-valuemin,aria-valuemax aria-orientation="vertical|horizontal"
Swatch
CommandPalette
Keyboard-triggered search and command overlay. Opened with Cmd+K (Mac) / Ctrl+K (Windows). Searches pages, actions, and recent items. Results are grouped and keyboard-navigable.
Anatomy
- Backdrop - full-viewport semi-transparent overlay
- Panel - centered, max-width 480px,
--overlaybackground - Search input - autofocused; placeholder "Search or type a command…"
- Result group - labeled section (Pages, Actions, Recent)
- Result item - icon + label + optional shortcut hint
- Empty state - "No results for [query]"
Keyboard
| Key | Behavior |
|---|---|
| Cmd/Ctrl+K | Opens palette |
| Arrow Up/Down | Moves focus through results |
| Enter | Executes focused result |
| Escape | Closes palette |
| Tab | Same as Arrow Down |
ARIA
- Panel:
role="dialog",aria-modal="true",aria-label="Command palette" - Input:
role="combobox",aria-autocomplete="list" - Results:
role="listbox", itemsrole="option" - Active result:
aria-selected="true"
Swatch
Icon System
Surface uses Lucide as the system icon library. All icons are 24×24, 1.5px stroke, currentColor. Never fill icons. Scale to 20px for standard UI and 16px for dense contexts.
Copy Standards
ArcGrid speaks like a senior engineer who respects the reader's time: precise, direct, no filler. Avoid marketing fluff and corporate hedging equally.
| Do | Don't |
|---|---|
| Your task was published. | Your task has been successfully published! |
| No results. Try a different filter. | Oops! We couldn't find anything. |
| Delete project - this can't be undone. | Are you sure you want to proceed? |
| Sign in to continue. | Please log in to access this resource. |
| Connecting to ArcGrid… | Please wait while we establish a secure connection to your workspace. |
| Saved. | Your changes have been automatically saved. |
| 3 items need attention. | We noticed some items that may require your attention! |
| ArcGrid - sovereign work platform | ArcGrid: AI-powered productivity for modern teams |
UX Patterns & Decision Rules
Behavioral standards and when-to-use-what lookup tables. Each pattern has a stable ID so agents and engineers can reference it unambiguously. Decision rules delegate to patterns; patterns do not recapitulate rules.
Standards for interaction behavior. Each has a stable ID for unambiguous reference.
UX-P01 — Destructive and consequential actions
Match confirmation weight to consequence. Buttons always name the action — never "OK" or "Yes".
| Condition | Treatment |
|---|---|
| Reversible (archive, remove, move, unassign) | Execute immediately + undo toast (10 s) |
| Irreversible, or affects others, or affects >25 items | Confirmation dialog naming object and consequence |
| Highest severity (delete client, workspace, project with history, billing) | Typed confirmation — type the object name |
UX-P02 — Optimistic updates
Low-risk edits (rename, status change, reorder, toggle) update immediately. On server failure, roll back and show an inline error at the element with retry. Never optimistic for payments, permissions, deletion of others' work, or agent execution.
UX-P03 — Loading and waiting
| Expected wait | Treatment |
|---|---|
| Under 300 ms | Nothing |
| 300 ms – 1 s | Inline spinner in the triggering control; control disabled |
| Over 1 s, content region | Skeleton matching the final layout (no layout shift) |
| Over 10 s | Progress with plain description of current step + cancel |
| Background work | Activity indicator in shell; completion notification if user navigated away |
UX-P04 — Errors
- Show errors where they happened: field, row, panel, or page — in that order of preference.
- Say what happened and what to do next. Raw codes only in an expandable details area.
- Never lose user input on error. Preserve drafts.
- Page-level failures offer retry and a way back.
UX-P05 — Empty states
| Kind | Content |
|---|---|
| First use | One sentence on what this area is for, one primary action |
| No results | State the filter or query, offer to clear it |
| Cleared (inbox zero, all done) | Quiet confirmation, no celebration graphics |
| No permission | Say who can grant access |
| Error loading | Per UX-P04 |
UX-P06 — Forms and saving
- Validate a field on blur after the user has interacted with it; validate everything on submit.
- Long forms (over 8 fields) show an error summary at the top linking to each field.
- Settings autosave per field with a "Saved." confirmation. Forms that create objects use an explicit primary action.
- Documents and editors autosave continuously with visible save state and version history.
- Unsaved changes warn on navigation only when autosave is not in effect.
UX-P07 — Feedback hierarchy
| Channel | Use for | Blocks work | Persists |
|---|---|---|---|
| Inline | Field and element state, local errors | No | While relevant |
| Toast | Transient success, undo, background completion | No | 5 s, 10 s with undo |
| Banner | Page or system state (offline, degraded, trial, maintenance) | No | Until resolved or dismissed |
| Dialog | A decision the user must make now | Yes | Until answered |
| Notification center | Async events to review later (mentions, approvals, agent completions) | No | Until read |
One toast at a time per region; stack at most three. Never a dialog for information that needs no decision.
UX-P08 — Search, filter and sort
- Active filters shown as removable chips with a clear-all.
- Filter, sort and view state encoded in the URL so views are shareable, and persisted per user per view.
- Result counts shown. Saved views available in list-heavy areas.
UX-P09 — Selection and bulk actions
- Checkbox selection with shift-click range select. Selecting shows a contextual action bar with the count.
- "Select all" selects the visible page; selecting across all pages is an explicit second step naming the total.
- Bulk destructive actions follow UX-P01.
UX-P10 — Navigation model
- Left-nav areas are the top level. Within an area: collection, then object.
- Objects open in a detail pane at lg and above; pushed view below lg.
- Every object has a stable deep link. Back returns to prior scroll position and selection.
- Breadcrumbs only when depth exceeds two. Opening a second layer on top of a dialog is not allowed — use a drawer or navigate.
UX-P11 — Keyboard model
| Key | Action |
|---|---|
Cmd/Ctrl K | Command palette (navigate, create, run plays, find anything) |
/ | Focus search |
? | Shortcut sheet |
Esc | Close topmost layer |
g then letter | Go to an area |
j / k | Move in lists |
Enter | Open selected item |
x | Select item |
Focus returns to the triggering element when a layer closes. Every shortcut is discoverable in the command palette.
UX-P12 — Permissions and unavailable actions
- Disable with a reason (tooltip or helper text) when the user could gain access or the condition could change.
- Hide when the action will never apply to this user or object.
UX-P13 — Data display
| Data type | Rule |
|---|---|
| Dates | Relative under 7 days ("3 hours ago"), absolute otherwise ("Sep 26"), year shown if not current; full timestamp on hover; user's local timezone |
| Durations | "1h 25m"; ArcTime uses the same formatter |
| Numbers | Thousands separators; tabular numerals in tables; compact form (1.2k) only in summaries and charts |
| Currency | Symbol and two decimals in detail, rounded in summaries; currency code shown when mixed |
| Truncation | End truncation for prose; middle truncation for ids and filenames; full value on hover and copyable |
| Empty values | "Not set" in tertiary text; never a bare dash in forms |
| Status | One status-to-color mapping used everywhere; always with a text label or icon (never color alone) |
| Names | Display name, then email on hover; agents labeled per AI-P01 |
UX-P14 — Real-time and presence
- Other people and agents viewing or editing an object shown as avatars in the header.
- Live updates never shift content under the cursor; new items above the viewport show a "New items" pill.
- Concurrent edits: field-level last-write with a visible notice, or presence locks for documents.
UX-P15 — Onboarding and help
- Contextual help near the thing it explains. No product tours by default.
- First-use empty states carry the onboarding load (UX-P05).
UX-P16 — Notifications
- In-app notification center is the source; email and mobile push are opt-in per category.
- Group related events. Every notification links to the object and states what changed and who did it (human or agent).
When-to-use-what lookup. Encoded in rules/decision-rules.json so agents can evaluate them programmatically.
DR-01 — Where does this content or task open?
| Condition | Use |
|---|---|
| Single value edit | Inline edit |
| A few fields; context must stay visible | Popover |
| Task or object detail while keeping the list visible | Drawer or detail pane (pane at lg+) |
| A decision that must be made now, little content | Dialog |
| Anything long, multi-step, shareable, or worth a URL | Full page |
| Phone ranges (xs, sm) + the choice above is popover or dialog | Sheet |
DR-02 — How is a collection displayed?
| Condition | Use |
|---|---|
| Items compared across several attributes; sorting matters | Table (becomes DataList below 560px container width) |
| Items scanned by title with one or two attributes | List |
| Items identified visually (images, previews, designs) | Cards |
| Items moving through stages | Board |
| Items defined by dates | Calendar or timeline |
DR-03 — Navigation within an area
| Condition | Use |
|---|---|
| 2–5 peer views of the same object | Tabs |
| 2–4 modes of the same view (list or board) | Segmented control |
| More than 5 sections, or settings | Secondary sidebar (collapses to select below md) |
| Views that should be linkable independently | Sub-routes |
DR-04 — Choosing from options
| Count / behavior | Use |
|---|---|
| 2–4, all visible matters | Radio group or segmented control |
| 5–15 | Select |
| Over 15, or searchable, or creatable | Combobox |
| Multiple values | Checkbox group (under 8) or multi-select combobox |
| Binary setting that applies immediately | Switch |
| Binary choice submitted with a form | Checkbox |
DR-05 — Confirmation
Delegates to UX-P01. Inputs: reversible, affects others, item count, severity. Returns: undo toast, confirm dialog, or typed confirmation.
DR-06 — Feedback channel
Delegates to UX-P07. Inputs: needs decision, scope (element, page, system), persistence. Returns: inline, toast, banner, dialog, or notification.
DR-07 — Date and time input
- Single date: date picker with typed entry.
- Range: range picker with presets (today, this week, last 30 days).
- Time only: typed entry with validation.
- Relative scheduling ("in 2 days") accepted wherever agents or plays schedule work.
DR-08 — Chart type
| Question | Use |
|---|---|
| Change over time | Line (area only for cumulative totals) |
| Comparison across categories | Bar, horizontal when labels are long |
| Part of a whole, 2–5 parts | Stacked bar; donut only in small summaries |
| Distribution | Histogram |
| Relationship | Scatter |
| Single key figure | Stat with trend, not a chart |
DR-09 — Human or agent action surface
Delegates to AI-P05. Inputs: risk tier from ArcCharter, reversibility, cost. Returns: auto-run, run-and-notify, approve, or dual-approve.
DR-10 — Hide or disable
Delegates to UX-P12. Disable with a reason when access could be granted or condition could change. Hide when the action will never apply.
Surface is agent-first. These patterns cover every surface where agents act: Chat, Curate, Plays, Studio, Whiteboard, Work. Defining them once makes ArcGrid feel like one product.
AI-P01 — Agent identity
- Agents use rounded-square avatars; people use circles. An agent marker is always present.
- Agents use identity colors from the same set as people, assigned once and never reused for a person in the same workspace.
- An agent acting on behalf of a person shows both: "Research agent for Charles".
- Agents never present as human.
AI-P02 — Agent status
One status vocabulary everywhere, rendered with the standard status pill and one subtle motion indicator (reduced motion: static icon). "Waiting on you" is the highest priority state and surfaces in the shell and notifications.
| Status | Meaning |
|---|---|
idle | Agent is available, no active work |
queued | Work accepted, waiting to start |
thinking | Planning or reasoning, no output yet |
working | Executing; shows current step text |
waiting on you | Needs human input or approval — highest priority |
blocked | Cannot proceed; shows reason |
done | Completed successfully |
failed | Ended with an error; see AI-P11 |
stopped | Halted by user; partial work preserved |
AI-P03 — Streaming output
- Render progressively in a region with reserved space to avoid layout jumps.
- Do not autoscroll if the user has scrolled away; show a "Jump to latest" control.
- Output is visibly a draft until complete. A stop control is always visible while streaming.
- Live region announces completion, not every token.
AI-P04 — Plans and steps
- Multi-step work shows its plan before executing when the plan is non-trivial or costly.
- Steps list with per-step status (AI-P02). Each step expandable to details, tool calls and logs.
- The user can edit, reorder or remove steps before approval.
AI-P05 — Approval gates
An approval card states: what the agent will do, why, the impact, a preview or diff, the cost estimate, and the expiry. Actions: Approve, Reject, Edit, Ask a question. Rejection accepts an optional reason that feeds the agent.
| Risk tier (ArcCharter) | Treatment |
|---|---|
| Low / routine | Auto-run |
| Medium | Run and notify |
| High | Approve (one human) |
| Critical / irreversible | Dual approve (two humans) |
Approvals appear in a single queue, in context, and on mobile through ArcPage.
AI-P06 — Provenance
- Every object and edit carries authorship: person, agent, or agent on behalf of person.
- Agent-authored text shows a subtle authorship marker until a person edits or accepts it.
- Claims drawn from sources carry citations that open the source.
- Model and route details (ArcRouter) available on demand in a details panel, not shown by default.
AI-P07 — Confidence and uncertainty
- Show confidence only when it changes what the user should do.
- Three levels — high, medium, low — in words, not percentages (unless calibrated through ArcReflex).
- Low confidence routes to review automatically and says why.
AI-P08 — Cost and budget
- Runs above a cost threshold show an estimate before starting.
- Cycles and plays show a budget meter (ArcCycle) with spent, remaining and projected.
- Actual cost per run visible in run details. Full cost reporting in the Operator Console.
AI-P09 — Undo and rollback
- Every agent write is reversible: undo within the window (UX-P01) or revert through version history.
- An activity log per object lists agent and human changes with revert on each agent change.
AI-P10 — Handoffs
| Direction | Format |
|---|---|
| Agent → person | Handoff card: summary, what was done, open questions, links. Lands in the person's queue. |
| Person → agent | Assign like assigning a person; add instructions and optional plan preview. |
AI-P11 — Agent errors
Say in plain words: what failed, what the agent tried. Offer: retry, edit instructions, or take over. No stack traces in the main view.
AI-P12 — Interruption and control
While an agent is working: pause, stop and redirect ("change the instructions") are always visible. Stopping preserves partial work.
AI-P13 — Suggestions
- Agent suggestions render as visibly distinct ghost or tinted content with accept and dismiss.
- Never auto-applied silently. Acceptance and dismissal are logged for the improvement loop (override rate).
AI-P14 — Context transparency
A "What I used" disclosure shows the context the agent drew on (documents, memory, graph nodes) and lets the user remove items and rerun.
Exemplars
Agents imitate far better than they follow abstract rules. Exemplars are built after components and patterns exist, rendered from real components in all three themes and all eight breakpoint ranges.
Golden screens
Each golden screen scores 95 or above on the scorecard and is captured as code plus screenshots in exemplars/manifest.json. Golden screens are the first place an agent looks (via ds.exemplar) when building or restructuring a page of that type.
| ID | Page type | Surface source | Status |
|---|---|---|---|
GS-01 | List + detail | Work tasks | In Progress |
GS-02 | Dashboard | Home or area overview | In Progress |
GS-03 | Settings | Workspace settings | In Progress |
GS-04 | Document or editor | Studio document | In Progress |
GS-05 | Table-heavy | Time entries or Audience | In Progress |
GS-06 | Chat and agent conversation | Chat | In Progress |
GS-07 | Approval queue | Agent approvals | In Progress |
GS-08 | First use and empty states | Any new area | In Progress |
GS-09 | Mobile shell and navigation | Global | In Progress |
GS-10 | Widescreen three-pane | Work at 3xl and 4xl | In Progress |
| Date | Project | Client | Description | Bill | Hours |
|---|---|---|---|---|---|
| Oct 10 | Website | Dwell | Hero section copy revisions | 1.5 | |
| Oct 10 | Proposal | Fort Knox | Q3 proposal final review | 0.5 | |
| Oct 9 | Design System | Internal | Wave V token sweepup | 2.0 | |
| Oct 9 | Website | Dwell | Homepage wireframes v3 | 3.0 | |
| Oct 8 | Branding | Fort Knox | Brand guidelines PDF export | 1.5 | |
| Oct 7 | Bindery | Internal | Feature matrix research | 2.0 | |
| Total (6 entries shown) | 10.5 | ||||
/api/flagin/deploy with FLAGIN_DEPLOY_SECRET to flip resolved → verified.Do and don't pairs
Harvested automatically from Wave V page sessions. Each pair includes the before screenshot (the don't), the after screenshot (the do), the rules involved, and one sentence explaining why. Stored in exemplars/manifest.json and shown in the Design System under the relevant component or pattern.
Anti-pattern catalog
Seeded from the census and extended during migration. Anti-patterns marked as hard fails block shipping regardless of score: AP-02, AP-06, AP-08, AP-10.
| ID | Anti-pattern | Detection |
|---|---|---|
AP-01 | Emoji or hand-drawn icon in UI chrome | SDS-L05, SDS-L07 |
AP-02 | Div or span used as a button hard fail | SDS-L08 |
AP-03 | Raw hex or off-scale value | SDS-L01 to SDS-L03 |
AP-04 | Action available only on hover | Scorecard, coarse pointer check |
AP-05 | Content stretched across a wide screen | Scorecard, line length and W-rules |
AP-06 | Dialog opened from a dialog hard fail | SDS-L20 |
AP-07 | Dialog used for information with no decision | Scorecard, UX-P07 check |
AP-08 | Destructive action with neither confirm nor undo hard fail | SDS-L21 |
AP-09 | Spinner replacing a whole page for over 1 s | Scorecard, UX-P03 check |
AP-10 | Agent output indistinguishable from human content hard fail | SDS-L23 |
AP-11 | Color as the only carrier of meaning | Scorecard, a11y check |
AP-12 | Raw date or number formatting | SDS-L22 |
AP-13 | Section label eyebrow above every heading | Scorecard, ATELIER judge |
AP-14 | Layout shift when content loads | Scorecard, CLS measurement |
Quality
How Surface screens are scored, what telemetry is collected, and how the design system improves itself over time.
Screen scorecard
Runs in CI on every change touching UI, on every page session, and on demand via ds.score. Ship threshold: 85 with no hard fails. Golden screens: 95.
| Dimension | Weight | Evidence |
|---|---|---|
| Conformance | 25% | Lint results, token use, contract tests |
| Accessibility | 20% | Axe, keyboard walk, contrast per theme, target sizes |
| Responsiveness | 15% | Visual regression across the viewport matrix |
| Pattern correctness | 15% | Decision rules followed, UX and AI patterns applied, anti-patterns absent |
| Usability heuristics | 15% | Agent heuristic review with screenshot evidence (10 Nielsen heuristics) |
| Taste | 10% | ATELIER-001 judge loop |
Hard fails (block ship regardless of score): any lint error, axe serious or critical finding, page-level horizontal scroll, missing required component states, AP-02, AP-06, AP-08, AP-10.
UX telemetry (ArcTrace)
Captured per page and per pattern, baselined in P3 before migration begins. Privacy: inputs masked, content never captured, scope governed by DATACLASS; client tenants opt in.
| Metric | What it tells us |
|---|---|
| Task success rate | Whether people can do the job |
| Time to first meaningful action | Clarity of the page |
| Error rate (validation and system) | Friction and fragility |
| Rage clicks and dead clicks | Broken affordances |
| Navigation backtracks | Confusing structure |
| Flow abandonment | Where people give up |
| Undo rate | Mistakes the UI invited |
| Approval latency | How well approval gates surface |
| Suggestion override rate | Agent suggestion quality and presentation |
| Flagin UI findings per page | Reported pain |
Improvement loop (P5)
Monthly review of open findings plus ad hoc response for severe regressions.
- Detect — a metric regresses, breaches a threshold, or Flagin findings cluster on a pattern.
- Diagnose — an agent analyzes affected pages and privacy-bounded traces and writes a finding.
- Propose — an amendment (
schemas/amendment.schema.json) changing a token, component, pattern, or rule, with expected effect. - Evaluate — scorecard on affected golden screens and pages; optional A/B on the Swift internal tenant for high-traffic patterns.
- Ratify — Charles approves or rejects.
- Roll out — the change ships through the system; every page using the pattern improves at once. Design System version bumps.
- Verify — metrics compared after rollout; result recorded on the amendment.
Supplementary
Reference material for tokens, data visualization, accessibility, and design system governance that extends the core specification.
Additional tokens
| Group | Tokens | Notes |
|---|---|---|
| Elevation | --elev-0 through --elev-4 per theme |
Dark and medium themes express elevation via surface lightness (sunken, base, raised, overlay); shadows stay subtle. Light theme uses soft shadows. |
| Focus ring | --focus-ring-color, --focus-ring-width (2px), --focus-ring-offset (2px) |
Always visible in all themes; never removed, only replaced by a component-specific variant. |
| Layer (z-index) | --layer-base, --layer-sticky, --layer-dropdown, --layer-drawer, --layer-modal, --layer-toast, --layer-tooltip |
Replaces all z-index literals; stacking is declared, not guessed. |
| Density | --row-h, --control-h-sm, --control-h-md, --control-h-lg per density mode |
Comfortable and compact modes. Coarse pointer overrides enforce 44px touch minimum. |
| Content width | --measure-read (~72ch), --measure-form (640px) |
W-01 reading and form caps; applied via max-width on content containers. |
Data visualization
- Categorical palette drawn from the eight identity colors, ordered for maximum distinction, with light-theme equivalents.
- Sequential and diverging scales per theme built from the accent and info hues.
- Axis, gridline, label, and tooltip tokens; chart text uses Caption and Mono roles; numbers formatted per UX-P13.
- Chart type chosen per DR-08. Never color alone: add labels, patterns, or direct annotation.
- Every chart palette passes a color vision deficiency check.
- Visual parity with ArcFigure diagrams so charts and diagrams feel like one system.
Accessibility beyond contrast
Target: WCAG 2.2 AA across Surface.
- Landmarks (
header,nav,main,complementary) and a logical heading order on every page. - Focus trapped in dialogs and drawers, returned to the triggering element on close; skip link to main content on every page.
- Live regions:
aria-live="polite"for toasts and agent completion;aria-live="assertive"only for errors that block the user. - Reduced motion alternatives for every animation, including agent status indicators.
- Forced colors (Windows High Contrast) mode supported for all controls and focus indicators.
- Every icon-only control carries an accessible name; decorative icons are hidden with
aria-hidden="true".
Governance
- Versioning: semantic (major for breaking changes — token removal or rename, contract prop removal; minor for additions; patch for fixes). v1.0.0 at Rev C ratification.
- Deprecation: deprecated tokens and props continue to work as aliases for two minor versions, flagged by lint warnings, then removed in the next major.
- Change control: every change is an amendment record with evidence and a decision ID. Ratification per D-SDS13.
- Agent contributions: agents file amendments via
schemas/amendment.schema.json; they never create local one-offs (R-11). - Release: each release updates
index.json,CHANGELOG.md, and this Design System's change log section, and notifies Grid agents through the index version bump. - Imagery: empty states and spot illustrations use Lucide glyphs at 48px in a tinted container. No stock illustration.