DESIGN.md

Overview

Sunbeam is AstraFoundry's design system, used by astrafoundry.si, Lyra, Arion and Telo. It should feel calm, warm and exact: a product that does real work and shows it plainly.

• Warm ink, one yellow. Neutrals are warm ink. colors.primary marks the one primary action on a screen or the result of a scene, and nothing else.
• Photographs, not gradients. Atmosphere comes from motion-blurred natural photographs, never from gradients, glows or noise.
• One solid focus. On a photograph exactly one surface is solid; everything around it is tinted, muted or cut off by the edge.
• Concentric corners. A rounded thing inside a rounded thing uses inner radius = outer radius − inset.
• Motion explains, then rests. A scene plays once when it is seen, shows action then result, and stops on the result.

The full specification, with feature tiles, 3D demonstration figures and a review checklist, is the Sunbeam agent skill at https://astrafoundry.si/design/skill.

Colors

Light mode is the default. Every semantic color has a dark- twin, and every component that changes in dark mode has a -dark variant; the twin aliases the light value where dark mode keeps it. Switch the whole set at once, never per component.

• Ramps. Two ramps carry every other color: yellow (colors.yellow-100, colors.yellow-300, colors.yellow-500, colors.yellow-700) and warm ink (colors.ink-50, colors.ink-100, colors.ink-200, colors.ink-300, colors.ink-400, colors.ink-500, colors.ink-700, colors.ink-800, colors.ink-900). Use the semantic names below, not the ramps.
• Paper and ink. colors.background is warm paper, colors.foreground warm ink. colors.card is solid content: panels, windows, mock product UI.
• Yellow. colors.primary fills the single primary action and marks a result; colors.ring is the focus ring. colors.accent with colors.accent-foreground is a quiet highlight, used sparingly.
• Quiet. colors.secondary and colors.muted fill wells and secondary controls; colors.muted-foreground carries leads and captions. colors.border and colors.input are 1px hairlines; colors.faint is the outline of drawn figures.
• Status. colors.success, colors.danger and colors.info color icons and dots only, never running text.
• Substrate. colors.substrate and its family are an always-dark backstage that does not change with the theme: behind demos, and for everything set on a photograph. colors.substrate-focus is the solid focus surface, white in both modes, with colors.substrate-focus-ink. colors.substrate-tint is the translucent chip beside it.
• Scrim. colors.scrim at up to 55% opacity, fading to transparent, is the only gradient, and only behind text on a photograph.

Never write physical colors in components, never use yellow for borders, badges or links, and never color a shadow.

Typography

Fraunces for display, IBM Plex Sans for everything else, JetBrains Mono for code. Chinese and Japanese fall back to system faces (PingFang SC, Hiragino, Noto) and use no tracking on headings.

• Headlines. typography.headline-display and typography.headline-lg are Fraunces at weight 400, for page and section titles only. Never bold, never italic for emphasis. The display size scales with the viewport from 48px to 96px.
• Headings and body. typography.headline-md heads blocks; typography.body-lg is a lead in colors.muted-foreground; typography.body-md is running text; typography.body-sm is dense UI.
• Labels and captions. typography.label-md for buttons and controls, typography.caption for captions. Nothing is set below 12px.
• Numbers that change or line up use tabular figures. Titles are balanced, paragraphs pretty, at most about 65 characters a line. Sentence case, no exclamation marks, no emoji.

Layout

Sizes come in steps of spacing.unit. Lines are spacing.hairline: separate cells with a one-pixel gap over colors.border rather than borders on each cell, so lines never double and corners never break.

A backdrop card keeps one inset for every zone: spacing.card-inset-sm on phones, spacing.card-inset-md from 640px, spacing.card-inset-lg from 1024px. The mark sits top-left at the inset, the focus row near the vertical middle, a status line under the focus surface, and the caption bottom-left at the same inset as the mark. Nothing is centered by default; compositions read left to right, top to bottom.

A feature tile insets its art panel by spacing.tile-inset.

Elevation & Depth

Depth comes from warm, two-layer shadows keyed off ink rather than neutral black: a one-pixel contact shadow and a soft spread below it, stronger in dark mode. Five levels: 1 for controls and chips, 2 for popovers, 3 for raised cards, 4 for dialogs, 5 for a window or the focus surface floating on a photograph.

No glass: no backdrop blur, no outer glows, no colored or gradient borders. A photograph is used as it is, without a tint, blur or vignette; choose a darker photograph rather than darkening a bright one.

Shapes

Corners are soft and concentric. The scale runs from rounded.none, rounded.xs and rounded.sm for marks and code to rounded.3xl for cards; controls and chips are rounded.full pills. Feature-tile grids use rounded.tile; stage and backdrop cards use rounded.3xl below 1024px and rounded.stage above.

Inner radius = outer radius − inset: a rounded.tile card with an 8px inset holds a 20px panel. When the inset is larger than the outer radius, the inner element keeps its own radius.

Components

The component tokens are recipes: color pairs, type and shape for the parts every Sunbeam page uses. Hairline and dot entries (divider, text-field-border, focus-ring, canvas-dot, figure-line, stage-line, stage-edge, image-outline) give the color of a line or dot of that size.

• Buttons. button-primary is the one yellow action on a screen; everything else is button-secondary or a quiet text button. Pressing scales to 0.97 over 150ms.
• Cards and popovers. card holds solid content; popover floats on shadow level 2.
• Fields. text-field is a solid field with a text-field-border hairline and a focus-ring on keyboard focus.
• Backdrop card. backdrop-card is a motion-blurred natural photograph (on colors.substrate until it loads) with one backdrop-focus surface, backdrop-chip neighbors that may bleed off the edges, and a backdrop-caption. Because the photograph does not change with the theme, these components have no dark variant.
• Stage. stage-panel and stage-raised build mock product UI on the dark substrate.
• Feature tiles and figures. Animated feature tiles and live 3D demonstration figures follow the Sunbeam skill, sections 6 and 7.

Motion

Four curves: ease-out cubic-bezier(.22, 1, .36, 1) for anything entering or moving, a spring cubic-bezier(.34, 1.4, .64, 1) for small things appearing, ease-in-out cubic-bezier(.65, 0, .35, 1) for something already on screen changing shape, and a drawer curve cubic-bezier(.32, .72, 0, 1). 150ms for hover and press, 200–300ms for popovers, 250–600ms per move, under about 3s per scene. Exits are faster than entrances. Animate transform, opacity and filter only. With reduced motion, show the final frame.

Do's and Don'ts

• Do set a card on a motion-blurred natural photograph; don't fill it with an indigo-to-violet gradient or a glow.
• Do make one surface solid and quiet the rest with tint; don't frost every element with glass blur.
• Do set captions in muted light ink at the card inset, bottom left; don't center bold white text with a drop shadow.
• Do use inner radius = outer radius − inset; don't give nested elements the radius of their container.
• Do spend yellow on the one primary action or result; don't use it for badges, borders, icons and links at once.
• Do play a scene once when it is seen and rest on the result; don't loop, bounce or pulse forever.
• Do show a real object as shaded solids with one part lit; don't draw a wireframe, or a glossy render with labels and arrows.
• Do keep WCAG AA contrast (4.5:1) for text; don't set status colors as running text.