# Happy (2) plugin app design This is the authoritative visual specification for a **plugin app**: the HTML document a Happy (2) plugin ships and Happy renders inside a sandboxed iframe (an MCP App view, or an applet served on its own isolated origin). It is written to be followed literally. Every rule states a name, a number, or a condition. Where a choice exists, this document makes it for you. If you are a model generating a plugin app and you are unsure what something should look like, the answer is in here; do not invent one. ## 0. How to use this document **Precedence.** Three contracts apply to a plugin app, in this order: 1. The **MCP Apps specification** (`@modelcontextprotocol/ext-apps`). It defines the handshake, the host context, and the closed set of style variables. Never violate it. 2. **This document.** It says how a Happy plugin app should look and behave inside that specification. 3. Your plugin's own product decisions — content, information architecture, feature set. The repository's root `DESIGN.md` is the contract for **Happy's own native UI**, written and reviewed inside the Happy codebase. It is _not_ the contract for a plugin app and you do not need to read it. This document deliberately restates every shared value (grid, radii, control heights, type scale) so a plugin app is self-contained. Where a number appears in both, it is the same number. **The one-sentence summary.** A Happy plugin app is a quiet, dense, neutral desktop surface built from flex rows and columns on a 4 px grid, painted only with host-provided CSS variables, with exactly one accent colour used only where something is interactive or selected. **Read at minimum:** §1 (host contract), §2 (surfaces and sizes), §5 (variable reference), §6 (typography), §11.6 (what to render before you are connected), §16 (anti-patterns), §18 (checklist). §17 is a complete working baseline you can copy verbatim. --- ## 1. The host contract ### 1.1 How appearance reaches your app Your app runs in an iframe on a different origin from Happy. It cannot read Happy's stylesheets, DOM, or fonts. Everything about appearance arrives as data in the **host context**, over the MCP Apps postMessage bridge: | Field | What it carries | | ------------------------- | ----------------------------------------------------------------------- | | `theme` | `"light"` or `"dark"` — the appearance Happy is currently rendering in. | | `styles.variables` | The standard MCP Apps CSS variables, resolved from Happy's live theme. | | `happy2/styles.variables` | Happy's extension: the roles the standard set has no key for (§5.3). | | `displayMode` | `"inline"` or `"fullscreen"` — which surface you are on (§2). | | `containerDimensions` | The space Happy allocated you **at connect time only** — see below. | | `platform` | Always `"desktop"` in Happy. | | `deviceCapabilities` | Always `{ touch: false, hover: true }` in Happy. | | `locale`, `timeZone` | For formatting dates and numbers. Never hard-code a format. | > **`containerDimensions` is not live.** Happy re-sends the host context when the > appearance changes, not when the window resizes, so this value goes stale the > moment the user drags the window edge. Use it to choose an initial layout at > most. **Never lay out from it in JavaScript.** Your size comes from CSS — > `height: 100%` and a flex column — and from container queries (§4.5). The SDK applies all of this for you. In a React app: ```tsx import { useHappyApp } from "happy2-plugin-sdk/app"; function App() { const { app, error, hostContext, isConnected } = useHappyApp({ appInfo: { name: "my-plugin-app", version: "1.0.0" }, autoResize: true, }); // Nothing else is needed for theming. } ``` `useHappyApp` calls the official `useHostStyles`, which sets `data-theme="light" | "dark"` and `style.colorScheme` on `` and writes every standard variable there as an inline custom property; and it calls Happy's `useHappyStyleVariables`, which writes the `--happy-*` variables the same way. **Your first paint is not themed.** Connecting is an asynchronous handshake over `postMessage`. Your app mounts and paints _before_ it completes — with `isConnected === false` and not one host variable set — then repaints when the context arrives, usually within a frame or two. This is why the fallback block in §5.4 is mandatory rather than a nicety: without it the app flashes unstyled, and in a host that never sends styles it stays that way. §11.6 says what to render during the handshake. ### 1.2 The theme can change at any moment Happy re-sends the host context whenever the resolved appearance changes: the operating system switches between light and dark, or the user picks an explicit appearance inside Happy. Your app is **not** remounted and **not** reloaded. This has one hard consequence: > **Every colour in your app must be a `var(--…)` reference that resolves through > the host variables.** A colour you computed once in JavaScript, baked into a > generated SVG, or hard-coded in a class name will be wrong the moment the theme > changes, and there will be no second chance to fix it. Corollaries: - Do not read a variable with `getComputedStyle` and store the value. - Do not branch on `theme` in JavaScript to pick a colour. Let CSS do it. - Do not use `@media (prefers-color-scheme: …)` to pick colours. The user may have overridden the appearance inside Happy, in which case the media query and the host disagree and the host is right. - **Do not write theme-conditional rules at all.** The variables already encode the difference; a rule keyed on `[data-theme="dark"]` is both unnecessary and a trap, because that attribute exists only after a host connects, so the rule silently never fires in a standalone browser tab. If a value genuinely has no variable — a hand-drawn illustration's two-tone fill, say — express it with `light-dark()`, which works in both situations. - `light-dark()` **is** safe: the host sets `color-scheme` on ``, so `light-dark(a, b)` follows the host's decision, including an in-app override. This is the recommended way to write a _fallback_ (§5.4). ### 1.3 What the host will never give you - Happy's fonts as files, its component CSS, its class names, or its icon fonts. - Arbitrary CSS. There is no channel for the host to inject rules into your document. Everything you paint, you paint yourself, from the variables. - Any variable outside the two documented sets. Do not guess at names such as `--happy-sidebar-width`; they do not exist and never resolve. ### 1.4 You are app content, not Happy chrome Happy already draws the frame around you: a header carrying the app's glyph, title, and controls (40 px on a message card, 56 px on a page or overlay); the window title bar; the feature rail; the modal card and its scrim. Your document is the region _inside_ that. **Do not imitate host chrome.** Specifically, never render: - A window title bar, traffic-light buttons, or a drag region. - A duplicate of the app's own title in a bar across the top of your document. Happy is already showing it, one hairline above you. - A close, minimise, maximise, reload, or "open in new window" control. - A global app-level navigation rail or sidebar of _Happy's_ features. - A backdrop or scrim covering the whole viewport for a "modal" that is really the whole app. If your app needs to be a dialog, request it from Happy. You _may_ render a toolbar or a header **for your own content** — a list's filter row, a document's breadcrumb — as long as it reads as part of the content, not as a second window frame. See §9.6. --- ## 2. Surfaces, dimensions, and gutters Happy is **desktop only**. There is no mobile viewport, no touch input, and no phone layout. Do not write `@media (max-width: 480px)` breakpoints, do not enlarge hit targets for fingers, and do not build a bottom tab bar. ### 2.1 The five surfaces | # | Surface | `displayMode` | Host header | Host gutter around you | Typical width | Height ownership | | --- | --------------------- | ------------- | ----------- | ---------------------------------------------------------- | ----------------------------- | ---------------- | | 1 | Message card (inline) | `inline` | 40 px | 0, or 8 px + 1 px hairline when the app asked for a border | the chat message column | **you**, 120–800 | | 2 | Workspace page | `fullscreen` | 56 px | none, flush | main region width | the host | | 3 | Modal card | `fullscreen` | 56 px | none, flush | `min(920px, window − 48) − 2` | the host | | 4 | Fullscreen overlay | `fullscreen` | 56 px | none, flush | `window − 48 − 2` | the host | | 5 | Rig plugin page | `fullscreen` | none | none, flush | the whole allocated region | the host | `hostContext.containerDimensions` reports the initial allocation as one of `{ width, height }`, `{ width, maxHeight }`, or `{ maxWidth, maxHeight }`. It does not track resizing — see the note in §1.1. Surfaces 2–4 are flush: no inset, no border, no rounded corner from the host. The seam between Happy's chrome and your document is one hairline, so your outermost background should normally be `--color-background-primary` (§7.1), which makes that seam invisible. **You cannot tell surfaces 2–5 apart, and you must not need to.** All four report `displayMode: "fullscreen"`; nothing in the host context says whether you are a workspace page, a modal card, or a whole window. Design one fullscreen layout that is correct at every size in §2.4 and it will be right on all four. The only distinction that reaches you is `inline` versus `fullscreen`, and it matters for exactly one reason: who owns your height (§2.2, §2.3). ### 2.2 Inline (surface 1) — you own your height On a chat message card, Happy sizes the frame to the height your document reports. The SDK does this for you when you pass `autoResize: true`. - Default before you report: **360 px**. - Clamped to **120 px minimum, 800 px maximum**. Content taller than 800 px scrolls _inside_ your document; design for that, do not fight it. - `containerDimensions` gives you `maxHeight: 800`. Therefore: on inline, **`` must size to its content**. Do not set `height: 100%` or `100vh` on `html`/`body`, or you will report 800 px forever and show a mostly empty card. ### 2.3 Fullscreen (surfaces 2–5) — the host owns your height The frame is exactly the region Happy allocated. Your document must fill it and manage its own overflow. ```css html, body { height: 100%; margin: 0; } #root { display: flex; flex-direction: column; height: 100%; min-height: 0; } ``` ### 2.4 The smallest size you must survive Happy's Electron window minimum is **720 × 480**. Subtract the 64 px feature rail, a navigation sidebar that can be as narrow as 250 px, the 56 px window title row, and the 56 px host app header, and the honest floor is: > **A plugin app must remain usable and unbroken at 400 × 360 CSS pixels, and > must look correct at 640 × 480 and above.** Design the primary layout for **640–1180 px** wide. Below 640 px, collapse optional columns; do not introduce a different design. ### 2.5 Gutters Except for the optional 8 px on a bordered inline card, the host region is flush, so your document supplies its own gutter: | Context | Gutter (padding) | | ----------------------------------------- | ---------------- | | Inline message card, outer edge | **12 px** | | Workspace page / overlay, outer edge | **16 px** | | Wide page (≥ 900 px), outer edge | **24 px** | | Inside a card | **16 px** | | Inside a card in a dense card grid | **12 px** | | Inside a compact list row | **8 px 12 px** | | Between a section heading and its content | **8 px** | Never use an outer gutter larger than 24 px. Never use 0 — content must not touch the frame edge. If your content has a natural reading width, cap the _inner_ measure and centre it; keep the scroll container full-bleed (§4). ```css .page-measure { width: 100%; max-width: 720px; margin-inline: auto; } ``` --- ## 3. The grid: 4 / 8 / 16 The scale applies to **layout spacing**: the `gap` between siblings, the padding of a container around its children, the page gutter, and the space between blocks. Every such value is one of: | Value | Use | | ----- | ------------------------------------------------------- | | 4 px | Tight vertical pairs, chip-to-chip | | 8 px | **The default gap.** Between controls, between cards | | 12 px | Between a row's columns, between fields in a dense form | | 16 px | Between content blocks, card padding, page gutter | | 24 px | Between major sections, wide page gutter | | 32 px | Around an empty state, above a page's first section | | 48 px | Rare; vertical breathing room in a nearly empty page | **Control internals are not on this scale.** The padding inside a button, the gap between a button's icon and its label, the padding inside an input, the height of a chip — these are fixed per component in §9 and are whatever number makes the component's declared height come out exactly right. Copy them from §9 verbatim; do not "correct" a `padding: 0 14px` to `0 16px`. Rules: - `0` is always allowed, and is the right answer more often than it looks: a stacked pair of text lines is separated by its line boxes, not by a `gap`, and a hairline-separated list uses `gap: 0` (§8). Anything greater than zero is one of the seven values above. - Every length is a whole number of CSS pixels. Never use `em`/`rem` for spacing, and never a fractional pixel. - 1 px is for hairline borders. 2 px is for a focus ring and its offset. - Border-box everywhere: `*, *::before, *::after { box-sizing: border-box; }`. - A declared size must be the rendered size. If a row promises 36 px, its padding, border, and line height must add to 36 px. - Prefer integer positions so 1 px borders stay crisp at 2× device scale. --- ## 4. Layout: flexbox, and scrolling ### 4.1 Flexbox is the default Use flexbox for every row, column, stack, toolbar, list, and centred box. ```css .row { display: flex; align-items: center; gap: 8px; } .column { display: flex; flex-direction: column; gap: 8px; } .center { display: flex; align-items: center; justify-content: center; } ``` Use CSS Grid **only** for a genuine two-dimensional grid of related tracks: a data table's cells, or a media matrix with equal row and column tracks. When you do, put a comment beside the declaration explaining the geometry flexbox cannot express. Never use floats, `inline-block` spacing hacks, layout tables, or absolute positioning for layout. Absolute positioning is for overlays, popovers, and badges that intentionally leave the flow. ### 4.2 The parent owns the spacing Spacing between siblings belongs to the flex parent, via `gap`. A child never gives itself an external margin to separate itself from a sibling it does not know about. ```css /* Correct */ .toolbar { display: flex; gap: 8px; } .toolbar > * { margin: 0; } /* Wrong */ .toolbar-button + .toolbar-button { margin-left: 8px; } .toolbar-button:not(:last-child) { margin-right: 8px; } ``` **The one legitimate margin** is `margin-inline-start: auto` on a flex child, to push it and everything after it to the far end of the row. That is positioning, not spacing, and it is the correct idiom — do not simulate it with a spacer element, and do not reach for `justify-content: space-between`, which spreads _every_ child rather than only the tail. ```css /* Preferred: let the middle column absorb the slack. */ .toolbar-title { flex: 1 1 auto; min-width: 0; } /* Or push the tail explicitly when there is no such column. */ .toolbar-count { margin-inline-start: auto; } ``` A conditional child must live in the same flex flow as its neighbours. When it is absent it contributes neither a box nor a gap; when it appears, the parent's `gap` separates it on both sides automatically. Do not wrap optional content in a nested div that creates its own spacing island. ### 4.3 A flex child that can shrink needs `min-width: 0` This is the single most common layout bug. A flex item's default minimum size is its content, so long text pushes its siblings out of the row instead of ellipsizing. ```css .row-main { flex: 1 1 auto; min-width: 0; } /* the column that may shrink */ .row-title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } .row-aside { flex: none; } /* fixed-size trailing content */ ``` The same applies vertically: a flex child that contains a scroll area needs `min-height: 0`. ### 4.4 Scrolling Exactly **one** element in a fullscreen layout owns vertical scrolling. It fills the region its parent gives it and has **zero padding and zero margin** — its viewport and scrollbar run edge to edge. All spacing, maximum widths, and centring belong to an inner wrapper. ```css .scrollport { flex: 1 1 auto; min-height: 0; width: 100%; overflow-y: auto; overflow-x: hidden; /* no padding, no margin */ } .scrollport-content { display: flex; flex-direction: column; gap: 12px; padding: 16px; } ``` Rules: - Never put `overflow: auto` on `` in a fullscreen surface; give it to the designated scrollport so the header and footer stay fixed. - Never nest scroll areas on the same axis. Two vertical scrollbars in one view is a defect. - Horizontal scrolling is allowed only for a wide data table, and only on the table's own container. - Keep the full painted extent of a focus ring inside the content wrapper's padding, so scrolling cannot clip it. A 2 px ring with a 2 px offset needs at least 4 px of clearance — the 16 px gutter covers it. - Style the scrollbar with the host thumb colour, or leave it native. Do not hide it. ```css .scrollport { scrollbar-width: thin; scrollbar-color: var(--happy-scrollbar-thumb, rgb(150 150 150 / 0.4)) transparent; } ``` ### 4.5 Responsive behaviour inside a desktop panel Respond to the **container**, not the viewport, and only to collapse or reflow — never to switch to a different design. ```css .page { container-type: inline-size; } /* Below 640px the metadata column folds under the main column. */ @container (max-width: 640px) { .split { flex-direction: column; } .split-aside { width: 100%; } } ``` Permitted responses to a narrow container, in order of preference: 1. Let a flex row wrap (`flex-wrap: wrap`) at a documented gap. 2. Hide a genuinely secondary column (never the primary action). 3. Reduce a 3-column card grid to 2, then 1. 4. Swap a side-by-side label/field pair to stacked. Forbidden: hiding the primary action, replacing the layout with a "mobile" one, introducing a hamburger menu, shrinking type below the minimums in §6. --- ## 5. Colour: the complete variable reference **Every colour in your app comes from this section.** A raw hex value, named colour, or `rgb()` literal in your CSS is a defect, with exactly one exception: the fallback inside `var(--x, fallback)` (§5.4). The two schemes are Happy's: light is white and `#f5f5f5` neutrals with black primary actions; dark is a `#1e1e1e` canvas with `#212121` surfaces and, again, black primary actions. You never write those values — they are given here only so you can predict what a variable will look like. ### 5.1 Standard MCP Apps variables — colour Set on `` by the official host-styles hook. Resolved live from Happy's theme, so they change with the appearance. | Variable | Meaning in Happy | Light | Dark | | ------------------------------ | ---------------------------------------------------------------------- | ------------- | ------------- | | `--color-background-primary` | The surface a card or page body sits on | `#ffffff` | `#212121` | | `--color-background-secondary` | A recessed panel: table head, sidebar, code well | `#f8f8f8` | `#171717` | | `--color-background-tertiary` | A pressed/active fill, or a deeper inset | `#f0f0f2` | `#2c2c2e` | | `--color-background-inverse` | The primary-action fill (black in both schemes) | `#000000` | `#000000` | | `--color-background-ghost` | Hover wash over any surface (translucent) | 8 % black | 8 % white | | `--color-background-info` | Soft informational fill (12 % accent over surface) | pale blue | dim blue | | `--color-background-success` | Soft success fill (14 % green over surface) | pale green | dim green | | `--color-background-warning` | Soft warning fill | `#fff8f0` | 15 % orange | | `--color-background-danger` | Soft error fill | `#fff0f0` | 15 % red | | `--color-background-disabled` | A disabled control's fill | `#f0f0f2` | `#2c2c2e` | | `--color-text-primary` | Body and heading text | `#000000` | `#ffffff` | | `--color-text-secondary` | Supporting text, labels, captions | `#49454f` | `#cac4d0` | | `--color-text-tertiary` | Metadata, timestamps, counts: 70 % of secondary over the surface | `#807d84` | `#97939c` | | `--color-text-inverse` | Text on `--color-background-inverse` | `#ffffff` | `#ffffff` | | `--color-text-ghost` | Text on a ghost/hover fill | `#49454f` | `#cac4d0` | | `--color-text-info` | Informational text and the accent for text | `#007aff` | `#0a84ff` | | `--color-text-success` | Success text | `#34c759` | `#32d74b` | | `--color-text-warning` | Warning text | `#ff9500` | `#ffab00` | | `--color-text-danger` | Destructive/error text | `#f44336` | `#f48fb1` | | `--color-text-disabled` | Disabled label: 45 % of secondary over the surface | `#adabb0` | `#6d6a70` | | `--color-border-primary` | **The default hairline.** Card, row, input border | `#eaeaea` | `#292929` | | `--color-border-secondary` | The one divider stronger than the hairline: 20 % text over the surface | `#cccccc` | `#4d4d4d` | | `--color-border-tertiary` | Identical to primary. Use primary. | `#eaeaea` | `#292929` | | `--color-border-inverse` | Border on an inverse fill | `#000000` | `#000000` | | `--color-border-ghost` | `transparent`, for a border that only reserves space | `transparent` | `transparent` | | `--color-border-info` | Informational outline | `#007aff` | `#0a84ff` | | `--color-border-success` | Success outline | `#34c759` | `#32d74b` | | `--color-border-warning` | Warning outline | `#ff9500` | `#ff9f0a` | | `--color-border-danger` | Error outline | `#f44336` | `#f48fb1` | | `--color-border-disabled` | Disabled control outline | `#eaeaea` | `#292929` | | `--color-ring-primary` | **The focus ring and the interactive accent** | `#007aff` | `#0a84ff` | | `--color-ring-secondary` | A neutral ring, the secondary text colour | `#49454f` | `#cac4d0` | | `--color-ring-inverse` | Ring against an inverse fill | `#000000` | `#000000` | | `--color-ring-info` | Same as ring-primary | `#007aff` | `#0a84ff` | | `--color-ring-success` | Success ring | `#34c759` | `#32d74b` | | `--color-ring-warning` | Warning ring | `#ff9500` | `#ff9f0a` | | `--color-ring-danger` | Error ring | `#f44336` | `#f48fb1` | ### 5.2 Standard MCP Apps variables — type, shape, elevation | Variable | Value | Use | | ---------------------------------------------------------- | -------------------------- | ----------------------------------------- | | `--font-sans` | Happy's UI stack | All interface text | | `--font-mono` | Happy's mono stack | Code, IDs, hashes, log output | | `--font-weight-normal` / `-medium` / `-semibold` / `-bold` | 400 / 500 / 600 / 700 | See §6 | | `--font-text-xs-size` / `-line-height` | 11 / 16 px | Micro-labels, table column heads | | `--font-text-sm-size` / `-line-height` | 12 / 18 px | Captions, metadata, chips | | `--font-text-md-size` / `-line-height` | 14 / 20 px | **Body default** | | `--font-text-lg-size` / `-line-height` | 16 / 24 px | Lead paragraph, prominent value | | `--font-heading-xs-size` / `-line-height` | 13 / 18 px | Section label | | `--font-heading-sm-size` / `-line-height` | 15 / 20 px | Card title, row title | | `--font-heading-md-size` / `-line-height` | 17 / 22 px | Page title on a small surface | | `--font-heading-lg-size` / `-line-height` | 20 / 26 px | Page title | | `--font-heading-xl-size` / `-line-height` | 24 / 30 px | Rare; a landing or empty-state headline | | `--font-heading-2xl-size` / `-line-height` | 28 / 34 px | Do not use in a plugin app | | `--font-heading-3xl-size` / `-line-height` | 34 / 40 px | Do not use in a plugin app | | `--border-radius-xs` | 6 px | Chips, small inputs | | `--border-radius-sm` | 6 px | **Controls: buttons, inputs, menu items** | | `--border-radius-md` | 8 px | **Content blocks, wells, list rows** | | `--border-radius-lg` | 10 px | **Cards** | | `--border-radius-xl` | 14 px | Large shells and dialog-like panels | | `--border-radius-full` | 999 px | Pills, avatars, progress tracks | | `--border-width-regular` | 1 px | Every hairline | | `--shadow-hairline` | `0 0 0 1px ` | A ring instead of a border | | `--shadow-sm` | `0 1px 2px <10 % black>` | A card lifted off the surface | | `--shadow-md` | `0 4px 12px <24 % black>` | A popover or dropdown | | `--shadow-lg` | `0 12px 32px <45 % black>` | An in-app dialog | ### 5.3 Happy's extension: `--happy-*` Delivered under the namespaced `happy2/styles` host-context member and applied by the SDK. These are the roles the standard vocabulary has no key for. They are all live theme values and follow appearance changes exactly like the standard ones. | Variable | Meaning | Light | Dark | | ----------------------------- | ------------------------------------------------------------------ | ---------- | ---------- | | `--happy-canvas` | The app canvas **behind** cards; use when your page is a card list | `#f5f5f5` | `#1e1e1e` | | `--happy-header-background` | A content header strip's fill (your own, not the host's) | `#ffffff` | `#212121` | | `--happy-header-text` | Text on that strip | `#18171c` | `#ffffff` | | `--happy-selected-background` | The fill of a **selected** row or tab | `#eaeaea` | `#2c2c2e` | | `--happy-link` | Hyperlink text (Happy teal, identical in both schemes) | `#2baccc` | `#2baccc` | | `--happy-input-background` | A text field's fill | `#f5f5f5` | `#303030` | | `--happy-input-text` | A text field's value | `#000000` | `#ffffff` | | `--happy-input-placeholder` | A text field's placeholder | `#999999` | `#8e8e93` | | `--happy-code-background` | The code/diff/log surface | `#f6f8fa` | `#161b22` | | `--happy-scrim` | Backdrop behind an in-app overlay you own | 48 % black | 48 % black | | `--happy-scrollbar-thumb` | Custom scrollbar thumb | 40 % grey | 40 % grey | | `--happy-shadow-color` | The base elevation tint, for a shadow you compose yourself | 10 % black | 10 % black | No other `--happy-*` name exists — the SDK applies these twelve names and nothing else, discards any value that is not a colour, and removes a variable that a later host context stops sending. If you need a role that is not listed, build it from the ones that are, with `color-mix`: ```css /* A 12% accent wash for a selected-and-focused row. */ background: color-mix(in srgb, var(--color-ring-primary) 12%, var(--color-background-primary)); ``` ### 5.4 Fallbacks: declare them once, in one place Every host variable can be absent — when your app is opened outside Happy, in a bare browser tab during development, or by a host that has not sent styles yet. Declare a fallback for each variable you use **exactly once**, in a `:root` block that maps host names to your app's own short names. Downstream CSS then uses your names with no fallbacks at all. ```css :root { /* Standalone documents follow the OS; inside Happy the host has already set `color-scheme`, so `light-dark()` below follows the host's decision. */ color-scheme: light dark; --app-surface: var(--color-background-primary, light-dark(#ffffff, #212121)); --app-raised: var(--color-background-secondary, light-dark(#f8f8f8, #171717)); --app-canvas: var(--happy-canvas, light-dark(#f5f5f5, #1e1e1e)); --app-text: var(--color-text-primary, light-dark(#000000, #ffffff)); --app-muted: var(--color-text-secondary, light-dark(#49454f, #cac4d0)); --app-border: var(--color-border-primary, light-dark(#eaeaea, #292929)); --app-accent: var(--color-ring-primary, light-dark(#007aff, #0a84ff)); --app-radius-control: var(--border-radius-sm, 6px); --app-radius-card: var(--border-radius-lg, 10px); --app-font: var(--font-sans, system-ui, -apple-system, sans-serif); --app-mono: var(--font-mono, ui-monospace, SFMono-Regular, monospace); } ``` Two rules about this block: - **Never alias a variable to itself.** `--happy-canvas: var(--happy-canvas, #f5f5f5)` is a cycle; the property becomes invalid and everything using it falls back to its initial value. Always map a host name to a _different_ local name. - **Never repeat a fallback downstream.** `background: var(--app-surface)` — not `var(--app-surface, #fff)`. One place to change, one place to be wrong. - The component snippets in §9 write `var(--host-name, fallback)` inline so each one can be read and copied on its own. That is a documentation convenience, not the pattern. When you assemble an app, alias every host variable you use in the `:root` block once — §17's block is the complete list — and rewrite the §9 snippets to use your local names with no fallback. ### 5.5 Contrast - Body text on any surface: at least **4.5 : 1**. - Text at 18 px+ or 14 px+ bold, and any non-text indicator (borders that carry meaning, focus rings, chart strokes): at least **3 : 1**. - The host variables already satisfy this for the documented pairings — primary and secondary text on primary/secondary/tertiary backgrounds. If you invent a pairing with `color-mix`, measure it. - Never put `--color-text-tertiary` or `--color-text-disabled` on anything other than `--color-background-primary` or `--color-background-secondary`. - Never rely on colour alone. A status must also carry a word or a glyph. --- ## 6. Typography ### 6.1 Families ```css body { font-family: var(--app-font); } code, pre, .mono { font-family: var(--app-mono); } ``` `--font-sans` resolves to Happy's UI stack and `--font-mono` to its code stack. The font _files_ are not available to your origin, so the stack ends in system fonts; that is expected and correct. Do **not** load a web font, do not use `@import url(https://fonts.googleapis.com/…)`, and do not embed a font as a data URL. A plugin app that ships its own typeface looks foreign and costs the user a network request from a sandboxed origin. Set `font-synthesis: none` on `body` so a missing weight is not faked. ### 6.2 The scale Use these seven roles and nothing else. Always set `font-size` and `line-height` together, both from the same row. | Role | Size / line height | Weight | Colour | Use | | ------------- | ------------------ | ------ | ------------------------ | ------------------------------------- | | Page title | 20 / 26 px | 600 | `--color-text-primary` | One per document, at most | | Section title | 15 / 20 px | 600 | `--color-text-primary` | Card and group headings | | Section label | 13 / 18 px | 600 | `--color-text-secondary` | Small caps-free group label | | Body | 14 / 20 px | 400 | `--color-text-primary` | **The default for everything** | | Row title | 14 / 20 px | 500 | `--color-text-primary` | The first line of a list row | | Body strong | 14 / 20 px | 600 | `--color-text-primary` | A value being emphasised in prose | | Caption | 12 / 18 px | 400 | `--color-text-secondary` | Secondary line under a title | | Micro | 11 / 16 px | 500 | `--color-text-tertiary` | Table column heads, chip text, counts | - **11 px is the absolute minimum.** Never render text smaller. - Weight vocabulary is 400, 500, 600 only. Do not use 700 in a plugin app; do not use 300 or lighter. - Do not use `text-transform: uppercase` on anything longer than a three-word label, and never with letter-spacing above `0.04em`. - `letter-spacing: -0.01em` is permitted on the page title and section title. Nowhere else. - Never justify text. Never centre a paragraph. Centre only a single-line label inside a control or an empty state. ### 6.3 Long text ```css .truncate { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } .wrap-anywhere { overflow-wrap: anywhere; } /* URLs, IDs, file paths */ .clamp-2 { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow: hidden; } ``` Every single-line title in a row or card must truncate, and its flex parent must carry `min-width: 0` (§4.3). Text that can contain an unbroken token — a URL, a hash, a path — must use `overflow-wrap: anywhere` or truncate; it must never widen its container. ### 6.4 Numbers Right-align numeric table columns and use tabular figures so digits line up: ```css .num { font-variant-numeric: tabular-nums; text-align: right; } ``` Format dates, times, and numbers with `Intl`, passing `hostContext.locale` and `hostContext.timeZone`. Never hard-code `MM/DD/YYYY` or a currency symbol. --- ## 7. Surfaces, borders, radii, shadows ### 7.1 Choosing a background | You are painting | Background | | ------------------------------------------------- | ------------------------------ | | The document, when the content **is** the surface | `--color-background-primary` | | The document, when it holds a list of cards | `--happy-canvas` | | A card on the canvas | `--color-background-primary` | | A recessed panel: table header, sidebar, well | `--color-background-secondary` | | A code, log, or diff block | `--happy-code-background` | | A hovered row | `--color-background-ghost` | | A selected row or active tab | `--happy-selected-background` | | A pressed control | `--color-background-tertiary` | | A text input | `--happy-input-background` | Default to the first row. A plugin app on a workspace page sits flush against Happy's own `--surface`; painting `--color-background-primary` makes the seam invisible, which is correct. Reach for `--happy-canvas` only when you genuinely have separated cards. ### 7.2 Borders One hairline, everywhere: `1px solid var(--color-border-primary)`. - Prefer a border over a shadow to separate things. Happy is a flat, quiet system. - A card gets a border **or** `--shadow-sm`, never both. - Between list rows use `border-bottom` on each row except the last, or better, a flex `gap` with no border at all. - To reserve space for a border that appears on hover or selection, use `--color-border-ghost` (transparent) rather than a margin that shifts on hover. ### 7.3 Radii | Element | Radius | | -------------------------------------------- | ------------------------- | | Button, input, select, menu item, small chip | `--border-radius-sm` (6) | | List row, content block, code well | `--border-radius-md` (8) | | Card | `--border-radius-lg` (10) | | A large panel or in-app dialog | `--border-radius-xl` (14) | | Pill, avatar, progress track | `--border-radius-full` | **Nested corners must be true parallel curves.** When a child's edge sits in a rounded corner of its parent: ``` inner radius = max(0, outer radius − inset) ``` `inset` is the real distance between the two border-box edges — the parent's border plus its padding. A 10 px card with a 1 px border and 12 px padding gives a child sitting in the corner a radius of `max(0, 10 − 13) = 0`. A header strip flush inside that card (1 px inset, no padding) gets `10 − 1 = 9 px`. If the horizontal and vertical insets differ, do not compromise — change the layout so they match. ### 7.4 Shadows Use a shadow only for something that genuinely floats above the page: | Thing | Shadow | | ---------------------------- | ---------------------- | | A card resting on the canvas | none, or `--shadow-sm` | | A dropdown, popover, tooltip | `--shadow-md` | | An in-app dialog you own | `--shadow-lg` | Never put a shadow on a button, input, row, chip, badge, or table. Never write a shadow with your own colour; if you must compose one, tint it with `--happy-shadow-color`. --- ## 8. Density and rhythm Happy is an information-dense desktop tool, not a marketing page. | Element | Height | | --------------------------------------------------- | --------- | | Small button / chip / compact control | **28 px** | | Default button, input, select | **36 px** | | Large button (a page's main action) | **44 px** | | Compact list row (one line) | **32 px** | | Standard list row (title + caption) | **44 px** | | List row with a ≥ 20 px glyph, avatar, or thumbnail | **56 px** | | Table header row | **32 px** | | Table body row | **36 px** | | Your own content toolbar | **48 px** | | Your own content header strip | **56 px** | Additional rules: - A vertical list of rows uses `gap: 0` with hairline separators, or `gap: 8px` with bordered rows. Not both. - Never exceed 24 px of vertical space between a heading and its content. - Never centre a whole page's content vertically, except an empty state (§11.1). - Never use a hero band, a full-bleed illustration, or a decorative gradient. - Icons in rows and buttons are **16 px**; in a page title, **20 px**; in an empty state, **32 px**. Nothing else. --- ## 9. Components Build each of these from plain HTML plus the variables. Do not add a component library, a CSS framework, or a design-token package. ### 9.1 Buttons Three variants, plus one destructive modifier of Secondary: | Variant | Fill | Text | Border | When | | --------- | ---------------------------- | ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------ | | Primary | `--color-background-inverse` | `--color-text-inverse` | none | One per view, the main action | | Secondary | `--color-background-primary` | `--color-text-primary` | `1px solid --color-border-primary` | Everything else | | Ghost | `transparent` | `--color-text-secondary` | none | Toolbar and row-level actions | | Danger | `transparent` | `--color-text-danger` | `1px solid --color-border-danger` | Only the confirming button of a destructive action, and never more than one per view | A destructive action is never the Primary variant — a black filled button is the safe default action, and the delete must not be the thing the eye lands on first. ```css .btn { display: inline-flex; align-items: center; justify-content: center; gap: 6px; height: 36px; padding: 0 14px; flex: none; font: inherit; font-size: 14px; line-height: 20px; font-weight: 500; border: 1px solid transparent; border-radius: var(--app-radius-control); background: transparent; color: var(--app-text); cursor: pointer; user-select: none; transition: background-color 120ms ease, border-color 120ms ease; } .btn:disabled { cursor: default; background: var(--color-background-disabled); color: var(--color-text-disabled); border-color: transparent; } .btn:focus-visible { outline: 2px solid var(--app-accent); outline-offset: 2px; } .btn-primary { background: var(--color-background-inverse); color: var(--color-text-inverse); } .btn-secondary { background: var(--app-surface); border-color: var(--app-border); } .btn-secondary:hover:not(:disabled) { background: var(--color-background-ghost); } .btn-ghost { color: var(--app-muted); padding: 0 10px; } .btn-ghost:hover:not(:disabled) { background: var(--color-background-ghost); color: var(--app-text); } .btn-danger { background: transparent; color: var(--color-text-danger); border-color: var(--color-border-danger); } ``` - Small button: `height: 28px; padding: 0 10px; font-size: 12px;`. - Large button: `height: 44px; padding: 0 20px; font-size: 15px;`. - An icon-only button is square: 28×28 or 36×36, and **must** have `aria-label`. - Button labels are sentence case, verb first: "Add item", not "ADD ITEM" or "Add Item". - Never a gradient fill, never a coloured shadow, never a full-width button unless the container is narrower than 320 px. ### 9.2 Inputs and forms ```css .field { display: flex; flex-direction: column; gap: 4px; } .field-label { font-size: 12px; line-height: 18px; font-weight: 500; color: var(--app-muted); } .input { height: 36px; padding: 0 10px; width: 100%; font: inherit; font-size: 14px; line-height: 20px; color: var(--happy-input-text, var(--app-text)); background: var(--happy-input-background, var(--app-raised)); border: 1px solid var(--app-border); border-radius: var(--app-radius-control); } .input::placeholder { color: var(--happy-input-placeholder, var(--app-muted)); } /* A field keeps its border when focused and draws the ring just inside its own edge, so there is no 3px halo gap between the two. Buttons, which have no filled edge to preserve, use the outward 2px offset instead. */ .input:focus-visible { outline: 2px solid var(--app-accent); outline-offset: -1px; } .input[aria-invalid="true"] { border-color: var(--color-border-danger); } textarea.input { height: auto; min-height: 72px; padding: 8px 10px; resize: vertical; } ``` - Labels go **above** the field, 6 px away. Never use a placeholder as the label. - **Exception, and only this one:** a search or filter field inside a 48 px toolbar has no room for a label above it, so its name is given by `aria-label` and its placeholder shows the same words. This is the single place a placeholder-only field is permitted; every field in a form body has a visible label. - A form is a flex column with `gap: 16px` between fields. - Error text sits 4 px under the field, 12/18 px, `--color-text-danger`, and is referenced by `aria-describedby`. - Actions go in a row at the end: `justify-content: flex-end; gap: 8px`, primary last (rightmost). - Never use a native ``, `` styling hack, or a custom checkbox that loses keyboard behaviour. Style the native control with `accent-color: var(--app-accent)`. ### 9.3 Lists The standard row: a leading glyph or nothing, a shrinking main column, a fixed trailing column. ```css .list { display: flex; flex-direction: column; } .row { display: flex; align-items: center; gap: 12px; min-height: 44px; padding: 8px 12px; border-bottom: 1px solid var(--app-border); background: var(--app-surface); } .list > .row:last-child { border-bottom: none; } .row:hover { background: var(--color-background-ghost); } .row[aria-selected="true"] { background: var(--happy-selected-background, var(--color-background-tertiary)); } .row-main { display: flex; flex-direction: column; /* No gap: the 20 px and 16 px line boxes already separate the two lines, and a two-line row measures 52 px. */ flex: 1 1 auto; min-width: 0; } .row-title { font-size: 14px; line-height: 20px; font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } .row-meta { font-size: 12px; line-height: 18px; color: var(--app-muted); } .row-aside { display: flex; align-items: center; gap: 8px; flex: none; } ``` - A whole row that is clickable must be a `