Design Tokens¶

Design tokens are the foundational values that define the visual design of Bast applications. They ensure consistency across all UI components.

Colors¶

Brand Colors (Decorative/Background)¶

Token	Value	Usage
`--primary-accent`	`#0090cc`	Primary brand color, links, CTAs
`--success`	`#02736b`	Success states, confirmations
`--warning`	`#f2c744`	Warning states, cautions
`--error`	`#f28d35`	Error states, destructive actions
`--info`	`#0090cc`	Informational states

Background Colors¶

Token	Light Mode	Dark Mode	Usage
`--bg`	`#dde3e9`	`#0f1419`	Main background
`--bg-elevated`	`#f5f7fa`	`#1a1f26`	Elevated surfaces

Text Colors (WCAG Compliant)¶

Token	Light Mode	Dark Mode	Usage
`--text-primary`	`#0d2935`	`#e8edf2`	Primary text
`--text-secondary`	`rgba(13,41,53,0.8)`	`rgba(232,237,242,0.8)`	Secondary text
`--primary-text`	`#186891`	`#55ccd9`	Colored primary text
`--success-text`	`#024d47`	`#03a89e`	Success text
`--warning-text`	`#f2c744`	`#f2c744`	Warning text
`--error-text`	`#b85500`	`#f28d35`	Error text

Border Colors¶

Token	Light Mode	Dark Mode
`--border`	`rgba(13,41,53,0.15)`	`rgba(85,204,217,0.2)`
`--border-subtle`	`rgba(13,41,53,0.08)`	`rgba(85,204,217,0.12)`

Typography¶

Font Families¶

Token	Value	Usage
`--font-display`	`'Estedad', sans-serif`	Display text, headings
`--font-mono`	`'IBM Plex Mono', monospace`	Code, technical content

Typography Scale¶

Size	Class	Pixel Value	Usage
H1	`type-h1`	38px	Page titles (raw scale)
H2	`type-h2`	30px	Section headings (raw scale)
H3	`type-h3`	24px	Card titles (raw scale)
H4	`type-h4`	19px	Subsections (raw scale)
H5	`type-h5`	15px	Small headings (raw scale)
Body	`type-body`	14px	Default text
Body Small	`type-body-sm`	12px	Secondary info
Caption	`type-caption`	10px	Labels, microcopy

Prefer semantic heading classes over composing raw type-h* + font-weight:

Semantic Class	Scale	Weight	Use
`screen-title`	h3	200	Page-level titles
`heading-3-strong`	h3	700	Section headings with icon
`heading-4`	h4	500	Modal headers, wizard steps
`heading-5`	h5	600	Card labels, form sub-sections

Font Weight Tokens¶

Token	Value	Usage
`--font-weight-screen-title`	200	`screen-title` class
`--font-weight-heading`	500	`heading-4` class
`--font-weight-heading-semibold`	600	`heading-5` class
`--font-weight-heading-strong`	700	`heading-3-strong` class

Line Heights¶

Token	Value
`--leading-tight`	1.25
`--leading-normal`	1.5
`--leading-code`	1.4

Spacing¶

Based on a 4px unit system:

Token	Value	Usage
`--space-1`	4px	Tight spacing
`--space-2`	8px	Small gaps
`--space-3`	12px	Form element padding
`--space-4`	16px	Default padding
`--space-5`	20px	Medium spacing
`--space-6`	24px	Section spacing
`--space-8`	32px	Large gaps
`--space-10`	40px	Extra large spacing
`--space-12`	48px	Section dividers

Border Radius¶

Token	Value	Usage
`--radius-small`	8px	Small elements, inputs
`--radius-default`	16px	Cards, buttons
`--radius-large`	24px	Large cards, modals
`--radius-full`	9999px	Pills, avatars

Shadows¶

Flat Shadows¶

Token	Usage
`--shadow-light`	Subtle elevation in light mode
`--shadow-light-inset`	Inset effect in light mode
`--shadow-dark`	Subtle elevation in dark mode
`--shadow-dark-inset`	Inset effect in dark mode

Neumorphic Shadows¶

Token	Description
`--neu-1`	Default raised elevation
`--neu-2`	Higher elevation (hover states)
`--neu-inset`	Pressed/inset effect

Theme-aware Aliases¶

Token	Light Mode	Dark Mode
`--shadow`	`--shadow-light`	`--shadow-dark`
`--shadow-inset`	`--shadow-light-inset`	`--shadow-dark-inset`
`--neu-1`	`--neu-light-1`	`--neu-dark-1`
`--neu-2`	`--neu-light-2`	`--neu-dark-2`
`--neu-inset`	`--neu-light-inset`	`--neu-dark-inset`

Transitions¶

Token	Value	Usage
`--transition-default`	`all 150ms ease-in-out`	Default transitions
`--transition-fast`	`all 100ms ease-in-out`	Quick interactions
`--transition-slow`	`all 300ms ease-in-out`	Complex animations

Easing Functions¶

Token	Value
`--ease-default`	`ease-in-out`
`--ease-out`	`cubic-bezier(0, 0, 0.2, 1)`
`--ease-in`	`cubic-bezier(0.4, 0, 1, 1)`
`--ease-bounce`	`cubic-bezier(0.68, -0.55, 0.265, 1.55)`

Usage in CSS¶

.my-component {
  background: var(--bg);
  color: var(--text-primary);
  padding: var(--space-4);
  border-radius: var(--radius-default);
  box-shadow: var(--neu-1);
  transition: var(--transition-default);
}

.my-component:hover {
  box-shadow: var(--neu-2);
}

Usage with Tailwind¶

The package includes a Tailwind preset that maps these tokens. Use arbitrary values:

<div class="bg-[var(--bg)] text-[var(--text-primary)] p-4 rounded-2xl">
  Content
</div>

Contrast ratios¶

WCAG 2.1 AA requires 4.5:1 for normal body text and 3.0:1 for large text (≥18pt or ≥14pt bold) and for non-text UI components and focus indicators. This table records contrast for the semantic text tokens introduced in the a11y-screen-reader-compliance change.

Measurements were computed against the current values of --bg in each theme. Re-run whenever a token changes.

Light theme — text tokens vs `--bg` (`#dde3e9`)¶

Token	Value	Ratio vs --bg	AA text (4.5:1)	AA large (3:1)
`--text-primary`	`#0d2935`	13.3:1	✅	✅
`--text-secondary`	`rgba(13,41,53,0.8)`	~10.5:1	✅	✅
`--primary-text`	`#0090cc`	3.2:1	❌	✅
`--success-text`	`#00975d`	4.0:1	❌	✅
`--warning-text`	`#92400e`	5.9:1	✅	✅
`--error-text`	`#991b1b`	5.9:1	✅	✅
`--info-text`	`#3c54a1`	5.9:1	✅	✅
`--info-muted`	`#5d6fb0`	~4.6:1	✅	✅

Dark theme — text tokens vs `--bg` (`#2b3038`)¶

Token	Value	Ratio vs --bg	AA text (4.5:1)	AA large (3:1)
`--text-primary`	`#edf3f9`	14.8:1	✅	✅
`--text-secondary`	`rgba(237,243,249,0.72)`	~10.2:1	✅	✅
`--primary-text`	`#26a1d4`	4.6:1	✅	✅
`--success-text`	`#2eaa7a`	4.5:1	✅	✅
`--warning-text`	`#eaac16`	6.6:1	✅	✅
`--error-text`	`#fca5a5`	6.6:1	✅	✅
`--info-text`	`#8897c6`	5.4:1	✅	✅
`--info-muted`	`#7c8ab9`	~4.7:1	✅	✅

Canonical brand tokens (`--warning`, `--error`) — not safe as text¶

--warning and --error are the canonical brand palette values — use them for icons, fills, backgrounds, progress bars, and large decorative indicators only. Use --warning-text / --error-text any time the color is applied to text (color:, text-[var(...)]).

A CI grep-check flags color: var(--warning) or color: var(--error) in .tsx / .css files to prevent regression — see packages/shared-styles/scripts/check-warning-error-text.mjs.

Token (canonical)	Value	Light bg ratio	Dark bg ratio	Use
`--warning`	`#eaac16`	1.5:1	6.6:1	Icons / backgrounds
`--error`	`#ed3b30`	3.1:1	3.5:1	Icons / backgrounds

Opacity floor on text¶

--text-secondary already carries 0.8 opacity in both themes. Do not compound with Tailwind opacity-70 / opacity-60 or /70 / /60 arbitrary values on elements that already apply --text-secondary (or --text-tertiary-muted). The effective contrast drops below 4.5:1. Use a dedicated token at full opacity instead.