Guidelines — Design Foundations

3 files · no external dependencies

Getting Started

Three CSS files and two patterns cover every use case.
Import, reference a token, apply a component class.

Import

Add three stylesheet links in order — tokens must load before shared, and shared before components.

html

<!-- 1. Primitive + semantic tokens -->
<link rel="stylesheet" href="tokens.css">
<!-- 2. Layout, header, hero, footer -->
<link rel="stylesheet" href="shared.css">
<!-- 3. All component classes -->
<link rel="stylesheet" href="components.css">

Using a token

Reference semantic tokens in your CSS — never raw primitives.

css

.my-element {
  color: var(--color-interactive-primary-text);
  /* resolves to --color-blue-600 */
  gap: var(--gap-md);
  /* resolves to 16px */
}

Always consume semantic tokens. Primitives like --color-blue-600 may change.

Using a component

Apply the BEM class from components.css directly to your markup.

html

<!-- Primary action -->
<button class="btn btn--primary">
  Label
</button>

<!-- Ghost variant -->
<button class="btn btn--ghost">
  Label
</button>

See the Button, Input, and Badge sections in Components.

Token Architecture

Three-tier token system — primitives, type tokens, and semantic color/spacing tokens — with full light and dark mode support.

Tier 1 · Primitives

Base Collection

0

Raw primitive values: colors, spacing numeric scale, font weights, and font families. The source of truth — all semantic tokens alias from here.

color/neutral/50–1000 color/blue · red · green · yellow · orange · purple scale/0–200 (19 steps) type/font-family · font-weight

Tier 2 · Type Tokens

Guidelines — Type

0

Semantic typography tokens for font sizes, line heights, and letter spacing. Each value aliases a specific step from the base scale.

fontsize/body/sm · md · lg fontsize/headings/h1–h6 lineheight · tracking

Tier 3 · Semantic

Color & Spacing

0

Role-based tokens with Light and Dark mode variants. Colors carry intent rather than raw values — the only tier components should consume.

Light / Dark modes bg · surface · border · overlay text · icon · interactive · feedback spacing/xs–page

Token Map

Mapping between Figma variable paths and their CSS custom property equivalents.
Click any CSS variable or value to copy it.

Color · Semantic

Figma path	CSS variable	Resolves to
color/text/primary	--color-text-primary	neutral-900
color/text/secondary	--color-text-secondary	neutral-600
color/text/ghost	--color-text-ghost	neutral-500
color/text/inverse	--color-text-inverse	white
color/text/buttons/disabled	--color-text-buttons-disabled	neutral-300
color/text/link/default	--color-text-link-default	blue-600
color/text/accent	--color-text-accent-default	blue-500
color/text/accent-dim	--color-text-accent-dim	blue-400
color/text/accent-subtle	--color-text-accent-subtle	blue-300
color/text/hero/dim	--color-text-hero-dim	neutral-400
color/text/hero/ghost	--color-text-hero-ghost	neutral-400
color/stroke/default	--color-borders-default	neutral-200
color/stroke/strong	--color-borders-strong	neutral-600
color/stroke/focus	--color-borders-focus	blue-400
color/stroke/accent/default	--color-borders-accent-default	blue-500
color/stroke/accent/dim	--color-borders-accent-dim	blue-400
color/stroke/hero	--color-borders-hero	rgba(255,255,255,0.06)
color/stroke/buttons/danger/default	--color-borders-buttons-danger-default	transparent
color/stroke/buttons/danger/hover	--color-borders-buttons-danger-hover	transparent
color/stroke/buttons/danger/active	--color-borders-buttons-danger-active	transparent
color/surface/page-bg	--color-surface-page-bg	neutral-50
color/surface/card	--color-surface-card	white
color/surface/hero	--color-surface-hero	neutral-800
color/surface/accent/default	--color-surface-accent-default	blue-500
color/surface/accent/dim	--color-surface-accent-dim	blue-400
color/buttons/danger/default	--color-buttons-danger-default	red-500
color/buttons/danger/hover	--color-buttons-danger-hover	red-600
color/buttons/danger/active	--color-buttons-danger-active	red-700
color/interactive/primary/text	--color-interactive-primary-text	blue-600
color/interactive/primary/default	--color-interactive-primary-default	blue-400
color/interactive/primary/hover	--color-interactive-primary-hover	blue-300
color/interactive/subtle	--color-interactive-subtle	blue-50

Typography · Font Size

Figma path	CSS variable	Value
fontsize/headings/h1	--font-size-h1	90px
fontsize/headings/h2	--font-size-h2	67px
fontsize/headings/h3	--font-size-h3	51px
fontsize/headings/h4	--font-size-h4	38px
fontsize/headings/h5	--font-size-h5	28px
fontsize/headings/h6	--font-size-h6	21px
fontsize/body/lg	--font-size-body-lg	21px
fontsize/body/md	--font-size-body-md	16px
fontsize/body/sm	--font-size-body-sm	14px
fontsize/body/xs	--font-size-body-xs	12px

Typography · Font Weight

Figma path	CSS variable	Value
type/font weight/light	--font-weight-light	300
type/font weight/regular	--font-weight-regular	400
type/font weight/medium	--font-weight-medium	500
type/font weight/semibold	--font-weight-semibold	600
type/font weight/bold	--font-weight-bold	700

Typography · Line Height (ratio)

CSS variable	Value	Use
line height/ratio/tight	--line-height-tight	1	display, counters, large headings
line height/ratio/snug	--line-height-snug	1.2	compact text, sidebar, mono labels
line height/ratio/relaxed-sm	--line-height-relaxed-sm	1.33	small text xs/sm
line height/ratio/base	--line-height-base	1.5	standard body text
line height/ratio/relaxed	--line-height-relaxed	1.6	comfortable body
line height/ratio/loose	--line-height-loose	1.65	spacious descriptions, cards
line height/ratio/prose	--line-height-prose	1.75	article body, section leads
line height/ratio/code	--line-height-code	1.85	code blocks, dense mono

Spacing · Gap Scale

Figma path	CSS variable	Value
sizes/gap/none	--gap-none	0px
sizes/gap/px	--gap-px	1px
sizes/gap/xs	--gap-xs	4px
sizes/gap/sm	--gap-sm	8px
sizes/gap/md	--gap-md	16px
sizes/gap/lg	--gap-lg	24px
sizes/gap/xl	--gap-xl	32px
sizes/gap/2xl	--gap-2xl	48px
sizes/gap/3xl	--gap-3xl	64px
sizes/gap/4xl	--gap-4xl	80px
sizes/gap/5xl	--gap-5xl	96px
sizes/gap/section	--gap-section	128px
sizes/gap/layout	--gap-layout	192px
sizes/gap/page	--gap-page	256px

Spacing · Border Width

Figma path	CSS variable	Value
sizes/border/none	--border-none	0px
sizes/border/br-1	--border-1	1px
sizes/border/br-2	--border-2	2px
sizes/border/br-4	--border-4	4px

Color System

7 families built in OKLCH — perceptually uniform lightness steps from 50 (near-white) to 900 (near-black). Hover swatches for values.

Neutral

UI · Surface · Text

--color-neutral-50

--color-neutral-100

--color-neutral-200

--color-neutral-300

--color-neutral-400

--color-neutral-500

--color-neutral-600

--color-neutral-700

--color-neutral-800

--color-neutral-900

Blue

Interactive · Primary

--color-blue-50

--color-blue-100

--color-blue-200

--color-blue-300

--color-blue-400

--color-blue-500

--color-blue-600

--color-blue-700

--color-blue-800

--color-blue-900

Red

Error · Danger

--color-red-50

--color-red-100

--color-red-200

--color-red-300

--color-red-400

--color-red-500

--color-red-600

--color-red-700

--color-red-800

--color-red-900

Green

Success · Positive

--color-green-50

--color-green-100

--color-green-200

--color-green-300

--color-green-400

--color-green-500

--color-green-600

--color-green-700

--color-green-800

--color-green-900

Yellow

Warning · Caution

--color-yellow-50

--color-yellow-100

--color-yellow-200

--color-yellow-300

--color-yellow-400

--color-yellow-500

--color-yellow-600

--color-yellow-700

--color-yellow-800

--color-yellow-900

Orange

Alert · Notification

--color-orange-50

--color-orange-100

--color-orange-200

--color-orange-300

--color-orange-400

--color-orange-500

--color-orange-600

--color-orange-700

--color-orange-800

--color-orange-900

Purple

Category · Accent

--color-purple-50

--color-purple-100

--color-purple-200

--color-purple-300

--color-purple-400

--color-purple-500

--color-purple-600

--color-purple-700

--color-purple-800

--color-purple-900

White & Black

color/neutral/00

#FFFFFF

color/neutral/1000

#000000

Opacity Tokens — 5 steps

10%

25%

40%

60%

80%

overlay/subtle · default · strong
scrim · disabled-surface

components.css → h1–h6, .text-* token-bound

Typography

Three-font system: Bebas Neue for display and headings, Barlow for body and UI, JetBrains Mono for code and technical content. Scale follows the Perfect Fourth modular ratio (× 1.333).

Perfect Fourth derives every size by multiplying or dividing the base (16 px) by 4/3. The result is a geometric progression — each step is exactly 33% larger than the one below it — giving the scale a natural, harmonic rhythm without arbitrary intermediate values. Heading sizes grow quickly (21 → 28 → 38 → 51 → 67 → 90 px) to create clear visual hierarchy, while body sizes stay close to the base for comfortable reading.

Display / Headings

Bebas
Neue

Bebas Neue · Regular · 0.02em tracking

Used for H1–H6 headings, large display figures, section labels, and data callouts.

ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789 & ! @ # $ % ^ *

Code / Technical

Regular Bold

JetBrains Mono · 400 / 700 weights

Code snippets, token names, keyboard shortcuts, tabular data, and any technical content requiring monospaced alignment.

const scale = base * 1.333;
0123456789 → Il1 O0 :;.,

Body / UI

Light Regular
Medium Semibold

Barlow · 300 / 400 / 500 / 600 weights

Paragraphs, labels, captions, and all UI copy. 16px base size, 1.5 line-height.

The quick brown fox jumps over the lazy dog. 0–9
The quick brown fox jumps over the lazy dog.

H1
Display

Display Title

90px / lh 100px

fontsize/headings/h1

H2

Page Heading

67px / lh 78px

fontsize/headings/h2

H3

Section Title

51px / lh 61px

fontsize/headings/h3

H4

Component Header

38px / lh 48px

fontsize/headings/h4

H5

Subsection Label

28px / lh 37px

fontsize/headings/h5

H6

Small Heading

21px / lh 29px

fontsize/headings/h6

Body Scale — Barlow

Large · 21px

The quick brown fox jumps over the lazy dog. Editorial and intro copy.

21px / lh 32px

fontsize/body/lg

Default · 16px

The quick brown fox jumps over the lazy dog. Primary body text, paragraphs.

16px / lh 24px

fontsize/body/md

Small · 14px

Labels, helper text, secondary content and supplementary metadata.

14px / lh 18px

fontsize/body/sm

Caption · 12px

Caption, annotation, timestamps, and supplementary metadata at minimum size.

12px / lh 16px

fontsize/body/xs

Code · 12px

const scale = base * ratio; // inline code, snippets, tokens

12px / lh 16px

fontsize/body/xs

Paragraph Spacing

Style	Token	Value
H3	--paragraph-spacing-h3	32px
H4	--paragraph-spacing-h4	24px
H5	--paragraph-spacing-h5	20px
H6	--paragraph-spacing-h6	16px
Body LG	--paragraph-spacing-body-lg	32px
Body MD	--paragraph-spacing-body-md	24px
Caption	--paragraph-spacing-caption	18px

tokens.css → --gap-* · --sp-* token-bound

Spacing

Named gap tokens from 4px (--gap-xs) to 160px (--gap-layout), organised by use context.
Always reference a token — never hardcode spacing values.

0px --gap-none

1px --gap-px

4px --gap-xs

8px --gap-sm

16px --gap-md

24px --gap-lg

32px --gap-xl

48px --gap-2xl

64px --gap-3xl

80px --gap-4xl

120px --gap-section

160px --gap-layout

200px --gap-page

tokens.css → --radius-* token-bound

Corner Radius

Nine named values from 4px to pill (9999px).
Apply via --radius-* to keep rounding consistent across components.

--radius-4
4px

--radius-8
8px

--radius-12
12px

--radius-16
16px

--radius-24
24px

--radius-32
32px

--radius-48
48px

--radius-200
200px

--radius-full
9999px · pill

components.css → .divider token-bound

Dividers

Three weight variants — default, strong, and subtle — plus a vertical option for inline layouts.

.divider (default — --color-borders-default)

.divider.divider--strong

.divider.divider--subtle

.divider--vertical (inside flex row)

Left content

Right content

3 tenets

Principles

Three tenets that govern every animated element in the system.
Purposeful, perceptible, and always accessible.

Purposeful

Every animated element serves a function — confirming an action, revealing content, or guiding focus. Motion never exists purely for decoration.

Perceptible

Animations are fast enough to feel responsive but slow enough to be understood. Duration and easing are chosen for clarity, not effect.

Accessible

All animations respect prefers-reduced-motion. Users who opt out of motion get an equivalent non-animated experience.

tokens.css → --dur-* 3 tokens

Duration Scale

Three named durations cover the full range of UI interactions.
Avoid hardcoding millisecond values — always reference a token so the system can tune motion globally.

--dur-fast240ms · hover states, micro-feedback

--dur-base500ms · entrances, reveals, modals

--dur-slow720ms · hero reveals, page load

Token reference

/* Duration tokens */
--dur-fast:   240ms;  /* hover, micro-interactions */
--dur-base:   500ms;  /* standard entrance / exit */
--dur-slow:   720ms;  /* hero reveals, page transitions */

tokens.css → --ease-* 3 curves

Easing Functions

Easing functions define the feel of motion.
All three are expo-family curves to keep the system coherent.

--ease-expocubic-bezier(0.16, 1, 0.3, 1) · expo-out

--ease-quartcubic-bezier(0.25, 1, 0.5, 1) · quart-out

--ease-exitcubic-bezier(0.4, 0, 1, 1) · accelerate

Token reference

/* Easing tokens */
--ease-expo:  cubic-bezier(0.16, 1, 0.3, 1);  /* expo-out  — enter */
--ease-quart: cubic-bezier(0.25, 1, 0.5, 1);  /* quart-out — hover */
--ease-exit:  cubic-bezier(0.4, 0, 1, 1);    /* accelerate — exit */

shared.css → @keyframes 3 keyframes

Keyframe Catalog

Three reusable @keyframes for entrances and ambient loops.
Always reference by name — never define new keyframes outside this catalog.

slide-up

Fades in while translating 24 px upward. Used for scroll reveals, modal content, and staggered list entrances.

fade-in

Pure opacity transition from 0 → 1. Ideal for overlays, tooltips, and elements with no spatial movement.

↓

scroll-hint

Looping vertical oscillation with opacity fade. Used on scroll indicators in hero sections.

duration × easing

Composition

Any animation is a combination of a duration and an easing.
The matrix below maps which pairings are recommended, acceptable, or discouraged.

Duration	ease-expo	ease-quart	ease-exit
--dur-fast · 240ms	✓ Recommendedhover, badges, toggles	✓ Goodcolor transitions	✓ Recommendedquick exits
--dur-base · 500ms	✓ Recommendedscroll reveals, modals	✓ Goodlayout shifts	⚠ Cautionfeels abrupt at 500ms
--dur-slow · 720ms	✓ Recommendedhero, page load	✓ Goodambient motion	✗ Avoidtoo fast to notice

WCAG 2.3 AA · prefers-reduced-motion

Reduced Motion

Users may set a system-level preference to reduce motion.
FORMA respects this with global overrides in every page and a standard pattern for custom animations.

Standard override pattern

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
  .reveal { opacity: 1; transform: none; }
}

Animation fallback table

Animation	Standard behavior	Reduced motion fallback
slide-up	Fades + translates 24 px up over 720ms	Instant appearance, no movement
fade-in	Opacity 0 → 1 over 500ms	Instant appearance at full opacity
scroll-hint	Looping vertical oscillation	Static icon, no loop
hover transitions	Color, background, shadow in 240ms	Instant state change
count-up (JS)	Number animates from 0 over 900ms	Final value rendered immediately

4 structures

Layout

Page-level layouts provide consistent structure. All use CSS grid with token-based gaps and respect the 220 px sidebar offset.

Full bleed — audit, landing

Sidebar + content — components, guidelines

Bento grid — index hero

Split 2-col — editorial, about

5 states

Interaction States

Every interactive component moves through the same state model. Consistent states reduce cognitive load and make the system predictable.

Button

Default

Hover

Active

Focus

Disabled

Input

Default

Filled

Focus

Error

Disabled

metrics · tables · scores

Data Display

Metric cells

272

Design Tokens

↑ +12 this sprint

9

Components

↑ +1 new

98%

WCAG AA Coverage

— unchanged

4

Foundations

↓ −0 changes

Score bars

Accessibility

98%

Performance

91%

Token Coverage

100%

Design Debt

12%

Data table

Token	Category	Value	Status
--color-blue-500	Color · Primitive	#127ae6	Stable
--dur-fast	Motion · Duration	240ms	Stable
--radius-12	Border Radius	12px	Stable
--gap-section	Spacing · Layout	120px	Review
--shadow-xl	Effect · Elevation	0 24px 48px …	Draft

tabs · breadcrumb · sidebar

Navigation

Tabs

The Overview tab contains a high-level summary of the component, its purpose, and when to use it within the system.

The Tokens tab lists every CSS custom property the component consumes, with its resolved value and semantic meaning.

The Usage tab provides code snippets, do/don't guidance, and accessibility notes for implementing the component correctly.

Breadcrumb

toast · alert · loading · empty

Feedback

Toast notification

Changes saved

Your design tokens have been updated.

Alert variants

Info

Use this pattern to surface neutral context or informational tips to the user.

Success

Confirms a completed action. Keep the message short and specific.

Warning

Flags a potential issue that doesn't block the user but requires attention.

Error

Communicates a failure. Always explain what went wrong and how to fix it.

Loading states

Spinner

Skeleton

Empty state

No tokens found

Try a different search term, or add a new token to the system.

input states · validation · layout

Forms

Form patterns cover field states, inline validation, and two standard layouts.

Field states

DefaultLabelOptional helper text to guide the user.

FocusedLabelField has keyboard focus — 2 px blue outline.

ErrorEmail addressEnter a valid email address.

DisabledLabelThis field is currently unavailable.

Inline validation

Full nameUsed in your profile and invoices.

Work email *Complete the domain — e.g. moises@company.com

Guidelines Token Reference