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

Design SSOT

Source of truth

• Primary visual source: incoming-files/sample style.css
• Runtime token file: design-tokens.css
• Runtime pattern file: 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