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.
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.
- 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.
- Hierarchy from ink and weight first. Reach for an ink level or a weight before a bigger size. Two weights, one short size scale.
- 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.
- Dense, never cramped. Fixed control heights, a 4px grid, one icon size per row.
- 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,
-inkfor text,-tintbehind it. - A number or word on a coloured fill uses the
-inkfill and itson-label:bg-red-ink text-on-red. on-ink(the surface) labels an ink fill.scrimsits behind a modal: black at 20% in light, 40% in dark.media,on-media,on-media-2andon-media-tintare the lightbox and the camera, black and white in every theme.paperis a page that stays white (HTML artifacts, QR codes, design thumbnails).- Identity colours keep their meaning everywhere: each provider's logo colour,
IMAGE_COLORviolet for an image (@milagre/shared/file-kinds), a PR label in its GitHub colour.
Surfaces
- lightdark
pageThe window, the transcript, the sidebar
#f4f9fe#0d1624
- lightdark
canvasThe canvas and recessed areas
#e9f1fa#111b29
- lightdark
surfaceCards, popovers, dialogs, the composer
#ffffff#172232
- lightdark
insetA well inside a card, a picked option row
#f9fcff#121c2b
- lightdark
fieldInputs, chips, neutral badges
#e8edf2#212c3c
- lightdark
hoverPointer hover on anything: translucent ink
#1c222b0f#e9eff70d
- lightdark
hover-2The open or selected row, a pressed toggle, the menu highlight
#1c222b1a#e9eff717
- lightdark
lineHairlines and the rings inside shadow tokens
#edeeee#273242
- lightdark
line-strongInput borders, bordered cards, button rings
#e0e1e3#303b4a
Ink
- AalightAadark
inkPrimary text, the primary button's fill
#1c222b#e9eff7
- AalightAadark
ink-2Secondary text: values, descriptions, chip labels
#4b515a#abb2bd
- AalightAadark
ink-3Tertiary text: section labels, metadata, placeholders; desktop control glyphs at rest
#60656d#939ca9
- lightdark
ink-4Decorative icons, dots, disabled controls. Never text
#8c929a#646c79
ink-2 is mix(ink, page, 0.25), a clear step above ink-3.
Accent
- lightdark
accentThe focus ring, the unread dot
#007df3#3e9afd
- AalightAadark
accent-inkLinks and inline actions that read as links
#0068cd#80b9fd
- lightdark
accent-tintBehind accent-ink, for an armed mode such as comment mode
#e3f0fe#3e9afd29
- AalightAadark
on-accentA label on an accent fill
#ffffff#0d1624
Status
- lightdark
greenAn open PR, online, enabled: fills, dots, icons
#199a4d#3cbb72
- AalightAadark
green-inkGreen as text
#00792e#3cbb72
- lightdark
green-tintBehind green text
#e5f2ef#3cbb7224
- AalightAadark
on-greenA label on a green-ink fill
#ffffff#0d1624
- lightdark
orangeNeeds you: an approval, a question; Full mode, Fast mode
#ef720d#f68f3c
- AalightAadark
orange-inkOrange as text
#ba4100#f68f3c
- lightdark
orange-tintBehind orange text
#f5efee#f68f3c24
- AalightAadark
on-orangeA label on an orange-ink fill
#ffffff#0d1624
- lightdark
redFailed, destructive, recording
#e3474c#ee5c61
- AalightAadark
red-inkRed as text; the danger button's fill
#c62935#fd696d
- lightdark
red-tintBehind red text; a danger-ghost button's hover
#f5ecef#ee5c6124
- AalightAadark
on-redA label on a red-ink fill
#ffffff#0d1624
Ultracode
- lightdark
purpleUltracode and merged PRs: fills, icons, the composer glow
#ad46ff#ad46ff
- AalightAadark
purple-inkPurple as text
#8e2bdc#d0a3ff
- lightdark
purple-tintBehind purple text, the Ultracode tile when on
#f6edff#ad46ff2e
Purple is ULTRACODE_PURPLE (@milagre/shared/themes), a brand colour themes don't override.
Diff
- lightdark
diff-addAn added line's row
#ddeee8#3cbb721f
- lightdark
diff-add-wordAn added word
#bbddc8#3cbb724d
- lightdark
diff-removeA removed line's row
#f6e9ec#ee5c611f
- lightdark
diff-remove-wordA removed word
#f7cecf#ee5c614d
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.
| Text | On | Floor | Light | Dark |
|---|---|---|---|---|
ink-2 | page | 4.5:1 | Aa7.56 | Aa8.50 |
ink-2 | surface | 4.5:1 | Aa8.00 | Aa7.50 |
ink-2 | field | 4.5:1 | Aa6.79 | Aa6.60 |
ink-2 | hover-2 | 4.5:1 | Aa6.20 | Aa5.88 |
ink-3 | page | 4.5:1 | Aa5.54 | Aa6.54 |
ink-3 | surface | 4.5:1 | Aa5.87 | Aa5.77 |
ink-3 | field | 4.5:1 | Aa4.98 | Aa5.08 |
ink-3 | hover-2 | 4.5:1 | Aa4.54 | Aa4.52 |
green-ink | page | 4.5:1 | Aa5.25 | Aa7.38 |
green-ink | surface | 4.5:1 | Aa5.56 | Aa6.52 |
orange-ink | page | 4.5:1 | Aa5.16 | Aa7.70 |
orange-ink | surface | 4.5:1 | Aa5.46 | Aa6.80 |
red-ink | page | 4.5:1 | Aa5.26 | Aa6.41 |
red-ink | surface | 4.5:1 | Aa5.57 | Aa5.66 |
green-ink | own tint | 4.8:1 | Aa4.84 | Aa5.09 |
orange-ink | own tint | 4.8:1 | Aa4.80 | Aa5.42 |
red-ink | own tint | 4.8:1 | Aa4.81 | Aa4.81 |
accent-ink | accent-tint | 4.5:1 | Aa4.70 | Aa6.09 |
on-green | own ink | 3:1 | Aa5.56 | Aa7.38 |
on-orange | own ink | 3:1 | Aa5.46 | Aa7.70 |
on-red | own ink | 3:1 | Aa5.57 | Aa6.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
bodyincluded, except-0.02emon 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
Allow the agent to run the mobile checks
Display (Onboarding)
Allow the agent to run the mobile checks
Page title, -0.02em
Allow the agent to run the mobile checks
Dialog title
Allow the agent to run the mobile checks
Section and card title
Allow the agent to run the mobile checks
Body UI, rows, buttons
Allow the agent to run the mobile checks
Secondary text, small buttons
Allow the agent to run the mobile checks
Caption, metadata, time
Allow the agent to run the mobile checks
Badges only
Phone
Allow the agent to run the mobile checks
Large title, the one 700 weight
Allow the agent to run the mobile checks
Title 1
Allow the agent to run the mobile checks
Title 2
Allow the agent to run the mobile checks
Title 3 (a PR title)
Allow the agent to run the mobile checks
Body, headline, sheet title
Allow the agent to run the mobile checks
A two-line row's title
Allow the agent to run the mobile checks
Subheadline, Chat titles
Allow the agent to run the mobile checks
Footnote, secondary text
Allow the agent to run the mobile checks
Caption 1
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), phonetextPx(15 at 22). Markdown headings areem-relative to it. - Desktop
bodyis 13px on a unitless18 / 13line, so unsized text follows the 13 step. New prose setstext-13 leading-5(13/20). - A group heading above a card is
SectionLabel: 12 mediumink-3(11 in menus), phone 13 footnoteink3. 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-1is 4,p-3is 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
rounded-inline4pxCode, kbd, menu itemsrounded-chip6pxChips, tooltipsrounded-control8pxButtons, inputs, menus, option rowsrounded-card10pxCards, popovers, toastsrounded-window14pxDialogs, the composer, panels, Settingsrounded-fullfullPills, person avatars
The desktop new-Chat tray is 20: the composer's 14 plus its 6 padding.
radius.chip6pxChipsradius.control10pxRows, controlsradius.card14pxCardsradius.sheet20pxSheets, hero cards, iPad side panelsradius.composer24pxThe composer; its tray is the composer + 4radius.fullfullPills, person avatars
- 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;PillButtonis 32, 44 or 52, set withminHeightso Dynamic Type can grow it. - A numbered pin over content is 20px with
shadow-pinand 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,shadowRaisedandshadowOverlayintheme.ts, each with a hairline ring and a dark variant; never hard-coded black. Phone grouped cards are flat panels with a hairline.
Light
hairlinebtncardraisedoverlaypin
Dark
hairlinebtncardraisedoverlaypin
Blur
Light
overlay3pxchip8pxedge4px
Dark
overlay3pxchip8pxedge4px
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
fast120msbase180msslow280ms- 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)- Press
pressscale 0.97, phone 0.97
- A bare
transitionruns atduration-fastonease-enter. Every hover hastransition-colors. - JS motion uses
EASE_OUTandDURATION(lib/ease.ts) on desktop andscaledTiming/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.
- 12px · 1.6Inside 20px marks and inline with captions
- 14px · 1.8Inside 28px chips, menu rows
- 16px · 1.8Window chrome, buttons, rows
- 18px · 2Large controls, the provider rail
- Phone sizes are 12, 16, 18, 20 and 24.
- One icon size per row.
- Control glyphs at rest are
ink-3on desktop andink2on the phone.ink-4only for decorative icons, dots and disabled controls. - Shared looks live in
packages/sharedand each app maps the palette keys and icon names to its own:chatMarkPresentation(chats),PR_TONEandpullRequestStatePill(pr-blockers),permissionPresentation(model-copy; Full is the only orange mode),presenceTone(chat-scopes: green, orange, red,ink-4offline),projectAvatarRadiusandPROJECT_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
switchrole, on either platform. Native menu items that draw a checkmark are fine. - Focus is one accent ring from
@layer baseinstyles.css. A component may restyle it withfocus-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-2on 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-hovereverywhere, the sidebar included.bg-hover-2is 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-2with an ink glyph (phone:hover2fill, ink icon).accent-tintwithaccent-inkonly 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,SpinnerRingandInlineError(phoneErrorNotice), with "…" (U+2026).
Components
Buttons
Light
Dark
- One primary style per platform: an ink fill with an
on-inklabel. DesktopButton(rounded-control, hover opacity 0.9), phonePillButton. 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 withshadow-btn);ghost;quiet(ink-2, ink on hover);link(accent-ink, an inline action);danger(ared-inkfill with anon-redlabel, the confirm of a destructive action);danger-ghost(red-inktext with ared-tinthover, the first step: Remove, Delete, Deny, Revoke, Stop). PhonePillButtonhas the same primary and destructive pair (redInk,onRedInk). IconButtonis 20, 24, 28 or 32; a 20 reaches the 24px hit area through::before. Itslabelis its name.
Chips and badges
Light
Dark
- Chips are 28 high, fully round, 12 medium (
Chip). A composer trigger chip (Run on, Isolation, model, permission) is transparentink-2,hoveron hover andhover-2while open; a field chip sits onfield; a filter chip is a surface withshadow-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
-inkshade (pullRequestStatePill): Merged purple, Closed red, Draft neutral (hoverfill,ink-2label). An open PR shows no state pill. - Badges such as Recommended are neutral: a
fieldfill with anink-2label. 10px text is for badges only.
Rows and lists
Light
Open, hovered with unread, needs you, running, disabled
Dark
Open, hovered with unread, needs you, running, disabled
- Desktop rows are 32 high, two-line rows 48. Hover
bg-hover, open or selectedbg-hover-2, disabled 60%. - Unread is an 8px accent dot. Running is a quiet
ink-3ring; 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-2once 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,inkmedium while unread, then the unread dot). Line two at 12ink-3: the Project's 14px tile and name, the computer (ink-2on the hovered or open row), and the PR on the right edge in its state's-inkcolour, "+n" for several, its tooltip the state glyph,#numberin mono and the title. The hover Done takes the state's place inink-2,inkunder 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
Dark
Waiting for approval
Run the desktop smoke check
npm test -- --only test-desktop
- Desktop approvals sit inline on their tool row (
agents/step-approval.tsx): "Waiting for approval" inorange-inkbeside 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?
Dark
Waiting for answer
Where should the page live?
- 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 12ink-2. A picked row turnsinsetwith aline-strongborder. - "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
Dark
- A toast is an ink capsule on both platforms:
bg-ink,on-inktext at 13/18,rounded-card,shadow-raised, an optional on-ink Undo. - A message that stays is a
Noticecard.
Model picker
Light
Effort High
Dark
Effort High
- Fast and Ultracode are bordered tiles with a checkbox role. At rest: a
lineborder, anink-2icon, an ink title. On: the tile takes its tint (orange-tintfor Fast,purple-tintfor Ultracode), the icon its fill colour and the title its-inkshade. - The effort slider (
RangeSlider) is a 32 highfieldtrack 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-2tile with an ink mark; the others rest inink-3.
Activity and running
Light
Dark
- A folded reply's activity summary shows at most four stacked circular marks, one per kind of work: 20px
fieldcircles overlapping by 6px, each ringed in the page colour, with a 12pxink-2glyph. 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 withshowModal:rounded-window,shadow-overlay, ascrimbackdrop withbackdrop-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-chipand 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,navandheaderareuser-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 inlineapp-region. - The window background is faint diagonal stripes (
--stripeover--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
- Allow once
Do Fill the primary button with ink Allow onceAllow onceDon't Fill a primary button with green or accent Do Mark a selection with ink: a tick, a fill or a dot Don't Mark a selection with accent - Show stats
Do Use a checkbox for on/off, a radio group for one-of Show statsDon't Use a switch - Waiting for approval
Do Write status text in its -ink shade Don't Write text in a plain status colour or ink-4 - Archive Done Chats after
Do Write labels in sentence case Archive Done Chats afterDon't Write tracked uppercase labels Do Let the shadow token paint an elevated edge Don't Add a border to a shadowed surface - Always allow
Do Keep the accent focus ring Always allowDon't Recolour or remove a control's focus ring - Fix the login redirect
Do Show unread as the one accent dot Fix the login redirectDon't Use accent for any other status
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 withArrowUpLeft01, Subchats withRedo03, Done inink-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 thehoverfill 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
-inkcolours; 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-sidebaris a deprecated alias). - Selection is ink; accent is for focus and links. A pressed or open toggle is
hover-2with an ink glyph. - The menu highlight is
hover-2plus the inset ring on keyboard focus; a checked row shows a 14px tick. - Group headings are
SectionLabel; 15 semibold only inside cards.ink-2ismix(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(phoneink2). - 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.tsxand the phone'sdesign-tokens.ts), andstyles.css's fallback colours match the default theme.design-tokens.test.tson desktop and phone: counts off-scale literals per file againstdesign-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 withUPDATE_DESIGN_TOKENS=1(the command is in each test's header).- The phone's
milagre-designOxlint plugin (apps/mobile/lint/design-system.mjs), innpm run lintand 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 oneoxlint-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.tsandbackdrop-blur.test.ts: the scroll, select and blur rules indocs/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.