# 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.