Design Conventions
The design-side sibling of API Conventions. Where API Conventions states what the code conventions are, this page states what good design looks like in Astryx — and why the defaults are what they are — so designers and engineers can build in compliance and reviewers can evaluate against a shared bar.
This page is content, not process: it states the conventions and marks how each is verified. It gathers what already lives in the token system, component source, and review rubrics — it doesn't invent. The 🟢 checks are run by the Night Watch Component Auditor; the 🟡/🔴 calls are made in Component Audit Rubric §5b. New standards enter via the Component Specification Protocol; decisions made in the Component Hardening Protocol's human design review roll back up into this page so judgments compound.
| Marker | Meaning | Verified by |
|---|---|---|
| 🟢 | Objective — clear pass/fail, no taste | Night Watch Component Auditor |
| 🟡 | Assisted — tool flags, human confirms | Auditor → Component Audit Rubric §5b |
| 🔴 | Judgment — proportion, composition, fit | Component Audit Rubric §5b |
- Understand the intention behind a decision. Tokens encode the system's design thinking, so they're a reliable guide — follow the token when in doubt. But they're a guide, not absolute law: a token used in the wrong role is still wrong. Know why a value exists so you can tell the difference.
- Themes control look, core controls structure. Every visual value references a token; the theme decides what it resolves to.
- Minimize visuals per state. Every distinct visual for the same state is overhead a user must learn. Reuse an existing representation before inventing a new one.
- Consistency is scoped to the family first, then the system.
- Design for every state — rest, hover, focus, active, disabled, loading, and the relevant status/selected states.
- Guidance over enforcement. Capability, not runtime design guardrails.
Each foundation pairs a design principle with the token category that expresses it. The defaults aren't arbitrary — they encode these intentions, which are also the rubric for judging whether a custom theme is well-designed. For each: why it matters, then the principle, the smells that signal drift, and what it looks like got right.
Why it matters. Before a word is read, proximity has already told the user what belongs together (Gestalt). Get relationships right and a dense screen still feels organized; get them wrong and no color or border will rescue it. Spacing does structural work — so it must be varied and intentional, not one value everywhere.
| Principle |
Space is the primary signal for how elements relate. Closely-related things sit tight; separate concerns sit apart; and the gap grows with each level of grouping — label→input < fields in a group < groups in a section < section→section. The 4px grid ( |
| Smells |
|
| Got it right |
you can squint at the layout and still see the groupings; gaps step up monotonically with grouping order; every value traces to a spacing token. Tight where related, generous where separate — never uniform. |
Why it matters. Rhythm is what makes a stack of controls feel engineered rather than assembled. Because size and density are set by different props, they drift apart easily. Visual size and touch size are also different jobs: a control can look compact but must still offer a 44px hit area.
| Principle |
Elements come in two flavors: fixed-height ones use size props (control heights sm 28 / md 32 / lg 36px); variable-height ones (inputs, list rows, menu items) use density props (internal padding). Both must be tuned together so a stack of mixed elements shares one vertical rhythm — a |
| Smells |
|
| Got it right |
fixed- and variable-height elements in a row share a baseline; size and density were adjusted together. (Open: density padding may deserve a themeable token so rhythm can be tuned system-wide.) |
Why it matters. Non-concentric corners are one of the most recognizable tells of unconsidered UI — the inner curve visibly fights the outer. Astryx derives child radii via calc() so concentricity falls out; a theme that sets radius freely breaks it.
| Principle |
Radius is chosen by an element's role ( |
| Smells |
|
| Got it right |
every nested pair satisfies |
Why it matters. Elevation is a promise about what sits above what. Get the order wrong and content renders underneath where it should cover (a dropdown clipped by a sticky header, a toast behind a modal). Shadow strength carries meaning too — an over-strong shadow reads as a higher layer than intended.
| Principle |
Outer shadows ascend |
| Smells |
|
| Got it right |
each surface's shadow tier matches its place in the stacking order; nothing renders underneath a higher layer; popovers escape their containers; shadows are subtle enough that you feel depth without noticing the blur. |
Why it matters. Hierarchy is what lets the eye triage a screen, and it comes from real contrast in size and weight — not many sizes that are almost the same. Line-heights snap to the 4px grid so text shares the spacing rhythm.
| Principle |
Type is a geometric scale (base 14, ratio 1.2) exposed as roles — headings 1–6, body/large/label/code/supporting, display 1–3 — with four meaningful weights (400 body · 500 label+dataviz · 600 titles+headings · 700 strong). Base+ratio is a personality dial: lower/tighter reads dense (dashboards), higher/larger reads editorial (reading surfaces). |
| Smells |
|
| Got it right |
heading, body, and supporting text are unmistakably different at a glance; sizes come from role tokens; leading gives multi-line text room; line length stays ~65–75ch; and the scale's density matches the surface's intent. |
Why it matters. Contrast is legibility, and emphasis is hierarchy: color is how the eye finds the primary action and reads status. The wrong neutral (a resting fill where an overlay belongs) reads as the wrong thing even when the shade looks similar. Overlays must be alpha, not opaque, so a tint composites over any surface.
| Principle |
A color is only meaningful relative to what it sits on, so foreground and background are decided together. Every token ships a |
| Smells |
|
| Got it right |
every fg/bg pair passes AA in both modes; the neutral matches the element's role; interaction tints are alpha overlays; status pairs color with an icon; and one clear primary action carries the emphasis. |
Why it matters. Motion should clarify a change, not perform. Natural movement decelerates smoothly and animates cheap properties; anything else reads as either janky or gimmicky, and unbounded motion is an accessibility problem.
| Principle |
Motion matches the visual weight of the change: micro-interactions use the fast band (~175ms), entrances/exits medium (~410ms), continuous/large motions slow, all eased with |
| Smells |
|
| Got it right |
duration matches the change's weight; easing decelerates smoothly; only transform/opacity animate; motion carries meaning; and reduced-motion is honored. |
Every component expresses state. Astryx organizes state visuals by who drives the change — the user, the system, or an agent. Each state has a small set of approved visual representations. Reuse one before inventing. Picking the right representation for an archetype is 🔴 human judgment.
States a person drives directly by pointing, clicking, typing, or tabbing.
| State | Visuals | Representation |
|---|---|---|
|
Rest neutral default |
 |
base tokens, no interaction |
Hovered (Overlay style):hover, guarded
|
 |
--color-overlay-hover tint layered over the base |
Hovered (Ring style):hover on a field
|
 |
--color-border-emphasized border + --shadow-inset-hover ring |
Pressed:active
|
 |
scale(0.98) + --color-overlay-pressed
|
|
Dragging (Ghost preview) drag handle · ordered lists / rows |
 |
source stays in place and both source + duplicate preview use 50% opacity; the preview follows the pointer freely on both axes without a raised-card shadow |
|
Drop target (Insertion line) active drag · ordered lists / rows |
 |
a 2px --color-accent line marks the candidate position; surrounding items stay stationary until release, then settle with tokenized motion |
Focused (Outline style):focus-visible
|
 |
2px --color-accent outline at 3px offset |
Focused (Ring style):focus-visible on a field
|
 |
--color-accent border + inset ring |
|
Selected (Filled style) toggles · aria-checked, value
|
  
|
--color-accent fills the control to signal on
|
|
Selected (Surface style) segmented · aria-checked
|
 |
active segment lifts on --color-background-surface + --shadow-low
|
|
Selected (Edge style) tabs / entries / steps · aria-selected/-current
|
  
|
--color-accent edge bar / underline marks the current item |
|
Selected (Border style) cards · isSelected
|
 |
--color-accent border + inset ring around the chosen card |
|
Selected (Depressed style) list & nav rows, toggle buttons · aria-current/-selected/-pressed
|
  
|
--color-neutral / --color-accent-muted fills the current item |
Reorder contract. Start from a dedicated handle. Pointer previews may move freely on both axes while placement is calculated on the collection's ordering axis; keyboard reordering uses the same insertion cue. Commit once on release / drop, then settle items with the fast motion band and
--ease-standard; update immediately under reduced motion. While the user is actively dragging, blanket 50% opacity on the stationary source and duplicate preview is an allowed temporary contrast exception; restore normal contrast immediately on drop or cancel, and never use this treatment for a resting or persistent state. Don't add a raised-card shadow. Keep focus on the handle and announce position changes. This treatment is for reordering ordered collections; canvas placement and file-drop targets need their own representation.
Selection is one intention with many treatments and many code states — split above by the visual style. Pick the style that fits your component and stay consistent within its family.
States the system drives: disabling, waiting, validating, and reporting outcome. Status always pairs a semantic token with an icon — never color alone. Status is shown by prominence tier — the same meaning scaled from quiet in-flow surfaces up to bold transient overlays.
| State | Visuals | Representation |
|---|---|---|
DisabledisDisabled → native disabled; disabledMessage
|
 
|
--color-text-disabled, muted and non-interactive; a message explains why |
Loading (Skeleton style)isLoading → aria-busy
|
 |
a skeleton placeholder stands in for content not yet arrived; dimensions stay stable |
Processing (Spinner style)isLoading → aria-busy
|
 
|
in-place content hidden (color: transparent) with a spinner over it, or a spinner in the field's end slot; dimensions stay stable |
|
Status (Muted style) low prominence, persistent · status.type
|
 
|
muted --color-{status}-muted background + colored text/border + icon — banners and in-flow surfaces (destructive actions read as error) |
|
Status (Inverted style) high prominence · status.type
|
 
|
solid --color-{status} fill with --color-on-{status} text — compact chips and high-severity toasts |
|
Temporal (Overlay style) brief, high prominence, transient |
 
|
--color-background-inverted overlay that appears briefly and dismisses — toasts and tooltips |
Prominence tiers, one meaning. A status renders quietly as a muted surface (banners, inputs, destructive actions — persistent, in-flow), boldly as an inverted / solid fill (badges, high-severity toasts), and briefly as a temporal overlay (default toasts, tooltips). The token + icon keep the meaning constant across tiers.
Mostly undefined. The intentions are named but the visuals aren't settled — the highest-value open design questions for an AI-native system. Propose treatments via the spec loop; keep new visuals close to the User / System language.
| State | Visuals | Representation |
|---|---|---|
|
Thinking agent reasoning / processing |
||
|
Reasoning chain-of-thought, thinking out loud |
||
|
Streaming receiving incremental text |
||
|
Tool Executing backend tool running |
||
|
Awaiting Input waiting for user response |
||
|
Syncing / Synchronized state synchronization |
||
|
Inspecting agent browsing / inspecting UI |
||
|
Rendering UI being generated & mounted |
The conventions above split by how they're verified. This page owns the what and why; the mechanics live in the linked docs.
| Kind | Reader | Home |
|---|---|---|
| 🟢 Objective — tokens-only, 4px grid, concentric radius, AA contrast, alpha overlays, type hierarchy/leading/size, motion safety, elevation↔z-index | Agent / linter | Component Audit Rubric §5a — check definitions, severity, and scoring; run nightly by the Night Watch Component Auditor |
| 🟡 Assisted — monotonous spacing, size/density rhythm, color-alone status | Agent flags, human confirms | Component Audit Rubric §5b — screenshot-gated; flagged by the Auditor as Needs Review and resolved in Component Audit Rubric §5b |
| 🔴 Human — right representation for the archetype, proportion, density, composition, AI tells | Human | Component Audit Rubric §5b, judged from screenshots; Component Audit Rubric §5b |
One source of truth. These conventions are the source; the rubric's checks derive from them. When a convention changes here, update the Component Audit Rubric check that cites it. When a pass finds a pattern not covered here, add it here first, then give the rubric a check for it.
Templates — page templates (full-page scaffolds) and blocks (drop-in patterns) — carry design responsibility beyond any single component. These consolidate the existing Contributing Templates rubric, the design-judge axes, and Component Audit Rubric §5b — a checklist, not a new invention.
Component & token purity (🟢)
- Compose from Astryx, not raw HTML (
VStack/Grid/Cardover<div>,Text/Heading,Button,Link,Table,FormLayout). Necessary exceptions:<img>with a CDN src,<form>for native submit. - Icons via
Icon/ icon props — never raw<svg>. - Style through props, not custom CSS. Tokens, never raw values.
Layout & structure (🟢)
- Page root is
LayoutorCenter, content-only — templates don't shipAppShell(the host owns chrome); the exception is theShell -category. - App chrome vs in-page nav: omit global nav; section nav →
LayoutPanelstart slot; page headers →LayoutHeader. - Responsive grids use
Grid+minChildWidth, not fixed columns. Blocks are single-pattern, ~20–100 lines, with a correctaspectRatio.
Content & imagery (🟡)
- Realistic mock data — never "Lorem ipsum" / "Item 1". Images from the astryx CDN only. Accurate
.doc.mjs(required fields, completecomponentsUsed).
Visual quality (the design-judge axes) (🔴) — beyond purity, a template is judged as a design on the same 5 axes the vision judge uses, the page-level analog of the Component Hardening Protocol's human design review:
| Axis | What it checks |
|---|---|
| Layout fidelity | Structural regions, grid, stacking — reads as an intentional page |
| Visual hierarchy | Sizing, weight, eye flow — passes the squint test |
| Spacing & alignment | Consistent, on-grid, proportional |
| Component fidelity | Right components/variants, correct affordances |
| Color & theming | Correct surface/accent usage, holds in light + dark |
Bar: every gallery template should grade B or above on the Contributing Templates rubric and read well on the 5 visual axes. Purity/structure is largely automatable (🟢); the visual axes are the human layer (🔴).
Themes control what things look like; core controls what things are.
| Change | Where | Why |
|---|---|---|
| "This gray should be darker" | Theme | Already references the right token |
| "Buttons rounder" | Theme | Role fixed; value is a theme call (respect concentricity) |
| "Badge should use a different gray than body text" | Core | Token selection changes the contract |
| "Add a compact Card variant" | Core | Variants are structural |
| "This needs a hover state" | Core | Interaction states are behavior |
Corollary: a raw value in core is fixed by replacing it with the right token reference — never by swapping one raw value for another.
Designers: you don't write specs. Highest-value contributions: themes (judged against the foundations' rationale), gap reports, stories, templates, and hardening review. See Contributing with AI Assistants.
Reviewers, in the Component Hardening Protocol's design review: let the Night Watch Component Auditor run the 🟢 objective checks first, then judge the 🟡/🔴 calls — state representation, proportions, density, and composition. When a review resolves a new design question, record the decision back into this page so the conventions compound.
- API Conventions — the code-side sibling
- Astryx Philosophy — the principles these express
- Theming Infrastructure — token layers, neutral-gray semantics, scales, concentric radius
- Container Padding System — the layout / bleed contract
- Component Audit Rubric — the graded checks these conventions map to (§5a objective, §5b rendered judgment)
- Night Watch Component Auditor — runs the 🟢 objective checks nightly
- Contributing Templates · Contributing with AI Assistants