HestiaOS Platform UI Kernel

Design Tokens → Primitives → Templates → Shell → Registry → Config

HestiaOS Platform UI is a modular, governance-first UI framework for building role-based dashboards and portals with Next.js 14 + React 18 + TypeScript.

Architecture

Module (Business Logic)
  │ uses
  ▼
Template (Structure + States + Slots)
  │ uses
  ▼
Primitives (Button, Card, Badge, Input, Panel)
  │ uses
  ▼
CSS Variables (no hardcoded colors)
  │ from
  ▼
Theme Adapter (Tokens → CSS Variables)
  │ reads
  ▼
Theme Pack (hestiaos-default-dark, -light, -pitch, -research)

Layers

Layer	Path	Content
Design Tokens	src/platform/design/tokens.ts	3-Layer: Base → Semantic → Component
Theme Adapter	src/platform/design/theme-adapter.ts	Tokens → CSS Variables
Theme Provider	src/platform/design/ThemeProvider.tsx	React Context + applyTheme()
Theme Packs	src/platform/themes/index.ts	Dark/Light/Pitch/Research
Primitives	src/platform/primitives/index.tsx	Button, Card, Badge, Input, Panel, StatusDot
Templates	src/platform/templates/	Loading/Error/Empty/Ready states
Shell	src/platform/components/Shell.tsx	Topbar + Sidebar + Main
Registry	src/platform/registry/	Module & Widget registries
Config	src/platform/config/	Navigation & platform config
Schemas	src/platform/schemas/module.schema.ts	Zod runtime validation
Types	src/platform/types/	TypeScript contracts

Rules

• No module knows a brand color (#E66A2C).
• No module defines its own Topbar/Sidebar.
• No template contains business logic.
• No primitive contains domain data.
• Only tokens know concrete color values.

Documentation

See docs/ for:

• Module Contract
• Widget Contract
• Adding a Module
• Adding a Widget
• Navigation Config
• Design Tokens
• Template Contracts
• Permissions & Roles
• Dashboard Customization
• Data Requirements
• Interfaces
• Migration from Legacy UI
• Branch & PR Strategy

License

Apache-2.0