Design system
The authoritative reference for engineers building Halwel surfaces. Extracted from the shipped components in packages/ui. Where this page and a shipped component disagree, the component file is the truth — update this page.
tokens.css is the single source for every value below. Never hard-code a color, font, or spacing at a call site.
Color — every color has a job
Two grounds, two registers. Deep Sea for emotional/marketing moments; warm cream for clinical/reading sections. A section picks one and commits — roughly 60% primary / 30% neutral / 10% accent. Color is functional, never decorative.
Type — semantic tokens, font-agnostic
Reference tokens everywhere; the family swaps in tokens.css without touching a component. Silenon is single-weight — always font-weight: 400; size and color carry hierarchy.
Layout — the section primitive
Every section caps content at a centered container and pads the wrapper — not the capped inner — so full-bleed grounds meet the edge while text stays measured.
The rule. Sections cap at --hw-container (1240px) centered, with edge padding via --hw-section-x (clamp(20px, 5vw, 24px)) on the section wrapper. The signature frame primitive (PhotoFrame) sits a product render on a warm studio backdrop inside a rounded inset — the recurring hero motif.
Component inventory
Every primitive, section, and pattern shipped in packages/ui, demoed live. Open a group to see variants and props.
Brand
The Halwel wordmark, mark, and brand primitives every surface shares.
Wordmark · Logo & markFoundations
Color, type, spacing, radii, motion, elevation.
Colors · Themes · Typography · Spacing · Radii · Motion · ElevationForms
Every form-input pattern, the staple of onboarding.
Text input · Email input · Phone input · Number input · Textarea · Date input · Address · Binary choice · Single select · Multi select · Dropdown · Acknowledgement · Calculated value · Split field row · Step navigation · Progress indicator · Question group · MFA enrollment · Step-upDashboard
Primitives that compose the patient, provider, and hq surfaces.
Hero header · Section header · Stat card · Status card · Portal card · Portal card list · Offer card · Status row · Data table · Empty state · Loading skeleton · Badge · Toolbar · Tabs · Segmented control · CheckboxLayout
Shells, sidenav, topnav, responsive states.
Dashboard shell · Settings layout · Form shell · Form engine demo · Journey map nav · Sidenav · Scroll fade · Topnav · Responsive statesProduct
Storefront primitives — the catalog-driven product page, on its cream ground.
Price card · Product offer card · Price from · Segmented track · Product card gridMarketing
Public-site conversion chrome — the announcement bar, the sticky mobile CTA, the footer trust grid, and the prose band.
Announcement bar · Sticky mobile CTA · Trust grid · Prose section · Prose callout · Section intro · Treatment principles · Evidence summary · Journey scroll · Photo carousel · Vial CTAPatterns
Composed examples — how primitives combine.
Dashboard home · Work queue · Detail page · Editor + live preview · Confirm + progress · Carousel dots · Photo cluster · Portrait cinema hero · Cinematic media chapter · Setting card gridMotion & interaction
Motion is a quiet cue, never a performance. Everything honours prefers-reduced-motion.
CTA lift. The canonical CTA rises 2px on hover with a soft shadow (0.28s ease). One primitive, one destination — “Check your eligibility”.
Mechanism art. On product pages the “how it works” icons animate — a stomach gear spins, a brain appetite-dial rocks — small, looping, meaning-first.
Voice & the evidence layer
Plain, calm, evidence-first. We would rather a patient understand the medicine than take our word for it.
Copy rules. Normal casing everywhere (the old all-lowercase rule is retired). Mechanism copy explains how a medicine acts, never promises an outcome. Every clinical figure carries a citation in the mono register; anything awaiting sign-off is flagged [VERIFY] on the page until counsel + clinical clear it.
Gotchas — learned the hard way
Never stark white grounds — cards are --color-card-cream, not #fff. Text on patina-blue is Ink, never white. Terracotta is for genuine warnings only — unavailable things are driftwood-gray, not red. One CTA primitive (MarketingCta) — don't hand-roll buttons. Domains come from @halwel/config — never hard-code a host.