Work/Documentation/STYLING.md

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:

--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:

--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:

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:

--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:

--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:

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:

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:

--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:

.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:

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.