# Research: Frontend Style Unification

## Decision 1: Tailwind-first unification through shared primitives and layout patterns

**Decision**: Use existing shared UI components and route-level layout patterns as the primary unification mechanism, with Tailwind utility classes as the style source of truth.

**Rationale**:
- Aligns with constitution requirement: Tailwind-first and minimal scoped styles.
- Reduces risk versus page-by-page ad-hoc class rewrites.
- Enables predictable rollout and easier review by centralizing style behavior.

**Alternatives considered**:
- Big-bang rewrite of all pages in one pass (rejected: high regression risk).
- Introducing a second styling abstraction layer (rejected: added complexity and drift).

---

## Decision 2: Incremental conformance with explicit exception registry

**Decision**: Apply style unification incrementally across core routes; for non-conformant legacy widgets, use documented fallback styles and track exceptions for follow-up.

**Rationale**:
- Preserves functional behavior while raising consistency quickly.
- Supports FR-005/FR-006 in spec by preventing disruption of critical flows.
- Makes scope and technical debt explicit.

**Alternatives considered**:
- Block release until 100% conformance (rejected: delays value delivery).
- Ignore non-conformant areas (rejected: no governance and unresolved inconsistency).

---

## Decision 3: Canonical UX state patterns for loading/empty/error/success

**Decision**: Define one reusable state pattern per state type (layout placement, message format, recovery action position) and apply to targeted modules.

**Rationale**:
- Directly supports UX reference and SC-003.
- Improves predictability and user trust.
- Simplifies QA with deterministic state contracts.

**Alternatives considered**:
- Module-specific state designs (rejected: reintroduces inconsistency).
- Visual-only alignment without message/rule alignment (rejected: incomplete UX consistency).

---

## Decision 4: i18n and terminology normalization as part of style work

**Decision**: Include text tone/terminology consistency in scope for user-facing state and action labels; avoid hardcoded strings during updates.

**Rationale**:
- Required by constitution i18n rule.
- Prevents mixed terms after visual unification.
- Supports FR-007 and UX tone requirements.

**Alternatives considered**:
- Deferring terminology to a separate feature (rejected: causes visible inconsistency after style updates).

---

## Decision 5: Accessibility-preserving visual alignment

**Decision**: Keep focus visibility and readable contrast as non-negotiable constraints; when style and accessibility conflict, accessibility wins.

**Rationale**:
- Matches edge-case requirements in spec.
- Reduces user risk and supports sustainable UI governance.
- Prevents regressions masked by purely visual approvals.

**Alternatives considered**:
- Prioritizing strict visual sameness in all cases (rejected: can degrade accessibility outcomes).

---

## Decision 6: Verification model = conformance checklist + route smoke tests + UX state checks

**Decision**: Validate through structured cross-route conformance checks, independent user-story tests, and targeted UX state verification.

**Rationale**:
- Produces measurable evidence for SC-001..SC-005.
- Aligns with independent testability principle in constitution.
- Keeps verification technology-agnostic at feature level while staying executable in project context.

**Alternatives considered**:
- Pure visual review without scenario checks (rejected: misses behavior regressions).
- Full end-to-end redesign QA cycle before incremental rollout (rejected: too heavy for initial unification phase).