# Styling Reference

This document explains which theme tokens control the main backgrounds, surfaces,
borders, and shell gradients in Moku Work.

It is focused on the current frontend shell scaffold so future visual tuning can
be done intentionally instead of by guesswork.

## Source Of Truth

There are two places to look when changing styling tokens:

- Runtime theme payload:
  - `Frontend/public/themes/moku-default.json`
- SCSS fallback defaults:
  - `Frontend/src/styles/themes/_light.scss`
  - `Frontend/src/styles/themes/_dark.scss`
- Full sample theme file:
  - `Documentation/STYLING-THEME-SAMPLE.json`

If you want to change the actual themed values used by the app, update the theme
JSON first. The SCSS files act as fallback/default variables.

---

## Core Surface Tokens

These are the main tokens currently driving shell backgrounds and card surfaces:

- `--color-canvas`
  - outer page background
- `--color-surface`
  - standard panel/card/topbar surface
- `--color-surface-muted`
  - quieter secondary panels and dropdown surfaces
- `--color-surface-hover`
  - hover state for solid surface rows
- `--color-border`
  - standard card/panel border
- `--color-border-strong`
  - stronger shell edges, separators, and emphasized borders
- `--color-text`
  - primary text color
- `--color-text-muted`
  - secondary/meta text color
- `--color-accent`
  - primary accent lane
- `--color-accent-strong`
  - stronger accent emphasis
- `--color-accent-soft`
  - soft accent wash for subtle fills

There are also ring-only multi-primary tokens currently used for the top-right
profile ring:

- `--color-primary-1`
- `--color-primary-2`
- `--color-primary-3`

---

## Light Mode Values

Current light-mode surface values:

```text
--color-canvas: var(--gray-50)
--color-surface: hsl(0 0% 100% / 0.9)
--color-surface-muted: var(--gray-0)
--color-surface-hover: var(--gray-100)
--color-border: hsl(220 15% 85% / 0.9)
--color-border-strong: hsl(220 12% 70% / 0.9)
--color-text: var(--gray-800)
--color-text-muted: var(--gray-500)
--color-accent: var(--blue-500)
--color-accent-strong: var(--blue-600)
--color-accent-soft: hsl(218 88% 61% / 0.12)
--color-primary-1: var(--blue-500)
--color-primary-2: hsl(271 72% 60%)
--color-primary-3: hsl(192 76% 48%)
```

## Dark Mode Values

Current dark-mode surface values:

```text
--color-canvas: var(--gray-900)
--color-surface: hsl(220 23% 14% / 0.92)
--color-surface-muted: hsl(220 22% 12% / 0.96)
--color-surface-hover: hsl(220 18% 20% / 0.96)
--color-border: hsl(220 12% 26% / 0.9)
--color-border-strong: hsl(220 12% 38% / 0.9)
--color-text: hsl(210 20% 96%)
--color-text-muted: hsl(220 12% 70%)
--color-accent: hsl(217 91% 67%)
--color-accent-strong: hsl(218 88% 61%)
--color-accent-soft: hsl(217 91% 67% / 0.18)
--color-primary-1: hsl(217 91% 67%)
--color-primary-2: hsl(272 80% 70%)
--color-primary-3: hsl(190 84% 62%)
```

---

## What Controls What

### 1. App Background

File:

- `Frontend/src/components/shell/AppShell/AppShell.module.scss`

The outer app frame uses:

```scss
background: var(--color-canvas);
color: var(--color-text);
```

So if you want to change the overall page backdrop, change `--color-canvas`.

### 2. Main Shell Split Background

File:

- `Frontend/src/components/shell/AppShell/AppShell.module.scss`

The shell derives two important internal surface blends:

```text
--sidebar-panel-surface: color-mix(in srgb, var(--color-surface-muted) 92%, transparent)
--workspace-panel-surface: color-mix(in srgb, var(--color-canvas) 94%, var(--color-surface))
```

It also derives frame/separator borders:

```text
--shell-frame-border: color-mix(in srgb, var(--color-border-strong) 44%, transparent)
--shell-divider-border: color-mix(in srgb, var(--color-border-strong) 34%, transparent)
```

Surface usage inside the shell:

- `.body` → `var(--color-surface)`
- `.railColumn` → `var(--color-surface)`
- `.sidebarColumn` → `var(--sidebar-panel-surface)`
- `.workspaceMain` → `var(--workspace-panel-surface)`

The major left/right shell background is drawn by `workspaceRegion::before` using a
horizontal gradient from sidebar surface to workspace surface.

### 3. Standard Content Cards

File:

- `Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.module.scss`

Cards currently use:

```text
background: var(--color-surface)
border: 1px solid var(--color-border)
box-shadow: var(--shadow-soft)
```

If cards feel too flat or too strong, start by adjusting:

- `--color-surface`
- `--color-border`

### 4. Top Bar

File:

- `Frontend/src/components/shell/TopBar/TopBar.module.scss`

The top bar itself uses:

```text
background: var(--color-surface)
```

Hover/focus states for top-right controls use transparent mixes based on:

- `--color-text`
- `--color-accent-strong`

So the bar is mostly controlled by `--color-surface`, while the interactive polish
comes from text/accent tokens.

### 5. Server Dock

File:

- `Frontend/src/components/shell/ServerDock/ServerDock.module.scss`

The dock uses two derived tokens:

```text
--server-dock-border: color-mix(in srgb, var(--color-border-strong) 75%, transparent)
--server-dock-surface: color-mix(in srgb, var(--color-surface) 94%, transparent)
```

That means the dock is visually tied most strongly to:

- `--color-surface`
- `--color-border-strong`

The server glyph fill uses a soft accent wash derived from:

- `--color-accent-soft`

### 6. Project Drawer

File:

- `Frontend/src/components/shell/ProjectSelector/ProjectSelector.module.scss`

Important layers:

- scrim:
  - `color-mix(in srgb, black 8%, transparent)`
- drawer panel surface:
  - defined in `.drawer::before`
  - vertical gradient from `--color-surface` to `--color-surface-muted`
- current-project summary block:
  - `color-mix(in srgb, var(--color-surface) 72%, transparent)`
- menu row hover:
  - based on `--color-surface-hover`
- menu row active:
  - based on `--color-surface`

So the drawer’s look is mainly shaped by:

- `--color-surface`
- `--color-surface-muted`
- `--color-surface-hover`
- `--color-border-strong`

### 7. Department Selector Dropdown

File:

- `Frontend/src/components/shell/DepartmentSelector/DepartmentSelector.module.scss`

The department dropdown is intentionally solid, not blurred.

It uses:

```text
.menu background: var(--color-surface-muted)
.menu border: 1px solid var(--color-border-strong)
.menuItem background: var(--color-surface-muted)
.submenuItem background: var(--color-surface-muted)
hover/active rows: var(--color-surface)
```

If the department menu feels too heavy or too subtle, start by adjusting:

- `--color-surface-muted`
- `--color-surface`
- `--color-border-strong`

---

## Quick Tuning Guide

If you want to change the overall visual mood quickly, these are the highest-leverage tokens:

### Make the app feel lighter / airier

Adjust:

- `--color-canvas`
- `--color-surface`
- `--color-surface-muted`

### Make shells/cards feel more separated

Adjust:

- `--color-border`
- `--color-border-strong`
- `--color-surface-muted`

### Make accent washes more or less noticeable

Adjust:

- `--color-accent-soft`

### Change the visual personality of the profile ring

Adjust:

- `--color-primary-1`
- `--color-primary-2`
- `--color-primary-3`

---

## Practical Rule Of Thumb

Use this mental model:

```text
canvas           = app/page background
surface          = primary panel or card
surface-muted    = quieter secondary panel
surface-hover    = solid hover state
border           = normal edge
border-strong    = stronger shell edge or divider
accent-soft      = subtle tinted wash
primary-1/2/3    = decorative multi-color accents
```

If you are unsure where to start, tune these in this order:

1. `--color-canvas`
2. `--color-surface`
3. `--color-surface-muted`
4. `--color-border`
5. `--color-border-strong`
6. `--color-accent-soft`

That usually gives the biggest visual shift with the fewest unintended side effects.