## Design Context

### Users
Internal Humain teams and external clients building products on the Humain platform. The component library powers HUMAIN One (platform dashboard) and HUMAIN Chat (AI assistant interface), along with other Humain products. Users are professionals in government, enterprise, and AI/data contexts who need interfaces that feel trustworthy and modern — not flashy or experimental.

### Brand Personality
**Ambitious, Strategic, Transformative.**

The Humain brand represents a company driving AI transformation for serious contexts (government, enterprise). The interface should feel like it belongs to a company that's confidently leading — not following trends. Every component should convey competence and forward-thinking without sacrificing clarity.

- **Voice**: Direct, confident, precise. No filler, no hype.
- **Tone**: Professional warmth — approachable but never casual. Think executive briefing, not startup pitch.
- **Emotion**: Trustworthy & modern. Users should feel they're using a tool built by people who understand their domain.

### Aesthetic Direction
- **Visual tone**: Clean, structured, purposeful. Generous whitespace with tight information density where needed (data tables, dashboards). Not minimal for minimalism's sake — every element earns its place.
- **Brand color**: Lagoon Flat teal (`--brand-500: #00bfb2`) — distinctive, not the typical blue SaaS palette. Use it strategically as accent, not everywhere.
- **Typography**: Inter — functional and readable. The library prioritizes clarity over typographic flair since it's a design system consumed by many products.
- **Theme**: Light and dark modes, both first-class. Dark mode is essential for HUMAIN Chat and AI contexts.
- **References**: HUMAIN One (platform), HUMAIN Chat (AI assistant)
- **Anti-references**: Generic SaaS dashboards with cyan-on-dark glow effects. AI-slop aesthetics (purple gradients, glassmorphism everywhere, bouncy animations). Government sites that look dated or bureaucratic.

### Design Principles

1. **Trustworthy by default** — Components should look and feel solid. No decorative flourishes that undermine credibility. Accessibility (WCAG AA) is non-negotiable.

2. **Token-driven consistency** — Every color, spacing value, and typographic choice comes from the design token system. No hard-coded values. This ensures coherence across HUMAIN One, HUMAIN Chat, and client products.

3. **Progressive enhancement** — Features degrade gracefully. Animations respect `prefers-reduced-motion`. Backdrop effects use `@supports` guards. SSR-safe by default.

4. **Density-aware** — The same components work in spacious marketing layouts and dense data dashboards. Container queries and responsive variants adapt to context, not just viewport.

5. **AI-native** — 27+ AI components are first-class citizens, not afterthoughts. Typing indicators, thinking loaders, message streams, and code blocks are as polished as buttons and forms.

### Accessibility
- **Target**: WCAG 2.1 AA compliance
- **Focus**: `focus-visible` indicators on all interactive elements (never strip with `focus:outline-none`)
- **Motion**: All animations respect `prefers-reduced-motion` via `useReducedMotion` or `motion-reduce:` classes
- **Contrast**: Minimum 4.5:1 for text, 3:1 for UI components
- **Keyboard**: Full keyboard navigation support; no focus traps