ss-tools/specs/001-unify-frontend-style/data-model.md

Data Model: Frontend Style Unification

Entity: StyleTokenGroup

Purpose: Canonical set of visual decisions reused across routes/components.

Fields

• token_group_id (string, required): Unique identifier of token group.
• name (string, required): Human-readable token group name.
• typography_roles (list, required): Named typography levels (e.g., page-title, section-title, body, helper).
• spacing_scale (list, required): Ordered spacing steps used by layout/components.
• color_roles (list, required): Semantic color roles (primary action, warning, error emphasis, neutral content).
• shape_rules (list, required): Corner/radius and border behavior rules.
• status (enum, required): draft | active | deprecated.

Validation Rules

• Must contain at least one typography role, spacing step, and color role.
• active token groups must not contain conflicting role names.

---

Entity: UIPatternRule

Purpose: Reusable contract for structural/interactive patterns.

Fields

• pattern_id (string, required): Unique pattern identifier.
• pattern_type (enum, required): page-shell | action-bar | card | form-section | state-block.
• target_scope (list, required): Routes or component families where rule applies.
• layout_requirements (list, required): Structural rules (placement, grouping, spacing).
• interaction_requirements (list, required): Behavior/state requirements.
• exception_policy (string, required): Allowed deviation rules.
• status (enum, required): proposed | approved | retired.

Validation Rules

• Each approved pattern must map to at least one scope item.
• Pattern must define at least one layout and one interaction requirement.

---

Entity: StatePresentationPattern

Purpose: Canonical representation for loading/empty/error/success feedback.

Fields

• state_pattern_id (string, required): Unique state pattern identifier.
• state_type (enum, required): loading | empty | success | error.
• message_tone_rule (string, required): Tone/voice constraint for user text.
• placement_rule (string, required): Where state is shown in page/component layout.
• recovery_action_rule (string, optional): Recovery expectations (e.g., retry, fix input).
• accessibility_notes (list, required): Focus/contrast/readability constraints.
• i18n_rule (string, required): Localization requirement for state text.

Validation Rules

• error and empty states should include explicit recovery guidance.
• Every state pattern must include i18n and accessibility notes.

---

Entity: ConformanceScopeItem

Purpose: Track conformance status of a route/component group to unified style.

Fields

• scope_item_id (string, required): Unique scope record identifier.
• scope_type (enum, required): route | component-group.
• scope_name (string, required): Name of route/component area.
• applied_token_group_id (string, optional): Linked active token group.
• applied_pattern_ids (list, optional): Linked pattern IDs.
• conformance_status (enum, required): not-started | partial | conformant | deferred.
• exception_reason (string, optional): Why full conformance is deferred.
• followup_action (string, optional): Planned action for deferred areas.
• owner (string, optional): Responsible implementation owner/team.
• last_review_date (date, optional): Last conformance verification date.

Validation Rules

• deferred status requires both exception_reason and followup_action.
• conformant status requires at least one applied token/pattern link.

---

Relationships

• StyleTokenGroup 1..N -> ConformanceScopeItem
  A token group can apply to multiple scope items.
• UIPatternRule N..N -> ConformanceScopeItem
  Multiple patterns may apply per scope item; one pattern can serve many scope items.
• StatePresentationPattern 1..N -> UIPatternRule
  State patterns are referenced by pattern rules where states are rendered.

---

State Transition Notes

ConformanceScopeItem Lifecycle

not-started -> partial -> conformant
partial -> deferred (if blocked by legacy constraints)
deferred -> partial -> conformant (after follow-up implementation)

StyleTokenGroup Lifecycle

draft -> active -> deprecated

---

Volume / Scale Assumptions

• Scope tracking is bounded to targeted primary routes and shared component groups.
• Pattern/token entities are low-volume and human-curated.
• Review updates occur during iterative feature delivery, not high-frequency runtime events.