Новый экранчик для обзора дашей

2026-02-23 15:54:20 +03:00
parent 0685f50ae7
commit 43dd97ecbf
35 changed files with 32880 additions and 828 deletions
--- a/specs/001-unify-frontend-style/checklists/requirements.md
+++ b/specs/001-unify-frontend-style/checklists/requirements.md
@@ -0,0 +1,42 @@
+# Specification Quality Checklist: Frontend Style Unification
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning  
+**Created**: 2026-02-23  
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## UX Consistency
+
+- [x] Functional requirements fully support the 'Happy Path' in ux_reference.md
+- [x] Error handling requirements match the 'Error Experience' in ux_reference.md
+- [x] No requirements contradict the defined User Persona or Context
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation iteration: 1
+- Result: PASS (all checklist items complete)
+- Specification is ready for planning workflow.
--- a/specs/001-unify-frontend-style/contracts/modules.md
+++ b/specs/001-unify-frontend-style/contracts/modules.md
@@ -0,0 +1,70 @@
+# Module Contracts: Frontend Style Unification
+
+## [DEF:FrontendStyleSystem:Module]
+@TIER: CRITICAL  
+@PURPOSE: Define and enforce unified visual primitives and page-shell rules across targeted frontend routes.  
+@RELATION: DEPENDS_ON -> [DEF:Std:UI_Svelte]  
+@RELATION: DEPENDS_ON -> [DEF:Std:Semantics]  
+@RELATION: BINDS_TO -> [DEF:StyleTokenGroup:Entity]  
+@RELATION: BINDS_TO -> [DEF:UIPatternRule:Entity]  
+@PRE: Target routes/components for unification are identified and included in scope.  
+@PRE: Existing behavior-critical user flows remain available for validation.  
+@POST: Shared visual primitives and shell patterns are applied consistently in targeted scope.  
+@POST: No critical functional flow is removed by style refactor.  
+@UX_STATE: Default -> Users see consistent hierarchy (title/actions/content) across targeted pages.  
+@UX_STATE: Loading -> Loading visuals appear in consistent zones without disruptive layout jumps.  
+@UX_STATE: Error -> Error blocks use consistent emphasis and include a clear recovery action.  
+@UX_STATE: Success -> Confirmation messages follow one tone/placement pattern.  
+@INVARIANT: Unified styling must not regress accessibility-visible focus and readable contrast behavior.
+
+---
+
+## [DEF:RouteShellContract:Component]
+@TIER: CRITICAL  
+@PURPOSE: Standardize route shell structure for primary pages (dashboards, tasks, reports, settings).  
+@RELATION: DEPENDS_ON -> [DEF:FrontendStyleSystem:Module]  
+@PRE: Route provides title context and action area metadata.  
+@POST: Route renders canonical shell order: context/breadcrumbs, title block, action region, content container.  
+@UX_STATE: Default -> Primary action location is discoverable quickly and consistently.  
+@UX_STATE: Empty -> Empty-state container is visually aligned with shell and includes next-step guidance.  
+@UX_RECOVERY: Empty -> User can recover using explicit action (refresh/filter adjust/create flow).
+
+---
+
+## [DEF:StateFeedbackContract:Component]
+@TIER: CRITICAL  
+@PURPOSE: Normalize loading/empty/error/success feedback rendering and wording across modules.  
+@RELATION: DEPENDS_ON -> [DEF:StatePresentationPattern:Entity]  
+@PRE: Module can expose current state category (loading/empty/error/success).  
+@POST: State-specific UI uses canonical placement, tone, and recovery behavior.  
+@UX_STATE: Loading -> Consistent indicator style and placement with stable layout rhythm.  
+@UX_STATE: Empty -> Neutral message + guidance action rendered in standard block.  
+@UX_STATE: Error -> Actionable error messaging with retry/fix path.  
+@UX_STATE: Success -> Concise confirmation in standard visual language.  
+@UX_FEEDBACK: Error -> Emphasis clearly distinguishes failure from neutral status.  
+@UX_RECOVERY: Error -> Retry or corrective action is always visible when recoverable.  
+@INVARIANT: State texts use canonical terminology and remain i18n-compatible.
+
+---
+
+## [DEF:TerminologyConsistencyContract:Module]
+@TIER: STANDARD  
+@PURPOSE: Keep user-facing wording consistent across page shells and state blocks.  
+@RELATION: DEPENDS_ON -> [DEF:Std:Constitution]  
+@PRE: Canonical term list for targeted flows is defined.  
+@POST: Targeted modules avoid mixed synonyms for the same concept.  
+@UX_STATE: Default -> UI labels and status texts remain concise and confidence-building.  
+@INVARIANT: User-facing text remains compatible with existing localization workflow.
+
+---
+
+## Contract Usage Simulation (Key Scenario)
+
+**Scenario**: User navigates from dashboards to reports and encounters a failed data load.
+
+1. `RouteShellContract` ensures both pages keep identical shell rhythm and action placement.
+2. `FrontendStyleSystem` ensures shared primitives (spacing/typography/cards/buttons) are consistent.
+3. `StateFeedbackContract` renders failure using canonical error block with explicit retry action.
+4. `TerminologyConsistencyContract` ensures error wording and action labels are aligned across pages.
+
+**Continuity Check**: No interface mismatch detected between shell-level structure and state-level feedback contracts.
--- a/specs/001-unify-frontend-style/data-model.md
+++ b/specs/001-unify-frontend-style/data-model.md
@@ -0,0 +1,119 @@
+# 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.
--- a/specs/001-unify-frontend-style/plan.md
+++ b/specs/001-unify-frontend-style/plan.md
@@ -0,0 +1,103 @@
+# 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.
--- a/specs/001-unify-frontend-style/quickstart.md
+++ b/specs/001-unify-frontend-style/quickstart.md
@@ -0,0 +1,72 @@
+# Quickstart: Frontend Style Unification
+
+## Purpose
+
+Validate that frontend style unification is implemented consistently across targeted routes without functional regressions.
+
+## Preconditions
+
+- Feature branch: `001-unify-frontend-style`
+- Frontend dependencies installed
+- Application starts successfully in local environment
+- Target routes available: dashboards, tasks, reports, settings
+
+## Validation Flow
+
+### 1) User Story 1 — Consistent Visual Foundation (P1)
+
+1. Open each target route: dashboards, tasks, reports, settings.
+2. Compare visual primitives:
+   - typography hierarchy
+   - spacing rhythm
+   - card/container style
+   - button variant consistency
+3. Confirm no route has conflicting visual language for shared primitives.
+
+**Expected Result**: Shared visual baseline appears coherent across all targeted routes.
+
+---
+
+### 2) User Story 2 — Unified Navigation and Page Shells (P2)
+
+1. Navigate through at least three top-level routes.
+2. Verify shell consistency:
+   - page title placement
+   - context/breadcrumb area behavior
+   - primary/secondary action region location
+   - content container alignment
+3. Confirm transitions do not break orientation cues.
+
+**Expected Result**: Page shell pattern is consistent and predictable across routes.
+
+---
+
+### 3) User Story 3 — Predictable Feedback and States (P3)
+
+1. Trigger loading state on at least two routes.
+2. Trigger empty state and error state where possible.
+3. Trigger one success feedback event (save/update/apply action).
+4. Compare message tone, placement, and recovery actions.
+
+**Expected Result**: Loading/empty/error/success feedback follows one canonical pattern.
+
+---
+
+## Regression Safety Checks
+
+1. Execute core functional flows on dashboards/tasks/reports/settings.
+2. Confirm style unification did not remove or alter business-critical actions.
+3. Confirm focus visibility and readability remain acceptable on updated UI areas.
+
+**Expected Result**: No critical user flow regression and no accessibility degradation.
+
+---
+
+## Conformance Checklist Snapshot
+
+- [ ] Shared primitives aligned in targeted scope
+- [ ] Page shell contract honored
+- [ ] State feedback contract honored
+- [ ] Terminology/tone consistency preserved
+- [ ] i18n-compatible user-facing text
+- [ ] No critical flow regressions
--- a/specs/001-unify-frontend-style/research.md
+++ b/specs/001-unify-frontend-style/research.md
@@ -0,0 +1,87 @@
+# 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).
--- a/specs/001-unify-frontend-style/spec.md
+++ b/specs/001-unify-frontend-style/spec.md
@@ -0,0 +1,131 @@
+# Feature Specification: Frontend Style Unification
+
+**Feature Branch**: `[001-unify-frontend-style]`  
+**Reference UX**: `[ux_reference.md]` (See specific folder)  
+**Created**: 2026-02-23  
+**Status**: Draft  
+**Input**: User description: "Даю тебе полный кардбланш на приведение фронтэнда к единому стилю. Прочитай .ai/ROOT.md, используй всю методологию workflow speckit при разработке. Вперед"
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Consistent Visual Foundation (Priority: P1)
+
+As a product user, I want all major screens and shared UI blocks to look and behave consistently so that the interface feels coherent and predictable.
+
+**Why this priority**: This is the core business value of the request. Without a shared visual baseline, every other UX improvement remains fragmented.
+
+**Independent Test**: Can be fully tested by opening key routes (dashboards, tasks, reports, settings) and confirming that shared UI primitives (spacing, typography hierarchy, cards, buttons, states) are visually consistent and predictable.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user opens two different primary routes, **When** they compare page structure and shared controls, **Then** they see the same spacing rhythm, typography hierarchy, and interaction patterns.
+2. **Given** a user interacts with common controls (buttons, tabs, cards), **When** the controls are viewed across different pages, **Then** they have consistent style variants and state behavior.
+
+---
+
+### User Story 2 - Unified Navigation and Page Shells (Priority: P2)
+
+As a user navigating between sections, I want navigation, headers, and content shells to follow one pattern so that I can orient quickly and reduce navigation errors.
+
+**Why this priority**: Once visual foundation exists, navigation consistency delivers immediate usability gains and lowers cognitive load.
+
+**Independent Test**: Can be tested independently by traversing main navigation paths and confirming shell consistency (title placement, breadcrumbs behavior, action region layout, content container behavior).
+
+**Acceptance Scenarios**:
+
+1. **Given** a user switches between at least three top-level pages, **When** each page loads, **Then** page shell structure (title, context, actions, content container) follows one standard pattern.
+2. **Given** a user relies on breadcrumbs and navigation cues, **When** they move deeper and back in the hierarchy, **Then** navigation cues remain consistent and unambiguous.
+
+---
+
+### User Story 3 - Predictable Feedback and States (Priority: P3)
+
+As a user performing actions, I want loading, empty, success, and error states to be consistent across modules so that I always understand system status and next steps.
+
+**Why this priority**: Consistent state feedback improves trust and task completion, but can be delivered after foundational visual and navigation unification.
+
+**Independent Test**: Can be tested by triggering common states (loading data, empty results, validation errors, successful actions) on selected modules and verifying consistent tone, placement, and recovery guidance.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user opens a page with delayed data, **When** loading is shown, **Then** loading indicators follow one standard style and placement pattern.
+2. **Given** a user encounters an empty or error state, **When** the state appears, **Then** the message format and recovery action style are consistent with other modules.
+
+---
+
+### Edge Cases
+
+- What happens when legacy components cannot be visually aligned without breaking current behavior?  
+  The system keeps behavior intact while applying the closest approved style fallback and records the component for deferred refinement.
+- How does system handle mixed localized text lengths affecting unified layout?  
+  Layout rules must preserve readability and alignment under longer labels and translated text.
+- What happens when a page includes highly custom data widgets that do not match standard containers?  
+  The page still applies shared shell and spacing rules while allowing controlled exceptions for specialized content blocks.
+- How does system handle accessibility-related differences (focus ring, contrast expectations) during unification?  
+  Accessibility-preserving variants take precedence over purely decorative alignment.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST define and apply a single frontend style baseline for typography hierarchy, spacing rhythm, color usage roles, and corner/radius behavior across primary user-facing pages.
+- **FR-002**: System MUST standardize shared component presentation patterns for page headers, cards, buttons, form sections, and content containers.
+- **FR-003**: Users MUST be able to navigate between core sections and observe consistent page shell structure, including title region, contextual navigation cues, and action placement.
+- **FR-004**: System MUST provide consistent state presentation rules for loading, empty, success, and error states in all targeted modules.
+- **FR-005**: System MUST preserve existing functional behavior while applying style unification; visual refactoring must not remove or alter core task flows.
+- **FR-006**: System MUST define explicit exception handling rules for modules/components that cannot fully conform immediately, including fallback styling and documented follow-up actions.
+- **FR-007**: System MUST align user-facing text tone and terminology in UI status messages to a unified voice and naming pattern.
+- **FR-008**: System MUST ensure unified styling remains compatible with existing localization and accessibility expectations (focus visibility, readable contrast, scalable layout for longer labels).
+
+### Key Entities *(include if feature involves data)*
+
+- **Style Token Group**: A logical definition of visual decisions (e.g., typography roles, spacing steps, semantic color roles, shape rules) used to enforce consistent appearance.
+- **UI Pattern Rule**: A reusable standard for structural or interaction patterns (e.g., page shell, action bar, card section, state message block).
+- **State Presentation Pattern**: A canonical rendering and messaging rule for loading, empty, success, and error states.
+- **Conformance Scope Item**: A mapped frontend area (route/component group) with current conformance status, expected target pattern, and exception note if needed.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: At least 90% of targeted primary frontend pages conform to the approved style baseline in a structured review checklist.
+- **SC-002**: Users can identify page title, navigation cue, and primary action location on targeted pages in under 5 seconds during UX validation walkthroughs.
+- **SC-003**: In cross-page UX review, at least 95% of sampled loading/empty/error/success states follow the same message and layout conventions.
+- **SC-004**: At least 80% of internal reviewers rate the updated UI as “visually consistent” or better after unification.
+- **SC-005**: No critical user flow regressions are introduced in the set of core routes covered by the style unification scope.
+
+---
+
+## Test Data Fixtures *(recommended for CRITICAL components)*
+
+### Fixtures
+
+```yaml
+style_review_sample:
+  description: "Representative result set for style conformance review"
+  data:
+    pages_checked:
+      - dashboards
+      - tasks
+      - reports
+      - settings
+    conformance_summary:
+      fully_conformant: 3
+      partially_conformant: 1
+      deferred_exceptions: 1
+
+state_feedback_sample:
+  description: "Representative UI state messages for consistency checks"
+  data:
+    loading_state:
+      message: "Loading data…"
+      action: null
+    empty_state:
+      message: "No items found"
+      action: "Refresh or adjust filters"
+    error_state:
+      message: "Unable to load data"
+      action: "Retry"
+    success_state:
+      message: "Changes saved"
+      action: null
--- a/specs/001-unify-frontend-style/tasks.md
+++ b/specs/001-unify-frontend-style/tasks.md
@@ -0,0 +1,138 @@
+# Tasks: Frontend Style Unification
+
+**Input**: Design docs from `specs/001-unify-frontend-style/`  
+**Prerequisites**: plan.md, spec.md, ux_reference.md, research.md, data-model.md, contracts/modules.md, quickstart.md
+
+## Phase 1: Setup (Project Initialization)
+
+- [ ] T001 Define style-unification scope matrix for target routes/components in specs/001-unify-frontend-style/quickstart.md
+- [ ] T002 Create conformance review checklist baseline in specs/001-unify-frontend-style/quickstart.md
+- [ ] T003 Prepare implementation notes for exception handling workflow in specs/001-unify-frontend-style/research.md
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+- [ ] T004 Define canonical page-shell pattern and shared layout rules in frontend/src/lib/components/layout/PageHeader.svelte
+- [ ] T005 [P] Define standardized card/container pattern alignment in frontend/src/lib/components/ui/Card.svelte
+- [ ] T006 [P] Define standardized action/button hierarchy rules in frontend/src/lib/components/ui/Button.svelte
+- [ ] T007 Define canonical state feedback pattern (loading/empty/error/success) in frontend/src/lib/components/ui/StateBlock.svelte
+- [ ] T008 Align core shared terminology keys for UI statuses/actions in frontend/src/lib/i18n/index.ts
+- [ ] T009 Document deferred exceptions tracking template in specs/001-unify-frontend-style/data-model.md
+
+**Checkpoint**: Foundational style primitives and contracts are in place; user-story delivery can proceed independently.
+
+---
+
+## Phase 3: User Story 1 - Consistent Visual Foundation (Priority: P1)
+
+**Goal**: Unify visual primitives and shared UI presentation across key pages.
+
+**Independent Test**: Open dashboards/tasks/reports/settings and verify typography, spacing, card/container style, and buttons follow one baseline.
+
+- [ ] T010 [US1] Apply unified visual baseline to dashboards page structure in frontend/src/routes/dashboards/+page.svelte
+- [ ] T011 [US1] Apply unified visual baseline to tasks page structure in frontend/src/routes/tasks/+page.svelte
+- [ ] T012 [US1] Apply unified visual baseline to reports page structure in frontend/src/routes/reports/+page.svelte
+- [ ] T013 [US1] Apply unified visual baseline to settings page structure in frontend/src/routes/settings/+page.svelte
+- [ ] T014 [P] [US1] Refactor shared card usage to canonical container rules in frontend/src/lib/components/reports/ReportCard.svelte
+- [ ] T015 [P] [US1] Refactor shared input/control spacing to baseline rules in frontend/src/lib/components/ui/Input.svelte
+- [ ] T016 [US1] Preserve functional behavior while applying visual refactor in frontend/src/routes/tasks/+page.svelte
+- [ ] T017 [US1] Verify implementation matches ux_reference.md (Happy Path & Errors) in specs/001-unify-frontend-style/ux_reference.md
+
+---
+
+## Phase 4: User Story 2 - Unified Navigation and Page Shells (Priority: P2)
+
+**Goal**: Standardize shell/navigation structure so orientation is predictable across sections.
+
+**Independent Test**: Navigate across at least three top-level pages and confirm consistent shell hierarchy and action placement.
+
+- [ ] T018 [US2] Standardize top shell layout behavior for navigation/title/action regions in frontend/src/lib/components/layout/TopNavbar.svelte
+- [ ] T019 [US2] Standardize breadcrumbs pattern and hierarchy rendering in frontend/src/lib/components/layout/Breadcrumbs.svelte
+- [ ] T020 [US2] Align sidebar navigation visual/state consistency with shell patterns in frontend/src/lib/components/layout/Sidebar.svelte
+- [ ] T021 [US2] Align global task drawer shell integration with unified layout rhythm in frontend/src/lib/components/layout/TaskDrawer.svelte
+- [ ] T022 [P] [US2] Align dashboards route shell contract usage in frontend/src/routes/dashboards/+page.svelte
+- [ ] T023 [P] [US2] Align tasks route shell contract usage in frontend/src/routes/tasks/+page.svelte
+- [ ] T024 [P] [US2] Align reports route shell contract usage in frontend/src/routes/reports/+page.svelte
+- [ ] T025 [US2] Verify implementation matches ux_reference.md (Happy Path & Errors) in specs/001-unify-frontend-style/ux_reference.md
+
+---
+
+## Phase 5: User Story 3 - Predictable Feedback and States (Priority: P3)
+
+**Goal**: Ensure loading/empty/error/success feedback is consistent in style, tone, and recovery guidance.
+
+**Independent Test**: Trigger state feedback on targeted modules and confirm canonical message/placement/recovery consistency.
+
+- [ ] T026 [US3] Implement canonical loading/empty/error/success blocks for reports experience in frontend/src/routes/reports/+page.svelte
+- [ ] T027 [US3] Implement canonical loading/empty/error/success blocks for tasks experience in frontend/src/routes/tasks/+page.svelte
+- [ ] T028 [US3] Align report detail feedback states to canonical patterns in frontend/src/lib/components/reports/ReportDetailPanel.svelte
+- [ ] T029 [P] [US3] Align report card status messaging and emphasis consistency in frontend/src/lib/components/reports/ReportCard.svelte
+- [ ] T030 [US3] Normalize user-facing status/recovery terminology via i18n keys in frontend/src/lib/i18n/locales/en.json
+- [ ] T031 [P] [US3] Normalize user-facing status/recovery terminology via i18n keys in frontend/src/lib/i18n/locales/ru.json
+- [ ] T032 [US3] Verify implementation matches ux_reference.md (Happy Path & Errors) in specs/001-unify-frontend-style/ux_reference.md
+
+---
+
+## Final Phase: Polish & Cross-Cutting Concerns
+
+- [ ] T033 Run route-level visual conformance walkthrough and update checklist in specs/001-unify-frontend-style/quickstart.md
+- [ ] T034 [P] Verify no critical flow regressions on dashboards/tasks/reports/settings in frontend/src/routes/dashboards/+page.svelte
+- [ ] T035 [P] Verify accessibility-visible focus/contrast constraints on updated components in frontend/src/lib/components/ui/Button.svelte
+- [ ] T036 Update deferred exceptions and follow-up actions in specs/001-unify-frontend-style/data-model.md
+- [ ] T037 Finalize implementation notes and readiness summary in specs/001-unify-frontend-style/plan.md
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- Setup (Phase 1) → required before Foundational (Phase 2)
+- Foundational (Phase 2) → required before all User Story phases
+- US1 (Phase 3) → MVP baseline
+- US2 (Phase 4) depends on foundational + US1 visual baseline
+- US3 (Phase 5) depends on foundational; can proceed after shell patterns are stable
+- Final Phase depends on completion of selected story scope
+
+### User Story Dependencies
+
+- **US1 (P1)**: Independent MVP slice
+- **US2 (P2)**: Builds on consistent primitives from US1
+- **US3 (P3)**: Can be implemented after foundational state blocks; best after US1/US2 alignment for consistency
+
+---
+
+## Parallel Execution Opportunities
+
+- T005, T006 can run in parallel after T004
+- T014 and T015 can run in parallel in US1
+- T022, T023, T024 can run in parallel in US2
+- T029, T031 can run in parallel in US3
+- T034 and T035 can run in parallel in Final Phase
+
+---
+
+## Implementation Strategy
+
+### MVP First (US1)
+
+1. Complete Phases 1–2
+2. Deliver US1 (consistent visual foundation) with T017 UX verification
+3. Validate quickstart conformance for core routes
+
+### Incremental Delivery
+
+1. Add US2 shell/navigation unification + T025 verification
+2. Add US3 feedback/state consistency + T032 verification
+3. Complete polish and final conformance/regression checks
+
+### Format Validation
+
+All tasks follow required checklist format:
+
+- `- [ ]`
+- Task ID (`Txxx`)
+- `[P]` marker only where parallelizable
+- `[USx]` label on user-story tasks
+- Explicit file path per task
--- a/specs/001-unify-frontend-style/ux_reference.md
+++ b/specs/001-unify-frontend-style/ux_reference.md
@@ -0,0 +1,63 @@
+# UX Reference: Frontend Style Unification
+
+**Feature Branch**: `[001-unify-frontend-style]`
+**Created**: 2026-02-23
+**Status**: Draft
+
+## 1. User Persona & Context
+
+* **Who is the user?**: Product user and internal analyst who frequently switches between dashboards, tasks, reports, and settings.
+* **What is their goal?**: Complete routine operations quickly in a UI that feels consistent, predictable, and trustworthy.
+* **Context**: Browser-based multi-page workflow in the existing web frontend, often under time pressure, with repeated navigation between sections.
+
+## 2. The "Happy Path" Narrative
+
+The user opens the application and immediately recognizes where they are because every page has the same shell rhythm: clear title area, predictable action zone, and familiar content layout. As they move between dashboards, tasks, and reports, controls look and behave the same, so they do not need to relearn interactions. Loading and feedback states appear in the same visual language, which reduces hesitation and prevents mistakes. The overall experience feels coherent, fast to parse, and professionally maintained.
+
+## 3. Interface Mockups
+
+### UI Layout & Flow (if applicable)
+
+**Screen/Component**: Global Page Shell + Section Pages (Dashboards, Tasks, Reports)
+
+* **Layout**:
+  * Unified vertical rhythm for all primary pages.
+  * Consistent top shell: breadcrumb/context (when present), page title, page subtitle/helper text, actions region.
+  * Content area uses standardized containers/cards with the same spacing and header/body semantics.
+* **Key Elements**:
+  * **Primary Action Button**: Same visual hierarchy and placement rule in each section.
+  * **Secondary Actions**: Same grouping and alignment rules near the primary action.
+  * **Card Containers**: Same elevation/border/radius language and internal spacing.
+  * **State Blocks**: Loading, empty, success, and error states share one visual and textual pattern.
+* **States**:
+  * **Default**: Structured and clean; key action is easy to locate in <5 seconds.
+  * **Loading**: Placeholder/skeleton or loader appears in a consistent zone without layout jumps.
+  * **Success**: Confirmation message style is consistent in tone and placement.
+  * **Error**: Error state uses consistent emphasis and an immediate recovery action (e.g., retry).
+  * **Empty**: Neutral empty message with guidance on next action.
+
+## 4. The "Error" Experience
+
+**Philosophy**: Errors should be consistent, informative, and recovery-oriented—never dead ends.
+
+### Scenario A: Validation / Input Conflict
+
+* **User Action**: User applies an invalid filter or submits an incomplete form.
+* **System Response**:
+  * The problematic field/area is highlighted consistently across modules.
+  * A concise message explains what is wrong and what to do next.
+* **Recovery**: User can correct input in-place and retry immediately, without page reload.
+
+### Scenario B: Data Loading Failure
+
+* **User Action**: User opens a page and backend request fails.
+* **System Response**:
+  * A standardized error block appears in the content area.
+  * The message format is consistent with other modules.
+  * A clear recovery action is presented (e.g., "Retry").
+* **Recovery**: User retries from the same state; on success the page returns to normal layout without disorientation.
+
+## 5. Tone & Voice
+
+* **Style**: Concise, clear, and confidence-building.
+* **Terminology**: Use consistent terms across the product (e.g., one canonical term per concept), avoid mixed synonyms in state messages and actions.
--- a/specs/020-task-reports-design/tests/reports/2026-02-23-report.md
+++ b/specs/020-task-reports-design/tests/reports/2026-02-23-report.md
@@ -30,6 +30,14 @@
 | `report_card.ux.test.js` | `lifecycle_function_unavailable` | Svelte 5 Vitest environment mismatch (mount on server error). Logic verified via integration tests. |
 | `report_detail.ux.test.js` | `lifecycle_function_unavailable` | Same as above. |

+## Semantic Protocol Validation (2026-02-23)
+
+- Ran semantic map generation via `python3 generate_semantic_map.py`.
+- Latest compliance artifact: `semantics/reports/semantic_report_20260223_144408.md`.
+- Global Semantic Compliance Score: **91.0%**.
+- Global parser status: **0 errors / 0 warnings**.
+- CRITICAL semantic issue for `backend/src/api/routes/__tests__/test_reports_detail_api.py` (missing `@INVARIANT`) has been resolved and file is now at **100%** in the latest report.
+
 ## Next Steps

 - [ ] Resolve Svelte 5 testing environment configuration for direct component mounting.