Typography

Overview #

Typography is built on a geometric type scale: base size × ratio^step, with 14px and 1.2 as defaults. Every text style is a semantic token that composes font size, weight, and line-height, so components express intent (heading, body, label) rather than raw values.

Two layers work together: raw size tokens (--font-size-xs ... --font-size-5xl) form the geometric scale, and semantic type scale tokens (--text-heading-1-size, --text-body-leading, etc.) reference them by var(). Themes override the entire scale by adjusting base and ratio in defineTheme; all semantic tokens recompute automatically.

Font Families #

Three font roles: body (UI text), heading (titles and headings), and code (monospace). By default, body and heading share the same system font stack; code uses a monospace stack. Custom themes can assign different families per role; heading inherits from body when not explicitly set.

Font family stacks for body, code, and heading text.

Full reference: Font Family Tokens.

Font Sizes #

Geometric scale: round(base × ratio^step), expressed in rem. The default scale is 14px × 1.2, producing 12 steps from 4xs (6px) to 5xl (42px). Adjusting base and ratio in defineTheme regenerates every size token while preserving proportional relationships.

Geometric type scale: round(14 × 1.2^step). Base is 14px (--font-size-base).

Full reference: Font Size Tokens.

Font Weights #

Four semantic weights: normal (400, body/code), medium (500, labels/data), semibold (600, headings/titles), bold (700, strong emphasis). Type scale tokens reference these by var() so themes can remap numeric values.

Font weight values for body, emphasis, and headings.

Full reference: Font Weight Tokens.

Line Height #

Line heights are computed from a tiered target ratio and snapped to a 4px vertical grid. Small text (<20px) targets 1.5, medium text (20–31px) targets 1.4, and large text (≥32px) targets 1.25. A minimum gap of fontSize + 4px is enforced. The result is a unitless ratio stored in each --text-*-leading token.

The 4px grid matters: every line box aligns to 4px increments, which keeps baselines, spacing, and component heights predictable. The expandTypeScale utility computes these automatically when you provide a base and ratio, so you should never need to set line-height manually.

Type Scale #

Semantic tokens that combine size, weight, and line-height into a single type style. Each token triplet (--text-*-size, --text-*-weight, --text-*-leading) is consumed by Text and Heading. Use the component props rather than composing raw font tokens.

Semantic tokens for headings, body, labels, code, supporting text, and display text. References font size and weight tokens. Override via typography.scale in defineTheme.

Full reference: Type Scale Tokens.

Display Text #

Display variants (display-1, display-2, display-3) continue the geometric progression above heading-1, at steps +6, +5, and +4. They use normal weight (400) instead of semibold, and tighter line-heights (~1.2), since large text reads better with less leading. Use display types for hero banners, marketing headlines, and data callouts, not for document headings.

Display text often needs heading semantics for accessibility. Use the type prop on Heading to apply display styling while preserving the correct HTML element: <Heading level={1} type="display-1"> gives you display-1 styling with an <h1> tag, so screen readers see the correct document outline.

Usage #

svelte
 
<script lang="ts">
	import { Heading } from '@astryx-svelte/core';
</script>
​
<!-- Heading levels map to semantic tokens: level 1 -> --text-heading-1-* -->
<Heading level={1}>Page Title</Heading>
<Heading level={2}>Section</Heading>
<Heading level={3}>Subsection</Heading>
​
<!-- Display type for hero/marketing headings — level sets the HTML element -->
<Heading level={1} type="display-1">Hero Title</Heading>
<Heading level={2} type="display-2">$1.2M Revenue</Heading>
​
<!-- Override the accessibility level when visual != document hierarchy -->
<Heading level={2} accessibilityLevel={3}>Sidebar Section</Heading>

svelte
 
<script lang="ts">
	import { Text } from '@astryx-svelte/core';
</script>
​
<Text type="body">Body text at the base scale.</Text>
<Text type="large">Emphasized body text.</Text>
<Text type="label">Form label</Text>
<Text type="supporting">Helper text, timestamps, metadata.</Text>
<Text type="code">const x = 1;</Text>
​
<!-- Display without heading semantics (data callouts, decorative) -->
<Text type="display-2">$1.2M Revenue</Text>

ts
 
import { defineTheme } from '@astryx-svelte/core/theme';
​
// Adjust the entire ramp holistically with base and ratio
const editorialTheme = defineTheme({
	name: 'editorial',
	typography: {
		scale: { base: 16, ratio: 1.25 }, // airy / article feel
		body: { family: 'Geist', fallbacks: '-apple-system, sans-serif' },
		heading: { weight: 'bold' },
		code: { family: 'Geist Mono', fallbacks: '"SF Mono", monospace' }
	}
});
​
const denseTheme = defineTheme({
	name: 'dense',
	typography: {
		scale: { base: 12, ratio: 1.125 } // compact / data-dense UI
	}
});

Best Practices #