Design System Reference

Diátaxis: Reference

Sources: .impeccable.md, packages/design-tokens/src/index.ts, apps/mobile/lib/fonts.ts, apps/mobile/tailwind.config.ts

Brand Identity

Direction: Italian Sole — Grounded · Reassuring · Efficient

Hybrid aesthetic: Airbnb-warm (consumer booking) + Uber/Bolt-precise (SOS dispatch)

Persona: Italian tradesperson: reliable, no-nonsense, quality-proud. Not startup-flashy, not corporate-cold.

Color Tokens

Semantic Roles

Token	Hex	Role
`primary.500`	`#B35F3B`	Terracotta — primary CTA, active states
`secondary.500`	`#6E7F3C`	Olive — trust badges, Verificato, verified states
`neutral.50`	`#FAF6EE`	Cream — default background
`accent.500`	`#E89059`	Sun amber — warm accent, highlights
`neutral.900`	`#2B1E10`	Dark Ink — primary text
`sos.500`	`#E5484D`	SOS red — emergency dispatch only

Primary (Terracotta)

Scale	Hex
50	`#FBF3EE`
100	`#F5E3D7`
200	`#EBC6AF`
300	`#DFA987`
400	`#D48C5F`
500	`#B35F3B`
600	`#9E5234`
700	`#85432A`
800	`#6D3521`
900	`#532818`
950	`#391B10`

Secondary (Olive)

Scale	Hex
50	`#F4F6EE`
500	`#6E7F3C`
600	`#617035`
700	`#505D2B`
950	`#202510`

Accent (Sun Amber)

Scale	Hex
50	`#FEF6EE`
500	`#E89059`
600	`#CC7B4E`
950	`#442617`

SOS (Emergency Red)

Scale	Hex
50	`#FEF0F0`
500	`#E5484D`
600	`#CC3A3F`
950	`#3F0F11`

Neutral

Scale	Hex
0	`#FFFFFF`
50	`#FAF6EE`
100	`#F0EBE0`
200	`#DDD5C8`
300	`#C8BFB0`
400	`#B5A898`
500	`#8C7B6A`
600	`#6E5E4F`
700	`#4D3F32`
800	`#3D2E1C`
900	`#2B1E10`
950	`#1A1008`

Semantic CSS Vars (Tailwind)

Var	Usage
`text`	Primary text
`background`	Page background
`foreground`	Inverted surface text

Typography

Font Families

Source: apps/mobile/lib/fonts.ts — single source of truth for all fontFamily refs.

Key	Font	Usage
`display`	`Gambarino-Regular`	Hero titles, brand logo, decorative headings
`thin`	`Switzer-Thin`	—
`light`	`Switzer-Light`	—
`regular`	`Switzer-Regular`	Default body text
`medium`	`Switzer-Medium`	Buttons, labels
`semibold`	`Switzer-Semibold`	Section titles, CTAs
`bold`	`Switzer-Bold`	Headings, prices, numbers
`extrabold`	`Switzer-Extrabold`	Hero numerics
`black`	`Switzer-Black`	Display-scale numerics only

Tailwind semantic aliases: sans / body → Switzer-Regular; heading → Switzer-Bold

Both fonts from Fontshare. Locked 2026-04-19.

Font Scale

Token	Size (px)
`2xs`	11
`xs`	12
`sm`	14
`base`	16
`lg`	18
`xl`	20
`2xl`	24
`3xl`	30
`4xl`	36
`5xl`	48

Line Height

Token	Value
`tight`	1.2
`snug`	1.3
`normal`	1.5
`relaxed`	1.6

Letter Spacing

Token	Value (px)
`tighter`	−0.44
`tight`	−0.24
`normal`	0
`wide`	+0.4

Spacing (8px Grid)

Token	px
`0.5`	2
`1`	4
`1.5`	6
`2`	8
`3`	12
`4`	16
`5`	20
`6`	24
`8`	32
`10`	40
`12`	48
`16`	64
`20`	80
`24`	96

Border Radius

Token	px
`xs`	4
`sm`	8
`md`	12
`lg`	16
`xl`	24
`2xl`	32
`full`	9999

Shadows

Token	Details
`sm`	offset (0,1), opacity 0.05, radius 2, elevation 1
`md`	offset (0,2), opacity 0.08, radius 8, elevation 3
`lg`	offset (0,4), opacity 0.12, radius 16, elevation 6
`sos`	color `#E5484D`, offset (0,4), opacity 0.3, radius 16, elevation 8

Motion

Spring Configs (react-native-reanimated)

Name	Damping	Stiffness	Mass
`spring`	15	150	1
`bouncy`	10	120	1
`gentle`	20	100	1

Duration

Token	ms
`fast`	150
`normal`	300
`slow`	500

Z-Index

Token	Value
`base`	0
`card`	10
`sticky`	20
`overlay`	30
`modal`	40
`toast`	50

Hard Bans

These are never permitted:

Side-stripe borders (>1px border-left accent lines)
Gradient text (background-clip: text)
Glassmorphism (backdrop-filter: blur + semi-transparent bg)
Stock purple→blue gradients
“Big number + small label” hero metrics as decoration
Pure black (#000000) or pure white (#FFFFFF) — use neutral.900 / neutral.0

Auth Pattern

Identifier-first unified flow via Clerk:

Component: <SignIn /> with signUpForceRedirectUrl
Single convergence route: /(welcome)/continue
Sign-up diverges at step 2: name + phone + role chip (consumer | professional)

Blueprint Constraints

Eight canonical constraints govering every screen:

Home = ChatGPT-style prompt (search via conversational triage)
Conversational triage: 4–6 questions max
Multi-quote comparison UI
Verificato badge is first-class (not a footnote)
Two pricing display modes (fixed vs. estimate range)
Pre-booking contact masking (no phone/email exposed until confirmed)
SOS flow lives separately from normal booking
Italian price certainty — no ambiguous “from €X” without ceiling

Design Principles

Clarity over decoration — every element earns its place
Grounded confidence — warm but not whimsical
Systematic consistency — tokens, not one-offs
Accessibility first — contrast ratios, touch targets ≥44px
Motion with purpose — spring physics, never gratuitous
Italian craft quality — precision in spacing and type