Introduction

Orbital is a Leptos component library for building focused, accessible product interfaces. The sections below define spacing, type, color, surfaces, and motion in concrete terms. Start with four principles that explain why those rules exist.Use the anchor rail to jump to a chapter, or browse individual components in the sidebar.
Principles
How to use these principles
Principles are review criteria—not slogans. Walk the four principles before shipping and let them break ties between valid options.
Before shipping a page, walk the four principles and check whether spacing, type, and interaction choices support them. When two implementation options are valid, the principle that serves the current task breaks the tie.
Familiar on every surface
Interfaces adapt to the device and build on patterns users already know. Invest custom UX only where the product has a signature moment worth learning.In practiceUse Orbital shell layouts before inventing new chrome. Prefer responsive padding and reflow over fixed desktop layouts shrunk to mobile. Reach for standard components over one-off styled wrappers.AvoidNovel navigation on every app; hiding core actions behind unique gestures; desktop-only density on phone widths.
Built for focus
Draw attention to the next action and the information needed for the current task. Remove noise so people stay in flow.In practiceKeep the content canvas as the lightest, most prominent surface. One primary action per region; secondary actions use subtle button appearances. Use typography hierarchy—one clear page title.AvoidDense walls of controls; competing primary buttons; decorative color and motion that do not carry meaning.
Inclusive by design
Design for a range of abilities, preferences, and contexts from the start—not as a retrofit.In practiceNever rely on color alone for status; pair with text or icon. Ensure keyboard reachability and visible focus. Respect prefers-reduced-motion; label icon-only controls.AvoidPlaceholder-only error states; contrast that fails accessibility targets; motion that cannot be reduced.
Cohesive product character
Apps built with Orbital should feel like parts of one platform: shared tokens, shared motion, shared patterns.In practiceUse design tokens for color, spacing, shadow, and radius—no ad-hoc hex in app code. Compose with Material, Stack, and typography presets. Brand accent sparingly on CTAs and selection.AvoidPer-app shadow and radius values; forked copies of shell components; brand color as the default page background.
Principles at a glance
Principle
Primary chapters
Familiar on every surface
Layout, shell patterns, responsive
Built for focus
Material, Elevation, Typography
Inclusive by design
Typography, Color, Motion
Cohesive product character
Tokens, Material, Typography presets
Layout
Spacing and proximity
Space is a grouping tool. When two controls share a small gap, people read them as one decision. When sections are separated by a full ramp step or more, the page reads in clear chunks without divider lines.Orbital constrains gaps to SpacingSize and CSS spacing tokens—avoid one-off margin values that break rhythm across pages.Common spacing ramp values
Token
Pixels
Size40
4px
Size80
8px
Size120
12px
Size160 (default)
16px
Size240
24px
Size320
32px
Spacing ramp

Each bar width matches the SpacingSize pixel value. Use SpacingSize in Flex gap and SpacingInset for padding.

Size40 | 4px
Size80 | 8px
Size120 | 12px
Size160 | 16px
Size240 | 24px
Size320 | 32px
Spacing proximity

Small gaps group related controls; larger gaps separate sections.

8px gap (Size80)
A
B
C
32px gap (Size320)
A
B
C
Shell content padding is responsive: 32px desktop (Size320), 24px tablet (Size240), 16px mobile (Size160). Regions in the shell body use a 12px gap (Size120) so chrome does not butt together.
Shape — radius and stroke
Border radius and stroke width are first-class tokens. Use BorderRadius and StrokeWidth enums on Box and in runtime style strings via Display / css_var().
Border radii

Use BorderRadius on Box and other typed surface props.

None--orb-radius-none
Small--orb-radius-sm
Medium--orb-radius-md
Large--orb-radius-lg
XLarge--orb-radius-xl
Floating--orb-radius-floating
Circular--orb-radius-circular
Stroke widths

Progressively thicker rules using StrokeWidth tokens.

Thin (--orb-stroke-thin)
Thick (--orb-stroke-thick)
Thicker (--orb-stroke-thicker)
Thickest (--orb-stroke-thickest)
Choosing a layout component
Start with the simplest primitive that fits. Stack is the default for even-gap vertical sections. Space distributes children to opposite edges. Reach for Flex when you need wrap, inline placement, fill, or inset padding.
Component
Use when
Box
One wrapper needs token-based padding or sizing—not sibling distribution
Stack
Even gaps on one axis (forms, button rows); defaults to column + full-width
Space
Opposite-edge distribution (page headers, footer action bars); defaults to space-between + full-width
Flex
Full 1D control: wrap, inline, fill, inset padding, or custom alignment
Grid
Two-dimensional layouts where column span and offset matter
AutoGrid
Fluid card walls that reflow by viewport without manual breakpoints
Container
Page-level max-width and horizontal centering inside the shell
ContentWithAside
Documentation pages with a growing content column and sticky aside rail
Grid
A column grid splits the content area into even tracks—use Grid and GridItem when column span matters. When tile count and width vary, AutoGrid reflows columns using minmax so you do not maintain breakpoint-specific column counts by hand.
Alignment
Misaligned baselines make forms feel broken faster than wrong colors. In a row of controls, align on the cross axis with Flex or Stack align props. Pair icons and labels by centering the glyph and start-aligning the label text.
Responsive design
Responsive layout is a set of techniques: reposition (stack to row), resize (container max-width), reflow (AutoGrid columns), show/hide (nav collapse), and re-architect (master/detail split on desktop, single pane on mobile).Breakpoint reference
Size class
Range
Breakpoint
Small
320–479px
< 480px
Large
640–1023px
< 1024px
X-Large
1024px+
≥ 1024px
Color
Never rely on color alone for status or meaning—always pair semantic color with text, icons, or labels.
Color expresses style, communicates meaning, and supports hierarchy. Orbital organizes color into neutral, shared accent, and brand palettes applied through design tokens.Neutral colors carry surfaces, text, and layout chrome. Shared accent colors highlight reusable components. Brand colors identify the product—use them sparingly on large surfaces.Semantic status colors (success, warning, danger) build on real-world associations. Always pair them with text or icons—never rely on color alone.Lighter neutrals on primary focus surfaces and darker neutrals on surrounding chrome draw the eye to the task. Interaction states progress from rest through hover, pressed, and selected; focus adds a thicker stroke.Key token families--orb-color-surface-*, --orb-color-text-*, --orb-color-brand-bg, --orb-color-status-success-fg, and related status tokens.
Color tokens

ThemeColor maps every Orbital palette slot to a typed enum with css_var() and name().

Neutral backgrounds
--orb-color-surface-canvas
--orb-color-surface-subtle
--orb-color-surface-overlay
Brand and status
--orb-color-brand-bg
--orb-color-status-success-bg
--orb-color-status-warning-bg
--orb-color-status-danger-bg
Semantic color with text
Semantic color

Status colors always ship with descriptive text via MessageBar intents.

Info — paired with descriptive text
Success — changes saved
Warning — review before continuing
Error — action could not complete
Elevation
Depth and shadow
Elevation is a hierarchy signal. A resting panel, a raised card, a dropdown, and a modal dialog each occupy a different depth. Orbital encodes depth with named shadow tokens so surfaces feel coherent instead of each team tuning shadows by eye.
Elevation ramp
Token
Typical use
--orb-elev-raised-sm
Cards, list items, content canvas, AppBar
--orb-elev-raised-md
Emphasized cards, raised command bars
--orb-elev-floating
Callouts, transient panels
--orb-elev-modal
Dialogs and modal panels
Elevation ramp

Shadow tokens from resting (--orb-elev-raised-sm) through modal (--orb-elev-modal).

--orb-elev-raised-xs--orb-elev-raised-xs
--orb-elev-raised-sm--orb-elev-raised-sm
--orb-elev-raised-md--orb-elev-raised-md
--orb-elev-floating--orb-elev-floating
--orb-elev-overlay--orb-elev-overlay
--orb-elev-modal--orb-elev-modal
Match elevation to how long the surface stays and how much it blocks what is beneath. Persistent page content stays at resting elevation. Blocking dialogs sit at the top of the ramp.
Shell conventions
Region
Elevation
AppBar
Resting (--orb-elev-raised-sm)
Content canvas
Resting (--orb-elev-raised-sm)
Drawer / transient overlay
Floating (--orb-elev-floating)
Dialogs
Modal (--orb-elev-modal)
Material
Material describes what a surface feels like—opaque workspace, frosted glass, tinted backdrop, or dimmed scrim—not how far it floats. Depth is elevation (see above). Pick variant first, then elevation where shadow applies.
Solid
Solid material is the default for anything that stays on screen while the user works—page body, cards, nav rails. Differentiate regions with background step tokens and elevation, not one-off hex fills.
Region
Background token
Shell ground
--orb-color-surface-subtle
Content canvas
--orb-color-surface-canvas
Top bar
--orb-color-surface-canvas
Shell ground (Bg3)
Content canvas (Bg1)
Frost
Frost surfaces are semi-transparent with a frosted backdrop. Use them for light-dismiss, transient overlays—menus and popovers—not for primary reading surfaces.
Frost
Shell
Scrim
Scrim is a dimmed overlay that blocks interaction with the page beneath. Pair it with dialog content at modal elevation. Always provide a clear dismiss path and move keyboard focus into the elevated content.
Scrim — blocks interaction with content beneath
The Material component
The Material component declares surface finish and depth in one place. Set variant to opaque, frosted, tinted, or dimmed. Set elevation when the surface should lift off its parent.
Solid
Frost
Shell
Scrim
View Material preview →
Typography
Hierarchy and type ramp
The type ramp is a ladder of paired font size, line height, and weight presets. Default reading text is Body1; scale up for titles, down for metadata.
Preset
Size
Typical use
Caption1
10px
Metadata, timestamps
Body1
14px
Default body text
Subtitle1
16px semibold
Card titles, content section headers
Title3
20px semibold
Page titles in the app shell
Display
60px semibold
Hero and marketing statements
Typography ramp

Preset components (Caption1, Body1, Title3, Display) map to the Orbital type scale.

Caption1Caption1 — metadata, timestamps
Body1Body1 — default reading text
Subtitle2Subtitle2 — section headers
Title3Title3 — page titles
DisplayDisplay
Font families

League Spartan (Base and Numeric), League Mono (Monospace), and Orbitron (Display) — self-hosted OFL fonts via FontFamily theme tokens.

BaseLeague SpartanOrbital 0123
NumericLeague Spartan (tabular)Orbital 0123
MonospaceLeague MonoOrbital 0123
DisplayOrbitronOrbital 0123
Regular — --orb-type-weight-regular
Semibold — --orb-type-weight-semibold
Bold — --orb-type-weight-bold
Caption (--orb-type-size-xs)
Body (--orb-type-size-sm)
Title (--orb-type-size-lg)
Large title (--orb-type-size-2xl)
Display (--orb-type-size-5xl)
View full type specimen →
Choosing a preset
If you reach for a raw element with inline font styles, check the ramp first—there is almost always a preset that fits. Use Title3 for app bar and panel titles, Subtitle1 for card and content section titles, SectionTitle for TOC rails and dense form groups, FormLabel for field labels, and FormHint for helper text below fields.
Form typography

FormLabel, FormHint, and SectionTitle are convenience wrappers around the type ramp.

We'll never share your email.Account settings
Styling text
Use sentence case for UI strings. Default start alignment for paragraphs and forms; center only for short, intentional focus. Typography carries meaning through size and weight first, color second—muted captions use foreground tokens, not random gray hex. Body text needs sufficient contrast against its background.
Motion
Motion confirms visibility changes—it should never distract from the task. Always honor prefers-reduced-motion; reserve decorative scroll effects for marketing surfaces, not routine data entry.
Orbital motion is a layered API in orbital-motion: MotionDuration and MotionCurve tokens map to Orbital --duration* and --curve* theme variables; PresenceMotion presets pair enter/exit atoms; OrbitalPresence applies them to conditional children; and OrbitalPresenceGroup staggers keyed lists. See the Motion overview for the full developer story.Start with a PresenceMotion preset (fade, slide, and others), wrap show/hide content in OrbitalPresence, and tune timing with with_duration / with_curve—not arbitrary CSS transitions. Dialogs, drawers, toasts, and menus already integrate this stack internally; reach for OrbitalPresence when you add your own mount/unmount surfaces.OrbitalPresence respects reduced motion by default (respect_reduced_motion=true). Use use_reduced_motion for imperative checks, or read Reduced motion in the catalog.