@emilioc/helix-ds

Helix Design System — React component library and token kit for Praxys products.

Overview

Helix is the cross-product design system for the Praxys pharma ecosystem. This npm package provides:

Semantic design tokens converted from the Flutter token source (helix_tokens.dart v2.2) — 184 tokens across colors, spacing, radius, size, typography, shadows, motion, and border widths.
React components built with zero external dependencies (besides React itself), consuming only Helix tokens — no hardcoded values anywhere.
AI guidelines in guidelines/ for use with Figma Make and LLM-assisted UI generation.

Installation

npm install @emilioc/helix-ds
# peer dependencies
npm install react react-dom

Font setup

Helix uses Figtree as its only font family. Load it before using any component:

<!-- In your HTML <head> -->
<link
  href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&display=swap"
  rel="stylesheet"
/>

Usage

Components

import { Button, Badge, Input, Text } from '@emilioc/helix-ds';

// Primary call-to-action
<Button variant="primary" size="md" onClick={handleSave}>
  Save
</Button>

// Destructive action
<Button variant="destructive" size="md" onClick={handleDelete}>
  Delete
</Button>

// Loading state — blocks interaction, shows spinner
<Button variant="primary" loading>
  Saving…
</Button>

// Subtle secondary action
<Button variant="subtle" size="sm">
  Cancel
</Button>

// Status badges
<Badge status="success">Active</Badge>
<Badge status="error">Error</Badge>
<Badge status="warning">Pending</Badge>
<Badge status="info">Info</Badge>
<Badge status="neutral">Draft</Badge>

// Input — standard appearance with focus ring
<Input
  label="Patient name"
  placeholder="Enter full name"
  helperText="As it appears on the prescription"
/>

// Input — error state
<Input
  label="Email"
  value={email}
  onChange={e => setEmail(e.target.value)}
  error="Enter a valid email address"
/>

// Input — flat appearance (no border, only bottom line)
<Input
  appearance="flat"
  label="Search"
  placeholder="Search records…"
/>

// Typography
<Text variant="headingLg">Patient records</Text>
<Text variant="bodyMd" color={HelixColors.text.secondary}>
  Last updated 5 minutes ago
</Text>
<Text variant="labelSm" as="label" htmlFor="input-id">
  Prescription number
</Text>

Tokens

import {
  HelixColors,
  HelixSpacing,
  HelixRadius,
  HelixMotion,
  HelixTypography,
  HelixShadow,
} from '@emilioc/helix-ds';

// Color tokens
const primaryBlue = HelixColors.action.primary.default; // '#157BB5'
const errorRed    = HelixColors.fill.errorDefault;      // '#DC2837'

// Spacing
const paddingMd = HelixSpacing.paddingComponent.md; // 12 (px)

// Motion
const hoverTransition = HelixMotion.micro.transition('background-color');
// → 'background-color 100ms cubic-bezier(0.4, 0.0, 0.2, 1.0)'

// Shadow
const cardShadow = HelixShadow.md;
// → '0px 4px 6px -2px rgba(18,18,23,0.051)'

// Typography styles
const heading = HelixTypography.headingLg;
// → { fontFamily: 'Figtree, sans-serif', fontSize: 24, fontWeight: 600, lineHeight: 1.3333 }

Token architecture

Helix follows a 3-layer token model:

Layer 1: Primitive  → raw values  (primary/500: #157BB5)
Layer 2: Semantic   → usage role  (action.primary.default → primary/500)
Layer 3: Component  → in progress (button-bg-primary → action.primary.default)

Rule: always consume semantic tokens. Never use primitive values or hex literals directly in component code.

Components reference

Component	Variants	States
`Button`	primary, destructive, featured, subtle	default, hover, pressed, focus, disabled, loading
`Badge`	success, warning, error, info, neutral	static (display only)
`Input`	standard, flat	default, focus, error, disabled
`Text`	20 type-scale variants	—

Guidelines for AI / Figma Make

See guidelines/ directory:

SYSTEM.md — design system rules for AI-assisted generation
TOKENS.md — token semantics, when to use subtle/default/strong
COMPONENTS.md — per-component usage, variants × states table, code examples
MOTION.md — motion tiers, enter/exit rules, implementation patterns

Healthtech note

Helix is built for the pharma ecosystem. Error states in inputs have clinical consequences — they must be precise, never silent. Touch targets are minimum 32px. Accessibility (WCAG contrast, visible focus, correct ARIA) is mandatory, not optional.

Maintainer

Emilio Carrozzino — Emilio.Carrozzino@praxys.com.ar