Skip to main content

​
Design System

A condensed overview of Reikon’s UI conventions. The full, exhaustive reference — every component prop, every exact Tailwind class, the complete don’t-do list — lives in docs/design-system.md in the repo and is the source of truth if anything here seems to conflict with the actual code. This page exists so a contributor can get oriented without reading all 1,000+ lines of that file first.

​
Stack

React 18 functional components, Tailwind CSS v3 + CSS custom properties for theming, Phosphor Icons (ph ph-* / ph-fill ph-* classes), class-strategy dark mode.

​
Color tokens

Surfaces use semantic tokens, never hardcoded hex: Two other special tokens:
  • --accent — user-customizable accent color (default #34d399), used for active states, progress bars, toggles. Never hardcoded.
  • --ai-gradient — a fixed blue→violet→pink gradient, used for every AI-sourced feature, never the user’s accent color. This is a hard rule: it’s how a user learns to visually distinguish “this number is AI-suggested” from “this number is computed deterministically,” and that distinction matters for trust.
Semantic color roles (consistent across the whole app): emerald = healthy/active, red/rose = error/critical, amber = caution/transient, indigo = data label only (never state), sky = informational.

​
Core components

Never hand-roll these — always use the shared primitive:
  • <Button> — never a raw <button> with manual styling
  • <Badge> — always a gradient pill, never flat/bordered; tone matches what it represents (e.g. rose for errors, emerald for healthy/active states)
  • <IconButton> — square icon-only actions, single fixed size
  • <Avatar> — contributor initials, never a hand-rolled div
  • <Tooltip> — never the native title= attribute
  • <SubTabs> — page-level sub-navigation, never reimplemented per page
Every modal follows the same structure: overlay → panel → header (icon badge + title, no subtitle) → body → footer, all wrapped in <Portal> so the overlay mounts on document.body and isn’t mispositioned by a transformed ancestor (the tab/dashboard entrance animations leave such transforms). items-start on the header flex, never items-center — it’s a small detail that looks fine until the title wraps to two lines. Full anatomy with exact classes is in docs/design-system.md’s Modals section.

​
The full-height scroll chain

Every scrollable tab follows the same pattern — a flex h-full min-h-0 flex-col root, with the scrollable content area getting flex-1 min-h-0 overflow-y-auto. Missing min-h-0 anywhere in that chain is the single most common layout bug in this codebase — content silently overflows instead of scrolling.

​
Tinted alert cards

A whole-card color wash (border + background + text all in one hue) is reserved for cards where the entire content shares one semantic meaning — a risk list, a warning. It’s not the default card style; most cards stay neutral white/slate. Reserve the tint for when color itself is the message, not decoration.

​
Before you build new UI

Read docs/design-system.md’s relevant section first — it has exact prop signatures, the complete color-token table, and roughly 40 specific “don’t do this” entries learned from real bugs (most logged with the bug they came from). This page is a map to that territory, not a replacement for it.