A · Philosophy
1 · Name by purpose, not appearance
surface-page, not teal-10-bg. The value can change; the job doesn't.
2 · Category first
text-secondary, border-strong, space-16. Names sort and autocomplete by family.
3 · Semantic tokens, not literal colors
Components read primary, never teal-500. Ramp steps are for illustration and data viz.
4 · Separate tone from state
btn-primary-bg-hover reads component · tone · property · state, always in that order.
5 · Status is a role, not a colour
error, warning, success, info. Never red or green, and never teal.
6 · One name per concept
Shadows are elevation-* everywhere. Not shadow, lift or raise in different places.
7 · Surface is an attribute, not a name
data-surface="caregiver" on an ancestor. No .card--caregiver, no surface prop.
8 · Function overrides size
A 32px dose is dose-32 (mono), not title-32. The name says what the text is for.
9 · Same name in Figma and code
The Figma variable and the CSS variable share one name, so the handoff is transcription, not interpretation.
10 · No cryptic abbreviations
space-16, not sp-m. The only short forms are btn and doh, used everywhere.
B · Syntax
Lowercase, dashes only, category first. Square brackets mark optional parts.
| Layer | Pattern | Examples |
|---|---|---|
| Primitive color | category-step | teal-500 · neutral-1000 |
| Semantic color | category-role[-variant][-state] | text-secondary · primary-hover · alert-error-bg-strong |
| Component token | component-tone-property[-state] | btn-primary-bg-hover · badge-error-bg |
| Scale | category-value | space-16 · radius-8 · duration-fast · icon-16 |
| Type style | role-size[-weight] | body-16-strong · title-24 · dose-32 |
| Component class | doh-component[-part] | doh-card · doh-card-title |
| Modifier class | doh-component-variant | doh-alert-banner · doh-badge-error |
| Button (CSS module) | variant-name · size-name | variant-secondary · size-lg |
| Type class | type-style | type-body-16 · type-data-12 |
| Tailwind alias | utility-role | bg-page · text-ink · border-line-strong |
C · Taxonomy
1 · Foundations
Tokens: color, type, spacing, radius, elevation, motion, grid.
tokens/tokens.json
2 · Primitives
The smallest components; no other component inside.
Button · Input · Badge · Chip
3 · Composites
Built from primitives and anatomy parts.
Card · Alert · Modal · Tabs · List · Table
4 · Patterns
Recurring arrangements of composites across screens.
Story picker · Guide strip (planned)
5 · Product screens
Evantis screens for the Day One Home feature. Built from the layers above, never added to them.
Recovery plan · Medication log (planned)
6 · Internal anatomy
Named parts of a component, styled but not exported.
doh-card-eyebrow · doh-modal-actions
D · Properties
| Property | Values | Rule |
|---|---|---|
variant (Button) | primary · secondary · link · danger | One prop carries emphasis and meaning, as in Buttons V2. Danger only for remove or revoke. |
tone | neutral · error · warning · success · info (Badge, Alert) | Status tones only. No Badge or Alert is primary. |
variant (Alert) | inline · banner | Changes placement, never meaning. |
size | sm · md · lg | md is the default and is never written. |
State | aria-pressed · aria-selected · aria-busy · disabled | Where ARIA has a word for the state, the state is that attribute, not a prop. |
Surface | data-surface on an ancestor | Never a prop. Components read it. |
E · Tokens
Every token family, its prefix and how many exist today. Counts are read from tokens.json.
| Family | Prefix | Count | Example |
|---|---|---|---|
| Color primitives | neutral- teal- bronze- error- warning- success- info- | 125 | teal-500 |
| Color semantic | surface- text- border- primary btn- badge- alert- … | 88 | text-secondary |
| Spacing | space- | 14 | space-16 |
| Radius | radius- | 11 | radius-card-caregiver |
| Elevation | elevation- | 4 | elevation-1 |
| Duration | duration- | 4 | duration-fast |
| Easing | easing- | 2 | easing-enter |
| Grid | grid-columns- | 3 | grid-columns-mobile |
| Icon sizes | icon- | 11 | icon-16 |
| Type styles | display- title- body- label- caption- button- tag- data- dose- alert-title- | 27 | body-16 |
| Tailwind aliases | --color- | 54 | bg-page |
F · Anatomy
Parts are named by their job inside the component, and the component prop says the same word.
Do
<Card eyebrow title footer> renders doh-card-eyebrow, doh-card-title, doh-card-footer. One word per part, everywhere.
Don't
CardTopLabel, doh-card-bronze-text, header2. Position, colour and numbering say nothing about the job.
G · Figma correspondence
Figma decides foundations; code receives them. Same name on both sides, read-only direction.
| Figma | Code |
|---|---|
color / surface-page | --surface-page |
Text / body-16 | .type-body-16 |
space / space-16 | --space-16 |
Button · variant=secondary, size=sm | <Button variant="secondary" size="sm"> |
H · Anti-patterns
1 · Colour-based names
red-badge, teal-card. Use the role: Badge tone="error".
2 · Raw ramp in a component
var(--teal-500) inside a component. Point at a semantic token instead.
3 · Tailwind palette utilities
bg-blue-500. The default palette is removed in theme.css, so it no longer compiles.
4 · Ambiguous abbreviations
sp-s, clr-pri. Spell it out.
5 · Synonyms for one state
active, selected, on and current for the same thing. Use the ARIA attribute.
6 · Status by colour alone
A red dot with no glyph or word. Every status carries its glyph and a word.
7 · Fraunces for a number
title-32 on a dose. Doses are dose-32, mono.
8 · Surface baked into a name
.input--clinical. Set data-surface on an ancestor.
I · Decision tree
Before adding anything, answer in order. Stop at the first yes.
- Is there already a semantic token for this job? Use it.
- Is it a raw value no component reads directly? Add a primitive to tokens.json.
- Does a component need a role the semantic layer lacks? Add a semantic token that points at a primitive.
- Does only one component need it? Add a component token: component-tone-property-state.
- Is it a whole component the system doesn't have? List it under Components → Candidates before building.
- Unsure? Flag the gap. Never invent a value.
J · Migration audit
Where Evantis code departs from the rules above, and whether that is deliberate.
| Finding | Decision |
|---|---|
| DS classes use doh-, not evantis- | doh- is Day One Home, the system's name. Kept: renaming would touch every class and break parity with the design system artifact. |
| Tailwind aliases rename roles | text-ink instead of text-text-primary, because Tailwind's text- prefix would double up. One alias per role, listed under Tokens → @theme. |
| Lab classes are ds-lab-* | Copied from the Website-v2 lab with its names, so both labs read the same. They style the lab only, never the product. |
| Figma variables not linked yet | The token names are ready for one-to-one Figma variables; no Evantis Figma file is connected to code yet. |
K · Sources
| Source | What it settles |
|---|---|
| Notion · Decision Log (2026-09-24) | Token naming convention: three-tier, dash-separated, category-first. |
| Day One Home design system | Brand book, tokens.json and component guidelines (tokens/DESIGN-SYSTEM.md). |
| EightShapes · Nathan Curtis, Naming Tokens in Design Systems | Category, concept, property, variant, state ordering. |
| Adobe Spectrum | Global, alias and component token tiers. |