104 lines
4.8 KiB
Markdown
104 lines
4.8 KiB
Markdown
# Implementation Plan: Frontend Style Unification
|
|
|
|
**Branch**: `[001-unify-frontend-style]` | **Date**: 2026-02-23 | **Spec**: [spec.md](./spec.md)
|
|
**Input**: Feature specification from `/specs/001-unify-frontend-style/spec.md`
|
|
|
|
## Summary
|
|
|
|
Unify the frontend visual system and interaction patterns across primary product routes so users experience a coherent, predictable interface.
|
|
The implementation approach is to standardize shared UI primitives and page-shell patterns first, then align navigation and state feedback patterns, while preserving existing behavior and i18n/accessibility constraints. UX consistency in `ux_reference.md` is treated as a hard requirement and mapped to concrete component contracts and verification steps.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Node.js 18+ runtime, SvelteKit (existing frontend stack)
|
|
**Primary Dependencies**: SvelteKit, Tailwind CSS, existing frontend UI primitives under `frontend/src/lib/components/ui`
|
|
**Storage**: N/A (UI styling and component behavior only)
|
|
**Testing**: Vitest + existing frontend component/store tests
|
|
**Target Platform**: Web browser (desktop-first internal product UI)
|
|
**Project Type**: Web application (frontend + backend repository, frontend-focused scope)
|
|
**Performance Goals**: Preserve existing perceived responsiveness; avoid layout shifts in loading/error/success/empty states
|
|
**Constraints**:
|
|
- Must follow Tailwind-first styling and avoid introducing native `fetch` usage (Constitution)
|
|
- Must keep user-facing text compatible with existing i18n strategy
|
|
- Must not regress core task flows while refactoring UI
|
|
- Must preserve accessibility-visible focus and readable contrast behavior
|
|
**Scale/Scope**: Core primary routes and shared layout/components used by dashboards, tasks, reports, settings
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
- ✅ **Semantic Protocol Compliance**: Planned artifacts include contracts with `[DEF]`/`@TIER`/`@PRE`/`@POST`/`@UX_STATE` for affected modules in `contracts/modules.md`.
|
|
- ✅ **Unified Frontend Experience**: Scope is frontend style unification with Tailwind-first constraints; i18n consistency explicitly included.
|
|
- ✅ **Independent Testability**: Spec includes independent tests per user story; quickstart includes isolated verification flows.
|
|
- ✅ **Architecture Integrity**: No plugin or backend execution model changes required; frontend-only structural alignment.
|
|
- ⚠️ **Known Repository Risk (External to this feature)**: Multiple `specs/001-*` directories exist in repo and trigger script warnings. Feature plan continues with explicit active feature directory `specs/001-unify-frontend-style`.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/001-unify-frontend-style/
|
|
├── plan.md
|
|
├── research.md
|
|
├── data-model.md
|
|
├── quickstart.md
|
|
├── contracts/
|
|
│ └── modules.md
|
|
└── tasks.md
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
backend/
|
|
└── src/
|
|
├── api/
|
|
├── models/
|
|
└── services/
|
|
|
|
frontend/
|
|
├── src/
|
|
│ ├── lib/
|
|
│ │ ├── components/
|
|
│ │ │ ├── layout/
|
|
│ │ │ ├── reports/
|
|
│ │ │ └── ui/
|
|
│ │ ├── stores/
|
|
│ │ └── i18n/
|
|
│ ├── components/
|
|
│ └── routes/
|
|
└── tests/
|
|
```
|
|
|
|
**Structure Decision**: Use existing web-application layout and implement changes primarily in `frontend/src/lib/components`, `frontend/src/routes`, and related frontend tests.
|
|
|
|
## Phase 0: Research Focus
|
|
|
|
1. Standardize style baseline strategy for existing Tailwind-based Svelte components.
|
|
2. Define migration strategy for legacy/non-conformant components without behavior regression.
|
|
3. Define UX-consistent state patterns (loading/empty/error/success) reusable across pages.
|
|
4. Define i18n and accessibility safeguards during style unification.
|
|
5. Define validation approach (visual conformance + behavior safety checks).
|
|
|
|
## Phase 1: Design & Contracts Outputs
|
|
|
|
- Produce `data-model.md` with style/token/pattern/conformance entities.
|
|
- Produce `contracts/modules.md` with semantic contracts and UX states for critical modules.
|
|
- Produce `quickstart.md` with executable validation steps for independent scenario checks.
|
|
- Re-run Constitution check after design to confirm no UX compromise.
|
|
|
|
## Complexity Tracking
|
|
|
|
No constitution violations requiring explicit exceptions.
|
|
|
|
## Test Data Reference
|
|
|
|
| Component | TIER | Fixture Name | Location |
|
|
|-----------|------|--------------|----------|
|
|
| FrontendStyleReview | CRITICAL | style_review_sample | spec.md#test-data-fixtures |
|
|
| StateFeedbackPattern | CRITICAL | state_feedback_sample | spec.md#test-data-fixtures |
|
|
|
|
**Note**: Tester Agent MUST use these fixtures when writing unit/integration tests for CRITICAL modules.
|