mirror of
https://github.com/different-ai/openwork
synced 2026-04-25 17:15:34 +02:00
new design
This commit is contained in:
Benjamin Shafii
474
DESIGN-SYSTEM.md
Normal file
474
DESIGN-SYSTEM.md
Normal file
@@ -0,0 +1,474 @@
|
||||
# OpenWork Design System
|
||||
|
||||
This document turns the visual direction in `DESIGN-LANGUAGE.md` into an implementation system that can unify:
|
||||
|
||||
- `apps/app` (OpenWork app)
|
||||
- `ee/apps/den-web` (OpenWork Cloud / Den web surfaces)
|
||||
- `ee/apps/landing` (marketing + product storytelling)
|
||||
|
||||
The goal is not to create three similar styles. The goal is one OpenWork design system with a few environment-specific expressions.
|
||||
|
||||
---
|
||||
|
||||
## 1. Why this exists
|
||||
|
||||
Today the product already has the beginnings of a system, but it is split across:
|
||||
|
||||
- app-specific CSS variables in `apps/app/src/app/index.css`
|
||||
- Tailwind theme setup in `apps/app/tailwind.config.ts`
|
||||
- Radix color tokens in `apps/app/src/styles/colors.css`
|
||||
- repeated utility-class decisions across app, Cloud, and landing
|
||||
|
||||
That creates three problems:
|
||||
|
||||
1. the app and Cloud can feel related but not identical
|
||||
2. visual decisions are made at the screen level instead of the system level
|
||||
3. tokens, primitives, and page composition rules are not clearly separated
|
||||
|
||||
This file defines the missing structure.
|
||||
|
||||
---
|
||||
|
||||
## 2. System model
|
||||
|
||||
OpenWork should use a three-layer design system:
|
||||
|
||||
### Layer 1: Foundations
|
||||
|
||||
Raw design tokens:
|
||||
|
||||
- color
|
||||
- typography
|
||||
- spacing
|
||||
- radius
|
||||
- shadow
|
||||
- motion
|
||||
|
||||
These are the only values components should depend on directly.
|
||||
|
||||
### Layer 2: Semantic tokens
|
||||
|
||||
Product-meaning tokens:
|
||||
|
||||
- `surface.page`
|
||||
- `surface.panel`
|
||||
- `surface.sidebar`
|
||||
- `text.primary`
|
||||
- `text.secondary`
|
||||
- `border.subtle`
|
||||
- `action.primary.bg`
|
||||
- `state.hover`
|
||||
- `state.selected`
|
||||
|
||||
These should map foundation tokens into product meaning.
|
||||
|
||||
### Layer 3: Component primitives
|
||||
|
||||
Reusable building blocks:
|
||||
|
||||
- Button
|
||||
- Card
|
||||
- Input
|
||||
- Modal shell
|
||||
- Sidebar shell
|
||||
- List row
|
||||
- Status pill
|
||||
- Section header
|
||||
- Empty state
|
||||
|
||||
Pages should mostly compose these primitives, not invent their own visual logic.
|
||||
|
||||
---
|
||||
|
||||
## 3. Relationship to existing docs
|
||||
|
||||
- `DESIGN-LANGUAGE.md` = visual philosophy and qualitative rules
|
||||
- `DESIGN-SYSTEM.md` = implementation structure and migration plan
|
||||
|
||||
If there is a conflict:
|
||||
|
||||
1. `DESIGN-LANGUAGE.md` decides what the product should feel like
|
||||
2. `DESIGN-SYSTEM.md` decides how to encode that in tokens and primitives
|
||||
|
||||
---
|
||||
|
||||
## 4. Core principle: one system, three expressions
|
||||
|
||||
OpenWork has three main UI contexts:
|
||||
|
||||
1. **App expression** — denser, flatter, operational
|
||||
2. **Cloud expression** — still operational, slightly more editorial and roomy
|
||||
3. **Landing expression** — more atmospheric, but still clearly the same product family
|
||||
|
||||
These should differ mostly in:
|
||||
|
||||
- spacing density
|
||||
- shell scale
|
||||
- amount of atmosphere
|
||||
- page composition
|
||||
|
||||
They should **not** differ in:
|
||||
|
||||
- brand color logic
|
||||
- button language
|
||||
- border philosophy
|
||||
- type hierarchy
|
||||
- selection behavior
|
||||
|
||||
---
|
||||
|
||||
## 5. Canonical token architecture
|
||||
|
||||
We should converge on a small token set that works everywhere.
|
||||
|
||||
### 5.1 Foundation color tokens
|
||||
|
||||
Use Radix as the raw palette source, but not as the public API for product styling.
|
||||
|
||||
Raw palette source:
|
||||
|
||||
- Radix gray/slate/sage for neutrals
|
||||
- Radix red/amber/green/blue for semantic states
|
||||
|
||||
### 5.2 Semantic color tokens
|
||||
|
||||
Canonical semantic token set:
|
||||
|
||||
- `--ow-color-page`
|
||||
- `--ow-color-surface`
|
||||
- `--ow-color-surface-subtle`
|
||||
- `--ow-color-surface-sidebar`
|
||||
- `--ow-color-border`
|
||||
- `--ow-color-border-strong`
|
||||
- `--ow-color-text`
|
||||
- `--ow-color-text-muted`
|
||||
- `--ow-color-text-subtle`
|
||||
- `--ow-color-accent`
|
||||
- `--ow-color-accent-hover`
|
||||
- `--ow-color-hover`
|
||||
- `--ow-color-active`
|
||||
- `--ow-color-success`
|
||||
- `--ow-color-warning`
|
||||
- `--ow-color-danger`
|
||||
|
||||
These should become the shared API across app and Cloud.
|
||||
|
||||
### 5.3 Current mapping from app tokens
|
||||
|
||||
Existing app tokens already point in the right direction:
|
||||
|
||||
- `--dls-app-bg` -> `--ow-color-page`
|
||||
- `--dls-surface` -> `--ow-color-surface`
|
||||
- `--dls-sidebar` -> `--ow-color-surface-sidebar`
|
||||
- `--dls-border` -> `--ow-color-border`
|
||||
- `--dls-text-primary` -> `--ow-color-text`
|
||||
- `--dls-text-secondary` -> `--ow-color-text-muted`
|
||||
- `--dls-accent` -> `--ow-color-accent`
|
||||
- `--dls-accent-hover` -> `--ow-color-accent-hover`
|
||||
|
||||
We should migrate by aliasing first, not by breaking everything at once.
|
||||
|
||||
---
|
||||
|
||||
## 6. Typography system
|
||||
|
||||
Typography should be systemized into roles, not ad hoc text sizes.
|
||||
|
||||
### Roles
|
||||
|
||||
- **display** — rare marketing or hero usage
|
||||
- **headline** — page and section headers
|
||||
- **title** — card and object titles
|
||||
- **body** — default reading text
|
||||
- **meta** — labels, helper copy, secondary information
|
||||
- **micro** — pills, badges, tiny metadata
|
||||
|
||||
### Shared rules
|
||||
|
||||
- one main sans family across product surfaces
|
||||
- medium weight does the majority of hierarchy work
|
||||
- muted text is the default support color
|
||||
- avoid large type jumps inside the app
|
||||
|
||||
---
|
||||
|
||||
## 7. Spacing system
|
||||
|
||||
OpenWork should use a consistent spacing scale instead of one-off values.
|
||||
|
||||
Recommended base scale:
|
||||
|
||||
- 4
|
||||
- 8
|
||||
- 12
|
||||
- 16
|
||||
- 20
|
||||
- 24
|
||||
- 32
|
||||
- 40
|
||||
- 48
|
||||
- 64
|
||||
|
||||
### Usage guidance
|
||||
|
||||
- micro control padding: 8–12
|
||||
- row padding: 12–16
|
||||
- card padding: 20–24
|
||||
- major section padding: 32–48
|
||||
- page rhythm: 48–64 on roomy surfaces, 24–32 in dense app surfaces
|
||||
|
||||
---
|
||||
|
||||
## 8. Radius system
|
||||
|
||||
Canonical radius roles:
|
||||
|
||||
- `--ow-radius-control` — small controls and rows
|
||||
- `--ow-radius-card` — cards and panels
|
||||
- `--ow-radius-shell` — sidebars, large grouped containers, modal shells
|
||||
- `--ow-radius-pill` — buttons, tabs, chips
|
||||
|
||||
Suggested mapping:
|
||||
|
||||
- control: 12px
|
||||
- card: 16px
|
||||
- shell: 24px–32px
|
||||
- pill: 9999px
|
||||
|
||||
---
|
||||
|
||||
## 9. Shadow system
|
||||
|
||||
Shadow should be a named system with very few levels.
|
||||
|
||||
- `--ow-shadow-none`
|
||||
- `--ow-shadow-control`
|
||||
- `--ow-shadow-card`
|
||||
- `--ow-shadow-shell`
|
||||
|
||||
Default behavior:
|
||||
|
||||
- app: mostly `none` or `control`
|
||||
- Cloud: mostly `none`, `control`, occasional `card`
|
||||
- landing: selective `card` or `shell`
|
||||
|
||||
---
|
||||
|
||||
## 10. Component primitive families
|
||||
|
||||
We should explicitly define a small primitive set shared across product surfaces.
|
||||
|
||||
### 10.1 Action primitives
|
||||
|
||||
- Primary button
|
||||
- Secondary button
|
||||
- Ghost button
|
||||
- Destructive button
|
||||
- Segmented pill / tab item
|
||||
|
||||
### 10.2 Structure primitives
|
||||
|
||||
- Page shell
|
||||
- Sidebar shell
|
||||
- Card
|
||||
- Quiet card
|
||||
- Modal shell
|
||||
- Section divider
|
||||
|
||||
### 10.3 Input primitives
|
||||
|
||||
- Text input
|
||||
- Textarea
|
||||
- Select
|
||||
- Checkbox/radio treatment
|
||||
- Inline field group
|
||||
|
||||
### 10.4 Navigation primitives
|
||||
|
||||
- Sidebar row
|
||||
- List row
|
||||
- Topbar item
|
||||
- Breadcrumb / section tab
|
||||
|
||||
### 10.5 Feedback primitives
|
||||
|
||||
- Status pill
|
||||
- Banner
|
||||
- Empty state
|
||||
- Toast
|
||||
|
||||
---
|
||||
|
||||
## 11. System-first implementation rules
|
||||
|
||||
### Rule 1: prefer semantic tokens over raw utility colors
|
||||
|
||||
Prefer:
|
||||
|
||||
- `bg-[var(--ow-color-surface)]`
|
||||
- `text-[var(--ow-color-text-muted)]`
|
||||
|
||||
Over:
|
||||
|
||||
- `bg-white`
|
||||
- `text-gray-500`
|
||||
|
||||
Raw grays are still acceptable for temporary legacy usage, but new primitives should use semantic tokens.
|
||||
|
||||
### Rule 2: page code should not define new visual language
|
||||
|
||||
Page files can compose primitives and choose layouts.
|
||||
They should not invent new button styles, new shadow rules, or new selection patterns.
|
||||
|
||||
### Rule 3: Radix stays underneath the system
|
||||
|
||||
Radix is the palette source.
|
||||
OpenWork tokens are the product API.
|
||||
|
||||
### Rule 4: app and Cloud should share primitives even if frameworks differ
|
||||
|
||||
Even when implementations differ, the primitive names and behaviors should match.
|
||||
|
||||
Example:
|
||||
|
||||
- `Button` in app
|
||||
- `Button` in den-web
|
||||
|
||||
Both should resolve to the same token logic and visual rules.
|
||||
|
||||
---
|
||||
|
||||
## 12. Migration strategy
|
||||
|
||||
Do not redesign everything at once.
|
||||
Use this sequence.
|
||||
|
||||
### Phase 1: lock the foundations
|
||||
|
||||
1. create canonical semantic tokens
|
||||
2. alias current app tokens to the new token names
|
||||
3. document primitive families and approved variants
|
||||
|
||||
### Phase 2: unify the most reused primitives
|
||||
|
||||
Start with:
|
||||
|
||||
1. Button
|
||||
2. Card
|
||||
3. Input
|
||||
4. Sidebar row
|
||||
5. Modal shell
|
||||
|
||||
These give the largest visual consistency gain.
|
||||
|
||||
### Phase 3: unify shell patterns
|
||||
|
||||
Standardize:
|
||||
|
||||
- page background
|
||||
- sidebar shell
|
||||
- panel/card shell
|
||||
- list row selection
|
||||
- headers and section spacing
|
||||
|
||||
### Phase 4: refactor high-traffic screens
|
||||
|
||||
Prioritize:
|
||||
|
||||
- workspace/session surfaces in `apps/app`
|
||||
- Cloud dashboard shells in `ee/apps/den-web`
|
||||
- share/package/connect flows in `apps/app`
|
||||
|
||||
### Phase 5: remove local style drift
|
||||
|
||||
As primitives stabilize:
|
||||
|
||||
- reduce repeated one-off class recipes
|
||||
- replace raw gray classes in repeated patterns
|
||||
- collapse duplicate card/button/input styles into primitives
|
||||
|
||||
---
|
||||
|
||||
## 13. Recommended initial source of truth files
|
||||
|
||||
If we implement this system, the likely canonical files should be:
|
||||
|
||||
- `DESIGN-LANGUAGE.md` — philosophy
|
||||
- `DESIGN-SYSTEM.md` — system rules and migration plan
|
||||
- `apps/app/src/app/index.css` — initial token host for app runtime
|
||||
- `apps/app/tailwind.config.ts` — Tailwind token exposure
|
||||
- `apps/app/src/app/components/button.tsx` — canonical action primitive start
|
||||
- `apps/app/src/app/components/card.tsx` — canonical surface primitive start
|
||||
- `apps/app/src/app/components/text-input.tsx` — canonical field primitive start
|
||||
|
||||
Later, a shared package may make sense, but not before the token model is stable.
|
||||
|
||||
---
|
||||
|
||||
## 14. Recommended file plan for the next step
|
||||
|
||||
The smallest safe implementation path is:
|
||||
|
||||
### Step A
|
||||
|
||||
Introduce canonical `--ow-*` aliases in `apps/app/src/app/index.css` without removing `--dls-*` yet.
|
||||
|
||||
### Step B
|
||||
|
||||
Refactor `Button`, `Card`, and `TextInput` to consume shared semantic tokens.
|
||||
|
||||
### Step C
|
||||
|
||||
Use the Den dashboard shell as the reference for:
|
||||
|
||||
- sidebar shell
|
||||
- row selection
|
||||
- neutral panel rhythm
|
||||
|
||||
### Step D
|
||||
|
||||
Restyle one OpenWork app screen fully using the system to prove the direction.
|
||||
|
||||
Recommended pilot screens:
|
||||
|
||||
- `apps/app/src/app/pages/settings.tsx`
|
||||
- session/workspace sidebar surfaces
|
||||
- share workspace modal
|
||||
|
||||
---
|
||||
|
||||
## 15. What a successful system looks like
|
||||
|
||||
We will know this is working when:
|
||||
|
||||
1. app, Cloud, and landing feel obviously from the same product family
|
||||
2. a new screen can be built mostly from existing primitives
|
||||
3. visual changes happen by adjusting tokens or primitives, not by editing many pages
|
||||
4. selection, buttons, cards, and inputs behave consistently everywhere
|
||||
5. raw color classes become uncommon outside truly local exceptions
|
||||
|
||||
---
|
||||
|
||||
## 16. Anti-goals
|
||||
|
||||
This system should not:
|
||||
|
||||
- introduce a trendy visual reboot disconnected from the current product
|
||||
- replace the OpenWork mood described in `DESIGN-LANGUAGE.md`
|
||||
- depend on a large new dependency just to manage styling
|
||||
- force a shared package too early
|
||||
- block incremental improvements until a perfect system exists
|
||||
|
||||
The correct approach is a strong design system built through small, boring, compounding steps.
|
||||
|
||||
---
|
||||
|
||||
## 17. Immediate next recommendation
|
||||
|
||||
If continuing from this doc, the best next change is:
|
||||
|
||||
1. add `--ow-*` semantic token aliases in `apps/app/src/app/index.css`
|
||||
2. standardize `Button`, `Card`, and `TextInput`
|
||||
3. then restyle one app shell to match the calmer Den dashboard direction
|
||||
|
||||
That gives a real system foothold without a broad rewrite.
|
||||
Reference in New Issue
Block a user