| name | helios-design |
| description | Use when building CLI tools, TUI apps, or GUI applications. Provides a design system with semantic color tokens, typography scale, component patterns, elevation, and accessibility guidelines adapted from HashiCorp Helios for any platform. |
Helios Design System (Generic)
Core Principles
- Rooted in Reality - Ground decisions in data, not assumptions
- Guidance Over Control - Balance configurability with consistency
- Quality by Default - Commit to a baseline of quality in all output
- Design in Context - Meet users where they are, consider current and future use
- Consider Everyone - Inclusive from the start, accessible by default
- Invite Feedback - Validate with stakeholders before finalizing
When to Use
- Building a CLI tool with colored output, status indicators, or structured layouts
- Building a TUI (terminal UI) application with panels, forms, or navigation
- Building a GUI desktop application with buttons, modals, forms, or data tables
- Choosing semantic colors, type scale, or component patterns for any app
Quick Reference
Semantic Color Roles
| Role | Purpose | CLI Example |
|---|
foreground-strong | High-contrast primary text | Bold headings |
foreground-primary | Standard body text | Default output |
foreground-faint | De-emphasized text | Help text, timestamps |
foreground-disabled | Non-interactive text | Greyed-out options |
action | Interactive/clickable elements | Links, commands |
success | Positive outcomes | Checkmarks, "done" |
warning | Caution, side effects | Warnings, deprecations |
critical | Errors, destructive actions | Error messages, delete |
highlight | Prominent callouts | Feature flags, "new" |
Status Feedback Pattern
| Feedback Type | Component | Persistence |
|---|
| Page-level event | Alert (page) | Until dismissed |
| Section-specific | Alert (inline) | Until dismissed |
| Quick notice | Alert (compact) | Always persistent |
| Action result | Toast | Auto-dismiss 7s |
| Destructive confirm | Modal (critical) | Blocks until response |
| Status metadata | Badge | Persistent |
Component Decision Tree
See references/components.md for full component anatomy, variants, and do's/don'ts.
Detailed References
references/colors.md - Full semantic color system, palette structure, contrast ratiosreferences/typography.md - Font families, type scale, weight systemreferences/components.md - Buttons, alerts, modals, toasts, badges, dropdowns, forms, tablesreferences/accessibility.md - WCAG compliance, focus management, keyboard navigationreferences/layout.md - App frame structure, elevation levels, spacing
Common Mistakes
- Using palette colors directly instead of semantic tokens (use
success not green-300)
- Multiple primary buttons on one screen - only one primary action per view
- Auto-dismissing critical/warning toasts - these must persist until user dismisses
- Skipping focus ring implementation on interactive elements
- Using color alone to convey meaning - always pair with icon or text
- Putting destructive actions without confirmation modals
