79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
# Workspace web design system
|
|
|
|
This document defines the visual rules for `web/workspace`. The current authority for tokens and reusable page/sidebar styling is `web/workspace/src/app.css`.
|
|
|
|
## Design position
|
|
|
|
Workspace web should read as a control surface, not a set of detached widgets. Group information primarily through spacing, typography, and text contrast. Use borders, rounded rectangles, shadows, and filled panels only when they clarify hierarchy that spacing cannot express.
|
|
|
|
## Palette
|
|
|
|
Colors are defined as CSS custom properties in OKLCH. The palette supports light and dark modes through `prefers-color-scheme`.
|
|
|
|
Rules:
|
|
|
|
- Background and layout surfaces use zero chroma: `oklch(... 0 0)`.
|
|
- Primary text and code text are near-neutral warm colors. Because CSS OKLCH exposes chroma (`C`) rather than saturation directly, encode the “about 5% saturation” intent as very low warm chroma, around `C = 0.01` to `0.012`.
|
|
- Muted text reduces lightness/chroma before introducing new hues.
|
|
- Accent/status colors are semantic exceptions. They should mark state, focus, or navigation, not decorate containers.
|
|
- Do not introduce raw hex/rgb colors in Workspace web components. Add or reuse a token in `app.css`.
|
|
|
|
Core tokens:
|
|
|
|
```css
|
|
--bg
|
|
--bg-raised
|
|
--bg-subtle
|
|
--line
|
|
--line-strong
|
|
--text
|
|
--text-strong
|
|
--text-muted
|
|
--text-faint
|
|
--code
|
|
--accent
|
|
--success
|
|
--warning
|
|
--danger
|
|
```
|
|
|
|
## Layout and grouping
|
|
|
|
Prefer vertical rhythm and text hierarchy over card chrome.
|
|
|
|
- Page sections are separated by whitespace and a light top rule.
|
|
- Navigation selection uses a left rule rather than filled pills.
|
|
- Nested records use indentation or top rules, not repeated rounded containers.
|
|
- Shadows are avoided in the base system.
|
|
- Rounded corners are reserved for small controls where hit area shape matters.
|
|
|
|
## Typography
|
|
|
|
- Headings and primary labels use `--text-strong`.
|
|
- Body text uses `--text`.
|
|
- Metadata, helper text, timestamps, and table headings use `--text-muted` or `--text-faint`.
|
|
- Uppercase labels are acceptable for small metadata labels only; avoid large all-caps UI blocks.
|
|
|
|
## Component styling boundary
|
|
|
|
`app.css` owns the shared visual language:
|
|
|
|
- reset/base body styles
|
|
- OKLCH tokens
|
|
- layout primitives
|
|
- page cards/sections
|
|
- sidebar/navigation sections
|
|
- tables, kanban lists, diagnostics, record bodies
|
|
|
|
Svelte components should keep local styles only when a behavior is truly component-specific. If a style affects color, spacing, borders, text hierarchy, or repeated record layout, it belongs in `app.css`.
|
|
|
|
## Adding new UI
|
|
|
|
When adding Workspace web UI:
|
|
|
|
1. Start with semantic HTML and existing classes from `app.css`.
|
|
2. Use spacing and text contrast first.
|
|
3. Use a border only when the boundary carries meaning.
|
|
4. Use background fills only for page-level surfaces or read-only code/record bodies.
|
|
5. If a new color is needed, define it as an OKLCH token and document why the existing semantic tokens are insufficient.
|