UI Components & Design System
Mission
Create reusable, semantically named, and maintainable component architectures. Avoid both extremes:
- BAD: One-off visual code (inline styles, magic numbers) everywhere.
- ALSO BAD: Turning every tiny wrapper into a bloated, over-engineered component.
Design Tokens
Require semantic design tokens. Do not hardcode magic values across the UI. At minimum cover:
- Typography: scales, weights, line heights, and tabular figures (
font-variant-numeric: tabular-numsfor data/counts). - Spacing: padding, margins, gaps
- Colors: semantic palette (primary, secondary, success, error, text, background). Secondary text on colored surfaces must be tinted from the background hue, NEVER generic gray.
- Surfaces: background, elevated, raised, depressed
- Browser Surfaces:
selection-bg,selection-text,caret-color,focus-ring(with offset),scrollbar. - Borders: colors, widths, styles
- Radii: none, small, medium, large (NO FULL/PILL RADII).
- Elevation: Single elevation architecture (border OR shadow, never both/ghost cards). Shadows must have y-offset and blur (no zero-offset glow halos).
- Motion: duration, easing curves
- States: active, disabled, hover variables
Semantic Token Naming
Examples of good token naming:
color-surface-elevatedtext-primary-inversespace-layout-gutterradius-control-default
Component States
Require rigorous component states. Ensure you design and implement the following states for interactive components:
- Default: The resting state.
- Hover: (Where relevant, primarily web)
- Pressed: Active state during interaction.
- Focus: Keyboard or programmatic focus.
- Disabled: Uninteractive and visually muted.
- Loading: Awaiting data or action completion.
- Selected: Chosen option in a set.
- Error: Invalid state.
- Success: (Where applicable)
Anti-Slop Component Rules
- No Pill Components: Do NOT build or use pill badges, pill tags, pill chips, or floating pill containers (
rounded-fullenclosures). Structure metadata and labels with crisp typography, micro-borders, or simple layout hierarchy. - No Icon Background Containers: Do NOT build component wrappers that add colored background fills, tinted boxes, circular backdrops, or square containers behind icons (e.g.
bg-primary/10 rounded-xl p-3). Icons must render cleanly directly on the surface. - Image Primacy: Design components to showcase rich visual media (screenshots, photography, 3D assets, architecture diagrams) rather than repetitive icon containers.
Documentation
Document your component structures using the docs/design-system-template.md format.


