dev_arc_aws/.kiro/steering/design-rules.md

# ArchNest Design Rules — Must Follow on Every Page

> Kept in sync with `/design-decisions.md` at the repo root, which is the
> canonical source — if the two ever disagree, trust `design-decisions.md`
> and fix this file to match. This file exists so Kiro steering injects the
> same rules automatically; it intentionally duplicates rather than replaces
> the root doc.

---

## Sidebar

- **Expanded width**: 200px (not 80px — that was the original pre-build mockup spec)
- **Collapsed width**: 64px (icon only)
- **Manually collapsible** via a toggle button (not just responsive breakpoints)
- **Active indicator**: gold left border + gold text
- **System status**: bottom of sidebar, colored dot + text, driven by live
  integration-status polling (not a static config)
- Main content `margin-left` must match the sidebar width exactly

## Top Bar

- **Page title**: 18px, bold, uppercase, tracking-wide, **gold (#C8A434)** — not white
- **Height**: 56px, sticky, z-40 (72px + larger 28px title on pages with a
  subtitle — currently only BookNest, via the `pageSubtitles` map)
- **Search bar**: ~300px, rounded-full, searches across pages/integrations/bookmarks
- **Avatar**: 36px, gold border + glow, initials or uploaded image
- **Dropdown menu**: Profile, Appearance, Security, Help & Support, Sign Out (red)

## Hero Banner

- Shown on: Glance, Infrastructure, BookNest (not Network — there is no
  Network page; Infrastructure has a disabled "Network" sub-tab instead)
- Not shown on: Terminal, Tunnels, Files, Containers, Remote Desktop,
  Host Metrics, Settings, Help
- `object-cover` with a tuned `object-position` per page (configured in
  `App.tsx`'s `heroObjectPosition` map) to show the upper portion, not center-crop
- Status/KPI cards overlap the bottom of the banner via negative margin
- If the image fails to load, the banner area just shows the card background
  color — no broken-image icon

## KPI / Status Cards

- Background `#141518`, border `1px solid #1E2025`, 12px radius, no box-shadow
- Padding ~16px for KPI cards, ~20-24px for content cards
- Hover: border transitions to gold, 0.2s ease
- Card titles: 10-11px uppercase, tracking-[1.5px], secondary color
- Large numbers: 24-28px bold, primary color

## Content Rows

- All rows in a page share the same horizontal padding so the hero banner,
  status cards, and content rows line up left/right
- No footer/status bar on any page — don't add one unless explicitly requested

## Colors

### Dark Mode (Default — Shipped)

| Role | Value |
|------|-------|
| Page background | `#0D0E10` |
| Card background | `#141518` |
| Sidebar background | `#0A0B0D` |
| Border | `#1E2025` |
| Gold accent | `#C8A434` |
| Success | `#2ECC71` |
| Warning | `#E67E22` |
| Danger | `#E74C3C` |
| Text primary | `#E8E6E0` |
| Text secondary | `#7A7D85` |

### Light Mode (Planned)

| Role | Value |
|------|-------|
| Page background | `#F7F6F3` |
| Card background | `#FFFFFF` |
| Sidebar background | `#FAF9F7` |
| Border | `#E8E5DF` |
| Gold accent | `#C8A434` |
| Success | `#2ECC71` |
| Warning | `#E67E22` |
| Danger | `#E74C3C` |
| Text primary | `#1A1A1A` |
| Text secondary | `#6B6560` |

## State Management

- **No Zustand or other global state library is used.** State is plain React
  component state plus `localStorage` for a small number of client-only
  preferences (Terminal theme/font prefs; `AuthContext`'s JWT). All
  dashboard data (integrations, bookmarks, resources, events, etc.) is
  fetched live from the Fastify backend via `src/lib/api.ts` — there is no
  client-side cache/store layer to keep in sync with the server.

## Target Screen

- Primary design target: 16-inch display / 1920px+ viewport
- Should feel spacious, not cramped — use the full width

## See also

- `/design-decisions.md` — full per-page implementation notes (what each
  page actually renders and where its data comes from)
- `/README.md` — architecture overview, page list, backend routes
- `/HANDOFF.md` — current task state and what to work on next