Design System Foundations
A living reference of all primitive components, tokens, and patterns.
Typography
Headings
Heading 1 — Page titles
Heading 2 — Section titles
Heading 3 — Subsections
Heading 4 — Minor headings
Heading 5 — Lead/intro paragraph text
Body Text
Body — Default paragraph text. This is the standard size for documentation content and general reading.
Body Medium — Slightly smaller than default body. Good for sidebars and secondary content.Body Small — Secondary text, captions, and helper text. Used for metadata and less prominent content.
Body Extra Small — Fine print, legal text, and timestamps.
Inline Code
const express = require('express'); Inline code: Use npm install express to install.
Weights
Light 300
Normal 400
Medium 500
Semibold 600
Bold 700
Polymorphic Rendering
H1 styled, rendered as h2
Body text rendered as span (inline)Type Scale
Aa 6xl (54px)
Aa 5xl (45px)
Aa 4xl (36px)
Aa 3xl (30px)
Aa 2xl (24px)
Aa xl (20px)
Aa lg (18px)
Aa base (16px)
Aa sm (14px)
Aa xs (12px)
Usage
import { H1, Body, Code } from '@components/primitives';
<H1 as="h2">h2 styled as H1</H1>
<Body>This is body text. It renders a paragraph by default.</Body>
<Code>const express = require('express');</Code>
Iconography
Icons are provided by astro-icon , a well-supported and officially
recommended package for Astro that gives access to 200,000+ icons from various icon sets. We
primarily use Fluent Icons (prefix fluent: ).
Examples
Usage
import { Icon } from "astro-icon/components";
<Icon name="fluent:airplane-24-regular" size="24" />
<Icon name="fluent:check-24-regular" color="var(--color-icon-primary)" />
Color Tokens
Primitive tokens
white
gray-50
gray-100
gray-200
gray-300
gray-400
gray-500
gray-600
gray-700
gray-800
gray-900
gray-950
black
sky-50
sky-500
sky-700
sky-800
green-50
green-300
green-500
green-700
green-900
amber-50
amber-300
amber-500
amber-600
amber-700
amber-900
red-50
red-300
red-500
red-600
red-700
red-900
Semantic tokens
bg-primary
bg-secondary
bg-tertiary
bg-inverse
bg-mute
bg-success
bg-warning
bg-error
text-primary
text-secondary
text-tertiary
text-inverse
text-mute
text-success
text-warning
text-error
border-primary
border-secondary
border-tertiary
border-inverse
border-mute
border-success
border-warning
border-error
Usage
.element {
background-color: var(--color-bg-primary);
color: var(--color-text-primary);
border: 1px solid var(--color-border-primary);
}
Spacing
Scale
0.5 (2px)
1 (4px)
2 (8px)
3 (12px)
4 (16px)
6 (24px)
8 (32px)
12 (48px)
16 (64px)
Usage
.element {
margin: var(--space-4);
padding: var(--space-2);
}
Form Elements
Accessible form components with full keyboard navigation and ARIA support.Select
Custom dropdown component using the button + listbox ARIA pattern. Supports full keyboard navigation (Arrow keys, Home, End, Escape, Enter, Space) and follows WAI-ARIA best practices.Variants
Default
Ghost
Minimal
Icon (with custom icon)
Sizes
Dropdown Alignment
With Placeholder
Full Width
Disabled State
Usage
import { Select } from "@components/primitives";
// Basic usage
<Select
options={[
{ value: '5x', label: 'v5.x', selected: true },
{ value: '4x', label: 'v4.x' },
{ value: '3x', label: 'v3.x', disabled: true },
]}
ariaLabel="Select version"
/>
// With variants and sizes
<Select
options={options}
variant="ghost"
size="lg"
dropdownAlign="right"
ariaLabel="Select option"
/>
// Icon-only variant (like LanguageSelect)
<Select
options={languages}
variant="icon"
icon="fluent:translate-16-regular"
hideLabel={true}
dropdownAlign="right"
ariaLabel="Select language"
/>
// Full width with placeholder
<Select
options={options}
placeholder="Choose an option..."
fullWidth={true}
ariaLabel="Select option"
/>
// Listen to changes
<Select
options={options}
id="my-select"
ariaLabel="Select option"
/>
<script>
const select = document.getElementById('my-select');
select?.addEventListener('select-change', (e) => {
console.log('Selected:', e.detail.value, e.detail.label);
});
</script>
Grid & Layout
12-column responsive grid system with Grid, Col, and Flex components.Grid Component
Responsive 12-column grid. Columns cascade from xs → md → lg. xs=12, md=6, lg=4
xs=12, md=6, lg=4
xs=12, md=12, lg=4
Usage
import { Grid, Col } from "@components/primitives";
<Grid gap="4">
<Col xs={12} md={6} lg={4}>Content</Col>
<Col xs={12} md={6} lg={4}>Content</Col>
<Col xs={12} md={12} lg={4}>Content</Col>
</Grid>
Flex Component
Flexbox layouts for 1D directional content. Item 1
Item 2
Item 3
Usage
import { Flex } from "@components/primitives";
<Flex direction="row" gap="4" justify="between">
<div>Item 1</div>
<div>Item 2</div>
</Flex>
FlexItem Component
Control flex-grow, flex-shrink, and flex-basis for individual flex children.Equal Columns
flex="1"
flex="1"
flex="1"
Different Basis & Grow
FlexItem basis="1/4"
FlexItem (grow="1")
Usage
import { Flex, FlexItem } from "@components/primitives";
<Flex gap="4">
<FlexItem flex="1">Equal column</FlexItem>
<FlexItem basis="1/4">Sidebar</FlexItem>
<FlexItem grow="1">Flexible content</FlexItem>
</Flex>
Container
Centered, responsive content wrapper with max-width and padding.Content centered with max-width: 1440px, width: 90-95%
Usage
import { Container } from "@components/primitives";
<Container>
<div>Your content here</div>
</Container>
Breakpoints
Current: Mobile (xs) < 768px Current: Tablet (md) 768px – 1439px Current: Desktop (lg) ≥ 1440px
Usage
/* Example media queries using design system breakpoints */
@media (--xs-only) {
/* mobile only */
}
@media (--md-only) {
/* tablet only */
}
@media (--md-up) {
/* above tablet */
}
@media (--lg-up) {
/* above desktop */
}
@media (--lg-down) {
/* below desktop */
}