SOTER Design System Specification

Purpose

This specification defines SOTER's design system: visual identity, typography, color model, UI tokens, component class vocabulary, and the relationship to Carbon-inspired implementation patterns.

The system is SOTER-owned. Carbon may inform component ergonomics and enterprise UI conventions, but SOTER must not name or structure its design language as a Carbon dependency.

Scope

This document covers:

• brand foundation and visual identity;
• typography and density;
• color roles and theme presets;
• CSS token catalog;
• component class vocabulary;
• migration from framework-specific styling to SOTER-owned tokens;
• validation rules for UI and documentation surfaces.

Non-Goals

• This document does not define the full frontend implementation.
• This document does not define generated UI interaction files; see LogosInteractionFileSpec.md.
• This document does not define projection layout algorithms; see ProjectionLayoutStrategiesSpec.md.

Terminology

Model or Contract

Brand Foundation

SOTER's visual language should communicate:

• operational clarity;
• trust and auditability;
• text-first modeling;
• semantic precision;
• enterprise readiness without generic SaaS decoration.

The interface should feel work-focused, dense enough for repeated use, and quiet enough to support analysis. It should avoid decorative gradients, vague stock imagery, and oversized marketing composition in operational surfaces.

Typography

Typography must prioritize readability and stable layout. Use restrained heading scales in tools, dashboards, forms, and technical views. Reserve large display type for public-facing entry points or true hero contexts.

Recommended roles:

Color System

Colors are split into brand and functional layers.

Brand tokens identify SOTER. Functional tokens express UI role. Do not overload one --soter-* namespace with both brand identity and surface state unless the token name makes the role explicit.

Recommended categories:

--soter-brand-*
--soter-surface-*
--soter-text-*
--soter-border-*
--soter-accent-*
--soter-status-*
--soter-focus-*

Token Catalog

The minimum token surface is:

:root {
  --soter-brand-primary: #1f4f8f;
  --soter-brand-secondary: #0f766e;
  --soter-surface-page: #f7f8fa;
  --soter-surface-panel: #ffffff;
  --soter-surface-muted: #eef2f6;
  --soter-text-primary: #172033;
  --soter-text-secondary: #4f5f73;
  --soter-border-subtle: #d6dde8;
  --soter-border-strong: #9aa8ba;
  --soter-accent-graph: #8b5cf6;
  --soter-status-success: #16803c;
  --soter-status-warning: #a16207;
  --soter-status-danger: #b42318;
  --soter-focus-ring: #2563eb;
}

These values are baseline tokens, not a final visual identity audit. Any future brand refinement must preserve the category split.

Component Class Vocabulary

Component classes should name stable UI roles rather than implementation framework internals:

soter-app-shell
soter-sidebar
soter-toolbar
soter-panel
soter-section
soter-table
soter-form
soter-field
soter-button
soter-button-primary
soter-button-secondary
soter-status-pill
soter-code-block
soter-diagram-surface
soter-model-editor
soter-inspector

Framework-specific classes may exist inside implementation code, but documentation and generated UI contracts should use SOTER-owned vocabulary.

Carbon-Inspired Migration

Carbon is useful as an enterprise UI reference: accessible components, dense tables, form patterns, status labels, and predictable toolbars. SOTER should borrow patterns, not identity.

Migration rule:

Carbon pattern -> SOTER token/component vocabulary -> implementation adapter

Do not expose Carbon naming as the canonical design language.

Rules

• Prefer functional token names over color names in component CSS.
• Keep brand tokens separate from surface, text, border, and status tokens.
• Keep operational UI dense, scannable, and restrained.
• Use cards only for repeated items, modals, or genuinely framed tools.
• Avoid nested cards and decorative page-section cards.
• Keep text within container bounds on desktop and mobile.
• Use icons for common tool actions where a standard icon exists.
• Treat design tokens as a contract referenced by generated UI surfaces.
• Treat Carbon as inspiration or implementation detail, not as SOTER's design source of truth.

Examples

Operational Panel

<section class="soter-panel">
  <header class="soter-toolbar">
    <button class="soter-button-primary">Validate</button>
  </header>
  <div class="soter-model-editor"></div>
</section>

Status Token Use

.soter-status-pill[data-state="warning"] {
  color: var(--soter-status-warning);
  border-color: var(--soter-status-warning);
}

Validation

Validate design-system use by checking:

• no new public component vocabulary is introduced without adding it here;
• brand tokens and functional tokens remain separate;
• operational UI avoids marketing-style composition;
• generated UI surfaces reference SOTER-owned classes/tokens;
• components remain legible and non-overlapping at supported viewport widths.

Compatibility

This document supersedes the previous split between visual identity, UI token catalog, and Carbon-inspired integration. Existing references to those documents should be redirected here.

Open Questions

• Should token values be generated from a source JSON file?
• Which UI components require first-class generated interaction contracts?
• Should public marketing pages use a separate visual theme derived from the same brand tokens?

Related Documents

• ProjectionOverview.md - projection and rendered output context.
• TechnicalArchitectureSpec.md - web interface and architecture context.
• LogosInteractionFileSpec.md - generated interaction surface contract.
• ProjectionLayoutStrategiesSpec.md - visual layout strategy.
• DocumentationStyleGuide.md - writing profile and document-type rules.
• TechnicalSpecTemplate.md - technical document template.