IntroductionOrbital 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 table of contents to jump to a chapter, or browse individual components in the sidebar.
Principles
How to use these principles
Principles are review criteria—not slogans. 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 valuesToken
Pixels
Size40
4px
Size80
8px
Size120
12px
Size160 (default)
16px
Size240
24px
Size320
32px
Choosing a layout component
Start with the simplest primitive that fits. Stack is the default for vertical sections and evenly spaced rows. Reach for Flex when you need alignment along both axes or inline placement.Component
Use when
One wrapper needs token-based padding or sizing—not sibling distribution
Multiple children, one axis, even gaps (forms, button rows)
Alignment, wrapping, or inline control groups beside text
Fluid card walls that reflow by viewport without manual breakpoints
Container
Page-level max-width and horizontal centering inside the shell
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 referenceSize class
Range
Breakpoint
Small
320–479px
< 480px
Large
640–1023px
< 1024px
X-Large
1024px+
≥ 1024px
Color
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--colorNeutralBackground*, --colorNeutralForeground*, --colorBrandBackground, --colorStatusSuccessForeground1, and related status tokens.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
--shadow4
Cards, list items, content canvas, TopBar
--shadow8
Emphasized cards, raised command bars
--shadow16
Callouts, transient sidebar panels
--shadow64
Dialogs and modal panels
Shell conventions
Region
Elevation
TopBar
Resting (shadow4)
Content canvas
Resting (shadow4)
Right sidebar (open)
Floating (shadow16)
Dialogs
Modal (shadow64)
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
--colorNeutralBackground3
Content canvas
--colorNeutralBackground1
Top bar
--colorNeutralBackground1
Acrylic
Acrylic surfaces are semi-transparent with a frosted backdrop. Use them for light-dismiss, transient overlays—menus and popovers—not for primary reading surfaces.Smoke
Smoke is a dimmed scrim 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.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.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
12px
Metadata, timestamps
Body1
14px
Default body text
Subtitle2
16px semibold
Card subtitles, section headers
Title3
24px semibold
Page titles in the app shell
Display
68px semibold
Hero and marketing statements
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 FormLabel for field labels, FormHint for helper text below fields, and SectionTitle for compact group headings in dense settings UI.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 guides attention and confirms actions—it should never distract from the task. Use theme duration tokens (--durationNormal, --durationGentle) and easing curves (--curveEasyEase) instead of arbitrary transition values.Respect prefers-reduced-motion. Orbital motion helpers such as HideOnScroll, ParallaxContainer, and use_reduced_motion honor reduced-motion preferences.Shell transitions (sidebar open/close, dialog enter/exit) should feel quick and predictable. Decorative motion belongs in marketing surfaces, not routine data entry.