MH-DashBoard-organization/docs/architecture/DESIGN_SSOT.md

# Design SSOT

## Source of truth

- Primary visual source: [incoming-files/sample style.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/incoming-files/sample%20style.css)
- Runtime token file: [design-tokens.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-tokens.css)
- Runtime pattern file: [design-patterns.css](/home/hyunho/projects/mh-dashboard-organization/.dev-worktree-8081/frontend/public/design-patterns.css)

`sample style.css` defines the intended MH visual language. `design-tokens.css` is the token-level SSOT, and `design-patterns.css` is the component-level SSOT that packages those tokens into reusable runtime patterns.

## Rules

- New UI must use `design-tokens.css` variables first.
- New UI must use `design-patterns.css` patterns before adding page-local variants.
- Direct hex values are exceptions, not defaults.
- Page files may define layout and composition, but color, panel, border, radius, and shadow values must come from tokens.
- Shared aliases in `legacy/static/common.css` and `frontend/public/styles.css` exist only to bridge older code to the SSOT.
- Reference files under `incoming-files/*` are not visual authority. Runtime visuals must follow `design-tokens.css` and `design-patterns.css`.

## Fixed vs Flexible

SSOT is not a pixel-locked screenshot spec. It is a design rule system with two layers.

### Fixed rules

These should be treated as stable defaults across screens.

- Brand color family and accent family
- Surface, border, text, and shadow tokens
- Radius scale
- Button, tab, input, panel, and card visual language
- Typography tone and hierarchy
- Background atmosphere and overall contrast direction

### Flexible rules

These must be interpreted per screen based on content density and interaction needs.

- KPI card width and number of columns
- Sidebar/content split ratios
- Table column widths
- Search/filter placement
- Card stacking and wrap behavior
- Desktop/mobile breakpoint behavior

Example:

- Wrong SSOT: `KPI width is 100px`
- Correct SSOT: `KPI cards use the shared panel, radius, spacing, and text hierarchy tokens, and their width adapts to content without collapsing readability`

## When SSOT does not define a component

If a screen needs a pattern that SSOT does not explicitly define yet, do not fall back to arbitrary legacy styling.

Use this order:

1. Reuse existing tokens and the nearest shared pattern
2. Design the missing component in the same visual grammar
3. If the pattern is likely to repeat, document and promote it into SSOT

This applies to examples such as:

- A table pattern that does not exist in the current SSOT
- A KPI strip that needs a different density than the sample
- A new modal layout for a data-heavy screen

## Candidate and deprecated styles

Not every style already visible in the product is automatically part of SSOT.

- `SSOT`
  - Approved and repeatable patterns
  - Token-backed visual rules
- `candidate`
  - Screen-local styles that look usable but do not yet have a documented basis
  - Can be promoted later if they prove reusable
- `deprecated`
  - Old blue/slate/indigo defaults
  - Temporary hardcoded fixes
  - Styles that conflict with the sample-based MH visual language

When a screen has a design with no clear basis, classify it as `candidate` first. Promote it only after it has been checked for reuse and consistency.

## Token groups

- Surface: `--ds-bg`, `--ds-panel`, `--ds-panel-soft`, `--ds-panel-strong`
- Text: `--ds-ink`, `--ds-text-soft`, `--ds-text-muted`
- Brand: `--ds-brand`, `--ds-brand-deep`, `--ds-brand-soft`, `--ds-accent`, `--ds-accent-soft`, `--ds-mint`
- Borders and shadows: `--ds-line`, `--ds-line-soft`, `--ds-shadow-*`
- Layout primitives: `--ds-radius-*`, `--ds-space-*`, `--ds-page-max-width`

## Promoted runtime patterns

These are now the official reusable patterns for current screens.

- Panels and heads: `.ds-panel`, `.ds-panel-head`
- KPI cards: `.ds-kpi-card`, `.ds-kpi-people`, `.ds-kpi-inverse`
- Filter surfaces and toggles: `.ds-filter-surface`, `.ds-filter-toggle`, `.ds-reset-button`
- Tables: `.ds-table-head`, `.ds-table-head-row`, `.ds-table-row`, `.ds-axis-cell`, `.ds-axis-cell-idle`, `.ds-axis-cell-active`
- Value emphasis: `.ds-project-cell`, `.ds-income`, `.ds-expense`, `.ds-subhead`, `.ds-empty`, `.ds-strong`, `.ds-muted`
- Breakdown/detail UI: `.ds-progress-track*`, `.ds-mode-chip`, `.ds-name-chip`, `.ds-mini-table-*`, `.ds-group-title`
- Position chips: `.ds-position-*` via `position-*` compatibility classes
- Business ledger popup/detail blocks: `.popup-*`, `.inline-card`, `.project-head-*`, `.summary-*`, `.ledger-*`, `.badge`, `.project-link`
- Organization modal forms/buttons: `.member-form-*`, `.modal-btn*`
- Seatmap action visibility: `.seatmap-actions .ghost-button`

These patterns may still have compatibility selectors for existing screen classes, but they should now be treated as the official design layer.

## Migration order

1. Token file and common aliases
2. Hub shell and shared controls
3. Team/Personal analysis and Organization
4. Project analysis
5. Business ledger detail cleanup

## Implementation guidance

- Prefer tokenized ranges over hardcoded single values when layout depends on data volume
- Prefer `design-patterns.css` component rules over one-off inline colors
- If a new pattern is introduced during implementation, update this document once the pattern is stable
- If a screen needs an exception, keep the exception local and explain why it cannot follow the shared pattern

## Anti-patterns

- Adding new `#4f46e5`, `#4338ca`, `bg-slate-*`, `text-indigo-*` style defaults
- Reintroducing separate page-level color systems
- Hardcoding “quick fix” brand colors in JS templates when a token/class can carry the same intent
- Letting reference/original files override runtime pattern files