Design Language

Asyar Design Language — Measure

This file answers one question: given what you are building, what do you use?

Every table below is a lookup. Find your row, use what it says. If your case is not in a table, the answer is at the bottom under When nothing fits — it is never "invent something".

The reasoning behind all of this lives in docs/reference/design-system/design-language.md. Read that once. Work from this.

pnpm check:design enforces the mechanical half and runs in CI. If it passes, you have not broken the system; it does not mean your UI is good. The judgement calls are the tables.

The thesis, in one paragraph

Every value in Asyar is measured, not chosen.

Asyar is 750 × 480, of which 384px is content, and it is on screen for two to six seconds. Nothing in it has room to be arbitrary. A value is either derived from a constraint — a window dimension, a contrast ratio, a scale step, a count of rows that must fit — or it is a guess, and this is a system that does not ship guesses. Four principles, in priority order, and every table below is one of them made operational:

1. Derived, Not Chosen — every value traces to a measurement or a scale step. "It looked right" is not a derivation.
2. Subtract First — borders, fills, shadows and animations start at zero and have to be argued in. Remove it and look; if nothing is lost, it was decoration.
3. One Candidate — exactly one element is the thing ⏎ will act on, and nothing else may compete for the eye.
4. Every Affordance Names Its Key — if it can be done, its key is visible.

When two rules below seem to conflict, the principle wins, and the lower-numbered principle wins over the higher.

Restraint is the position here, not a fallback applied when nothing better comes to mind. If you are about to make something look more designed, that is the moment Principle II applies, not an exception to it.

The 30-second version

Never write a var(--token, fallback). Every token is always defined, so a fallback can only ever hide a typo — that is exactly how a whole subsystem in this app once ended up running on invented token names nobody noticed.

1. Fonts — which font, where

Two faces. There is no third.

• --font-ui is applied globally to *. You only name it explicitly inside a component that also sets font-family for another reason.
• Satoshi renders on every platform, macOS included. There is deliberately no per-platform override. Asyar used to fall back to San Francisco on macOS; that gave the app no typographic identity on its primary platform. Do not reintroduce it.
• Reach for mono when characters need to line up or be read individually. A duration, a count, or a version number in prose stays in --font-ui; the same value in a table column goes mono. .text-mono already carries tabular-nums.

Tracking

Never write a raw letter-spacing: -0.02em. The .text-* classes already carry the right value, which is the main reason to use them.

2. Colour

The one rule people get wrong

A colour that fills cannot also be the colour that speaks.

There are two accent ramps, and picking the wrong one is a contrast bug that looks fine to you and is unreadable to someone else.

The test is mechanical: does this surface have --text-on-accent (or --control-knob) on top of it? Yes → -fill. No → the voice.

/* A filled button, a checked checkbox, a user chat bubble, a coloured tile */
background: var(--accent-primary-fill);
color: var(--text-on-accent);

/* A status dot, a meter bar, a progress fill, a left accent seam — no text */
background: var(--accent-primary);

/* An accent-coloured label, a link, an icon */
color: var(--accent-primary);

check:design fails the build on a voice token used as a background in the same rule as --text-on-accent (voice-as-fill). It cannot catch the inverse, so: never use a -fill token as a text colour — it is too dark to read on an Asyar surface.

Surfaces, from back to front

Never set an opaque background on the root container — platform overrides (macOS transparency, Windows Acrylic, opaque Linux) handle that automatically. Elevation is a scalar, not a stack: a popup opened from a card is still one popup, not a card plus a popup. If you want a fourth level, what you actually want is --scrim to push the thing beneath it back.

Text

Three tiers. If you want a fourth, you want a different layout.

Colour is never the only channel

Every state must be legible with all hue removed. Simulated for deuteranopia (~6% of men) the three state colours collapse toward the same olive — success against danger sits at a luminance ratio of 1.23. No contrast tuning fixes that, because the problem is hue discrimination.

So a state colour is an accelerant on top of a shape, an icon, or a word, never the sole carrier. A status indicator needs a label or an adjacent word; a severity needs an icon with a different silhouette. Badge is fine — it carries text. A bare coloured dot is not.

Review test: screenshot it, desaturate it, and see if you can still read the state.

Semantic state

For a tinted background in a state colour, mix it rather than inventing a second token — this is the house formula, and it uses the voice ramp for both the tint and the text so they always agree:

background: color-mix(in srgb, var(--accent-danger) 12%, transparent);
color: var(--accent-danger);

Lines and edges

Prefer alignment to a border. Two things sharing a left edge already read as one column; a border on top of that is a line the layout has already drawn (Principle II). Use a real border when the job is "this is an interactive control with an outline".

Code colour

Only for rendered code and structured data. The Prism markdown theme and JsonTree both read from these, so a snippet looks the same everywhere.

--syntax-comment · --syntax-keyword · --syntax-string · --syntax-number · --syntax-function

Everything else

--scrim / --scrim-opaque for modal backdrops · --control-knob for the Toggle knob · --shadow-color inside shadows only · --kbd-rim for key chips.

3. Typography — which class, where

Use the class. Only drop to raw var(--font-size-*) inside a component that needs a size the classes do not cover.

Weight rules: 500 (font-medium) is the heaviest weight for body and label text. 600 (font-semibold) is for headings and the command line. 700 does not appear in the product — at display sizes with display tracking, 600 is already maximally emphatic and 700 reads as shouting. Never font-bold.

The command line is the largest text in the app and nothing may match it. If you are adding something at --font-size-2xl or above outside SearchHeader, you are competing with the query. Don't.

4. Elevation

Every drop shadow casts straight down. Every shadow is 0 Ypx.

Height comes from blur radius and negative spread, never from sliding the shadow sideways. This is consistency, not physics: shadows that disagree about their direction read as a rendering mistake, and the scale is easier to reason about when height is the only variable. It binds drop shadows — an inset box-shadow used to draw an edge is a drawing primitive, not a cast.

--rim-light / --rim-shade are ingredients inside --shadow-launcher-popup and the filled-button gradients. There are no .rim / .rim-all utility classes — they existed, had zero call sites, and were removed.

Radius — --radius-xs (4) · sm (6) · md (8) · lg (10) · xl (12) · popup (20) · full. Small controls take sm, cards take md, modals take xl, floating launcher surfaces take popup.

Stacking — never a bare number:

Modal uses native <dialog>, which renders in the browser's top layer and is above all of these regardless of z-index. You never need to out-number a modal.

5. Space and size — which measurement, where

Space is the gap between objects. Size is the object. Two scales, and reaching into the wrong one is how --space-* ended up with values like 11px and 23px — those were an icon tile and a spinner, not rhythm.

Space — a 2px grid

var(--space-N), from --space-0-5 (2px) to --space-11 (48px). Whole steps only:

2 · 4 · 6 · 8 · 10 · 12 · 16 · 20 · 24 · 32 · 40 · 48

Four tokens are deprecated. Do not add new uses of them — they are the only off-grid values in the system, and they exist because sizes had no scale:

Size — a 4px grid

The names are t-shirt, not role, so pick by value and use the canonical column as a guide. --size-lg on a spinner is fine; it is 24px, not "a tile".

The nine-row fit — do not break this by accident

The launcher's content area is 384px, the list insets it by --space-3 top and bottom, and 368px is exactly nine rows: 9 × 40 + 8 × 1.

• The row height is var(--shell-row-h) (40px). Changing it changes how much of Asyar is visible at once.
• Row separation is a raw 1px, not --space-0-5. Two pixels overflows 368 and costs a whole row. This is the one place a raw pixel beats a token.
• Never hardcode 56px, 40px or 384px. Use --shell-header-h, --shell-footer-h, --shell-row-h, or calc() off them.

Density — how fast is this read?

The tokens are identical across all five surfaces; the rhythm is not.

If you are unsure how much space to use, the question is not "what looks right" but "how fast is this read?"

Pointer targets: the launcher's 40px row is below the 44px guideline, which is an accepted trade for the ninth result on a keyboard-first surface. Nothing that is not keyboard-first gets that excuse — Settings and onboarding use the roomier density above.

6. Motion

Four durations, four curves. Every animation is one of each. There is no fifth of either — adding one is a change to the design language, not to your component.

Rules that are not negotiable:

• Arrival and departure use different curves. One curve for both is the fastest way to make an interface feel cheap.
• --ease-settle may only be applied to scale. Overshoot on position reads as sloppy; on opacity it is incoherent.
• Before adding any animation, ask: if this were removed, would the user be confused about what happened? If no, don't add it.
• Reduced motion is handled globally in style.css. You do not need a prefers-reduced-motion block unless your component animates via JS.

Two animations are specifically not wanted. Both are the obvious thing to reach for, and both fail the test above:

• The selection travelling between rows. Selection snaps. The user pressed ↓; nobody is confused about where the highlight went.
• The launcher animating on summon or dismiss. The window appears. An arrival animation delays the first usable moment on the one surface whose whole promise is being already there.

--transition-fast/normal/smooth/slow still exist and still work; they are shorthands over the tokens above. New code should pair a duration with a curve directly.

7. Voice — how it reads

Asyar is mostly words, and it writes the way an instrument reports: flatly, in the user's terms, without personality.

• A result is named, never described. Title = what it is called. Subtitle = where it lives or what it does. Neither is a sentence.
• Truncate at the end, except file paths, where the middle goes.
• Fixed terms, not synonyms: a command is declared by an extension; an action is what you can do to a selected result; a result is a row; an extension ships them.

8. Components — which component, where

Read src/components/index.ts before deciding anything does not exist. It exports every component in the app except ConfirmDialog and the extension inspector's internals, both documented at the bottom of that file. The checker fails the build if a component is missing from it, so the barrel is trustworthy — treat it as the catalogue.

By what you are building

If two components look like they both fit, pick the more specific one.

9. Layout

The launcher shell

┌───────────────────────────────────┐
│  SearchHeader   .search-header    │  fixed, --shell-header-h, --z-header
├───────────────────────────────────┤
│                                   │
│  .shell-content custom-scrollbar  │  fixed between the two bars, scrolls
│                                   │
├───────────────────────────────────┤
│  BottomActionBar                  │  fixed, --shell-footer-h, --z-footer
└───────────────────────────────────┘

• The header and footer are already mounted by routes/+page.svelte. A view renders into the content area only.
• Never add a second fixed header or footer inside a view.
• Never hardcode 56px or 40px. Use --shell-header-h / --shell-footer-h, or calc() off them, so the five places that depend on those heights stay in agreement.
• For a master/detail view inside the content area, use SplitListDetail (or SplitView for a plain resizable split) — not a hand-rolled flex layout.

Scrolling

Every scrolling container gets .custom-scrollbar. No exceptions — the checker enforces it, because the platform default scrollbar against Asyar's surfaces is immediately obvious.

The five surfaces

The tokens and components are identical across all three. What differs is density and how much chrome is acceptable.

10. Interaction and accessibility

Every interactive element covers every state:

Hover must never be mistakable for selection (Principle III). --bg-hover is neutral; --bg-selected carries chroma. That difference is load-bearing — do not "improve" hover by tinting it.

The selected row is a flat band, everywhere, and it is not yours to restyle. background-color: var(--bg-selected) plus box-shadow: inset 0 0 2px 0.5px var(--kbd-rim), identical in .list-row.selected and .selected-result. It never takes a border, a gradient, or an accent seam — this is the most-seen element in the app and the most tempting one to make expressive, and it is deliberately plain.

Focus is already solved globally. *:focus-visible applies var(--shadow-focus) app-wide. Two things break it, both worth knowing:

1. A more specific rule that also sets box-shadow (e.g. .item.active) silently wins. If your component sets box-shadow in any state — and the Rim is a box-shadow — restate the ring in a :focus-visible rule after it.
2. :focus-within does not match when the real input is a sibling rather than a descendant. Drive the ring off the input with :global(.peer:focus-visible) ~ .track.

Use :focus-visible, not :focus, for buttons and rows — :focus also fires on mouse click. Text fields are the exception: they legitimately use :focus, and the global rule already stands aside for input/textarea/select.

Other rules:

• Anything clickable is a <button> or <a>. A <div onclick> needs a role, a tabindex, and a key handler — and is almost always the wrong answer.
• svelte-ignore uses underscores in Svelte 5 (a11y_no_static_element_interactions). The Svelte 4 hyphenated names silently suppress nothing.
• Decorative icons get aria-hidden="true"; meaningful ones get a label.
• Never hijack text editing shortcuts: In views with a search bar or text input, never bind native text editing shortcuts (⌘⌫ / Cmd+Backspace, ⌥⌫, ⌘A, ⌘C, ⌘V, ⌘X, ⌘Z) to list actions or item deletion.
• Destructive actions belong in ⌘K: Operations that delete, trash, or uninstall items belong in the ⌘K Action Panel (styled with destructive: true), not bound directly to ⌘⌫.

11. Third-party extensions (Tier 2, iframe sandbox)

Extensions run in two sandboxed iframes — a hidden worker and an on-demand view. Design rules apply to the view.

• Every CSS token above is injected automatically, along with the real Satoshi and JetBrains Mono files. var(--bg-primary), var(--font-ui) etc. just work. The same "never hardcode a colour" rule applies, and so does the voice/fill split.
• Icons come from the <asyar-icon> web component: call registerIconElement() once in the view entry, then <asyar-icon name="calculator" size="20">. Icons inherit currentColor.
• There is no bare asyar-sdk entry point — import from asyar-sdk/view, asyar-sdk/worker, or asyar-sdk/contracts. The icon helpers are DOM-dependent and ship on /view only.
• For IDE autocomplete outside the running app, import asyar-sdk/tokens.css.

A theme extension may override colour, shadow, radius, font family and duration tokens. It may not override --space-*, --font-size-*, --tracking-* or --ease-* — those are design-system-owned, and applyTheme filters them out. A theme recolours the app; it never resizes or re-times it.

12. When nothing fits

In order. Do not skip a step.

1. Re-read the barrel. src/components/index.ts exports ~100 components. The thing you want usually exists under a name you did not guess.
2. Check whether an existing component takes a prop for it. EmptyState grew compact and bordered this way; Badge already has five variants. Extending beats duplicating.
3. Build a new reusable component in src/components/{category}/, style it with tokens, export it from the barrel, and use it. If it is worth building, it is worth making reusable.
4. A token genuinely missing? Add it to :root in resources/styles/style.css with a comment saying what it is for, and give it a light and dark value if it is not constant. If it is a colour that belongs to a palette, add it to both copies of that palette — themePalettes.test.ts will fail if you add it to only one. Then add it to THEME_VAR_NAMES in lib/themeVariables.ts so extension iframes get it.

The escape hatch

Some values legitimately are not on a scale: a glyph sized to a fixed tile, a metric pinned to a native platform dimension, a standalone webview with no theme injection. For those, and only those:

/* design-ok: glyph scaled to the fixed 128px box, not UI text */
font-size: 64px;

A reason is required — a bare design-ok does not suppress. For a whole file (there is currently exactly one, the HUD window), use design-ok-file: <reason>.

If you find yourself writing the third design-ok for the same kind of value, that is the system telling you a token is missing. Add the token instead.

13. Before you call it done

Run pnpm check:design. It fails on:

Then check the things a script cannot:

• Did you import components, or write markup? Zero imports from ../components in a new view is a red flag.
• Does it look right in both light and dark? Toggle and look.
• Desaturate the screenshot. Can you still read every state? Colour is never the only channel.
• Can you name where every number came from? Pick the three least obvious values in your

…(truncated)