arcgrid

Tokens, components, icons, motion, and voice reference for every ArcGrid surface. The single source of truth for how the platform looks and behaves.

DBA Agent Space, LLC
Domain arc-grid.com
Themes Dark / Medium / Light
Identity

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

16px - favicon
24px - nav
32px - avatar
48px - card / hero
96px - feature

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.

arcgrid

Don'ts

Don't rotate
Don't recolor
Don't distort
Themes

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.

Dark default
arcgrid Live
Sprint 12
3 in progress
Done Blocked Review
Surface
--sunken #0B0E14
--base #10141C
--raised #141926
--overlay #1C2235
Text
--text-primary #D7DEE8
--text-secondary #8B96A5
--text-tertiary #5C6673
Accent
--accent #4FD6BE
--accent-dim #1E4A42
Semantic
--green #3FB950
--yellow #E3B341
--red #F85149
--info #58A6FF
Medium Discord dark
arcgrid Live
Sprint 12
3 in progress
Done Blocked Review
Surface
--sunken #1E1F22
--base #2B2D31
--raised #313338
--overlay #383A40
Text
--text-primary #F2F3F5
--text-secondary #B5BAC1
--text-tertiary #80848E
Accent
--accent #4FD6BE
--accent-dim #1D3D38
Semantic
--green #57F287
--yellow #FAA61A
--red #ED4245
--info #5865F2
Light clean white
arcgrid Live
Sprint 12
3 in progress
Done Blocked Review
Surface
--sunken #F2F3F5
--base #FFFFFF
--raised #F7F8FA
--overlay #FFFFFF
Text
--text-primary #1A1B1E
--text-secondary #4E5058
--text-tertiary #86898F
Accent
--accent #1A9E8C
--accent-dim #D1F0EC
Semantic
--green #1A7A3F
--yellow #B07D14
--red #C7312D
--info #3B44C1

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.

Blue
--identity-1
#58A6FF / #3B44C1
Teal
--identity-2
#4FD6BE / #1A9E8C
Purple
--identity-3
#BC8CFF / #6B4FCF
Amber
--identity-4
#E3B341 / #B07D14
Red
--identity-5
#F85149 / #C7312D
Green
--identity-6
#3FB950 / #1A7A3F
Coral
--identity-7
#FF9580 / #D05F2A
Sky
--identity-8
#89CFF0 / #2A7FBF
Color

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

Sunken
--surface-sunken
#1E1F22
Base
--surface-base
#2B2D31
Raised
--surface-raised
#313338
Overlay
--surface-overlay
#383A40

Borders

Subtle
--border-subtle
#27292C
Default
--border-default
#3F4147
Strong
--border-strong
#5C5F66

Text

Primary
--text-primary
#F2F3F5
Secondary
--text-secondary
#B5BAC1
Tertiary
--text-tertiary
#80848E

Accent

Teal
--color-accent
#4FD6BE
Teal dim
--color-accent-dim
#1D3D38

Semantic

Success
--color-green
#57F287
Warning
--color-yellow
#FEE75C
Danger
--color-red
#ED4245

Cycle statuses

Draft
--status-cycle-draft
Active
--status-cycle-active
Complete
--status-cycle-complete
Paused
--status-cycle-paused
Cancelled
--status-cycle-cancelled
Archived
--status-cycle-archived

Brand colors (external, fixed)

These values are theme-invariant. Use only for third-party brand identity contexts (settings, connections, integrations).

Google
--brand-google
#4285F4
GitHub
--brand-github
#6e40c9
Slack
--brand-slack
#4A154B
Notion
--brand-notion
#000000
Figma
--brand-figma
#F24E1E
LiveKit
--brand-livekit
#00B4D8
Typography

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.

Display
32px / 700 / -0.02em
Sovereign Infra
Heading 1
28px / 700
ArcGrid Surface
Heading 2
22px / 600
Platform Overview
Heading 3
17px / 600
Active Projects
Body
15px / 400 / 1.6
The grid handles orchestration so agents can focus on output. Every task routes through the right model at the right cost.
Caption
13px / 400
Last updated 3 minutes ago · 42 items
Label
11px / 600 / +0.08em
Section label
Dense
--text-dense / 11px / lh 15px
Sub-scale for dense UIs: curate row labels, SessionView timestamps, compact tables
Mono
13px / 400 / mono
--color-accent: #4FD6BE
Spacing & Radius

Space & Shape

Base unit is 4px. All spacing is a multiple. Never use arbitrary pixel values - stay on the scale.

Spacing scale

--space-0
2px sub-scale / tight rule gaps
--sp1
4px icon gaps
--sp2
8px tight inline
--sp3
12px pill padding
--sp4
16px button pad / gap
--sp6
24px card padding
--sp8
32px section gap
--sp10
40px lead margin
--sp16
64px hero / section pad

Border radius

--rx-xs 4px - chips, tags
--rx-sm 6px - buttons, inputs
--rx-md 8px - menus, tooltips
--rx-lg 10px - cards, panels
--rx-full 9999px - pills, badges
Layout

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

viewport edgeviewport edge
.wrap - max-width: 1120px - padding: 0 28px
.page-wrap - max-width: 960px - padding: 0 24px

Breakpoints

Max-widthTokenWhat 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
Application Layout

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.

TokenRange (CSS px)Typical devicesShell layout
xs0 – 479Most phones portrait (360–440)Single column. Bottom tab bar or drawer nav. Sheets instead of dialogs.
sm480 – 767Large phones landscape, foldable inner screens, small tabletsSingle column, wider gutters. Drawer nav.
md768 – 1023iPad portrait, iPad miniCollapsible rail nav (icons only). One primary pane; detail opens as overlay or push.
lg1024 – 1279iPad landscape, iPad Pro portrait, small laptopsRail nav. List + detail split where the page has one.
xl1280 – 159913–14″ laptops, MacBooks at default scalingFull sidebar. Split panes.
2xl1600 – 191915–16″ laptops, 1080p at 100–125%Full sidebar. Optional third context pane.
3xl1920 – 25591080p and 1440p desktop monitorsThree panes available. Content width caps apply.
4xl2560+1440p at 100%, 21:9 and 32:9 ultrawides, 4KThree or four panes. Caps and pane rules are mandatory.

Widescreen rules

Extra width is used for more information, never for stretched content.

RuleRequirement
W-01Reading content (text, forms, settings) caps at ~80 characters. Forms cap near 640px.
W-02Extra width adds panes in order: list → detail → context (activity, properties, agent chat) → optional pinned secondary view.
W-03Tables may use full width but columns have min and max widths. Beyond max, extra space goes to a details pane, not wider columns.
W-04Dashboards increase column count (4, 8, 12, 16) with width rather than scaling cards up.
W-05Panes are user-resizable and collapsible at xl and above. Widths are persisted per user.
W-06Nothing 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 / svh units, never raw 100vh, so browser chrome does not clip content.
  • Respect safe areas with env(safe-area-inset-*) and viewport-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 rem for type and spacing tokens so user font settings apply.
Viewport Test Matrix

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

iPhone 15 / 16 Pixel 8 / 9 iPad 10th gen / Air 11 MacBook Pro 14 default 1080p monitor 1440p monitor 21:9 1440p ultrawide

iOS phones

DeviceSize (CSS px)Range
iPhone SE (3rd gen)375 × 667xs
iPhone 13 mini375 × 812xs
iPhone 15 / 16393 × 852xs
iPhone 16 Plus / 15 Pro Max430 × 932xs
iPhone 16 Pro Max440 × 956xs
Current flagship lineup (2026)verifyxs
Minimum supported320 × 640xs

Android phones

DeviceSize (CSS px)Range
Galaxy S-series base360 × 780xs
Galaxy A-series360 × 800xs
Pixel 8 / 9412 × 915xs
Galaxy S Ultra412 × 915xs
Galaxy Z Fold (cover)344 × 882xs
Galaxy Z Fold (inner)673 × 841sm

Phones landscape

DeviceSize (CSS px)RangeNote
iPhone 16 landscape852 × 393mdShort height — test sticky headers and sheets
Pixel landscape915 × 412md

Tablets

DeviceSize (CSS px)Range
iPad mini744 × 1133sm
iPad 10th gen / iPad Air 11820 × 1180md
iPad Pro 11834 × 1210md
iPad Air 131024 × 1366lg
iPad Pro 13 (M4)1032 × 1376lg
iPad 10th gen landscape1180 × 820lg
iPad Pro 13 landscape1376 × 1032xl
Galaxy Tab S9800 × 1280md

Laptops

DeviceSize (CSS px)Range
Small Windows laptop1366 × 768xl
MacBook Air 13 default1470 × 956xl
MacBook Pro 14 default1512 × 982xl
1080p laptop at 125%1536 × 864xl
MacBook Pro 16 default1728 × 11172xl

Desktops and ultrawides

DeviceSize (CSS px)Range
1080p monitor1920 × 10803xl
1440p monitor2560 × 14404xl
4K at 150%2560 × 14404xl
4K at 100%3840 × 21604xl
21:9 1440p ultrawide3440 × 14404xl
32:9 super ultrawide5120 × 14404xl

Windowed (split screen)

ContextSize (CSS px)RangeNote
Half of 1440p1280 × 1440xlSplit screen
Half of 1080p960 × 1080mdSplit screen — desktop pointer at tablet width

Modality overrides

ContextBase devicePointerHover
iPad with keyboard and trackpadiPad Pro 13finehover
Touchscreen laptop1080p laptop at 125%coarsehover

Zoom and text scaling

TestBase device
200% browser zoomMacBook Pro 14 default
Large OS text (1.5×)iPhone 15 / 16
Motion

Timing & Easing

Motion is for orientation, not decoration. Use the fastest duration that doesn't feel abrupt. Always respect prefers-reduced-motion.

--dur-instant / 80ms Icon swaps, toggle state changes
--dur-fast / 150ms Hover highlights, button press, badge
--dur-normal / 250ms Panel open/close, drawer, modal
--ease / cubic-bezier .2, .8, .3, 1 - fast out, soft land

Live demo

Click a duration to fire a panel entrance at that speed. All use --ease.

Panel appeared
Components

UI Components

These are the canonical component forms. Copy tokens and structure exactly - variants must stay within this vocabulary.

Buttons
Badges
Default Active Online Pending Error ArcGrid
Status pills
Online Away Busy Offline
Input
Card
ArcGrid Harness Beta

Orchestration layer for the sovereign agent fleet.

Surface Live

Work platform for the team - tasks, time, clients.

Surface Application

Component Library

Full anatomy, states, keyboard behavior, and ARIA contract for every component Surface uses. All components use semantic tokens only - never raw values.

Actions2

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 via padding: equal
  • Icon - Lucide icon, 20px default, 16px sm, 24px lg
  • Tooltip - required for accessibility (see Tooltip entry)

States

StateVisual
DefaultTransparent background, --text-tertiary icon
HoverBackground --overlay, icon --text-primary
Focus-visible2px offset outline --accent
ActiveBackground darkens one step; transform scale(0.95)
Disabledopacity 0.45; pointer-events none; aria-disabled="true"

Keyboard

KeyBehavior
Enter / SpaceTriggers action
TabAdvances focus

ARIA

  • Role: button (native)
  • aria-label required - describes the action, not the icon
  • aria-disabled="true" when disabled (do not rely on HTML disabled alone)

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 ExternalLink at 12px for new-tab links

States

StateVisual
Default--accent color, no underline
HoverUnderline appears; opacity 0.85
Focus-visible2px offset outline --accent
VisitedMuted - --text-tertiary (navigation links only)
Disabledopacity 0.45; pointer-events none

Keyboard

KeyBehavior
EnterFollows link or triggers action
TabAdvances focus

ARIA

  • Role: link (native <a>) or button (action trigger)
  • target="_blank" links add rel="noopener" and visually indicate new-tab behavior
  • aria-current="page" on active nav links

Swatch

Inputs7

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

StateVisual
DefaultBorder --border-default, background --sunken
FocusBorder --accent, box-shadow --accent-glow
ErrorBorder --red, helper text --red
Disabledopacity 0.45; cursor not-allowed
Read-onlyNo focus ring; background --raised

Keyboard

KeyBehavior
TabMoves focus in/out of field
EnterInserts newline (not form submit)
Ctrl+EnterSubmit form (when configured)

ARIA

  • Role: textbox with aria-multiline="true" (native)
  • aria-describedby links to helper text and/or character count
  • aria-invalid="true" in error state

Swatch

0 / 500

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

StateVisual
DefaultBorder --border-default, placeholder --text-tertiary
FocusBorder --accent, glow
OpenChevron rotates 180deg; dropdown visible
Disabledopacity 0.45; cursor not-allowed
ErrorBorder --red

Keyboard

KeyBehavior
Space / EnterOpens dropdown
Arrow Up/DownNavigates options
EnterSelects focused option
EscapeCloses without change
TabCloses and moves focus

ARIA

  • Role: combobox with aria-expanded and aria-haspopup="listbox"
  • Listbox: role listbox, options role option
  • 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 --raised panel
  • 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

StateVisual
ClosedShows placeholder or selected value; chevron down
OpenDropdown visible; input editable; chevron rotated
LoadingSpinner in dropdown while options fetch
Disabledopacity 0.45; cursor not-allowed

Keyboard

KeyBehavior
Arrow DownOpens dropdown or moves focus to next option
Arrow UpMoves focus to previous option
EnterSelects focused option; closes if single-select
EscapeCloses; restores previous value
BackspaceMulti-select: removes last tag when input is empty

ARIA

  • Input: role="combobox", aria-autocomplete="list", aria-controls points to listbox
  • Listbox: role="listbox", options role="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 Check path, --accent color
  • Label - inline text, clickable

States

StateVisual
UncheckedBorder --border-strong, transparent fill
CheckedFill --accent, white check, no border
IndeterminateFill --accent-dim, horizontal dash
Focus-visible2px offset outline --accent
Disabledopacity 0.45; cursor not-allowed
ErrorBorder --red

Keyboard

KeyBehavior
SpaceToggles checked state
TabAdvances focus

ARIA

  • Role: checkbox (native <input type="checkbox">)
  • aria-checked="mixed" for indeterminate state
  • aria-labelledby or 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

StateVisual
UnselectedBorder --border-strong, transparent center
SelectedBorder --accent, filled --accent dot
Focus-visible2px offset outline --accent
Disabledopacity 0.45; cursor not-allowed

Keyboard

KeyBehavior
Arrow Up/Down/Left/RightMoves selection within group
SpaceSelects focused radio

ARIA

  • Group: role="radiogroup" with aria-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-default off / --accent on
  • Thumb - 14x14px white circle, translates 14px on activation
  • Label - optional text

States

StateVisual
OffTrack --overlay, thumb left
OnTrack --accent, thumb right
Focus-visible2px offset outline on track
Disabledopacity 0.45; cursor not-allowed

Keyboard

KeyBehavior
SpaceToggles state
TabAdvances 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 = --accent fill; in-range = --accent-dim

States

StateVisual
ClosedInput shows placeholder or formatted date
OpenCalendar popover visible below input
Date selectedDay cell filled --accent
RangeStart/end = --accent; in-between = --accent-dim
DisabledInput disabled; specific dates greyed out

Keyboard

KeyBehavior
Enter / SpaceOpens/closes calendar; selects focused day
Arrow keysNavigates days within calendar grid
Page Up/DownNavigates months
Home / EndMoves to first/last day of week
EscapeCloses without change

ARIA

  • Input: role="combobox", aria-haspopup="dialog"
  • Calendar: role="dialog", aria-label="Calendar"
  • Grid: role="grid"; cells: role="gridcell"

Swatch

Selection2

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

StateVisual
DefaultColor --text-tertiary
ActiveColor --accent; 2px bottom border --accent
HoverColor --text-secondary
Focus-visible2px offset outline
Disabledopacity 0.4; pointer-events none

Keyboard

KeyBehavior
Arrow Left/RightMoves focus through tab triggers
Home / EndFirst / last tab
Enter / SpaceActivates focused tab
TabMoves focus into the active panel

ARIA

  • Tab list: role="tablist"
  • Tabs: role="tab", aria-selected, aria-controls points to panel
  • Panels: role="tabpanel", aria-labelledby points to tab

Swatch

OverviewActivityMembersSettings
Overview panel content

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 --sunken background
  • Segment - button per option; active has --raised background

States

StateVisual
UnselectedTransparent background, --text-tertiary
Selected--raised background, --text-primary
Focus-visibleOutline on active segment
Disabledopacity 0.45

Keyboard

KeyBehavior
Arrow Left/RightMoves selection
Home / EndFirst / last segment

ARIA

  • Container: role="radiogroup"
  • Segments: role="radio", aria-checked

Swatch

Status & Identity2

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 X at 12px, appears on hover or always
  • Dot - optional 6px indicator for status variants

States

StateVisual
DefaultBackground --overlay, border --border-default
HoverRemove button becomes visible / more opaque
Focus-visible2px outline on remove button
Status variantMatches --status-* color family

Keyboard

KeyBehavior
Backspace / DeleteRemoves tag when tag itself is focused
Enter / SpaceActivates remove button when focused

ARIA

  • Tag: role="option" within a role="listbox"
  • Remove button: aria-label="Remove [tag label]"

Swatch

Design Active Blocked

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

StateVisual
DefaultNo ring
Online2px --green ring
Away2px --yellow ring
Busy2px --red ring

ARIA

  • aria-label="[Name]'s avatar" or alt on the image
  • Decorative-only avatars: aria-hidden="true"
  • Stack: aria-label="[A], [B], and 3 more"

Swatch

CB
SA
LG
CB
SA
+3
Overlays6

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 - --overlay background, 1px border, 4px radius
  • Arrow - 5px CSS triangle pointing to trigger

States

StateVisual
Hiddenopacity 0, pointer-events none
Visibleopacity 1, translateY(0); 300ms open delay
Reduced motionNo animation; instant appear/hide

ARIA

  • Bubble: role="tooltip"
  • Trigger: aria-describedby points to tooltip id
  • Never receives keyboard focus

Swatch

Edit settings

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 - --raised card with 1px border and --rx-lg
  • Close button - top-right X button (optional)
  • Content zone - unconstrained; can contain any interactive content

States

StateVisual
ClosedPanel not rendered in DOM
OpenPanel visible; focus moves to first focusable element inside

Keyboard

KeyBehavior
Enter / SpaceOpens popover from trigger
EscapeCloses; returns focus to trigger
TabCycles through interactive elements inside

ARIA

  • Trigger: aria-haspopup="dialog", aria-expanded, aria-controls
  • Panel: role="dialog" or role="region", aria-label

Swatch

Filter options

Menu

Contextual dropdown list. Opens on trigger click. Supports dividers, icons, keyboard shortcuts, and destructive items.

Anatomy

  • Trigger - any button or right-click target
  • Panel - --raised card, min-width 180px, --rx-md
  • Item - 36px tall; icon (optional), label, keyboard shortcut (optional)
  • Divider - 1px --border-subtle separator between groups

States

StateVisual
Default item--text-secondary
Focused/Hovered itemBackground --overlay, color --text-primary
Destructive itemColor --red
Disabled itemopacity 0.45; pointer-events none

Keyboard

KeyBehavior
Arrow Up/DownMoves focus through items
EnterActivates focused item
EscapeCloses; returns focus to trigger
Home / EndFirst / last item

ARIA

  • Panel: role="menu"
  • Items: role="menuitem" (or menuitemcheckbox / menuitemradio)
  • Trigger: aria-haspopup="menu", aria-expanded

Swatch

EditE
DuplicateD
Delete⌫

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

StateVisual
OpeningBackdrop fades in; panel scales from 0.96 to 1 + fades
ClosingReverse; --dur-fast
DestructivePrimary action uses btn-destructive

Keyboard

KeyBehavior
EscapeCloses dialog
TabCycles within dialog (focus trap)
Shift+TabCycles backward within dialog

ARIA

  • Panel: role="dialog", aria-modal="true", aria-labelledby points to title
  • Focus trap active while open; restored to trigger on close

Swatch

Confirm deletion
This action cannot be undone. The project and all its data will be permanently removed.

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

StateVisual
ClosedPanel offscreen (translateX ±100%)
OpeningSlides in over --dur-normal
OpenPanel on screen; focus moved to header

Keyboard

KeyBehavior
EscapeCloses drawer
TabCycles within drawer (focus trap when overlay)

ARIA

  • Panel: role="dialog", aria-modal="true" for overlay; role="complementary" for push
  • aria-labelledby points to drawer title

Swatch

Details
Drawer body content

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

StateVisual
Mobile (bottom)Slides up from bottom edge
Desktop (side)Slides in from right edge
Snap expandedHeight extends to next snap point on swipe/drag

Keyboard

KeyBehavior
EscapeCloses sheet
TabCycles through contents

ARIA

  • Role: dialog, aria-modal="true"
  • Handle: role="separator", aria-orientation="horizontal"

Swatch

Share
Sheet content area
Feedback4

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

StateVisual
EnteringSlides up from bottom + fade in
VisibleFully opaque; progress bar optionally shows time remaining
ExitingFades out + slides down

ARIA

  • Container: role="status" for info/success; role="alert" for warning/error
  • aria-live="polite" (info/success) or aria-live="assertive" (error)
  • Dismiss button: aria-label="Dismiss"

Swatch

Project published successfully.
Failed to save. Try again.

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

StateVisual
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: alert for error/warning; status for info/success
  • Dismiss button: aria-label="Dismiss"

Swatch

A new version is available. Update now
Trial expires in 3 days.
Payment failed. Update your billing info.
Data Display3

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

StateVisual
Row hoverBackground --raised
Row selectedBackground --accent-dim, left border --accent
LoadingSkeleton rows replace data rows
EmptyEmptyState component centered in table body
Sorted asc/descColumn header shows Lucide ChevronUp/Down

Keyboard

KeyBehavior
TabMoves focus through interactive cells
SpaceToggles row selection
EnterOpens row detail or activates primary action

ARIA

  • Role: table (or grid for interactive cells)
  • Sortable header: aria-sort="ascending|descending|none"
  • Selected row: aria-selected="true"

Swatch

Name Status Owner
Project AlphaActiveCharles B.
Design SystemDoneSarah A.
API MigrationIn ReviewCharles 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-subtle between rows

ARIA

  • Rendered as <dl> with <dt> (label) and <dd> (value) pairs

Swatch

Status
Active
Owner
Charles B.
Created
Sep 26, 2026

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, --overlay background
  • 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

No projects yet
Create your first project to start organizing work.

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

Saving…
Layout & Shell6

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 ChevronRight separators
  • 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

Work Projects

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

KeyBehavior
Arrow Left/RightMoves focus through toolbar items
Home / EndFirst / last toolbar item
TabExits 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

StateVisual
ExpandedFull width; icon + label visible
Collapsed (rail)48px; icons only; labels appear as tooltips
Active itemBackground --overlay, --text-primary
BadgeNumeric 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-dim background, --accent icon
  • Tooltip - label appears on right on hover/focus

Keyboard

KeyBehavior
Arrow Up/DownMoves focus through rail items
Enter / SpaceNavigates to item

ARIA

  • Nav: role="navigation", aria-label="Primary navigation"
  • Items: role="link" or button, aria-label with 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

StateVisual
DefaultDivider at configured default position
DraggingCursor changes to resize; divider highlights
SnappedOne pane at min-width; other fills space

Keyboard

KeyBehavior
Arrow Left/Right (on divider)Moves divider 10px per press
Home / EndSnaps to min or max

ARIA

  • Divider: role="separator", aria-valuenow (percent), aria-valuemin, aria-valuemax
  • aria-orientation="vertical|horizontal"

Swatch

List pane
Detail pane

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, --overlay background
  • 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

KeyBehavior
Cmd/Ctrl+KOpens palette
Arrow Up/DownMoves focus through results
EnterExecutes focused result
EscapeCloses palette
TabSame as Arrow Down

ARIA

  • Panel: role="dialog", aria-modal="true", aria-label="Command palette"
  • Input: role="combobox", aria-autocomplete="list"
  • Results: role="listbox", items role="option"
  • Active result: aria-selected="true"

Swatch

Pages
Dashboard
Clients
Actions
New project
Icons

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.

Library lucide-react ^1.23
Viewbox 0 0 24 24
Stroke width 1.5px
Color currentColor
Fill none
License ISC
Interface
Search
X
ChevronRight
ChevronLeft
ArrowLeft
ExternalLink
Moon
Sun
Link2
LayoutTemplate
Hash
Status & Feedback
Check
CheckCircle2
CheckSquare
AlertCircle
AlertTriangle
Bell
Sparkles
Content & Data
FileText
Files
FolderKanban
History
Code
Download
Film
Table2
System & Identity
Server
Shield
Bot
User
Users
KeyRound
GitBranch
Globe
Palette
Zap
Actions
Play
Copy
Save
Trash2
Clock
MessageSquare
Phone
Pin
ScreenShare
Video
Volume2
Voice

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
Patterns

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.

Behavioral
UX Patterns

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".

ConditionTreatment
Reversible (archive, remove, move, unassign)Execute immediately + undo toast (10 s)
Irreversible, or affects others, or affects >25 itemsConfirmation 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 waitTreatment
Under 300 msNothing
300 ms – 1 sInline spinner in the triggering control; control disabled
Over 1 s, content regionSkeleton matching the final layout (no layout shift)
Over 10 sProgress with plain description of current step + cancel
Background workActivity 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

KindContent
First useOne sentence on what this area is for, one primary action
No resultsState the filter or query, offer to clear it
Cleared (inbox zero, all done)Quiet confirmation, no celebration graphics
No permissionSay who can grant access
Error loadingPer 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

ChannelUse forBlocks workPersists
InlineField and element state, local errorsNoWhile relevant
ToastTransient success, undo, background completionNo5 s, 10 s with undo
BannerPage or system state (offline, degraded, trial, maintenance)NoUntil resolved or dismissed
DialogA decision the user must make nowYesUntil answered
Notification centerAsync events to review later (mentions, approvals, agent completions)NoUntil 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

KeyAction
Cmd/Ctrl KCommand palette (navigate, create, run plays, find anything)
/Focus search
?Shortcut sheet
EscClose topmost layer
g then letterGo to an area
j / kMove in lists
EnterOpen selected item
xSelect 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 typeRule
DatesRelative 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
NumbersThousands separators; tabular numerals in tables; compact form (1.2k) only in summaries and charts
CurrencySymbol and two decimals in detail, rounded in summaries; currency code shown when mixed
TruncationEnd 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
StatusOne status-to-color mapping used everywhere; always with a text label or icon (never color alone)
NamesDisplay 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).
Lookup
Decision Rules

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?

ConditionUse
Single value editInline edit
A few fields; context must stay visiblePopover
Task or object detail while keeping the list visibleDrawer or detail pane (pane at lg+)
A decision that must be made now, little contentDialog
Anything long, multi-step, shareable, or worth a URLFull page
Phone ranges (xs, sm) + the choice above is popover or dialogSheet

DR-02 — How is a collection displayed?

ConditionUse
Items compared across several attributes; sorting mattersTable (becomes DataList below 560px container width)
Items scanned by title with one or two attributesList
Items identified visually (images, previews, designs)Cards
Items moving through stagesBoard
Items defined by datesCalendar or timeline

DR-03 — Navigation within an area

ConditionUse
2–5 peer views of the same objectTabs
2–4 modes of the same view (list or board)Segmented control
More than 5 sections, or settingsSecondary sidebar (collapses to select below md)
Views that should be linkable independentlySub-routes

DR-04 — Choosing from options

Count / behaviorUse
2–4, all visible mattersRadio group or segmented control
5–15Select
Over 15, or searchable, or creatableCombobox
Multiple valuesCheckbox group (under 8) or multi-select combobox
Binary setting that applies immediatelySwitch
Binary choice submitted with a formCheckbox

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

QuestionUse
Change over timeLine (area only for cumulative totals)
Comparison across categoriesBar, horizontal when labels are long
Part of a whole, 2–5 partsStacked bar; donut only in small summaries
DistributionHistogram
RelationshipScatter
Single key figureStat 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.

Agent-first
AI-native Patterns

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.

StatusMeaning
idleAgent is available, no active work
queuedWork accepted, waiting to start
thinkingPlanning or reasoning, no output yet
workingExecuting; shows current step text
waiting on youNeeds human input or approval — highest priority
blockedCannot proceed; shows reason
doneCompleted successfully
failedEnded with an error; see AI-P11
stoppedHalted 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 / routineAuto-run
MediumRun and notify
HighApprove (one human)
Critical / irreversibleDual 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

DirectionFormat
Agent → personHandoff card: summary, what was done, open questions, links. Lands in the person's queue.
Person → agentAssign 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.

Canonical screens

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.

IDPage typeSurface sourceStatus
GS-01List + detailWork tasksIn Progress
GS-02DashboardHome or area overviewIn Progress
GS-03SettingsWorkspace settingsIn Progress
GS-04Document or editorStudio documentIn Progress
GS-05Table-heavyTime entries or AudienceIn Progress
GS-06Chat and agent conversationChatIn Progress
GS-07Approval queueAgent approvalsIn Progress
GS-08First use and empty statesAny new areaIn Progress
GS-09Mobile shell and navigationGlobalIn Progress
GS-10Widescreen three-paneWork at 3xl and 4xlIn Progress
GS-01 List + detail — Work tasks (list view) Target score ≥ 95 · responds to D / M / L theme toggle
Workspace
My Work
Projects
Audience
Studio
Plays
Chat
Time
Reports
Settings
Work/My Work
+ New item ⊕ Log time
My Work
M
T
W
T
F
S
S
≡ List ⊞ Card ⬜ Kanban ⊷ Gantt ◎ Sprint
Sort: Due date ↑ All open
Overdue · 2
DW-018Dwell Update hero section copy In Progress ●1.5h+ overdue
FK-033Fort Knox Review Q3 proposal draft Review — + overdue
Today · 3
ARC-045Internal Design system token audit — Wave V In Progress ●2.0h+ Oct 9
DW-019Dwell Homepage wireframes v3 Review — + Oct 9
FK-034Fort Knox Brand guidelines PDF export Todo — + Oct 9
This week · 2
ARC-046Internal GS-01 golden screen build In Progress ●0.5h+ Oct 12
BK-007Bindery Feature matrix competitive research Todo — + Oct 14
Done today · 1
ARC-044Internal Quality + Supplementary DS sections redesign Done ●1.0h Oct 9
Patterns and components active in this screen
L-01Sidebar + main-column shell with active nav dot indicator
UX-P02Grouped list: time-based buckets — Overdue, Today, This week, Done today
UX-P03Progressive disclosure: Done group rendered at 40% opacity
UX-P09Week shape mini bar chart in page header — logged hours at a glance
DR-08Status communicated via color + label text — never color alone
C:ViewToggleList / Card / Kanban / Gantt / Sprint tabs, active tab raised with border
C:StatusPillyellow=in progress, teal=review, green=done, todo=muted border
AP-11Overdue: red color AND the word "overdue" — passes no-color-only rule
GS-02 Dashboard — Home / area overview Target score ≥ 95 · responds to D / M / L theme toggle
Home
My Work
Clients
Audience
Studio
Plays
Settings
Good morning, Charles
⊕ Quick add
Today's focus · 3
IPUpdate hero copyDW
RVReview Q3 proposalFK
TDBrand PDF exportFK
Active clients · 3
DW
Dwell2 open
FK
Fort Knox1 review
BK
Binderyon track
This week
M
T
W
T
F
8.5h logged · target 40h
Quick add + Task ⏱ Time entry ✉ Message 📄 Document
Patterns and components active in this screen
L-01Sidebar + main shell; Home is active nav item
UX-P09Week shape bar chart in zone 3 shows logged hours at a glance
UX-D01Greeting personalization — time-of-day greeting with user's first name
C:ZoneCard3-col zone grid: Today's focus / Active clients / This week — equal-width, same height
C:QuickActionsContextual quick-add row pinned to content bottom — Task, Time, Message, Document
DR-08Client avatar uses color + 2-letter code — never color alone
GS-03 Settings — Workspace general settings Target score ≥ 95 · responds to D / M / L theme toggle
Home
My Work
Settings
Settings/General
Workspace
General
Members
Billing
Personal
Integrations
Notifications
Workspace name
Shown on invoices and in your team's URL.
Swift Innovation
Save
Workspace logo
Logo
Upload image
Default timezone
America/Chicago (UTC-5) ▾
Danger zone
Permanently delete this workspace and all its data.
Delete workspace
Patterns and components active in this screen
L-04Settings sub-nav: narrow secondary nav panel left of content, section labels as eyebrows
UX-P05Inline save on each form section — no global save button; Save appears only when field is dirty
AP-08Danger zone: destructive action has confirm gate (not shown) — hard fail without one
C:FormSectionEach setting group separated by bottom border; label + description + control stacked
DR-03Danger zone uses red-dim background + red border — visually distinct, not just red text
GS-04 Document / editor — Studio document Target score ≥ 95 · responds to D / M / L theme toggle
My Work
Studio
Plays
Studio/Documents/Q4 Strategy Brief
Share Publish
B I U
H1 H2
🔗 🖼 💬
Q4 2026 Strategy Brief
This document outlines the strategic priorities for Q4, covering product growth, client expansion, and team capacity planning. All decisions should be reviewed against the North Star metric: agent-assisted revenue per team hour.
Our current trajectory puts us on pace for the quarterly target, assuming the Surface platform stabilizes by the end of October and the Flagin integration ships on schedule.
Key assumption
ArcRouter v3 latency improvements land before Nov 1. If delayed, revise capacity targets in section 3.
Priorities
  • Surface AWARE.5d — dedup and reconnect stability
  • Flagin webhook delivery confirmation
  • ArcTime (TimeSubNav + sprints) shipped by Oct 20
Comments · 2
Sarah A.resolved
"Can we quantify the latency improvement target?"
Charles B.open
"Confirm Flagin deploy window with Sarah before locking this."
Reply
Patterns and components active in this screen
L-05Editor layout: toolbar + scrollable body + fixed-width comment gutter on the right
C:ToolbarInline formatting toolbar above document body; icon-or-label buttons grouped with dividers
C:CalloutAccent-left-border callout block for key assumptions and warnings
UX-P08Comment thread in right gutter: resolved threads dimmed to 50%, open thread has accent border
AP-10Comments are attributed to a person — agent output in this document would need agent badge
GS-05 Table-heavy — Time entries Target score ≥ 95 · responds to D / M / L theme toggle
My Work
Time
Reports
Time/Entries
⏱ Log time
Oct 1 – Oct 10 ▾ Dwell × Fort Knox All clients Total: 18.5h
Date Project Client Description Bill Hours
Oct 10WebsiteDwellHero section copy revisions1.5
Oct 10ProposalFort KnoxQ3 proposal final review0.5
Oct 9Design SystemInternalWave V token sweepup2.0
Oct 9WebsiteDwellHomepage wireframes v33.0
Oct 8BrandingFort KnoxBrand guidelines PDF export1.5
Oct 7BinderyInternalFeature matrix research2.0
Total (6 entries shown)10.5
Patterns and components active in this screen
C:DenseTableFull-width table: sticky header, monospace key/hour columns, alternating subtle row separators
C:FilterChipsActive filter shown with accent background + × to remove; inactive chips use border-default
UX-P04Sticky total row pinned to table bottom; accent color signals it is derived, not editable
DR-08Billable column uses filled/empty circle — green filled = billable; never text alone
C:DateRangeDate range picker triggers a popover; current range shown as a button, not an input field
GS-06 Chat — Channel conversation with agent reply Target score ≥ 95 · responds to D / M / L theme toggle
My Work
Chat
Channels
# general 3
# design
# dev
Direct
Sarah A.
Fitim L.
# general Team channel
🔍⊞ Threads
CB
Charles B.10:14 AM
Wave V is merged. @Sarah can you verify the Flagin hex replacements look right in FindingsBoard?
SA
Sarah A.10:19 AM
Checked — the blue is rendering correctly in dark and light. One note: the medium theme fallback in the confidence bar:
background: var(--color-blue, #58A6FF);
AI
ArcGridagent10:20 AM
The fallback value is correct — it matches the medium theme token definition. No change needed. The codemod preserved it intentionally as a CSS custom property fallback, not a raw hex usage.
Message #general 📎 @
Patterns and components active in this screen
L-06Three-column chat shell: global sidebar / channel list / message area + composer
AP-10Agent reply has distinct "agent" badge beside name — never indistinguishable from human message
C:MessageAvatar + name + timestamp + body; code block inside message uses overlay background + mono font
C:ComposerComposer stays pinned to bottom; placeholder text names the channel; attachment + mention icons right-aligned
UX-P01Channel list: unread badge uses accent fill + dark text for count; no badge when zero
GS-07 Approval queue — Agent action approvals Target score ≥ 95 · responds to D / M / L theme toggle
My Work
Plays
Plays/Approvals 4
All · 4 Pending · 3 Approved Rejected
AR
ArcRouter
Route request to Flagin webhook — 2 min ago
Pending
Send POST to /api/flagin/deploy with FLAGIN_DEPLOY_SECRET to flip resolved → verified.
Confidence94%
{"action":"POST","endpoint":"/api/flagin/deploy","secret":"[redacted]"}
✓ Approve ✕ Reject
AI
ArcFlow
Send Slack message to #dev — 5 min ago
Pending
72%
AR
ArcRouter
Update model alias in config.yaml — 1h ago
Approved
Patterns and components active in this screen
C:ApprovalCardAgent name + action + timestamp + confidence bar + Approve/Reject; expanded state shows detail JSON
C:ConfidenceBarProgress bar colored by confidence tier: green ≥90%, yellow 70–89%, red <70%
AP-10Agent action origin always shown — never anonymous; agent avatar uses "AI" or agent initials
UX-P03Approved cards dimmed to 60% — progressive disclosure; still visible but visually deprioritized
AP-08Destructive approve/reject: irreversible actions have distinct confirm-style button pair, not a toggle
GS-08 First use / empty states — New project Target score ≥ 95 · responds to D / M / L theme toggle
My Work
Studio
My Work/Q4 Campaigns
⊕ Create item
No items yet
Q4 Campaigns is empty. Create your first item or import from a template to get started.
⊕ Create item Import
📖
Getting started
🎯
Templates
💬
Ask an agent
Patterns and components active in this screen
UX-P06Empty state anatomy: illustration + headline + sub-text + primary CTA + secondary CTA + helper tiles
C:EmptyIllustrationSVG icon in accent-glow tile — not a full bleed image; scales to 80×80, never decorative only
C:PrimaryCTAPrimary action uses accent fill; secondary action uses overlay fill + border — never two filled buttons
C:HelperTiles3-col helper row below CTAs; icon + 2-word label; links to docs, templates, agent onboarding
AP-09No spinner on empty states — content is ready; spinner anti-pattern only applies to async load states
GS-09 Mobile shell and navigation — Phone viewport Target score ≥ 95 · responds to D / M / L theme toggle
My Work ☰
Overdue · 1
IPUpdate hero copyoverdue
Today · 2
IPToken audit Wave VOct 9
TDBrand PDF exportOct 9
This week · 1
TDFeature matrix researchOct 14
Work
Home
Chat
Clients
More
TopbarLogo + page title + hamburger; no breadcrumb on mobile
ListCondensed rows: status pill + title + due; key and client columns hidden
BottomNav5-tab bar: active tab uses accent dot + label; safe area padding below
NotchStatus bar with notch placeholder; no system UI rendered — device chrome only
Patterns and components active in this screen
L-07Mobile shell: topbar (no sidebar) + scrollable content + bottom tab bar; sidebar hidden on mobile
C:BottomTabBar5 tabs: Work / Home / Chat / Clients / More; active tab accent fill + label; inactive tabs text-tertiary
UX-M01Dense list on mobile: key and client columns collapsed; status pill shrinks to 2-char code label
UX-M02Safe area inset respected below bottom tab bar — 8px padding above home indicator zone
AP-04All actions reachable by tap — no hover-only actions on mobile; tap targets ≥ 44px
GS-10 Widescreen three-pane — Work at 3xl / 4xl Target score ≥ 95 · responds to D / M / L theme toggle
My Work
+ New
Overdue · 1
IPUpdate hero section copyoverdue
Today · 2
IPToken audit Wave VOct 9
RVHomepage wireframes v3Oct 9
This week · 2
IPGS-02–10 golden screensOct 12
TDFeature matrix researchOct 14
In ProgressToken audit Wave V
⏱ Log⋯
Project
Design System · Internal
Due
Oct 9, 2026
Run V1 existing-token sweepup and V2 new token introduction (blue/pink). Codemods at tools/sds-codemod/.
Sub-items · 2
✓V1 sweepup — 77 replacements
✓V2 new tokens — 32 replacements
Activity
Charles opened PR #3252 · 2h ago
Status changed to In Progress · 4h ago
Patterns and components active in this screen
L-08Three-pane widescreen: icon-only sidebar (48px) / list pane (340px) / detail pane (flex 1)
C:IconSidebarIcon-only mode at 3xl+: no labels; active area highlighted; tooltip on hover names the destination
UX-P11Selected list row highlighted with accent-glow background; detail pane shows that item's full record
C:DetailPaneMetadata grid (2-col) + description + sub-items + activity feed stacked in right pane; no modal
AP-06Detail pane opens inline, not as a dialog — no dialog-from-dialog risk; back navigation is native browser
Before / After

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.

Hard fails & common mistakes

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.

IDAnti-patternDetection
AP-01Emoji or hand-drawn icon in UI chromeSDS-L05, SDS-L07
AP-02Div or span used as a button hard failSDS-L08
AP-03Raw hex or off-scale valueSDS-L01 to SDS-L03
AP-04Action available only on hoverScorecard, coarse pointer check
AP-05Content stretched across a wide screenScorecard, line length and W-rules
AP-06Dialog opened from a dialog hard failSDS-L20
AP-07Dialog used for information with no decisionScorecard, UX-P07 check
AP-08Destructive action with neither confirm nor undo hard failSDS-L21
AP-09Spinner replacing a whole page for over 1 sScorecard, UX-P03 check
AP-10Agent output indistinguishable from human content hard failSDS-L23
AP-11Color as the only carrier of meaningScorecard, a11y check
AP-12Raw date or number formattingSDS-L22
AP-13Section label eyebrow above every headingScorecard, ATELIER judge
AP-14Layout shift when content loadsScorecard, 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.

DimensionWeightEvidence
Conformance25%Lint results, token use, contract tests
Accessibility20%Axe, keyboard walk, contrast per theme, target sizes
Responsiveness15%Visual regression across the viewport matrix
Pattern correctness15%Decision rules followed, UX and AI patterns applied, anti-patterns absent
Usability heuristics15%Agent heuristic review with screenshot evidence (10 Nielsen heuristics)
Taste10%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.

MetricWhat it tells us
Task success rateWhether people can do the job
Time to first meaningful actionClarity of the page
Error rate (validation and system)Friction and fragility
Rage clicks and dead clicksBroken affordances
Navigation backtracksConfusing structure
Flow abandonmentWhere people give up
Undo rateMistakes the UI invited
Approval latencyHow well approval gates surface
Suggestion override rateAgent suggestion quality and presentation
Flagin UI findings per pageReported pain

Improvement loop (P5)

Monthly review of open findings plus ad hoc response for severe regressions.

  1. Detect — a metric regresses, breaches a threshold, or Flagin findings cluster on a pattern.
  2. Diagnose — an agent analyzes affected pages and privacy-bounded traces and writes a finding.
  3. Propose — an amendment (schemas/amendment.schema.json) changing a token, component, pattern, or rule, with expected effect.
  4. Evaluate — scorecard on affected golden screens and pages; optional A/B on the Swift internal tenant for high-traffic patterns.
  5. Ratify — Charles approves or rejects.
  6. Roll out — the change ships through the system; every page using the pattern improves at once. Design System version bumps.
  7. 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

GroupTokensNotes
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.