Astro Design System

Overview

Astro's marketing site is the only major web-framework brand that makes a performance benchmark chart a hero-tier design element. Gradient-as-atmosphere. Where Next.js uses photography and Remix uses a bare white-on-dark canvas, Astro fills the hero with a radial gradient mesh — purple through fuchsia through royal blue — that reads as deep space rather than a brand-color fill. The gradient is not a background gradient behind content; it is the visual identity, and it spans the entire above-fold zone without resolving to a single named accent. The CTA button is a ghost pill outline in white, refusing to compete chromatically with the atmosphere behind it.

Typography makes the second structural decision. Weight extremes as signature: the hero h1 runs Obviously at 48px / weight 700 — a blocky, high-confidence geometric display. Body text runs system-ui at weight 300. The gap between headline and body is 400 weight units; no other framework marketing site captures this range. Section subheadings also drop to Obviously weight 300 for one registered rhetorical move ("Astro is a JavaScript web framework optimized for building fast, content-driven websites"), where the weight drop reads as a shift from declaration to explanation.

The embedded terminal and code panels use a near-black surface ({colors.surface-code} — #18181b) with aqua teal ({colors.aqua} — #4bf3c8) as the selection-text and interactive feedback color — a usage consistent with VS Code's aqua selection but mapped to the brand context. The aqua never appears in navigation, CTAs, or body text; it is scoped entirely to code-surface interactivity.

Key Characteristics:

• Gradient brand identity: purple (#b845ed) through fuchsia (#f041ff) through royal blue (#3245ff) — no single hex IS the brand.
• Near-black blue-tinted canvas ({colors.canvas} — #0c0f19) carries a slight violet cast in oklch that makes the gradient atmospheric rather than pasted-on.
• Ghost-pill primary CTA — white outline, white text, no fill — defers to the gradient behind it rather than competing.
• Obviously at weight 700 for all display headings; system-ui at weight 300 for body — a 400-unit weight gap.
• 9999px pill radius dominates (58 occurrences) for CTAs, version badge, framework integration chips, newsletter input.
• Aqua teal ({colors.aqua}) appears only on the performance benchmark chart bar and as terminal selection-text — scoped to code interactivity.
• MDIO monospace family used for the "Astro 6.1" version badge label — a subtle typographic signal of technical precision.
• Performance-benchmark chart (Astro 66% vs WordPress 48%, Gatsby 47%, Next.js 30%, Nuxt 28%) is a named design section, not a footnote.

Colors

Brand Gradient

• Primary Violet ({colors.primary} — #b845ed): frequency 12, all gradient. The warm anchor of the brand gradient mesh — violet at the high-energy end.
• Primary Fuchsia ({colors.primary-fuchsia} — #f041ff): frequency 10, all gradient. The mid-point of the brand gradient — fuchsia that reads as pink-violet.
• Primary Royal ({colors.primary-royal} — #3245ff): frequency 13, all gradient. The cool anchor of the brand gradient — a near-indigo royal blue. The page meta themeColor (a middle-purple) sits perceptually between the violet and fuchsia anchors but does not appear as a standalone rendered color.
• Primary Royal Mid ({colors.primary-royal-mid} — #2f4cb3): frequency 5, all gradient. A mid-saturation royal used as a gradient stop on the below-fold feature sections.

Interactive Accent

• Aqua ({colors.aqua} — #4bf3c8): frequency 39. Used as text (18), border (17), gradient (4). Wired as --ec-uiSelFg (terminal selection-foreground). The interactive feedback color — scoped entirely to code panels, the performance chart bar fill, and terminal selection states. Never appears in marketing chrome.
• Sky ({colors.sky} — #54b9ff): frequency 32. Used as text (16), border (16). A lighter periwinkle-blue that appears in code syntax highlighting and feature-card border accents on the dark surface.

Surface

• Canvas ({colors.canvas} — #0c0f19): frequency 35 as background. The deep near-black canvas with a subtle violet cast (oklch hue ~271). The page floor that makes the purple-blue gradient read as atmospheric depth.
• Surface-1 ({colors.surface-1} — #2c2c2c): frequency 23 as background. The dark card and panel surface — used for framework-integration badge backgrounds and feature card interiors.
• Surface-2 ({colors.surface-2} — #343841): frequency 6 as background. Secondary elevated surface for the performance chart panel and sidebar navigation elements.
• Surface Code ({colors.surface-code} — #18181b): frequency 8. The code editor and terminal panel background — wired as --ec-codeBg and --ec-frm-edBg. Darker than surface-1 to keep code panels visually distinct.

Text

• Ink ({colors.ink} — #f2f6fa): frequency 444 — the dominant text color on the dark canvas. Slightly blue-tinted near-white (clustered from #f2f6fa and pure white) that softens the stark contrast against the near-black canvas.
• Ink Muted ({colors.ink-muted} — #bfc1c9): frequency 84. Body paragraph text — a cool light gray, 84 text occurrences on body and supporting-paragraph elements.
• Ink Dim ({colors.ink-dim} — #858b98): frequency 73. Caption text and secondary labels — used under feature headings and for metadata labels. 15 text + 50 border occurrences.

Hairlines

• Hairline ({colors.hairline} — #545864): frequency 8, predominantly borders. Dark panel borders — used on code editor tabs, terminal frame outlines, and card boundaries.
• Hairline Light ({colors.hairline-light} — #e5e7eb): frequency 628 — the dominant border tone. Used for hairline card outlines in the feature grid below the fold (clustered from #e5e7eb and a near-white code-editor chrome value).

Syntax & Illustrations

• Amber ({colors.amber} — #ffd493): frequency 6. Warm amber used in code-syntax highlighting and as an illustration accent on framework-integration icons.
• Accent Periwinkle ({colors.accent-periwinkle} — #acafff): frequency 6. A lavender-periwinkle used in code annotations and the occasional feature-card accent.

Typography

Font Families

The system runs three distinct families. Obviously (the proprietary display family from OH no Type Co) handles every heading level with weight 700 for display and one weight-300 rhetorical variant. System-ui (resolved as ui-sans-serif) handles all body, nav, button, and label text at weights 200–600 — a deliberately broad weight range. MDIO (a specialized monospace from Mass-Driver) appears only in the "Astro 6.1" version badge as a 12px label — a micro-typographic signal of technical care.

The two-variable-weight pairings (Obviously 700/300 and system-ui 200/600) produce the page's extreme weight range.

Hierarchy

Principles

The body weight of 300 (system-ui) is the system's most distinctive typographic move. At 16px / 24px line-height on a near-black canvas with muted-gray text, weight 300 remains legible because the line-height is generous and the letter-spacing is default — not because the contrast is high. The hero sub-paragraph drops to weight 200, which is at the edge of readability for body text; it works here because the sub-paragraph is short (two lines) and sits on a gradient-rich background that already carries visual weight. Matching this move requires a neutral-geometry system sans (Inter or Inter Display) that remains readable at weight 200–300.

Note on Font Substitutes

Obviously is proprietary (OH no Type Co). Neue Montreal at weight 700 or Cabinet Grotesk at weight 800 are the closest open-source alternatives for the bold display tier. For the weight-300 variant, these same families at 300 work. For system-ui body, the browser's own system sans is acceptable; Inter at matching weights is the controlled substitute.

Layout

Spacing System

• Base unit: 8px (63 occurrences — the dominant gap value).
• Tokens: {spacing.xs} 4px · {spacing.sm} 8px · {spacing.md} 12px · {spacing.base} 16px · {spacing.lg} 24px · {spacing.xl} 32px · {spacing.2xl} 48px.
• Section padding (vertical): variable by section — the hero has no explicit top padding (content begins immediately under the nav), while below-fold sections use ~64px vertical spacing.
• Card internal padding: 16px on dark feature cards; {spacing.base} (16px) standard.
• Newsletter section padding: {spacing.2xl} (48px) vertical.

Grid & Container

• Max content width: ~1024px on the hero headline; ~1280px on the feature grid.
• Hero: centered single column, gradient as full-bleed background behind transparent surfaces.
• Performance chart: full-width bar chart below the hero, with the Astro bar in aqua teal against gray comparison bars.
• Framework integration section: single row of circular icon chips (React, Vue, Preact, Svelte, SolidJS) with a code-panel split to the right.
• Feature grid ("Fully Featured"): 3-column masonry-style grid with dark bordered cards, each showing a feature illustration (icons, code snippets, interface screenshots).

Rhythm

The page moves through four distinct bands: gradient-atmosphere hero → white-canvas interstitial (the "What is Astro?" section on a lighter near-white) → dark-panel code-and-benchmark sections → dark feature grid. The white interstitial is the most unusual: a band of lighter surface that creates a breath between the dramatic gradient hero and the technical content below.

Elevation

The system uses surface-color contrast rather than shadows for depth. Dark-surface tiers ({colors.surface-code} → {colors.surface-1} → {colors.canvas}) create a 3-step elevation ladder. Shadows appear in only 8 occurrences (all as rgba-black ink on the {colors.surface-code} terminal panel). The hairline border ({colors.hairline-light} — #e5e7eb at 628 occurrences) carries the elevation signal on the below-fold feature cards, where a 1px border lifts the card off the lighter page band.

Shapes

The radius scale is pill-dominant: 9999px (58 occurrences) for interactive chrome, with a 8–16px tier for content cards.

• {rounded.none} 0px — hero headline zone, section dividers.
• {rounded.sm} 8px — code panels, terminal frames, small input fields. 27 occurrences.
• {rounded.md} 12px — feature cards in the grid below the fold. 20 occurrences.
• {rounded.lg} 16px — larger card surfaces, embedded product UI screenshots. 21 occurrences.
• {rounded.xl} 20px — one large card variant.
• {rounded.full} 9999px — version badge, CTA buttons, framework integration chips, newsletter input, nav chips. 58 occurrences — the dominant radius.

The pill dominance is striking: the system uses 9999px more than all other radii combined. Pills read as the "interactive" shape — everything a user might tap or read-as-a-tag gets the pill treatment.

Components

button-primary — The ghost-pill CTA. Near-black {colors.canvas} fill, white text, 9999px pill radius, 8×16px padding, 42px height, 1px {colors.ink-dim} border. "Get Started" and "Skip to content" are the canonical instances. Notably, the primary CTA is not a chromatic fill — it is a ghost outline.

button-primary-hover — Lifts to {colors.surface-2} (#343841) on hover — a slightly lighter dark surface.

version-badge — Dark {colors.surface-1} pill, white text, 1px {colors.hairline} border, 4×12px padding. "Astro 6.1" and "Available now →" rendered as two adjacent pill badges in the hero.

hero-heading — Obviously 48px / weight 700, white text, transparent background. "The web framework for content-driven websites" — the loudest typographic moment.

section-heading — Obviously 36px / weight 700 for major section h2s. Falls to {typography.display-sub} (36px / weight 300) for the descriptive "What is Astro?" subheading.

body-paragraph — System-ui 16px / weight 300, muted-gray {colors.ink-muted} text. The lightest-weight body style in any major framework brand.

framework-badge — {colors.surface-2} pill, white text, 8×16px padding. Used for React, Vue, Preact, Svelte, SolidJS integration chips in the Zero Lock-In section.

card-dark — {colors.surface-1} fill, white text, 12px radius, 16px padding. The default feature card in the "Fully Featured" grid.

card-feature — Canvas-colored with {colors.hairline-light} border, 16px radius. The lighter feature card variant used in the "built-on" section.

terminal-panel — {colors.surface-code} fill, white text, mono typography, 8px radius, 1px {colors.hairline} border. The embedded code editor and terminal-output panel.

chart-bar — Aqua {colors.aqua} fill, 8px radius. The Astro bar in the Core Web Vitals performance comparison chart — the only place where {colors.aqua} appears as a fill.

newsletter-input — Canvas fill, white text, pill radius (9999px), 8×24px padding, 44px height, 1px {colors.hairline} border.

code-block — {colors.surface-code} fill, 8px radius, 16px padding, monospace text.

footer — Canvas fill, dim-gray text, 48×32px padding. Continues the near-black surface without surface contrast.

Do's and Don'ts

Do treat the gradient as the brand identity, not any individual hex. Violet, fuchsia, and royal blue only work together as a mesh; using any one color alone as a "brand accent" produces a result that reads as generic purple SaaS, not as Astro.

Do keep body text at weight 200–300. The weight-300 body is the page's most unusual move and its most transferable; it requires a generous line-height (24px at 16px font size, which is 1.5) to maintain legibility.

Do treat the aqua teal ({colors.aqua} — #4bf3c8) as a code-interactivity-only color. Its role is scoped entirely to the terminal selection-text token and the performance chart bar; deploying it in navigation, CTAs, or card accents would break the color discipline.

Do use 9999px pill radius for all interactive chrome (buttons, badges, chips, inputs). The system's pill-dominant radius scale makes every interactive element visually distinct from content cards; switching to 8px radius on CTAs would make them read as cards.

Don't add a chromatic fill to the primary CTA button. The ghost-pill treatment is the deliberate move — the gradient behind the headline is the visual energy, and the CTA defers to it. A purple or blue fill button would compete with the gradient and reduce the atmospheric reading.

Don't use {colors.aqua} (#4bf3c8) or {colors.sky} (#54b9ff) as section backgrounds or card fills. Both appear exclusively as text, border, or gradient tones in the captured page (0 background occurrences for sky, 0 for aqua outside the chart bar). Filling a card or section with either color would create a jarring chromatic block on a page built around atmospheric gradient.

Don't apply {typography.display-sub} (36px / weight 300) to more than one heading per section. The weight-300 display variant appears exactly once in the captured page as a contrast move against the surrounding weight-700 headings; using it broadly would collapse the weight range that defines the typographic identity.

Don't use the MDIO mono family ({typography.code-badge}) outside the version badge context. It appears exactly twice in the captured page — both in the "Astro 6.1" badge label. It signals a specific typographic precision; deploying it in body or label contexts would read as misplaced terminal aesthetic.

Known Gaps

• Gradient geometry: the token system captures the gradient color anchors but not the radial mesh geometry. The actual CSS gradient is a radial gradient with multiple stops and blur layers; the colors alone are not sufficient to reproduce the atmospheric depth without the radial definition.
• Hover states beyond button: full hover, focus, and active state matrix is not captured for nav links, framework chips, or the newsletter input.
• Light-mode variant: the "What is Astro?" section below the hero uses a lighter near-white surface band (#f2f6fa), but no full light-mode token set is declared on the captured page.
• Responsive breakpoints: all captured surfaces are desktop-only. Mobile navigation, single-column card layout, and responsive chart sizing are not documented.
• Motion: the hero gradient animates on mouse-move and the performance chart bars animate on scroll-into-view; easing curves and animation timing are not captured.
• Product application surfaces: this DESIGN.md captures the marketing site only. The Astro documentation site (docs.astro.build) and the Astro DB product carry separate token sets.
• Social proof section: the customer logo wall (Google, Microsoft, Porsche, Visa, etc.) uses white logos at uniform treatment, but the logo-wall component token is not fully specified here — it would follow the same pattern as Cloudflare's monochrome logo wall.