Evantis

Design System

Naming

  • 10principles
  • 10name patterns
  • 8anti-patterns
How tokens, classes and components are named in Evantis, and why. Same anatomy as the Website-v2 naming page. Read it before adding a token or a component, whether you're a person or an agent.

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.

LayerPatternExamples
Primitive colorcategory-stepteal-500 · neutral-1000
Semantic colorcategory-role[-variant][-state]text-secondary · primary-hover · alert-error-bg-strong
Component tokencomponent-tone-property[-state]btn-primary-bg-hover · badge-error-bg
Scalecategory-valuespace-16 · radius-8 · duration-fast · icon-16
Type stylerole-size[-weight]body-16-strong · title-24 · dose-32
Component classdoh-component[-part]doh-card · doh-card-title
Modifier classdoh-component-variantdoh-alert-banner · doh-badge-error
Button (CSS module)variant-name · size-namevariant-secondary · size-lg
Type classtype-styletype-body-16 · type-data-12
Tailwind aliasutility-rolebg-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

PropertyValuesRule
variant (Button)primary · secondary · link · dangerOne prop carries emphasis and meaning, as in Buttons V2. Danger only for remove or revoke.
toneneutral · error · warning · success · info (Badge, Alert)Status tones only. No Badge or Alert is primary.
variant (Alert)inline · bannerChanges placement, never meaning.
sizesm · md · lgmd is the default and is never written.
Statearia-pressed · aria-selected · aria-busy · disabledWhere ARIA has a word for the state, the state is that attribute, not a prop.
Surfacedata-surface on an ancestorNever a prop. Components read it.

E · Tokens

Every token family, its prefix and how many exist today. Counts are read from tokens.json.

FamilyPrefixCountExample
Color primitivesneutral- teal- bronze- error- warning- success- info-125teal-500
Color semanticsurface- text- border- primary btn- badge- alert- …88text-secondary
Spacingspace-14space-16
Radiusradius-11radius-card-caregiver
Elevationelevation-4elevation-1
Durationduration-4duration-fast
Easingeasing-2easing-enter
Gridgrid-columns-3grid-columns-mobile
Icon sizesicon-11icon-16
Type stylesdisplay- title- body- label- caption- button- tag- data- dose- alert-title-27body-16
Tailwind aliases--color-54bg-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.

FigmaCode
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.

  1. Is there already a semantic token for this job? Use it.
  2. Is it a raw value no component reads directly? Add a primitive to tokens.json.
  3. Does a component need a role the semantic layer lacks? Add a semantic token that points at a primitive.
  4. Does only one component need it? Add a component token: component-tone-property-state.
  5. Is it a whole component the system doesn't have? List it under Components → Candidates before building.
  6. Unsure? Flag the gap. Never invent a value.

J · Migration audit

Where Evantis code departs from the rules above, and whether that is deliberate.

FindingDecision
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 rolestext-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 yetThe token names are ready for one-to-one Figma variables; no Evantis Figma file is connected to code yet.

K · Sources

SourceWhat it settles
Notion · Decision Log (2026-09-24)Token naming convention: three-tier, dash-separated, category-first.
Day One Home design systemBrand book, tokens.json and component guidelines (tokens/DESIGN-SYSTEM.md).
EightShapes · Nathan Curtis, Naming Tokens in Design SystemsCategory, concept, property, variant, state ordering.
Adobe SpectrumGlobal, alias and component token tiers.