Milagre design system

The rules behind every Milagre screen on the Mac, the iPhone and the iPad. Each value on this page is read from the apps' own code when the site builds.

DESIGN.md on GitHubDocs

Sections

The rules every Milagre screen follows: the desktop app (apps/desktop/app/src), the phone and iPad app (apps/mobile/src) and the looks they share (packages/shared). Read it before you change UI, and review UI against it.

  • Values not listed here are drift. Where code disagrees with a rule, the rule wins and the code moves toward it, one surface at a time.
  • The token tables are checked against the code by apps/site/src/design-system.test.ts. Change a token in the code and in its table in the same PR.
  • milagre.cloud/design publishes this file with live specimens drawn from the same tokens.
  • How-tos for scroll areas, menus, sliders and blur live in docs/agents/ui.md.

Principles

Milagre is a calm, dense workbench for people who run coding agents all day.

  1. Neutral structure, colour with meaning. Surfaces and text are neutral. Colour shows up only where it says something: one accent for focus and links, green, orange and red for state, purple for Ultracode and merged PRs, and identity colours for providers, file kinds and PR labels.
  2. Hierarchy from ink and weight first. Reach for an ink level or a weight before a bigger size. Two weights, one short size scale.
  3. Native on each platform. Desktop reads like a macOS tool, the phone like iOS. Features, behaviour and copy match; controls and layout follow each platform.
  4. Dense, never cramped. Fixed control heights, a 4px grid, one icon size per row.
  5. One way to do each thing. New UI uses the shared primitives. When one is missing, copy the closest existing one exactly instead of inventing values.

Colour

Every theme comes from one builder, packages/shared/src/themes/build.ts: a theme names a few official colours (page, surface, ink, accent, the status colours) and the builder derives every other token, solving the contrast floors below for that theme. Twelve themes ship (Milagre Blue, the default, plus Gray, three Catppuccins and seven popular editor themes), and a custom theme is built the same way. The tables list Milagre Blue.

Desktop reads each token as a CSS variable and a Tailwind colour (bg-surface, text-ink-2). The phone reads the same key in camelCase from theme.ts (colors.ink2, colors.greenInk).

  • Never put a Tailwind palette colour (purple-500, black/40) or a hex in a component. Never stack opacity on a text colour.
  • Accent is for focus rings, links and the unread dot. It never fills a button and never marks a selection.
  • Each status colour has three shades: the plain one for fills, dots, icons and borders, -ink for text, -tint behind it.
  • A number or word on a coloured fill uses the -ink fill and its on- label: bg-red-ink text-on-red.
  • on-ink (the surface) labels an ink fill. scrim sits behind a modal: black at 20% in light, 40% in dark. media, on-media, on-media-2 and on-media-tint are the lightbox and the camera, black and white in every theme. paper is a page that stays white (HTML artifacts, QR codes, design thumbnails).
  • Identity colours keep their meaning everywhere: each provider's logo colour, IMAGE_COLOR violet for an image (@milagre/shared/file-kinds), a PR label in its GitHub colour.

Surfaces

Ink

ink-2 is mix(ink, page, 0.25), a clear step above ink-3.

Accent

Status

Ultracode

Purple is ULTRACODE_PURPLE (@milagre/shared/themes), a brand colour themes don't override.

Diff

Settings › Appearance › Diff colors can swap the pair; the theme's own green and red stay for status and errors.

Contrast floors

The builder solves these for every theme, and packages/shared/src/themes/index.test.ts checks every theme in both schemes. A ground behind translucent fills (field, hover-2, a tint) is measured over both the page and the surface.

TextOnFloorLightDark
ink-2page4.5:1Aa7.56Aa8.50
ink-2surface4.5:1Aa8.00Aa7.50
ink-2field4.5:1Aa6.79Aa6.60
ink-2hover-24.5:1Aa6.20Aa5.88
ink-3page4.5:1Aa5.54Aa6.54
ink-3surface4.5:1Aa5.87Aa5.77
ink-3field4.5:1Aa4.98Aa5.08
ink-3hover-24.5:1Aa4.54Aa4.52
green-inkpage4.5:1Aa5.25Aa7.38
green-inksurface4.5:1Aa5.56Aa6.52
orange-inkpage4.5:1Aa5.16Aa7.70
orange-inksurface4.5:1Aa5.46Aa6.80
red-inkpage4.5:1Aa5.26Aa6.41
red-inksurface4.5:1Aa5.57Aa5.66
green-inkown tint4.8:1Aa4.84Aa5.09
orange-inkown tint4.8:1Aa4.80Aa5.42
red-inkown tint4.8:1Aa4.81Aa4.81
accent-inkaccent-tint4.5:1Aa4.70Aa6.09
on-greenown ink3:1Aa5.56Aa7.38
on-orangeown ink3:1Aa5.46Aa7.70
on-redown ink3:1Aa5.57Aa6.41

The status inks reach 4.8:1 on their tints because they letter 10px badges there (A, M and D in Changes). A focus style never drops under 3:1 against what it sits on.

Type

  • Two weights: 500 (medium) and 600 (semibold). 700 only for the phone's 34pt large title.
  • No half-pixel sizes. Letter-spacing 0 everywhere, the desktop body included, except -0.02em on 22px titles.
  • Desktop text uses the system UI font (SF Pro on macOS) unless Settings › Appearance picks another, and code uses ui-monospace (SF Mono). The phone uses the iOS system font and Menlo for code.

Desktop

  1. text-2626 / 32

    Allow the agent to run the mobile checks

    Display (Onboarding)

  2. text-2222 / 28

    Allow the agent to run the mobile checks

    Page title, -0.02em

  3. text-1717 / 24

    Allow the agent to run the mobile checks

    Dialog title

  4. text-1515 / 20

    Allow the agent to run the mobile checks

    Section and card title

  5. text-1313 / 18

    Allow the agent to run the mobile checks

    Body UI, rows, buttons

  6. text-1212 / 16

    Allow the agent to run the mobile checks

    Secondary text, small buttons

  7. text-1111 / 16

    Allow the agent to run the mobile checks

    Caption, metadata, time

  8. text-1010 / 14

    Allow the agent to run the mobile checks

    Badges only

Phone

  1. largeTitle34 / 41

    Allow the agent to run the mobile checks

    Large title, the one 700 weight

  2. title128 / 34

    Allow the agent to run the mobile checks

    Title 1

  3. title222 / 28

    Allow the agent to run the mobile checks

    Title 2

  4. title320 / 25

    Allow the agent to run the mobile checks

    Title 3 (a PR title)

  5. body17 / 22

    Allow the agent to run the mobile checks

    Body, headline, sheet title

  6. callout16 / 21

    Allow the agent to run the mobile checks

    A two-line row's title

  7. subheadline15 / 20

    Allow the agent to run the mobile checks

    Subheadline, Chat titles

  8. footnote13 / 18

    Allow the agent to run the mobile checks

    Footnote, secondary text

  9. caption112 / 16

    Allow the agent to run the mobile checks

    Caption 1

  10. caption211 / 13

    Allow the agent to run the mobile checks

    Caption 2

The phone sizes are the iOS Dynamic Type defaults (type and lineHeight in apps/mobile/src/design-tokens.ts).

  • Chat text is user-scaled: desktop --chat-size (14px at 1.6 by default), phone textPx (15 at 22). Markdown headings are em-relative to it.
  • Desktop body is 13px on a unitless 18 / 13 line, so unsized text follows the 13 step. New prose sets text-13 leading-5 (13/20).
  • A group heading above a card is SectionLabel: 12 medium ink-3 (11 in menus), phone 13 footnote ink3. 15 semibold is only for a title inside a card.
  • Button labels are 500 on desktop and 600 on the phone (each platform's own style, not drift).
  • Prompt chip labels are 0.875em on both platforms.

Spacing

  • A 4px grid. 2 and 6 only inside dense rows. Never 3, 5, 7 or 14.
  • 10 only as the horizontal inset of 28px controls and bordered fields: the 1px border plus 10 puts the text 11 in, lined up with an unbordered 32 button's 12.
  • Desktop uses Tailwind's spacing utilities on the same grid (gap-1 is 4, p-3 is 12).
  • Phone: a 16 gutter on every screen, header and body alike; 24 between sections; overlays under the Chat header sit at chrome.header (52) plus 8.

Radius

The desktop new-Chat tray is 20: the composer's 14 plus its 6 padding.

  • Every phone radius sets borderCurve: "continuous".
  • Nested corners: the inner radius is the outer radius minus the padding between them.
  • Project tiles are rounded squares on both platforms, projectAvatarRadius(size): 16 → 4, 20 and 24 → 6, 32 and 40 → 10, 72 → 20. Without an image, a tile is an ink fill with its on-ink initial at 600 (@milagre/shared/project-list).

Sizes

  • Desktop controls: 24 for icon and extra-small buttons, 28 small (composer chips, tabs, approval buttons), 32 default (buttons, selects, rows), 36 inputs. Two-line list rows are 48. Heights are fixed, never derived from padding.
  • The desktop hit area floor is 24px. Extend a smaller visual with before:absolute before:-inset-*, never over a neighbour's target.
  • Phone: a 44pt minimum target (hitSlop={hitSlopFor(size)} when the visual is smaller); rows are 52 for one line and 56 for two; PillButton is 32, 44 or 52, set with minHeight so Dynamic Type can grow it.
  • A numbered pin over content is 20px with shadow-pin and its number at 10 semibold.

Elevation

  • An elevated surface takes a shadow token and no border: each token paints its own 1px ring. Borders are for inputs, flat panels and bordered cards (the approval row, the question card).
  • Dark mode has its own, deeper shadows in styles.css, never the light ones on a dark page.
  • Phone elevation comes from shadowCard, shadowRaised and shadowOverlay in theme.ts, each with a hairline ring and a dark variant; never hard-coded black. Phone grouped cards are flat panels with a hairline.

Light

  • hairline
  • btn
  • card
  • raised
  • overlay
  • pin

Dark

  • hairline
  • btn
  • card
  • raised
  • overlay
  • pin

Blur

Light

  • overlay3px
  • chip8px
  • edge4px

Dark

  • overlay3px
  • chip8px
  • edge4px

Never use Tailwind's own blur sizes or a hand-written backdrop-filter. The phone's EdgeFade uses a native variable blur. In styles.css, write backdrop-filter alone, never -webkit-backdrop-filter: the minifier keeps whichever comes last and Chromium ignores the prefixed one.

Motion

  • fast120ms
  • base180ms
  • slow280ms
  • Hover or tap a row to play it on the enter curve.
  • enter(0.23, 1, 0.32, 1)
  • slide(0.32, 0.72, 0, 1)
  • Presspressscale 0.97, phone 0.97
  • A bare transition runs at duration-fast on ease-enter. Every hover has transition-colors.
  • JS motion uses EASE_OUT and DURATION (lib/ease.ts) on desktop and scaledTiming / springTo (motion.ts) on the phone, so Settings › Appearance › Animations scales it.
  • Reduced motion keeps a loading cue (a stepped opacity fade), never a frozen spinner. Springs and slides stop.
  • Motion explains a change of state. The only loops are running marks: the running Milagre logo, a spinner ring, Ultracode's breathing composer.

Icons

Hugeicons everywhere (@hugeicons/core-free-icons), drawn in the text colour.

  • Phone sizes are 12, 16, 18, 20 and 24.
  • One icon size per row.
  • Control glyphs at rest are ink-3 on desktop and ink2 on the phone. ink-4 only for decorative icons, dots and disabled controls.
  • Shared looks live in packages/shared and each app maps the palette keys and icon names to its own: chatMarkPresentation (chats), PR_TONE and pullRequestStatePill (pr-blockers), permissionPresentation (model-copy; Full is the only orange mode), presenceTone (chat-scopes: green, orange, red, ink-4 offline), projectAvatarRadius and PROJECT_AVATAR (project-list), IMAGE_COLOR (file-kinds).

States

  • No switches. Use a checkbox for an independent on/off setting and a checked list or radio group for one choice out of several. No sliding track and thumb, no native Switch, no switch role, on either platform. Native menu items that draw a checkmark are fine.
  • Focus is one accent ring from @layer base in styles.css. A component may restyle it with focus-visible: utilities but never recolour it. Text fields, the composer and comment boxes show no focus mark: the caret is enough. Menu and picker rows inside a clipped panel keep their fill and add the ring inset (focus-visible:-outline-offset-2), never a fill alone.
  • Press: active:scale-press (0.97) on filled buttons (primary, danger), pills and icon buttons; active:bg-hover-2 on rows. Phone: opacity 0.6, plus scale 0.97 on filled buttons.
  • Disabled: 40% on controls, 60% on list rows (an offline Project too).
  • Hover is bg-hover everywhere, the sidebar included. bg-hover-2 is the open or selected row, a pressed toggle and the menu highlight, so a hovered row never looks like the open one.
  • Menus and pickers have one moving highlight, bg-hover-2, for pointer and keyboard, plus the inset ring on keyboard focus. A checked row shows only a 14px tick, no fill.
  • Selection is ink on both platforms: a tick, a fill or a dot. Accent never marks a selection.
  • Toggles: a pressed or open toggle is bg-hover-2 with an ink glyph (phone: hover2 fill, ink icon). accent-tint with accent-ink only for an armed mode that changes what a click does (comment mode).
  • Chat status marks: orange means the Chat needs you (an approval's shield, a question's bubble, the top bar's waiting dot); work in progress is quiet ink-3 (the running spinner, the background ring); failed is red. Unread is the one accent status mark, an 8px accent dot, kept on purpose from macOS Mail and Slack. Nothing else uses accent as a status.
  • Scrollbars are overlays: the thumb is transparent at rest and shows while its scroller is hovered or scrolling (data-scrolling, 800ms after the last scroll event), as on macOS.
  • Empty, loading and error states go through EmptyState, SpinnerRing and InlineError (phone ErrorNotice), with "…" (U+2026).

Components

Buttons

Light

Allow onceAlways allowCancelDetails
Fix in ChatDenyDelete Worktree
322824Focused

Dark

Allow onceAlways allowCancelDetails
Fix in ChatDenyDelete Worktree
322824Focused
  • One primary style per platform: an ink fill with an on-ink label. Desktop Button (rounded-control, hover opacity 0.9), phone PillButton. Neither green nor accent ever fills a primary button.
  • Desktop sizes: 32 by default, 28 in compact rows and composer chips, 24 inline.
  • Variants: primary; secondary (surface with shadow-btn); ghost; quiet (ink-2, ink on hover); link (accent-ink, an inline action); danger (a red-ink fill with an on-red label, the confirm of a destructive action); danger-ghost (red-ink text with a red-tint hover, the first step: Remove, Delete, Deny, Revoke, Stop). Phone PillButton has the same primary and destructive pair (redInk, onRedInk).
  • IconButton is 20, 24, 28 or 32; a 20 reaches the 24px hit area through ::before. Its label is its name.

Chips and badges

Light

Worktree Opus 5.5 Every day
AllRunningPaused
bugenhancementdocumentationgood first issuedesign
MergedClosedDraftRecommended

Dark

Worktree Opus 5.5 Every day
AllRunningPaused
bugenhancementdocumentationgood first issuedesign
MergedClosedDraftRecommended
  • Chips are 28 high, fully round, 12 medium (Chip). A composer trigger chip (Run on, Isolation, model, permission) is transparent ink-2, hover on hover and hover-2 while open; a field chip sits on field; a filter chip is a surface with shadow-btn, and checked, an ink fill with an on-ink semibold label.
  • A PR label is a chip in its GitHub colour (.pr-label): the label's hue at a fixed lightness per theme, so its text clears 4.5:1 on the chip.
  • A PR state pill is a tint with its label in the -ink shade (pullRequestStatePill): Merged purple, Closed red, Draft neutral (hover fill, ink-2 label). An open PR shows no state pill.
  • Badges such as Recommended are neutral: a field fill with an ink-2 label. 10px text is for badges only.

Rows and lists

Light

Design system pagenow
Fix the login redirect4m
Run the mobile checks12m
Refactor the PR panel1h
Offline Project2d

Open, hovered with unread, needs you, running, disabled

Dark

Design system pagenow
Fix the login redirect4m
Run the mobile checks12m
Refactor the PR panel1h
Offline Project2d

Open, hovered with unread, needs you, running, disabled

  • Desktop rows are 32 high, two-line rows 48. Hover bg-hover, open or selected bg-hover-2, disabled 60%.
  • Unread is an 8px accent dot. Running is a quiet ink-3 ring; needs you is orange.
  • The sidebar's One list Chat row has two styles, picked in Settings › General › Chat list (One list or Title first). Classic (the default) is 50 high: the Project's icon, the title at 13 with its time, one dotted line under it. Title first is 54 high, 2 apart ("Alt A", design gpui-sidebar-v-a): the title first at 14 medium (ink, ink-2 once read with nothing going on) with the Chat's state on its right edge (the spinner, the question or approval icon, a red alert, else the time: ink-3, ink medium while unread, then the unread dot). Line two at 12 ink-3: the Project's 14px tile and name, the computer (ink-2 on the hovered or open row), and the PR on the right edge in its state's -ink colour, "+n" for several, its tooltip the state glyph, #number in mono and the title. The hover Done takes the state's place in ink-2, ink under the pointer. A folded family's parent row draws as open while one of its Subchats is.

Approvals

Light

Waiting for approval

Run the desktop smoke check

npm test -- --only test-desktop

DenyAlways allowAllow once

Dark

Waiting for approval

Run the desktop smoke check

npm test -- --only test-desktop

DenyAlways allowAllow once
  • Desktop approvals sit inline on their tool row (agents/step-approval.tsx): "Waiting for approval" in orange-ink beside an orange dot, then Deny (danger-ghost), Always allow (secondary) and Allow once (primary), all 28 high, with what the tool would run beneath.
  • The phone keeps the approval card for its 44pt buttons.

Question card

Light

Waiting for answer

Where should the page live?

/designShort to share, a Design link in the nav
/docs/designUnder Docs, beside the CLI reference
Other…
DismissSend answer

Dark

Waiting for answer

Where should the page live?

/designShort to share, a Design link in the nav
/docs/designUnder Docs, beside the CLI reference
Other…
DismissSend answer
  • A bordered card (line-strong, rounded-card, surface): "Waiting for answer", the question at 15 semibold, then each option as a bordered row (rounded-control) with a radio or checkbox, its label at 13 medium and its description at 12 ink-2. A picked row turns inset with a line-strong border.
  • "Other…" is the last option row: a text field with the mic and image buttons inside it.
  • Its footer is Dismiss (ghost) and Send answer (primary), both 28 high, bottom right.

Toasts and notices

Light

Chat archived UndoCopied the branch name

Dark

Chat archived UndoCopied the branch name
  • A toast is an ink capsule on both platforms: bg-ink, on-ink text at 13/18, rounded-card, shadow-raised, an optional on-ink Undo.
  • A message that stays is a Notice card.

Model picker

Light

Effort High

FastQuicker replies, higher usage
FastQuicker replies, higher usage
UltracodeParallel agents for big work

Dark

Effort High

FastQuicker replies, higher usage
FastQuicker replies, higher usage
UltracodeParallel agents for big work
  • Fast and Ultracode are bordered tiles with a checkbox role. At rest: a line border, an ink-2 icon, an ink title. On: the tile takes its tint (orange-tint for Fast, purple-tint for Ultracode), the icon its fill colour and the title its -ink shade.
  • The effort slider (RangeSlider) is a 32 high field track that fills with ink at 15% up to its value, a tick dot per step and an ink bar handle.
  • The picked provider in the rail is a hover-2 tile with an ink mark; the others rest in ink-3.

Activity and running

Light

Read 6 files, searched 2 times, edited 3 files, ran 2 commands
0:42
Needs you: an orange mark, never accent

Dark

Read 6 files, searched 2 times, edited 3 files, ran 2 commands
0:42
Needs you: an orange mark, never accent
  • A folded reply's activity summary shows at most four stacked circular marks, one per kind of work: 20px field circles overlapping by 6px, each ringed in the page colour, with a 12px ink-2 glyph. Its timer and chevron follow the summary content and call count without a spacer, with the timer first.
  • A running turn shows the animated Milagre logo beside the turn timer (12px ink-3, tabular figures). The current tool's purpose or thinking summary heading sits between the logo and timer on desktop and phone. This label uses plain language; shell commands stay in tool rows, with "Running a command" as the footer fallback.

Dialogs and Settings

  • A dialog is a native <dialog> opened with showModal: rounded-window, shadow-overlay, a scrim backdrop with backdrop-blur-overlay, a 17 semibold title, actions bottom right.
  • Settings is an in-window dialog, not a second window: Milagre is a one-window app, so Settings opens over the Chat it was opened from (rounded-window, scrim behind, ⌘, and Esc), keeps its own search and nav, and closes back to where you were. Its group labels keep their position, and the selected radio card keeps its 2px ink frame. The phone shows Settings as its own stack of screens.

Composer

  • The composer is a floating control: the surface at 76% with backdrop-blur-chip and a low shadow, never a raised card. In an open Chat it and the chip row float over the transcript, which scrolls on under their glass; the transcript's bottom pad is their height, and with one Chat alone (no Terminal drawer) the transcript runs to the window's bottom edge, under the composer, fading out over its last 24px there.
  • With Ultracode on, its border and glow take purple and breathe slowly.
  • The phone and iPad composer is the same glass (a native blur under the surface at 76%, 50% over Android's denser blur; Android below 12 draws the surface at 95% without a blur) and the same rows: the prompt on top, a paperclip bottom left, then model · effort, the context ring, the mic and Send or Stop bottom right. The mic sits beside Send, never inside the field, and the composer has no permission chip: the model sheet's footer shows the mode, Full in orange, as desktop's picker does. A new Chat's composer stays solid inside its tray.

Copy

  • Sentence case everywhere. No tracked uppercase labels.
  • Product nouns stay capitalised: Project, Chat, Routine, Run, Link, Heartbeat, Worktree, and Done, the named Chat state ("Rename Chat", "New Worktree", "Archive Done Chats after").
  • Shared words live in UI_COPY (@milagre/shared/model-copy), so desktop and phone say the same thing.
  • An ellipsis is "…" (U+2026): loading text, and a label that opens more input ("Other…", "Compare with…").

Platforms

Desktop

  • One window. Settings, dialogs and the command palette open over it.
  • Every enabled button, role="button", link and input label shows the pointer cursor. That is a deliberate departure from macOS; keep it.
  • Chrome doesn't select: button, [role=button|menuitem|tab|option], label, nav and header are user-select: none. The transcript, markdown, code, diffs, errors and paths stay selectable.
  • Window drag strips use .title-drag; a control inside one takes .no-drag, not an inline app-region.
  • The window background is faint diagonal stripes (--stripe over --stripe-bg). Bordered transcript blocks sit on the column edges, and tool glyphs start on the reply text's edge (their hover fill reaches 13px past it). The transcript has no fade above the composer: text runs crisp to it, under the glass pills.

Phone and iPad

  • 44pt targets, Dynamic Type (minHeight, never a fixed height on text controls), continuous corners.
  • Dialogs are sheets; Settings is a stack of screens.
  • iPad side panels use radius.sheet (20).
  • The phone's own chapter, with every palette key, every primitive and where iOS and Android differ, is apps/mobile/DESIGN.md; Settings › Design system on the phone shows it live.

Desktop and phone stay in sync

Every change lands on both platforms in the same task, unless the owner says to keep it on one (AGENTS.md). Keep features, behaviour, copy, states and fixes the same; use each platform's native controls and layout. Shared logic, looks and copy live in packages/shared.

Do and don't

Decided calls

The owner's decisions. Don't re-propose a rejected option; changing any of these needs Victor's say-so.

Kept after the desktop council (2026-11-09)

  • The Unified / Split diff toggle stays two icon buttons, not a labelled segmented control.
  • PR labels stay GitHub-coloured chips, not neutral chips with a dot.
  • Fast and Ultracode stay bordered tiles, not checkbox rows.
  • The effort slider keeps its fill.
  • Settings group labels keep their position (no 16px inset); the selected Settings radio card keeps its 2px ink frame.
  • The activity summary keeps its stacked circular tool marks.
  • The running turn keeps the animated Milagre logo beside the timer.
  • Files / Commits and PR Summary / Files are segmented controls.
  • The question card's "Other…" is the last option row, with the mic and image buttons inside it.
  • Unread stays a blue accent dot, the one accent status. Settings stays an in-window dialog. Done is a product noun.

GPUI port to Electron (2026-11-13)

  • The sidebar's One list row can follow design Alt A, "status on the edge, title first" (see Rows and lists): the Title first card in Settings › General › Chat list; One list (Classic) stays the default. The phone keeps its own list rows (kept 2026-11-10); only the unread time drops the accent there.
  • The composer's model chip shows no permission shield; Full stays orange in the picker's footer.
  • A Subchat's breadcrumb parent is plain text flush with the Chat title: no box, arrow or dot.
  • ⇧⌘D shows or hides the Changes panel on the view it was left on.
  • Film grain (Settings › Appearance › Film grain, on by default): faint static specks over the window background, the Chat's top band and the side panels (sidebar, Changes) at half strength; never on the composer or the Details glass.
  • The sidebar has no dividers above Done, the usage block or its footer.
  • The window's right corner runs Details, Terminals, PR, Changes, then the other panels (Artifacts, Designs, Browser, Simulators) and Canvas last.
  • The top-left bar is the sidebar toggle, Routines and Search. Canvas is the last button of the window's right corner; Link Projects is the third choice of the Add Project dialog (Open a folder, Clone a repository, Link Projects), whose computer is a menu. No grid or Subchats side-by-side buttons: a grid comes from dragging a Chat onto the open one.
  • The model picker has no provider and model-count header above its account and search.
  • No Subchats pill above the composer on desktop: the Details panel's Lineage lists them. The phone keeps its pill (it has no Details panel). No "N waiting" chip in the top bar, nor the phone's Attention pill.
  • The Details overlay (from GPUI's Details tab) floats over the Chat under the corner's buttons, never pushing it aside; a panel docked at the right (Changes, Browser, a design, a simulator) pushes Details to the Chat's right edge, 12 from it: the composer's glass (surface at 76%, backdrop-blur-chip), a 1px ring and a faint shadow, fading in moving down. It is the first corner button (a card with right-aligned lines, AlignBoxMiddleRight) and has no shortcut: Environment, Lineage (the parent with ArrowUpLeft01, Subchats with Redo03, Done in ink-3, not green; under the pointer a muted → takes the place of the state; a right-click opens the Chat's sidebar menu without Report a bug, unread, Finder, the editor, Commit and Pin, Rename editing the title in place), Background tasks and Links. Rows are 32 high, inset 8 from the card's edges so the hover fill is a rounded block; Lineage, Background tasks and Links fold. Artifacts, Designs, Browser and Simulator keep their shortcuts.

Routines page (2026-11-10)

  • The header is the title and New Routine only, on both platforms; the lid note shows in the empty state.
  • Filters are two chip dropdowns, Show and Computer, with counts in their menus; no chip rows.
  • Rows have no on/off tick: Pause and Resume are the first action in the ⋯ menu (phone: the long press), and each Routine's own page keeps its checkbox. A row's glyph is bare (no tile), rows are 56 high, and the status sits in a 72px column ("Next 16:00" today, "Fri 16:00", "Nov 18 10:00", "Paused").
  • Group labels have no glyph and sit on the column edge. The Flow badge is a neutral badge. Schedules read in words ("Fridays 16:00", "every 30 min from :15"); only other shapes show their cron.

Phone pass verdict (2026-11-10)

  • Kept: the phone Chat list rows (56pt, a trailing status slot, no state words, no Project tile in a one-Project list, last activity on line two) and the phone model sheet (bordered tiles in both themes, one surface, a compact glass Cancel and Done, no repeated logos).
  • Rejected: an "N waiting" chip; a waiting line in place of the timer; SF Mono and light chips; a send arrow with a stop square; the card restyle; the Settings close and search changes; the New Chat layout; a "Compare with…" collapsed chip; the diff layout; darker diff -ink colours; an orange question tone; "1 other waiting"; a stronger effort fill; dropping Project tiles on desktop.

Review rounds (2026-10-28 and 2026-10-29)

  • Hover and hover-2 are translucent ink; the sidebar hovers like everything else (hover-sidebar is a deprecated alias).
  • Selection is ink; accent is for focus and links. A pressed or open toggle is hover-2 with an ink glyph.
  • The menu highlight is hover-2 plus the inset ring on keyboard focus; a checked row shows a 14px tick.
  • Group headings are SectionLabel; 15 semibold only inside cards. ink-2 is mix(ink, page, 0.25).
  • Desktop body text is 13/18; chat text 14 at 1.6; the 10 inset only on 28px controls and bordered fields.
  • Press scale only on filled buttons, pills and icon buttons. Toasts are an ink capsule on both platforms.
  • The desktop new-Chat tray is 20; the phone composer 24, its tray composer + 4; iPad side panels 20.
  • A pasted image uses the image file-kind colour on both. The floating inbox follows the theme.
  • Product nouns are capitalised, everything else sentence case. The Recommended badge is neutral.
  • Button labels are 500 on desktop, 600 on the phone. Control glyphs at rest are ink-3 (phone ink2).
  • Chrome labels don't select. Desktop approvals are inline on their tool row; the phone keeps the card.
  • Text fields, the composer and comment boxes show no focus mark (2026-11-02).

Decided, not built yet

Each lands in its own PR, desktop and phone together:

  • The two-row composer: the prompt on top, attach bottom left, model · effort · send bottom right, no collapsed state. It needs its own design pass first.
  • The phone Chat list rows and model sheet kept on 2026-11-10.
  • The running Milagre logo on main: the restore (commit 9099b01b) missed the #985 merge.

Primitives

New UI uses these; hand-written copies move onto them.

Desktop (apps/desktop/app/src/components/primitives/): Button and buttonClass(), IconButton, Dialog, Popover with MenuRow, Input / FIELD / FIELD_AREA (36px, no focus edge), Checkbox, RadioGroup, Segmented, Tabs, Select, PickerPanel / PickerRow, RangeSlider, Chip, StatusPill, Icon, ProjectAvatar, SectionLabel, TranscriptDivider, EmptyState, InlineError, SpinnerRing, Skeleton, ProgressBar, ScrollArea, Tooltip, ShortcutKeys, and Notice (components/Notice.tsx) for a dismissable card over a view.

Phone (apps/mobile/src/primitives/): PillButton (Button); IconButton, CircleButton, GlassIconButton and HeaderButton (IconButton); Field (Input); Checkbox, CheckRow and ChoiceRow (PickerRow, RadioGroup); Chip, Tag and Segmented; ListRow and Group (settings rows and cards); SectionLabel; TranscriptDivider; ErrorNotice and InlineError; Sheet (Dialog); PullDown and NativeMenuSection (menus); Toast; ProgressBar; PageScroll (ScrollArea); pressStyle; announce.

Enforcement

  • apps/site/src/design-system.test.ts: every token table in this file matches the code (the theme builder, styles.css, Icon.tsx and the phone's design-tokens.ts), and styles.css's fallback colours match the default theme.
  • design-tokens.test.ts on desktop and phone: counts off-scale literals per file against design-tokens.baseline.json (desktop: font sizes and radii; phone: icon sizes, durations, computed and SwiftUI fonts, tracking). A file's count may only go down; after moving a file onto the scale, lower it with UPDATE_DESIGN_TOKENS=1 (the command is in each test's header).
  • The phone's milagre-design Oxlint plugin (apps/mobile/lint/design-system.mjs), in npm run lint and the pre-commit hook: no type, radius, spacing, colour, shadow, opacity or weight literals off the system, no blur outside its primitives, no unknown accessibilityRole, no "Mac" in copy, no SF Symbol toolbar button outside an iOS branch. Zero violations, no baseline; an exception is one oxlint-disable-next-line milagre-design/<rule> -- <why>.
  • packages/shared/src/themes/index.test.ts: the contrast floors, every theme, both schemes.
  • scripts/no-switch-controls.test.cjs: no switch controls or roles.
  • scroll-area-only.test.ts, no-native-select.test.ts and backdrop-blur.test.ts: the scroll, select and blur rules in docs/agents/ui.md.

The site

milagre.cloud (apps/site) lives in the day the desktop app's first-launch intro, Dawn, ends on: a cream page, warm ink and a gold-brown accent, with Geist for text and Instrument Serif italic for the headline's accent words. Live copies of the app on it (the Designs panel, the canvas, a terminal, the recordings) keep dark Milagre Blue. It follows the colour roles, radii and motion above, except where it borrows from Dawn: the download button is a dark pill in warm light, like the intro's Begin, and the hero plays the intro.

  • The landing hero is Dawn's sky. Every load plays the intro (night, the falling star landing on the logo, dawn into day); reduced motion opens on its last frame. The headline, the apps and the download button are there from the first frame.
  • Below the hero, the star winds down the page with the scroll, behind the app windows, with warm light round it and a trail of star dust, and lands on the footer's logo as its legs rise (a scroll timeline, off with reduced motion).
  • Clouds and light stay in the hero. Sections below it sit on the plain page.
  • Its Lighthouse scores never drop below apps/site/lighthouse-budget.json.