3.6 KiB
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).