| name | Rome | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| description | A compounding agent OS for recursive agents. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| colors |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| typography |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| rounded |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| spacing |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| components |
|
Creative North Star: "The Quiet Workbench"
Rome's interface is a calm, well-lit bench where a person and their agents work side by side. Every tool sits in plain view on a warm, low-contrast ground, and one accent marks the thing that needs a hand: an approval waiting, a routine running, a button worth pressing. Nothing performs. Warmth comes from the linen canvas, the ink that stays slightly brown instead of black, and complete sentences, never from decoration.
The system is built for scanning and operating. Type runs in seven fixed roles on a 4px grid, controls come in three heights, and depth is conveyed by tone and hairline borders at rest. Shadows answer to state. Color answers to meaning. Under Ember, Ash, and Slate the same components render without a line of theme-specific code, because every component reads a semantic token and every theme supplies its own value for it. Brand lives in details: the coral on a primary button, a lit ember on an info note, the concentric corners of a control inside a card.
Visual rejections are the ones the codebase already enforces. There is no marketing-style hero inside the app, no gradient or orb, no saturated color as ornament, and no one-off font size, gap, or radius.
Key Characteristics:
- Warm neutrals with a single chromatic accent, remapped per theme rather than restyled per component.
- Seven typography roles in one sans, with Petrona reserved for reading surfaces and IBM Plex Mono for code and identifiers.
- Fixed control scale (28, 32, 44px) with concentric radii (8, 10, 12px). The large platform scale uses a 44px control floor and larger control typography.
- Flat at rest. Shadows mark hover, checked state, and floating layers only.
- One focus edge everywhere: a 1px outline in the ring color at 50% alpha, quieter than the 2px solid invalid edge.
- Meaning in tinted chips and alerts, never in the canvas.
The palette is a warm neutral ramp with a coral accent and four status hues held in pale tints, so an idle screen reads as paper and ink, and color appears where something has a state.
Rome has three themes, each with a light and a dark half. The frontmatter records Ember light, the default. Ash keeps Ember's ink and accent hue but lightens its surfaces and deepens the interactive coral to #c05433 so labels clear AA. Slate is achromatic: oklch(0.985 0 0) canvas, oklch(1 0 0) cards, and an ink-colored oklch(0.18 0 0) primary that inverts to near-white in dark mode. Components never see these values. They read semantic tokens such as --primary, --surface, and --border, and the theme supplies the value.
- Coral Ember (
#d86f4c): The one interactive accent. Fills the primary button, the checked switch, and the selected filter chip. Alpha-modulated for identity:primary/5on a selected card,primary/15behind a brand badge,primary/30for a selection ring. Also thebrandtoken under Ember and Ash, so the logo stays on the same hue as the controls. - Deep Ember (
#c2410c): Theprimary-hovertoken under Ember, and#a63a08under Ash. The kit'sButtondoes not read it. Its hover is the primary fill at 80% alpha, and the token serves surfaces that want a solid darker step, such as the sign-in callback page. - Ember Flare (
#e55a22): The focus ring under Ember and the Emberinfomark. A slightly hotter step than the accent so a focused control stands apart from a resting primary button.
- Linen Canvas (
#f4f3ef): The generic dashboard ground, used where no dedicated context canvas applies. - Linen Chat Canvas (
#f4f3ef): The ground behind chat prose and its composer. Kept softly tinted for long-form reading. - Warm App Canvas (
#fdfcf9): The brighter ground behind compact app UI. It may share a fill with a card, whose border then carries the boundary. - Warm Paper (
#fdfcf9): A raised card, panel, or table row on the canvas. Dialogs and sheets use it too. - Paper White (
#ffffff): The highest layer, for popovers, menus, and toasts. - Recessed Linen (
#efe9e1): A region recessed inside a card: a well, a code block, a table header, the segmented control track, and themutedfill behind ghost-button hover. - Pressed Linen (
#eae6df): Hover and active fill of a row or list item, and thesecondaryandaccentfills. - Ink (
#1a130f): Body and control text. Warm, not black. - Muted Ink (
#7a6857): Descriptions, placeholders, table headers, and annotations. Sits at 5.2:1 on Warm Paper. A lighter step drops card and dialog descriptions under AA. - Subtle Ink (
#b0a294): Tertiary text, archived items, and inactive glyphs. Below AA by design. Never carries a fact the reader needs. - Hairline (
#ece6de): The default border and the input edge. - Hairline Strong (
#e0d8cd): Field hover edge, tile borders, and unselected chip borders. - Scrim: A 45% ink over the page, the
overlaytoken. The alpha is baked in, so it is used at full opacity. Sheets and the mobile backdrop paint it.Dialogpaints a 35%foregroundwash with a small backdrop blur instead, a divergence this file records rather than resolves.
- Signal Red (
oklch(0.58 0.245 27)) with Red Tint, Red Ink, and Red Edge: Thedestructivefamily. Also theunreadfill, in every theme and mode. The destructive button is a red tint at 10% with red text, not a solid red fill. - Moss (
#5b7a4a) with Moss Tint, Moss Ink, and Moss Edge: Thesuccessfamily. Ember and Ash use a warm moss whose pale end sits comfortably on linen. Slate uses a cool green at hue 150. - Amber (
oklch(0.78 0.15 80)) with Amber Tint, Amber Ink, and Amber Edge: Thewarningfamily and the "waiting for approval" state. - Ember Tint (
#ffead9), Ember Ink (#b0421a), Ember Edge (#fbcda6): Theinfofamily under Ember and Ash, which have no blue in play. Slate mapsinfoto blue at hue 250.
The One Ember Rule. A screen at rest carries one chromatic accent, primary, and it marks what waits on the guardian or what the guardian can press. Status hues live inside tinted chips and alerts. The canvas, the cards, and the type stay neutral.
The Semantic-Only Rule. A component names a semantic token (bg-primary, text-muted-foreground, border-border). It never names a primitive (--neutral-500), a raw color, or a per-theme override. Theming and dark mode both ride on this indirection.
The Tinted-Not-Solid Rule. Status is a pale tint with a deep ink of the same hue (success-bg with success-fg), and a hairline *-border when it needs an edge. Solid status fills belong only to a dot, a bar, or the marker on a switch.
Display and Body Font: Funnel Sans (with system sans fallbacks, then PingFang SC, Hiragino Sans GB, Microsoft YaHei, Noto Sans CJK SC, and Source Han Sans SC for Simplified Chinese) Reading Font: Petrona (with Cormorant Garamond, Times New Roman) Mono Font: IBM Plex Mono (with ui-monospace, SFMono-Regular, Menlo)
Character: One humanist sans does almost all the work, and hierarchy comes from weight and position rather than size jumps. Petrona is present in the kit for prose that is read rather than operated, such as chat blocks and the type specimen, and the dashboard uses it sparingly. Plex Mono sets identifiers, timestamps in columns, and code.
Every text run takes exactly one of seven roles. A role sets size, line height, letter spacing, and weight together, and each line box lands on the 4px grid.
- Display (400, 30px/36px): The one hero moment on a screen, such as the home greeting. Never a second element on the same screen.
- Title (500, 18px/24px): The heading a page or dialog carries once, at the top.
- Section (500, 15px/20px): The heading of a section, card, or panel inside a surface.
- Body (400, 16px/20px): Prose someone reads as content: chat messages and paragraphs. Also the smallest size mobile Safari does not zoom on focus.
- UI (400, 14px/20px): Controls: sidebar rows, menu items, buttons, tabs, fields and their labels, and both rows of a compact alert.
- Badge (500, 13px/16px): Text inside a compact labeled container: chips, tags, status pills, counters.
- Aux (400, 13px/16px): Metadata that annotates other content: timestamps, uncontained counts, group headers, captions. Columns of times or counts add
tabular-nums.
The font size scale has eleven steps (13, 14, 15, 16, 17, 18, 20, 22, 24, 28, 30px). The seven roles read 13, 14, 15, 16, 18, and 30. Steps 20, 22, and 24 back the Markdown heading tokens, not a dashboard role, and 17 and 28 back the phone ramp.
In the large platform scale, UI, Body, Section, Aux, and Badge rise and keep their names. Display and Title keep their shared values. Below 768px, PageTitle sets the Title role locally to 28px/36px at weight 700.
| Role | Medium scale | Large scale |
|---|---|---|
| UI | 400, 14px/20px | 400, 17px/24px |
Body (text-composer) |
400, 16px/20px | 400, 17px/24px |
| Section | 500, 15px/20px | 600, 17px/24px |
| Title | 500, 18px/24px | 500, 18px/24px |
| Aux | 400, 13px/16px | 400, 15px/20px |
| Badge | 500, 13px/16px | 500, 15px/20px |
In the large platform scale, editable controls read text-ui at 17px. A native field with no role gets the same default. The viewport allows pinch zoom.
The Seven Roles Rule. Text reads text-display, text-title, text-section, text-composer, text-ui, text-badge, or text-aux. A one-off size or line height is unfinished migration, not a pattern.
The Weight, Not Size Rule. Emphasis comes from color, weight, or position within the same role. A label is never bumped one size to read as important, and an active row leads by fill, not by scale. The CJK system fallbacks ship no 500 face, so the weight on Title, Section, and Badge is Latin-only. Hierarchy on a bilingual surface also comes from size through a different role, ink, position, or container geometry.
The grid is 4px. Spacing comes from one scale of fifteen steps (0, 4, 8, 12, 16, 20, 24, 28, 32, 36, 40, 48, 64, 80, 96px) and every gap, padding, and inset is a step. A value between steps never enters as a one-off.
The guardian shell is a sidebar plus a content column. On desktop (768px and up) the sidebar is sticky and 256px wide, collapsing to a 64px rail. Below 768px it becomes a fixed slide-over, and a 48px mobile header (plus the safe-area inset) sits at the top of the content column. Chat is the home screen. A swipe right anywhere drags the sidebar out under the finger, and the page slides right with it under the scrim, so the sidebar pushes the page rather than covering it. On release it settles open past a third of its width or on a flick. A swipe left or a tap on the dimmed page closes it, and the header's menu button stays as the visible way in. A swipe gives way to a sideways scroller that is not at its start, to a surface that handles its own touch (touch-action: none, such as a diagram's pan), and to text fields. Mobile Safari keeps the screen's left edge for its back gesture, so there a swipe starts a little way in. The file browser switches from two panes to a compact single pane below a 1024px container width. Apps mount inside the content column in a Shadow DOM and inherit the theme layer.
Density is operational but not cramped. Cards carry 16px inner padding, tiles 12px, menu items 4px by 8px. Controls share sm at 28px and md at 32px. The Button family also offers xs at 24px for small inline actions and lg at 44px for standalone actions. Badges are 22px. Avatars are 24, 32, and 40px. A row with a control and loose text takes the taller of the two. Use the air ratio to choose sizes for mixed rows.
In the large platform scale, standard controls and menu options take a visible 44px floor. Square icon buttons and calendar days are 44px squares. Chips, tabs, and page-nav entries are 44px tall. The switch is 48 by 28 at both scales, with a 44px tall target. A segmented control's 36px segments extend their targets into their own track's padding. Row floors follow the control step to 52px.
Labeled Buttons in dense surfaces can opt into compact at xs, sm, and md. The button paints at its selected height and keeps a touch target at least 44px high and wide. The kit reserves the space above and below the button with protected block margins, so adjacent targets stay separate. Put any additional spacing on the parent.
Selection controls keep their glyph geometry inside accessible labels or their composite hit areas. Hover-only disclosure is never the only path to an action.
Rome is flat at rest. Two context canvases sit beneath three content depths: a raised card (surface), a recessed region inside a card (surface-muted), and a floating layer (surface-elevated). Chat uses chat-canvas; compact app UI uses the brighter app-canvas; dashboard pages without a dedicated context use background. A canvas and card may share a fill, so the card's hairline border must still carry its boundary. In dark mode the distinct steps lighten as they rise, which is why depth names describe position rather than lightness.
Shadows appear as a response to state or to floating. A card takes shadow-4 on hover. A checked segment takes shadow-1, and the active sidebar row takes shadow-4 with one outer edge. Menus, popovers, and selects take shadow-4 with a 10% ink ring, and a submenu that opens beside a menu takes shadow-10. Dialogs and sheets take shadow-25 over their backdrop. Nothing else in the kit casts. A dashboard page that paints shadow-1 on a resting card is unfinished migration, not a pattern.
- Rest lift (
box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)):shadow-1, on the checked segment of a segmented control. - Hover lift (
box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)):shadow-4, on card hover, the active sidebar row, menus, popovers, selects, and toasts. - Submenu (
box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)):shadow-10, on a submenu that opens beside a menu, and on the dashboard's floating composer chrome. - Modal (
box-shadow: 0 25px 50px -12px rgb(0 0 0 / 0.25)):shadow-25, on dialogs and sheets.
Dark mode deepens the ink (alpha 0.4 to 0.7) and widens the blur, because a 10% black cast vanishes on a near-black canvas. The values are per theme in themes.ts, and every theme carries all four steps in both halves.
The State Shadow Rule. A surface at rest has a border and a tone, never a shadow. A shadow says hover, checked, or floating.
The Achromatic Ink Rule. Every shadow is black at an alpha. A tinted shadow would fork per theme.
Corners come from one scale (4, 8, 12, 16px) plus a saturation token for fully round (9999px). Neighbors differ by 4px, which is one spacing step, so a box inset by one step from an enclosing corner lands exactly one radius step down and nested corners stay concentric.
Controls take their own three steps, 8, 10, and 12px, matched to their heights (28, 32, 44px), and inputs, buttons, and select triggers on the same size share the same corner. A small button inside a button group squares to 8px so the group reads as one object. Cards are 12px, dialogs 16px, menus and popovers 12px, menu items and tiles 8px, tooltips 8px, and inline code 4px. Badges, chips, switches, and avatars are pills.
Borders are 1px hairlines in border. A control that can paint a border declares the width unconditionally and lets a variant change only the color, so nothing shifts on hover. Fields show a hairline edge at rest, border-strong on hover, and no fill on light themes. The focus edge is a 1px outline in ring at 50% alpha. Filled and ghost controls sit it at offset 0, outside the box. Bordered controls (inputs, textareas, select triggers, outline buttons) inset it 1px onto their own border. The control carries the outline at rest, transparent, so focus changes only the style and the color. Invalid is 2px of solid destructive, always louder than focus. A translucent halo never appears.
The Concentric Corner Rule. A corner nested one spacing step inside another corner is one radius step smaller. No arithmetic, no eyeballing.
The Silent Corner Rule. A radius never signals a state. A range endpoint may round its outer corners and square the shared seam, but an input never softens on focus.
Components are precise and restrained. Each one declares its own typography role and reads only semantic tokens, so a call site never sets a type utility, a color, or a per-theme class on it.
- Shape. Medium is 32px tall with a 10px radius and horizontal padding of 14px for centered content or 12px for start-aligned content. Small is 28px tall with an 8px radius and 10px padding. Extra-small is 24px tall with the small radius. Large is 44px tall with a 12px radius. Icon-only buttons are square at each height.
- Primary: Coral Ember fill, white label at weight 500. Hover is the same fill at 80% alpha (
hover:bg-primary/80), not theprimary-hovertoken. Under Ash the fill is the deeper coral and under Slate it is ink. - Outline: Canvas fill, hairline border, ink label. Hover switches to the recessed fill. Dark mode uses a 30% input tint.
- Ghost: No fill or border at rest. Hover takes the recessed fill.
- Secondary: Pressed Linen fill, ink label. Hover mixes 5% ink into the fill.
- Destructive: 10% red tint with Signal Red label. Hover deepens to 20%. Never a solid red fill.
- Link: Coral text, underline on hover with a 4px offset.
- Press: Every button drops 1px on active. Focus is the shared 1px
ringoutline at 50% alpha, outside the box. Disabled is 50% opacity with pointer events off.
- Badge: 22px pill, 9px horizontal padding,
text-badge. Variants are tinted: default and muted on Recessed Linen, info, success, warning, and destructive on their tint with their ink, brand on 15% coral with coral text, outline on a hairline. - Filter chip: Pill with 12px by 4px padding on Warm Paper with a strong hairline. Selected fills Coral Ember with a white label. An optional count trails in
tabular-nums, in Subtle Ink when unselected.
- Card: Warm Paper on the canvas, 12px radius, hairline border, 16px padding, 16px gap between header, content, and footer. Title is
text-section, description istext-uiin Muted Ink. No shadow at rest. Interactive cards takeshadow-4on hover. - Tile: 8px radius, 12px padding, strong hairline border. Hover recesses the fill. A selected tile takes a coral border, a 5% coral fill, and a 1px coral ring.
- Alert: 8px radius, 12px by 16px padding,
text-uiin both rows with the title at weight 600, and a 16px leading icon. Default is Warm Paper with a hairline and a Muted Ink description. Status variants use the tint, ink, and edge of their family and set the description toforeground.
- Style: Transparent fill, hairline
inputborder, 32px height, 10px radius, 12px start inset,text-ui. Placeholder is Muted Ink. A leading glyph sits at the start inset and pushes the text by the glyph width plus 6px. - Hover: Border steps up to Hairline Strong.
- Focus: 1px
ringoutline at 50% alpha, inset onto the border. No glow. - Error: 2px solid Signal Red at offset 0.
- Disabled: 50% opacity, cursor
not-allowed, and a 50% input tint. - Plain variant: No border, radius, or fill, for a field already framed by its surface, such as the command palette input.
- Textarea: The same recipe with 8px vertical padding, a 64px minimum, and
field-sizing: content. - Select trigger: Matches the input, with the value clamped to one line and a 16px chevron.
- Segmented control: A 32px Recessed Linen track with 4px inner padding and 10px radius. Segments are 8px-radius items at 60% ink. The checked segment lifts to its context canvas color with
shadow-1and full ink. - Tabs: Transparent list, 32px tall. Triggers are
text-uiat 60% ink, full ink on hover and when active. The active trigger draws a 2px ink underline 5px below the label. No fill. - Switch: A pill track that fills coral when checked. The thumb follows its context canvas color, 16px in the default size, 12px in small, with a 1px inset. The hit area extends 12px horizontally and 8px vertically past the track.
- Sidebar: Canvas fill with 1px region boundaries in
border-strong. Navigation groups and the footer use the shared Separator withborder-strong; shell columns and the Tasks card use the same token for their edges. Footer and topic-menu action glyphs follow their control's size, 14px at the small step and 16px at the medium step. Navigation rows, chat rows outside the Tasks card, and the search pill use--row-h(36px), with 12px corners and regular-weighttext-ui. Both columns use the medium row inset for 12px of content padding and a matching 12px icon gap. A 16px icon slot starts at x=20 and text at x=48 within each column. Bordered links subtract their border from that inset. Project children and the Tasks card derive their text insets from the same column offset. Project chats keep the tree guide and selected marker; selection does not increase their weight. The New chat row has no separator above it, and its shortcut uses a square muted Badge rendered askbd. The chat-list header aligns with the rail header. Its mode switch uses the shared outer inset and the SegmentedControl padding, independent of the row icon column. New-chat and main-chat rows share the navigation rhythm. Topic rows show a#in the same icon slot as the main chat so their text starts on the same vertical line. An unread count is an 11px circle on the bottom right corner of the row's icon, 6px past its right edge and 4px past its bottom, so the logo or#still shows. It uses semibold 8px/11px type from the host-owned--row-count-*tokens and shows up to99+, widening to the left into a pill so it never reaches the name. Its fill and numerals are theunreadpair, one red with white numerals in every theme and mode (4.7:1). Unlike theinfodots, it is the familiar red of a notification count. A 2px ring in the row's fill (background, or the hover fill) cuts it out of the icon. It stays until the count clears and stays visible when the row menu appears. Lists and the Tasks card share an 8px outer inset, and the Tasks heading uses the same row height. The navigation rail's search trigger is a borderless pill with asurface-mutedfill. The medium row vertical inset separates it from the navigation group. Navigation, list glyphs, and app artwork are 16px. The Projects and Chat glyphs share a stroke width. The Apps, Chat, and Projects glyphs tilt during hover or keyboard focus. Filled artwork reads slightly larger than outline glyphs within the same fixed slots, and names stay aligned. Hover takessurface-hover. The selected row takessurface,shadow-4, a single 1px outer edge inborderat 70% alpha, regular-weight text, and aprimaryglyph; dark mode usessurface-hover. App artwork keeps its own colors. Rows inside the Tasks card use 8px corners, matching its heading and the concentric corner rule. A selected task uses the hover fill without another shadow. Archived chats read in Subtle Ink. Unread activity is an 8pxinfodot that hides on hover to reveal the row action. Below the pinned entries, a hairline and an aux "Recent" label introduce up to three unpinned apps the guardian built or opened in the last 14 days, most recent first, with a "Show more" row for the rest. The zone is absent when empty. An installed, never-opened app carries the same 8pxinfodot, which on hover gives way to a Pin action. On touch the Pin action is always visible and the dot sits beside it. - Mobile header: 48px plus the safe-area inset, hairline bottom border, hidden from 768px up.
- Chat search:
Command+Kon Apple platforms andCtrl+Kelsewhere open a command dialog. The trigger stays visible beside the list settings, since a shortcut is never the only path. A leading@turns the field into an agent picker, and a picked agent pins as a composer chip before the text. From then on the field holds a message, and Enter starts a new chat with that agent in the default project. Backspace in the empty field unpins the agent.
- Menu and context menu: Paper White, 12px radius, 4px padding,
shadow-4with a 10% ink ring, the same as popovers and selects. A submenu takesshadow-10. Items are 8px radius with 4px by 8px padding, and the focused item takes theaccentfill. Destructive items take a 10% red tint on hover. - Tooltip: Ink fill with canvas-colored
text-aux, 8px radius, 4px by 12px padding. - Dialog: Warm Paper, 16px radius, hairline border,
shadow-25, a 5% black ring, over a 35%foregroundwash with a small backdrop blur. Sheets share the treatment with a left hairline instead of a radius, over theoverlayscrim. - Toast: Paper White, 8px radius, hairline border, 16px padding,
shadow-4. - Motion: Floating layers fade and zoom from 95% over 100ms and slide 8px from their trigger side. The mobile sheet rises over 280ms on
cubic-bezier(0.16, 1, 0.3, 1)with a 200ms backdrop fade. The sidebar slides and resizes over 200ms ease-out. Empty states rise 12px with a blur over 720ms. Every animation is disabled underprefers-reduced-motion.
A centered block with a 44px Recessed Linen glyph well (12px radius), a text-section title, and a text-ui description in Muted Ink. Minimum height 192px.
- Do write
bg-primary,text-muted-foreground, andborder-border. The theme supplies the value, and every theme and both modes come for free. - Do pick a text role by asking what the text is: a control reads
text-ui, a chip readstext-badge, a timestamp readstext-aux. - Do spend
primaryon the one thing a screen needs the guardian to notice or press, and use alpha (primary/5,primary/15) when the accent marks identity rather than action. - Do put status in a tinted chip or alert:
success-bgwithsuccess-fg, and the family's border when it needs an edge. - Do compose the complete focus recipe:
outline-1 outline-offset-0 outline-transparent focus-visible:outline-solid focus-visible:outline-ring/50. The width utility alone renders no outline. - Do take every gap, inset, and radius from a scale step, and let a nested corner sit one step below its parent.
- Do give compact surfaces a visible action affordance. Long-press, right-click, hover, and drag are accelerators.
- Don't name a primitive (
--neutral-500) or a raw color inside a component. It compiles, passes tests, and breaks in every other theme. Adark:variant is a mode step on a semantic token, as indark:bg-input/30, never a way to reach a raw color, and a component that reads semantic tokens rarely needs one. - Don't add a marketing hero, a gradient, an orb, or saturated color as ornament inside the app.
- Don't bump a font size to make something important, or invent a size between steps.
- Don't put a shadow on a surface at rest. Shadows mean hover, checked, or floating.
- Don't paint a solid status fill behind text, or use
danger,brand, oraccentwheredestructiveorprimaryis the token. - Don't use
bg-black/40for a scrim. Theoverlaytoken carries its own alpha. - Don't read a host-only token from inside an app without compiling it. Geometry and typography come from
@rome-os/app-web-sdk/styles, and only the theme layer crosses the Shadow DOM.