328 lines
7.7 KiB
Markdown
328 lines
7.7 KiB
Markdown
# 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.
|