# HOMECORE-FRONTEND Design Recon — ADR-131

**Source:** cognitum-one/v0-appliance dashboard at `http://cognitum-v0:9000/`
**Captured:** 2026-05-25 by browser-recon agent (session `20260525-181819-adr131-recon`)
**Pages fetched:** dashboard, cogs, seeds, edge, analytics, settings, cluster, tailscale, aidefence, guide (all HTTP 200)
**Auth:** dashboard is unauthenticated; `/api/*` requires bearer token — all recon confined to dashboard pages

---

## 1. Color Palette

The entire UI is dark-only. There is no light mode and no `prefers-color-scheme` media query anywhere in the stylesheet. Every surface is drawn from a tight family of near-black navy blues with two accent hues: a cool teal (`--primary`) and a green (`--accent`).

### Core tokens (hex conversions from HSL source)

| CSS variable | HSL value | Hex | Role |
|---|---|---|---|
| `--background` | `220 25% 6%` | `#0b0e13` | Page background, modal overlay base |
| `--foreground` | `210 20% 92%` | `#e6eaee` | Body text, headings |
| `--primary` | `185 80% 50%` | `#19d4e5` | Teal — active nav underline, CTA borders, ring focus, brand slash |
| `--primary-foreground` | `220 25% 6%` | `#0b0e13` | Text on filled primary buttons |
| `--accent` | `142 70% 50%` | `#26d867` | Green — secondary CTA, success state, deploy button text |
| `--accent-foreground` | `220 25% 6%` | `#0b0e13` | Text on filled accent buttons |
| `--secondary` | `220 20% 14%` | `#1c212a` | Button fill, pill-tab background |
| `--card` | `220 20% 10%` | `#14171e` | Card surface (also popover) |
| `--surface-elevated` | `220 20% 12%` | `#181c24` | Slightly elevated card variant |
| `--surface-overlay` | `220 20% 8%` | `#111318` | Modal scrim, sticky navbar |
| `--muted` | `220 15% 15%` | `#20242b` | Muted chip backgrounds, scrollbar track |
| `--muted-foreground` | `215 15% 55%` | `#7b899d` | Secondary text, labels, timestamps |
| `--border` | `220 15% 18%` | `#272b34` | All borders (at 50% opacity by default) |
| `--destructive` | `0 65% 50%` | `#d22c2c` | Error state, danger button |
| `--ring` | `185 80% 50%` | `#19d4e5` | Focus ring (same hue as primary) |

### Semantic status colors (inline, not variables)

| State | Color | Hex | Usage |
|---|---|---|---|
| Online / success | `hsl(142 70% 50%)` | `#26d867` | `.badge.online`, `.dot.up`, `.heat-cell.up` |
| Warning | `hsl(38 80% 60%)` | `#e69940` | `.badge.unpaired`, `.hero-dot.warn`, banner backgrounds |
| Error / offline | `hsl(0 65% 50%)` | `#d22c2c` | `.badge.offline`, `.badge.danger`, `.dot.down` |
| Info (log line) | `hsl(205 80% 65%)` | `#4db8f5` | Log viewer `.info` class |
| Paired | `hsl(185 80% 50%)` | `#19d4e5` | `.badge.paired` (same as primary) |

---

## 2. Typography

### Font families

The CSS declares two font families via CSS custom properties:

- `--font-display: 'Outfit', system-ui, sans-serif` — all headings, nav items, buttons, card titles, KPI values. Outfit is a modern geometric sans loaded locally (no Google Fonts outbound call; the source comment says "ship from local chrome.css fallback").
- `--font-mono: 'JetBrains Mono', monospace` — timestamps, port numbers, version strings, table cells, log output, KPI labels, chip text.

### Type scale

| Token name / usage | Size | Weight | Notes |
|---|---|---|---|
| Hero title (`h1.hero-title`) | `clamp(1.5rem, 2.4vw, 2.1rem)` | 600 | Fluid, capped at ~33.6px |
| Page h1 (`.page`) | `1.5rem` (24px) | 600 | All inner pages |
| Section heading (`.row-h h2`) | `1.125rem` (18px) | 700 | Section openers on Cogs/Dashboard |
| Card title (`.card-title`) | `0.9375rem` (15px) | 600 | |
| Body / button | `0.8125rem` (13px) | 400/500 | Default body, nav links, buttons |
| Secondary body / lede | `0.875rem` (14px) | 400 | Page lede text |
| Small label | `0.75rem` (12px) | 400–600 | Table cells, modal sub-text |
| Micro label | `0.6875rem` (11px) | 600 | Section eyebrows, uppercase KPI labels, badge text |
| Mono micro | `0.625rem` (10px) | 400 | Heatmap cells, chip category text |

Letter-spacing: `0.1em` on section eyebrows (`.section h2`), `0.08em` on filter-rail headings and chip category text, `-0.02em` on all `h1–h4` display headings. Line-height for body is `1.5`; lede text uses `1.45`.

---

## 3. Layout Primitives

### Page shell

```
┌─────────────────────────────────────────────────────────┐
│  .appbar  (sticky, z-50, backdrop-filter:blur(8px))     │
│  [brand-mark] [brand-text] [nav links scrollable]       │
├─────────────────────────────────────────────────────────┤
│  .wrap  (max-width: 1400px, padding: 1.5rem 1.25rem)   │
│    ┌── .hero (full-width, gradient bg, radial accents) │
│    ├── .kpi-grid  (auto-fill, min 170px columns)       │
│    ├── .section > h2 (eyebrow) + content               │
│    └── .grid / .grid-2 / .grid-3  (auto-fit)          │
├─────────────────────────────────────────────────────────┤
│  footer.appfoot  (border-top, centered text)           │
└─────────────────────────────────────────────────────────┘
```

**Appbar:** `position: sticky; top: 0; z-index: 50`. Background is the page background at 90% opacity with 8px blur backdrop-filter, so the page content bleeds through. Nav links overflow-scroll horizontally with a right-fade mask gradient.

**Active nav state:** primary-colored text + a 2px bottom border line (`::after` pseudo-element) positioned at bottom: -2px of the link. Hover reveals secondary background fill on the link.

**Content wrap:** max-width 1400px, centered, 1.25rem horizontal padding. Inner page sections are separated by margin-bottom spacing in multiples of 0.75rem (base unit = 12px at 16px root).

### Cogs page: app-store sub-navigation

The Cogs page adds a sticky secondary nav bar (`.subnav`) at `top: 3.25rem` (just below the appbar). Tabs are borderless buttons with a 2px bottom underline indicator when active. A `flex: 1` spacer pushes a gear icon to the right edge.

### Card patterns

Three card variants, all sharing the same surface gradient and border:

1. **Standard card (`.card`)** — `background: var(--gradient-card)` (linear 180deg from `--surface-elevated` to `--surface-overlay`), 1px border at 50% opacity, `--radius` (0.75rem), `box-shadow` 8px/32px dark drop shadow.
2. **KPI card (`.kpi`)** — 38px icon square left + text right, same gradient, 1rem/1.125rem padding, smaller vertical rhythm.
3. **Empty-state card (`.empty-card`)** — dashed 1px border (instead of solid), centered text, optional compact variant. The headline in `.empty-card h3` uses the primary teal, body explains what to do next.

### Spacing rhythm

Base unit is 4px. Gaps between grid items are universally `0.75rem` (12px). Card padding is `1.25rem` (20px) for standard, `0.875rem` (14px) for compact. Section margin-bottom is `1.5rem` (24px). The hero section uses `1.75rem` (28px) horizontal padding.

---

## 4. Component Vocabulary

### Navigation components

- **Appbar** — sticky top bar with brand + horizontal nav links. Brand mark is a 32px rounded SVG icon square.
- **Nav link** — 0.4rem × 0.7rem padding, 0.4rem radius, transitions on color + background. Active state: primary text + 2px underline pseudo-element. Mobile: wraps below brand row at 720px.
- **Sub-nav / secondary tab bar** (`.subnav`) — app-store style horizontal tab strip, sticky under appbar. Used exclusively on Cogs.
- **Pill tabs** (`.pill-tabs` + `.pill-tab`) — smaller rounded-rect tab group for in-card filter switching. Active state fills with primary color.
- **Page tabs** (`.page-tabs`) — used on Analytics for domain view switching. Underline-style, same pattern as sub-nav but at content level.

### Card & data display

- **Card** (`.card`) — base data container with gradient surface, subtle border, shadow.
- **KPI tile** (`.kpi`, `.kpi-tile`) — metric display with icon, label (uppercase micro mono), large value, and optional sub-line. Two variants: `.kpi` (icon-left layout) and `.kpi-tile` (stack layout, used on Seeds/Edge/AIDefence).
- **Node card** (`.node`) — cluster member card with mono metadata rows. Key-value pairs in `.node-meta` with dimmed label prefix (`.l` class).
- **Cog card** (`.cog`) — product-catalog card with emoji icon, name, description, category chips, and a "Get" pill button. Hover lifts 2px with primary glow border.
- **Pick card** (`.pick-card`) — horizontal-scroll featured card (220px fixed width), snap-scroll container. Smaller emoji + name + category + pill CTA.
- **Category tile small** (`.cat-tile-sm`) — 180px min-width grid item, emoji + name + count.
- **Category tile large** (`.cat-tile-big`) — 16:9 aspect-ratio card, full-bleed with gradient per category.
- **Nav tile** (`.nav-tile`) — dashboard home navigation card with icon square, title, description, and a chevron arrow that translates +2px on hover.
- **Architecture action card** (`.arch-card`, `.arch-action-card`) — setup wizard launcher cards on the dashboard.

### Status & feedback

- **Badge** (`.badge`) — pill with 1px border, 11px mono text. Variants: `role-master` (teal), `role-worker` (green), `online` (green), `offline` (red), `unknown` (muted), `paired` (teal), `unpaired` (amber), `danger` (red).
- **Dot** (`.dot`) — 8px circle status indicator. `.up` glows green with box-shadow, `.down` is red, default is muted gray.
- **Hero dot** (`.hero-dot`) — 7px circle in the dashboard hero status row. Same three states: `.ok` (green glow), `.warn` (amber glow), `.down` (red glow).
- **Op-pill** (`.op-pill`) — "operational status" pill with colored dot inside. Used in dashboard architecture hub.
- **AI pill / status chip** (`.pill` on AIDefence, `.md-badge` in cluster) — inline classification badge at 0.68rem. States: `.ok`, `.warn`, `.bad`.
- **Chip** (`.chip`) — tiny category/difficulty label, all-caps, 0.5625rem, pill-shaped. Category-colored variants (`.cat-ai`, `.cat-health`, `.cat-security`, etc.) each get a hue-appropriate 15% opacity background.

### Actions

- **Button** (`.btn`) — 0.5rem × 0.875rem padding, 0.4rem radius, secondary fill. Variants: `.primary` (filled teal, 600 weight, box-shadow), `.outline` (transparent fill), `.danger` (red tint), `.sm` (compact).
- **Hero button** (`.hero-btn`) — slightly larger, display-font, 0.9rem padding, glass-effect dark fill. `.primary` variant uses the green accent gradient.
- **Pill CTA** (`.get`, `.pget`) — full pill-radius (9999px), primary-tint background at rest, fills solid on hover. Used on cog cards and pick cards.
- **Gear button** (`.gear-btn`) — icon-only square button, transparent at rest, border appears on hover.
- **Context menu** (`.ctx-menu`) — dark card dropdown (min-width 180px), each item is a full-width button with secondary hover fill.
- **Copy button** (`.copy-btn`) — positioned absolute in `.copy-row`, 0.7rem opacity at rest, `.copied` state turns green/accent.

### Forms & inputs

- **Input** — all `<input>`, `<textarea>`, `<select>` inherit dark theme globally. Focus ring: 2px solid primary at 30% opacity (`box-shadow: 0 0 0 2px hsl(var(--ring) / 0.3)`). Checkboxes and radios use `accent-color: hsl(var(--primary))`.
- **Collapsible section** (`.coll`, `.coll-h`, `.coll-body`) — used in Settings page. Header row is clickable with `user-select: none`. Body `display: none` by default, revealed on expand.
- **Key-value row** (`.kv`) — 3-column grid (160px label | 1fr value | auto action) for settings display.
- **Filters rail** (`.filters-rail`) — sticky sidebar on Cogs/Apps tab. Sticky at `top: 7rem` (below both navbars). Contains checkboxes, a range input, and a reset button.
- **Range input** — native `<input type="range">` styled with `accent-color: hsl(var(--primary))`.

### Data visualization

- **Heatmap** (`.heatmap`) — CSS grid of 14px × variable cells. 60 time columns, label column at 90px. Cell states: `up` (green 70%), `down` (red 70%), `empty` (muted 30%).
- **Bar chart** (`.bar-list` + `.bar-row` + `.bar-fill`) — horizontal bar list, 3-col grid (120px label | 1fr bar | 30px value). Bar fill transitions width in 0.3s.
- **uPlot time-series** (`.uplot-host`) — 200px height host container; actual charting via uPlot library.
- **Three.js 3D** — importmap for `three` + `OrbitControls` in Analytics page, for 3D sensor visualization.
- **Log box** (`pre.logbox`) — monospace pre-formatted block, max-height 30rem, overflow-y scroll. Dark background on dark background gives subtle separation via border.
- **OTA row table** (`.ota-row`) — 3-col grid (160px | 80px | 1fr) for firmware OTA records.

### Overlays

- **Modal** (`.modal-bg` + `.modal`) — fixed inset, 70% opacity blur-backdrop scrim. Modal itself is card-surfaced, max-width 560px. Result states: `.modal-result.ok` (green tint) and `.modal-result.err` (red tint).
- **Detail modal** (`.detail-modal-bg` + `.detail-modal`) — larger variant (max 820px, 2rem padding) used on Cog detail view. Header has emoji, name, meta chips; sections below are tabbed.
- **Keyboard shortcut tag** (`.kb`) — small monospace tag with secondary background, used inline in Settings and Tailscale pages to show keyboard shortcuts.

---

## 5. Iconography

All icons are inline SVG, 24×24 viewBox, `fill: none`, `stroke: currentColor`, `stroke-width: 2`. The path geometry is **Lucide Icons** — confirmed by comparing the Sun/gear/shield/grid/activity paths against Lucide's source. Key examples observed:

- Sun/rays (brand mark, dashboard hero)
- Settings/gear (nav, subnav gear button)
- Activity/pulse (KPI signal icon)
- Bar chart 3 (analytics KPI)
- Grid 2×2 (cluster/cog layout)
- Shield with checkmark (AIDefence)
- House (home nav tile)
- Book-open (guide nav)

No external icon font is used. Every icon is self-contained in the HTML at point of use — no sprite sheet.

---

## 6. Dark Mode

The design is **dark-only**. There is no `prefers-color-scheme: light` media query in `v0-chrome.css` or any page-level stylesheet. The color system is entirely designed around the dark palette above. The source comments explicitly note that `fonts.googleapis.com` is blocked for Tailnet isolation, reinforcing that this is an always-dark appliance UI, not a consumer product that needs theming.

Surface hierarchy (light to dark, within the dark palette):
1. `--surface-elevated` (`#181c24`) — slightly lighter card variant
2. `--card` (`#14171e`) — standard card
3. `--surface-overlay` (`#111318`) — modal/sticky appbar base
4. `--background` (`#0b0e13`) — page root

The appbar uses `background: hsl(var(--background) / 0.9)` + `backdrop-filter: blur(8px)` so content underneath bleeds through as a translucency effect.

---

## 7. Notable Interactions

- **Nav hover:** 150ms color + background transition, no translate. Active state uses a 2px pseudo-element underline that animates in via opacity.
- **Nav link active press:** `transform: translateY(1px)` on `:active` at 50ms — very subtle tactile response.
- **Card hover:** `transform: translateY(-2px)` at 200ms on cards and cog items. Border shifts from `--border/0.5` to `primary/0.4` on hover. On the nav tiles, box-shadow deepens.
- **Hero button hover:** `transform: translateY(-1px)` + border-color shift to primary at 70%.
- **Pick card hover:** translateY(-2px) + primary-glow box-shadow.
- **Focus ring:** 2px solid primary at 30% opacity as box-shadow — uses `outline: none` everywhere and replaces it with the ring shadow. nav links use `outline: 2px solid hsl(var(--primary)/0.6); outline-offset: 1px` for focus-visible.
- **Bar fill animation:** `transition: width 0.3s` on bar chart fill elements for data-load entrance.
- **Modal backdrop:** `backdrop-filter: blur(4px)` on modal scrim, `blur(6px)` on the Cog detail modal.
- **Copy button feedback:** `.copied` state class swaps border and text to accent green, visible for a short duration (JS-controlled).
- **Pill CTA:** Background fills from 15% opacity teal to 100% solid on hover — a strong affordance for primary actions.
- **Scroll fade mask:** The nav bar has `mask-image: linear-gradient(to right, black calc(100% - 24px), transparent)` to fade out the rightmost item, hinting at horizontal scroll.
- **Cogs hero carousel:** Paginator dots expand from 0.55rem circles to 1.5rem pill shape (border-radius 0.4rem) when active — a distinctive indicator pattern.

---

## 8. HA-Parity Opportunities

For ADR-131 P2, the following comparisons are relevant between this design and Home Assistant's frontend (`home-assistant-main`):

| HOMECORE component | Cognitum V0 pattern | HA equivalent | Better reference |
|---|---|---|---|
| KPI metric card | `.kpi` — icon + label + value | `ha-statistic-card`, `sensor-badge` | **Cognitum** — cleaner dense layout; HA's is more verbose |
| Status badge/pill | `.badge` + `.chip` — pill with 1px border | `ha-label-badge`, `state-badge` | **HA** — HA has more state variants and i18n built in |
| Dark surface cards | `--gradient-card` linear gradient | HA uses flat `var(--card-background-color)` | **Cognitum** — gradient gives depth HA lacks |
| Toggle/switch | `accent-color` native checkbox | HA `ha-switch` (Material) | **HA** — purpose-built, accessible, animated |
| Navigation | Horizontal sticky nav, underline indicator | HA sidebar (vertical) | Neither — HOMECORE needs a new shell; Cognitum's horizontal bar is appropriate for appliance context |
| Heatmap timeline | CSS grid `.heatmap` | No HA equivalent | **Cognitum** — take this pattern directly |
| Bar chart | CSS-only `.bar-fill` bar list | HA uses Recharts | **Cognitum** — zero-dep CSS bars good for simple metrics; use for small cards |
| Time-series chart | uPlot `.uplot-host` | HA uses ApexCharts / Recharts | **HA** — ApexCharts has more features, better RTL support |
| Modal | `.modal-bg` blur-backdrop | HA `ha-dialog` (Material) | **HA** — a11y and focus-trap already solved |
| Toast / alert banner | `.modal-result.ok/err` inline result + `.cl-banner.warn/err` | HA `ha-alert` | **HA** — HA's alerts are more composable |
| Focus ring | `box-shadow` ring pattern | HA uses `:focus-visible` outline | **HA** — HA's approach has better browser compatibility |
| Chip (category) | `.chip.cat-*` per-category color mapping | HA `ha-chip` | **Cognitum** — the category-specific hue mapping is richer |

---

## 9. Design Tokens for HOMECORE-FRONTEND P1

Concrete CSS variable names and starting values for the TypeScript+WASM frontend to adopt. These follow the Cognitum V0 source directly, adjusted where needed for HOMECORE context.

```css
:root {
  /* Surfaces */
  --hc-bg:                   hsl(220 25% 6%);      /* #0b0e13 — page root */
  --hc-surface-card:         hsl(220 20% 10%);     /* #14171e — card fill */
  --hc-surface-elevated:     hsl(220 20% 12%);     /* #181c24 — raised panel */
  --hc-surface-overlay:      hsl(220 20% 8%);      /* #111318 — modal/nav base */

  /* Text */
  --hc-text:                 hsl(210 20% 92%);     /* #e6eaee — primary text */
  --hc-text-muted:           hsl(215 15% 55%);     /* #7b899d — secondary/label */

  /* Accent palette */
  --hc-primary:              hsl(185 80% 50%);     /* #19d4e5 — teal, primary actions */
  --hc-primary-fg:           hsl(220 25% 6%);      /* #0b0e13 — text on primary */
  --hc-accent:               hsl(142 70% 50%);     /* #26d867 — green, success/CTA */
  --hc-accent-fg:            hsl(220 25% 6%);      /* #0b0e13 — text on accent */
  --hc-destructive:          hsl(0 65% 50%);       /* #d22c2c — error/danger */
  --hc-warning:              hsl(38 80% 60%);      /* #e69940 — warning/amber */

  /* Borders & rings */
  --hc-border:               hsl(220 15% 18%);     /* #272b34 — subtle border */
  --hc-ring:                 hsl(185 80% 50%);     /* #19d4e5 — focus ring */

  /* Radii */
  --hc-radius:               0.75rem;              /* cards, modals */
  --hc-radius-sm:            0.4rem;               /* buttons, inputs, chips */
  --hc-radius-pill:          9999px;               /* badges, CTA pills */

  /* Typography */
  --hc-font-display:         'Outfit', system-ui, sans-serif;
  --hc-font-mono:            'JetBrains Mono', monospace;

  /* Shadows */
  --hc-shadow-card:          0 8px 32px -8px hsl(220 25% 2% / 0.8);
  --hc-shadow-glow:          0 0 60px -10px hsl(185 80% 50% / 0.3);

  /* Gradients */
  --hc-gradient-card:        linear-gradient(180deg, hsl(220 20% 12%) 0%, hsl(220 20% 8%) 100%);
}
```

**Notes for P1 implementation:**

- Adopt Outfit + JetBrains Mono from Google Fonts in development; ship local fallbacks for production (Tailnet appliances block outbound font requests per the Cognitum source comment).
- The `--hc-ring` focus approach should be implemented as `box-shadow: 0 0 0 2px hsl(var(--hc-ring) / 0.3)` combined with `outline: none` — matches Cognitum's pattern and avoids the offset-gap issue in Firefox.
- Add `--hc-gradient-hero` and `--hc-gradient-glow` when the dashboard hero section is built; keep them out of the P1 design-token foundation to avoid premature complexity.
- The `--hc-warning` amber is not in the Cognitum `:root` block (it is inline throughout) — elevating it to a token is a deliberate improvement for HOMECORE.