# Somnia Design System

> Tokens, tones and React components for Somnia's marketing site and explorer, and the explorer sidebar every product page embeds.

## Setup
- Install: npm install @somnia-chain/ui @somnia-chain/explorer-sidebar
- CSS: @import "tailwindcss"; @import "@somnia-chain/ui/theme.css";
- Next.js: import components from "@somnia-chain/ui/next" so internal links use next/link.
- Explorer chrome: import "@somnia-chain/explorer-sidebar/styles.css" and wrap pages in <ExplorerShell>.
- Use semantic token utilities (text-fg-2, border-line, bg-surface) rather than raw colors.
- Full-height frames: use h-viewport, min-h-viewport and max-h-viewport (100dvh) or h-viewport-s, min-h-viewport-s and max-h-viewport-s (100svh), not raw dvh, svh or h-screen. The text size zooms the page and these divide by --ui-zoom; divide any other viewport length by var(--ui-zoom,1).

## Foundations
- [Color](/foundations/colors): Scales, semantic tokens and how tones redefine them.
- [Typography](/foundations/typography): Inter, Inter Tight and Source Code Pro, and the type utilities.
- [Tones](/foundations/tones): The five section backgrounds and how they behave in each theme.
- [Motion](/foundations/motion): One easing, three durations and the motion utilities every transition uses.
- [Text size](/foundations/text-size): A viewer's text size, the zoom behind it, and the viewport utilities full-height frames use.

## Components
- [Button](/components/button) (Button, buttonClass): A link styled as a button, in five variants and three sizes: md for marketing pages, sm for the console, xs for dense console panels. danger is for destructive actions, such as a stop switch. External links open in a new tab and get an up-right arrow.
- [TextLink](/components/text-link) (TextLink, SmartLink): Inline accent link with an arrow, for 'see all' style actions beside headings.
- [Input](/components/input) (Input, inputClass): The console's text field, in the heights of the console buttons: sm (36px) beside an sm button, xs (28px) beside an xs one. inputClass() styles a <select> or any other field the same way.
- [Badge](/components/badge) (Badge, StatusBadge, STATUS_TONES): Compact mono label for statuses in tables and headers. StatusBadge picks the tone from a lifecycle word such as resolved, pending or failed.
- [Tag and StatusTag](/components/tag) (Tag, StatusTag): Tag is a quiet outlined category label, e.g. an article type. StatusTag is the small accent pill for 'Coming soon' in menus and beside page titles.
- [LiveDot](/components/live-dot) (LiveDot): Pulsing status dot. halo adds the soft ring used next to live data sources on the marketing site; pulse={false} holds it still for a status that isn't live.
- [Section](/components/section) (Section, SectionHeader): A full-width band in one of the tones, with the page container inside. Tones redefine the semantic colors for their subtree, so everything inside just works.
- [Panel](/components/panel) (Panel, PanelHeader): The console's bordered surface, with an optional header for eyebrow, title, description and actions.
- [PageHero](/components/page-hero) (PageHero, Breadcrumbs): Marketing page hero on the ink tone with a grid backdrop and violet glow. With a subtitle, the title becomes a mono kicker and the subtitle the headline.
- [PageHeader](/components/page-header) (PageHeader, PageBody): Console page header: breadcrumb, icon, title and status, a one-line summary, actions and sub-page tabs. Every product page in the explorer starts with one.
- [Tabs](/components/tabs) (Tabs, NavTabs, isActive): Underlined sub-page tabs. Pass the current pathname, or use NavTabs from @somnia-chain/ui/next to read it from the router.
- [Sidebar](/components/sidebar) (Sidebar, AppShell, Topbar): The console's sidebar: logo, nav sections with icons, a meta slot and status tags per row, nested sub-links, and a drawer below lg. Compose it with Topbar in an AppShell; the Explorer's sidebar specializes it.
- [StatBand](/components/stat-band) (StatBand, Stat): A hairline band of console stats. Each Stat has a label, a value with optional unit, a sub line and a tone.
- [StatGrid](/components/stat-grid) (StatGrid): The marketing KPI strip: large figures with labels, notes and linked sources, with a live dot for live sources.
- [Table](/components/table) (Table, Th, Td, Tr, Addr, Delta): Console table parts: Table scrolls horizontally, Th and Td handle alignment and mono figures, Tr adds the hover. Addr and Delta format addresses and changes.
- [KeyValues](/components/key-values) (KeyValues): Label and value pairs in a grid, for contract details and chain parameters.
- [Meter](/components/meter) (Meter): Thin horizontal meter for a value from 0 to 1, e.g. utilization or a YES probability.
- [RowList](/components/row-list) (RowList): One row per item with a name on the left and detail on the right, e.g. partners or integrations.
- [EmptyState](/components/empty-state) (EmptyState): Placeholder for an empty list or panel.
- [FeatureGrid](/components/feature-grid) (FeatureGrid): Feature cells in a hairline grid. comfortable is the marketing size, with bullet points and whole-cell links; compact is the console size, numbered on a rounded surface.
- [LinkCard](/components/link-card) (LinkCard, linkCardClass): The hover for any card that is a link: the border firms up, a faint tint and a 1px lift, with a corner → for internal links or ↗ (and a new tab) for absolute URLs. Give it the card's radius, border colour, fill and padding. linkCardClass is the same treatment for a link you render yourself. Cards that are not links stay flat.
- [Steps](/components/steps) (Steps): Numbered steps in a hairline grid.
- [Faq](/components/faq) (Faq): Disclosure list of questions and answers, built on <details> so it works without JavaScript.
- [Callout](/components/callout) (Callout): Inline notice in the accent, neutral, up, warning or down tone, with an optional icon.
- [CtaCard](/components/cta-card) (CtaCard): A wide highlighted card that points to one next step.
- [CtaBand](/components/cta-band) (CtaBand): The closing violet band on marketing pages, with a heading and up to two actions.
- [CodeBlock](/components/code-block) (CodeBlock, CopyButton): Code sample with a copy button. window draws the always-dark editor chrome used on marketing pages; plain sits inside a Panel and follows the theme.
- [DocsShell](/components/docs-shell) (DocsShell, activeSection): Documentation chrome in the explorer's family look: a violet sidebar with the logo and the current section's pages, a top bar with a tab per section, search and the theme toggle, and a drawer on narrow screens. This site and the Somnia docs run on it.
- [DocsArticle](/components/docs-article) (DocsArticle, Toc): A docs page: breadcrumb, title and lede, the body styled by prose-docs, previous and next links, and an 'On this page' list that follows your scroll from the xl breakpoint up. Code blocks in an html body get a Copy button.
- [DocsSearch](/components/docs-search) (DocsSearch): Title search over a static page list, opened with ⌘K, with arrow-key navigation.
- [Logo](/components/logo) (Logo, LogoMark, WORDMARK, MARK): The Somnia wordmark and the {s} mark, drawn from the brand kit and colored by currentColor.
- [ThemeToggle](/components/theme-toggle) (ThemeToggle, ThemeBootstrap, themeScript, THEME_KEY, SavedPreferences): Light/dark switch. Pair it with ThemeBootstrap in <head>: from one set of options it renders themeScript(), so the saved theme applies before first paint, and SavedPreferences, so it comes back on a page the browser draws from scratch, such as a 404. Every Somnia app uses the same storage key, so a choice carries across sites and explorer zones on one origin.
- [TextSizeControl](/components/text-size-control) (TextSizeControl, textSizeScript, TEXT_SIZE_KEY, TEXT_SIZES): Text size switch for console apps: Default, Large or Larger, a radio group named Text size. A choice zooms the page at once and is saved per viewer under the same key in every Somnia app. Pair it with themeScript({ textSize: true }) in <head>, and use the viewport utilities for full-height frames (Foundations, Text size).

## Explorer sidebar
- [@somnia-chain/explorer-sidebar](/explorer-sidebar): ExplorerShell, ExplorerSidebar, ExplorerTopbar, ChainProvider, NAV_ITEMS. Zone-aware links for multi-zone apps.