Professional Divi 5 Design System Guide

Design System Guide

A practical guide for building clean, consistent, client-ready Divi 5 websites. Use it to choose colors, type, spacing, layout rhythm, and UI details with confidence.

76 Color Tokens 2 Typefaces 8 Spacing Steps 8 Gap Steps Divi 5 Native Fluid Clamp Values 133 Design Tokens

💡

Design Philosophy

The core principles behind every design decision in this system.

🔗

Single Source of TruthThe palette starts with one core value: --primary: #0179cb. Update the primary color and the connected tints, shades, secondary color, and semantic tokens follow. Avoid hardcoded values in real projects — use the system instead.

Variables over values

Use system tokens instead of one-off hex, px, or rem values. This keeps the website easier to update, easier to rebrand, and harder for clients to accidentally break.

Fluid by default

Typography, spacing, and layout gaps use clamp() values, so layouts respond smoothly between mobile and desktop without extra breakpoints.

Semantic naming = intentional decisions

Use color-bg-subtle instead of color-neutral-50 even when both currently resolve to the same color. Semantic names describe purpose, so future theme changes are safer and faster.

Scale discipline

Use the defined scales for spacing, gaps, type sizes, and radii. Random values create visual noise. Scale discipline is what makes a layout feel professionally designed.

🎨

Brand Colors

The core brand colors and supporting variants used across the system.

Primary & Secondary

Primary Color

Primary #0179cb

The main brand color for buttons, links, highlights, and key actions.

Secondary Color

Secondary 180° hue

Complementary accent for contrast, highlights, and secondary emphasis.

Heading Color

Heading −60 lightness

A deep brand-tinted color for strong, polished headings.

Primary Tints — Lightness +

Base

Tint 1
+7L

Tint 2
+20L

Tint 3
+34L

Tint 4
+47L

Token	Δ Lightness	Best Use
primary-color-tint-1	+7	Hover states for primary buttons and links
primary-color-tint-2	+20	Focus rings, active states, and selected UI elements
primary-color-tint-3	+34	Soft accents, illustrations, and icon backgrounds
primary-color-tint-4	+47	Light backgrounds, disabled states, and subtle panels

Primary Shades — Lightness −

Shade 1
−10L

Shade 2
−27L

Shade 3
−43L

Shade 4
−60L

Token	Δ Lightness	When to Use
primary-color-shade-1	−10	Pressed states and active controls
primary-color-shade-2	−27	Dark-section accents and footer highlights
primary-color-shade-3	−43	Deep background sections and overlays
primary-color-shade-4	−60	Heading color — same visual role as `Heading`

Alpha Variants

primary-alpha-glow

Primary · 50%

Soft primary glow for cards, highlights, and background effects.

primary-alpha-shadow

Shadow · 50%

Dark brand shadow for depth, overlays, and premium UI effects.

secondary-alpha-glow

Secondary · 50%

Soft secondary glow for contrast accents and supporting visuals.

⬜

Neutral Scale

The neutral scale controls backgrounds, text, dividers, borders, and interface depth.

100

200

300

400

500

600

700

800

900

950

Token	Hex	Primary Use
`color-neutral-50`	`#fafafa`	Page background, card backgrounds on white
`color-neutral-100`	`#f4f5f5`	Alternate row background, input fill
`color-neutral-200`	`#e5e6e7`	Default border, dividers, rule lines
`color-neutral-300`	`#d5d6d7`	Strong border, focused form field borders
`color-neutral-400`	`#a3a5a8`	Subtle text, icons, placeholder text
`color-neutral-500`	`#737679`	Muted body text, captions
`color-neutral-600`	`#54575a`	Secondary body text
`color-neutral-700`	`#404245`	Supporting headings on light backgrounds
`color-neutral-800`	`#282929`	Dark section backgrounds (inverse-subtle)
`color-neutral-900`	`#181a1b`	Dark section backgrounds, footers
`color-neutral-950`	`#0e0f10`	Near-black, deep dark sections

🏷️

Semantic Color Tokens

Purpose-based color names that make design decisions clearer and safer.

⚠️

Design by purpose, not by numberUse color-bg-default for a page background instead of choosing color-neutral-50 directly. The result may look the same today, but the semantic token protects the design when the theme changes later.

Text Tokens

Token	Resolved From	Use Case
color-text-primary	Primary color	CTAs, links, highlighted text
Heading Text Color	Primary −60L	All H1–H6 headings
Body Text Color	= Heading color	All body paragraphs
color-text-muted	Neutral 500	Captions, secondary labels, meta text
color-text-subtle	Neutral 400	Placeholder text, disabled labels
color-text-inverse	Neutral 50	Text on dark / colour backgrounds

Background Tokens

Token	Resolved From	Use Case
color-bg-default	Neutral 50	Main page background
color-bg-subtle	Neutral 50	Card backgrounds, alternate sections
color-bg-muted	Neutral 100	Input backgrounds, tag chips
color-bg-inverse	Neutral 900	Dark hero sections, footers
color-bg-inverse-subtle	Neutral 800	Secondary dark sections, dark cards

Border Tokens

Token	Resolved From	Use Case
color-border-subtle	Neutral 100	Dividers, ghost card outlines
color-border-default	Neutral 200	Form fields, default UI borders
color-border-strong	Neutral 300	Focused inputs, table borders
color-border-inverse	Neutral 700	Borders on dark backgrounds

🚦

Status Colors

Use these colors only for alerts, validation, confirmations, and feedback states.

Success

Subtle
#dcfce7

Default
#16a34a

Text
#14532d

Error

Subtle
#fee2e2

Default
#dc2626

Text
#7f1d1d

Warning

Subtle
#fef3c7

Default
#d97706

Text
#78350f

Info

Subtle
#dbeafe

Default
#2563eb

Text
#1e3a8a

✅

Always use the three-layer patternEach status includes a subtle background, a stronger icon/border color, and a darker text color. Use the full set together so alerts stay readable and consistent.

📋

Color Usage Rules

Rules that keep the interface clean, readable, and easy to use.

Primary color = action only

Reserve primary color for actions: buttons, links, focus rings, and CTAs. When everything is blue, nothing feels clickable.

🎯

Secondary ColorThe secondary color is included as a supporting accent. Use it sparingly for contrast, feature highlights, badges, and secondary emphasis — not as a replacement for the primary action color.

Never use more than 2 brand colours per section

Primary plus secondary is enough. Let neutrals and white space do the heavy lifting. Too much color makes the design feel busy and cheap.

Text on colour must pass WCAG AA

Use high-contrast text on colored backgrounds. Avoid placing body copy on light tints unless contrast has been checked.

Dark sections use inverse tokens only

On dark backgrounds, use color-text-inverse, color-border-inverse, and color-hover-dark. Do not reuse light-section text and border tokens inside dark sections.

Status colours are communication tools, not decoration

Do not use green, red, amber, or info-blue as decoration. Users read these colors as success, error, warning, and information.

🔤

Typefaces

Two typefaces with clear roles: one for personality, one for readability.

Heading Font · --font-heading

Poppins — Heading font

The quick brown fox jumps

over the lazy dog

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z & 0 1 2 3 4 5 6 7 8 9

Body Font · --font-body

Inter — Body font

The quick brown fox jumps over the lazy dog.

Inter is engineered for screen legibility. Its generous x-height and open apertures maintain clarity across retina and standard displays. The letterforms are neutral without being sterile — they recede to let content lead, exactly what body copy demands at any scale.

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z & 0 1 2 3 4 5 6 7 8 9

ℹ️

Pairing logicPoppins gives headings a confident, modern voice. Inter keeps paragraphs and UI text easy to read. Keep these roles consistent so the system feels intentional.

📐

Type Scale

All sizes use fluid clamp() values that scale smoothly from mobile to desktop.

Display Sizes — Hero / Landing Only

Token	CSS Variable	Min → Max	Clamp Value	Use
Display LG	`--display-lg`	64 → 128px	`clamp(4rem, calc(8vw + 2rem), 8rem)`	Main hero statement. Use once per page.
Display MD	`--display-md`	56 → 96px	`clamp(3.5rem, calc(6vw + 2rem), 6rem)`	Large hero support lines and major feature sections.
Display SM	`--display-sm`	48 → 72px	`clamp(3rem, 2.44vw + 2.42rem, 4.5rem)`	Large section headlines and editorial callouts.

Heading Scale — H1 to H6

Tag	CSS Variable	Min → Max	Clamp Value	Preview
`H1`	`--h1`	36 → 48px	`clamp(2.25rem, 2rem + 1vw, 3rem)`	Page Title
`H2`	`--h2`	30 → 36px	`clamp(1.875rem, 1.6rem + 0.7vw, 2.25rem)`	Section Heading
`H3`	`--h3`	24 → 30px	`clamp(1.5rem, 1.3rem + 0.6vw, 1.875rem)`	Subsection Heading
`H4`	`--h4`	20 → 24px	`clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem)`	Card Heading
`H5`	`--h5`	17 → 20px	`clamp(1.0625rem, 0.95rem + 0.4vw, 1.25rem)`	Minor Heading
`H6`	`--h6`	14 → 17px	`clamp(0.875rem, 0.8rem + 0.3vw, 1.0625rem)`	Label / Eyebrow

Body & Small Text

Token	CSS Variable	Clamp Value	Use
body-text-lg	`--body-text-lg`	`clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem)`	Hero intro text and important lead paragraphs
body-text	`--body-text`	`clamp(1rem, 0.90rem + 0.40vw, 1.25rem)`	Standard paragraphs and long-form content
text-s	`--text-s`	`clamp(0.875rem, 0.82rem + 0.28vw, 0.9375rem)`	Labels, captions, navigation, compact UI text
text-xs	`--text-xs`	`clamp(0.75rem, 0.70rem + 0.20vw, 0.875rem)`	Fine print, legal text, timestamps, small meta text

↕️

Line Height

Line-height presets that control rhythm, density, and readability.

Token	CSS Variable	Value	Use
`leading-none`	`--leading-none`	1em	Single-line display text, logos, eyebrows — no space for descenders
`leading-tight`	`--leading-tight`	1.1em	Display headings, hero type, H1. Creates visual mass in large type.
`leading-snug`	`--leading-snug`	1.2em	H2–H4 headings, card titles, subheadings
`leading-normal`	`--leading-normal`	1.3em	All body copy, paragraph text, UI text — default for Inter

✅

Simple rule: larger type needs tighter leadingDisplay → leading-tight. H2–H4 → leading-snug. Body → leading-normal. Never use leading-normal on display headings — it creates ungainly gaps.

↔️

Letter Spacing

Letter-spacing presets for hierarchy, polish, and optical correction.

Token	CSS Variable	Value	Use
`tracking-tight`	`--tracking-tight`	−0.02em	Display type and H1. Corrects optical gaps in large type.
`tracking-normal`	`--tracking-normal`	0em	Default — all body text and most headings. Do not override without intent.
`tracking-wide`	`--tracking-wide`	+0.05em	Small caps, button labels, H6 eyebrow headings.
`tracking-wider`	`--tracking-wider`	+0.1em	Section labels, all-caps decorative text, navigation eyebrows.

📝

Typography Usage Rules

The rules that separate professional from amateur typography.

One typeface per role — no exceptions

Poppins for headings. Inter for body. Never mix within the same element or swap for "variety." Variety comes from weight and scale, not typeface changes.

Maximum 3 type sizes per section

One heading size, one body size, optionally one label size. Using 5+ sizes in a section creates visual chaos and signals lack of design confidence.

Apply tracking-tight to all display type

Any heading above H2 must have --tracking-tight applied. At large sizes, normal tracking creates optical gaps that make type feel loose.

Limit line length to 65–75 characters

Body copy spanning the full width of wide screens is fatiguing. Constrain paragraph containers to ~700–800px max-width. This is the "measure" in typography.

Use weight — not colour — for hierarchy

H1–H2 = 700. H3–H6 = 600. Colour-coding headings for hierarchy creates clutter, not clarity.

📏

Spacing Scale

8-step scale for padding and margins. All values are fluid clamp() from the JSON.

ℹ️

Spacing vs Gapspace-* tokens → padding and section breathing room. gap-* tokens → grid/flex gaps between elements. They have different scales because padding and gap serve different visual functions.

Token	CSS Variable	Min	Max	Visual	Use For
`space-0`	`--space-0`	0	0		Removing spacing intentionally
`space-xs`	`--space-xs`	8px	12px	8–12px	Badge padding, icon margins, tight internal spacing
`space-s`	`--space-s`	12px	16px	12–16px	Button padding, list item spacing, label margins
`space-m`	`--space-m`	16px	24px	16–24px	Card padding, paragraph bottom margin, nav items
`space-l`	`--space-l`	24px	40px	24–40px	Section internal padding, heading bottom margin
`space-xl`	`--space-xl`	32px	64px	32–64px	Section top/bottom padding, content blocks
`space-2xl`	`--space-2xl`	48px	96px	48–96px	Hero section padding, major section separators
`space-3xl`	`--space-3xl`	64px	128px	64–128px	Full-screen sections, dramatic vertical breathing room

🔲

Gap Scale

8-step scale for grid and flex gaps. All values are fluid clamp() from the JSON.

Token	CSS Variable	Min	Max	Visual	Use For
`gap-0`	`--gap-0`	0	0		Flush grids, borderless button groups
`gap-xs`	`--gap-xs`	8px	12px	8–12px	Icon + label, tag chips, inline button groups
`gap-s`	`--gap-s`	12px	20px	12–20px	Horizontal nav links, compact card grids
`gap-m`	`--gap-m`	16px	28px	16–28px	Standard card grids (3-col), feature lists
`gap-l`	`--gap-l`	24px	40px	24–40px	2-col content layouts, team grids
`gap-xl`	`--gap-xl`	32px	56px	32–56px	Hero two-col layouts, large feature blocks
`gap-2xl`	`--gap-2xl`	40px	80px	40–80px	Split-screen layouts, alternating content rows
`gap-3xl`	`--gap-3xl`	56px	112px	56–112px	Full-width feature sections, dramatic two-col layouts

📋

Spacing Usage Rules

The discipline that makes layouts feel designed, not assembled.

Always step up for section-level spacing

Component padding uses space-m to space-l. Section padding uses space-xl to space-3xl. Never use space-s as section padding — it suffocates the layout.

Never skip more than 2 steps

Moving from space-xs directly to space-3xl within the same component creates jarring proportion jumps. Step progressively — each step is approximately 1.5× the previous.

Gap should be smaller than surrounding section padding

If your section has space-xl padding, use gap-l or gap-m for the inner grid. Gaps should never compete with the breathing room around the section container.

Heading margin-bottom = space-s or space-m only

Headings must feel attached to the content below. Use space-s between a heading and its body copy. Oversize margins disconnect headings from their context.

⬛

Border Radius

The system uses one consistent radius: 4px. This keeps every card, button, input, pill, and panel visually aligned.

Default Radius

4px · Cards and panels

Control Radius

4px · Buttons and inputs

Label Radius

4px · Tags and pills

Preview Radius

4px · Swatches and demos

⚠️

Radius consistency ruleUse 4px across the interface. Do not mix 8px, 16px, 24px, and full-pill rounding in the same guide. Multiple radius sizes make the system look accidental instead of designed.

📦

Border Width

Six border thickness presets for structure, state, and emphasis.

border-none

0px

border-xs

1px — Default UI

border-s

2px — Focus state

border-m

3px — Highlighted card

border-l

4px — Featured card

border-xl

6px — Decorative

⚡

Animation Timing

Three speed presets for a consistent, polished motion feel.

150ms

duration-fast

Hover states, tooltips, icon swaps. Should feel near-instant.

250ms

duration-base

Dropdowns, modals, slide-ins. Default for all UI transitions.

400ms

duration-slow

Page transitions, image fades, dramatic reveals.

✅

Always pair with easingUse ease-out for elements entering. ease-in for elements leaving. ease-in-out for state toggles like accordions. Never use linear for UI transitions — it feels mechanical.

✅

Approved Design Combinations

Pre-approved token pairings for the most common UI patterns.

Pattern	Background	Text	Border	Radius	Padding
Standard Card	color-bg-subtle	Heading + body	color-border-default / border-xs	radius-m	space-l
Feature Card	color-bg-default	Heading + body	Primary / border-l	radius-m	space-l
CTA Button	Primary	color-text-inverse	none	radius-full	space-s × space-m
Ghost Button	transparent	Primary	Primary / border-s	radius-full	space-s × space-m
Hero Section	color-bg-default	Heading + body-text-lg	none	—	space-3xl (Y) space-xl (X)
Dark Section	color-bg-inverse	color-text-inverse	color-border-inverse	—	space-2xl (Y) space-xl (X)
Form Input	color-bg-muted	Body color	color-border-default / border-xs	radius-s	space-s × space-m
Alert / Notice	Status subtle bg	Status text	Status default / border-xs	radius-m	space-m
Navigation Bar	color-bg-default	Body + primary (active)	color-border-subtle (bottom)	—	space-m (Y) space-xl (X)
Footer	color-bg-inverse	color-text-inverse + muted	color-border-inverse (top)	—	space-2xl (Y)
Testimonial Block	color-bg-subtle	Heading + body	primary-tint-3 / border-xl (left)	radius-m	space-l
Pricing Card (Featured)	Primary	color-text-inverse	none	radius-l	space-xl

🚫

Anti-Patterns to Avoid

The most common mistakes that break design consistency and professionalism.

🚫

Using hardcoded hex valuesThe moment you type #0179cb anywhere other than the Primary token definition, you have broken the system. Client rebrands become multi-file nightmares. Always reference token names.

🚫

Inventing spacing valuesPadding of 37px, margin of 22px, gap of 11px — these break the visual rhythm that makes a layout feel designed. If it is not in the scale, do not use it.

🚫

Using status colors decorativelyA green section background reads "success." An amber banner reads "warning." These colours carry universal UI meaning. Decorative use destroys trust.

🚫

Mismatching radius across a pageUse radius-m for cards and panels, radius-s for compact controls, and radius-full only for pills or circles. Random radius changes make the system feel unfinished.

🚫

Display text without tracking-tightLarge headings at default tracking look loose and amateur. Any text at H1 or above must have --tracking-tight (−0.02em) applied.

🚫

Dark sections with light-mode text tokensPlacing Body Text Color (near-black) on a dark background creates invisible text. Dark sections must always use color-text-inverse and color-hover-dark.

✅

Designer Delivery Checklist

Use this before handing a website to a client or publishing a template.

Check hierarchy at a glance

The page should make sense in five seconds: one clear headline, one clear action, and supporting sections that follow a logical order.

Use spacing consistently

Sections, cards, headings, and content blocks should use the defined spacing and gap scales. Avoid custom one-off values unless there is a strong design reason.

Test mobile first

Review the design at mobile, tablet, and desktop widths. Headings should wrap cleanly, buttons should remain easy to tap, and sections should not feel cramped.

Audit color contrast

Check every button, link, alert, and dark section for readable contrast. Do not rely on visual judgement alone for accessibility.

Remove design drift

Scan for random font sizes, hardcoded colors, inconsistent button styles, and spacing values outside the system. These are the details clients notice, even when they cannot name them.