tasks ready

specs/013-unify-frontend-css/spec.md

@@ -0,0 +1,102 @@
+# Feature Specification: Unify Frontend CSS & Localization
+
+**Feature Branch**: `013-unify-frontend-css`
+**Created**: 2026-01-23
+**Status**: Draft
+**Input**: User description: "Я хочу унифицировать CSS для фронта. Добавь в спецификацию требование, что я хочу l18n для всех текстовых элементов. Плюс, должен быть переключатель языков. Для начала два языка - русский и английский, русский по умолчанию."
+
+## Clarifications
+
+### Session 2026-01-23
+
+- Q: Should we refactor existing UI elements into reusable Svelte components or just apply standardized CSS utility classes? → A: Create thin wrapper Svelte components (e.g., `<Button variant="primary">`) that apply utility classes internally, using Svelte's reactivity for states.
+- Q: How should the selected language persist across sessions? → A: Use a simple client-side persistence (LocalStorage) for now; migrate to user profile settings later when a full user system is implemented.
+
+## User Scenarios & Testing
+
+### User Story 1 - Consistent Visual Experience (Priority: P1)
+
+As a user, I want the application to look consistent across all pages (Dashboard, Settings, Tools) so that I have a cohesive user experience without jarring visual differences.
+
+**Why this priority**: Inconsistent UI makes the application feel unprofessional and harder to use. Unifying styles ensures a polished look and predictable interactions.
+
+**Independent Test**: Navigate to at least 3 different pages (e.g., Dashboard, Settings, a Tool page) and verify that buttons, inputs, and layout spacing share the same visual properties (colors, padding, border radius).
+
+**Acceptance Scenarios**:
+
+1. **Given** I am on the Dashboard, **When** I look at a primary action button, **Then** it should have the same color, padding, and hover state as a primary action button on the Settings page.
+2. **Given** I am viewing a data table in "Migration", **When** I compare it to a table in "Tasks", **Then** the headers, row spacing, and borders should be identical in style.
+
+---
+
+### User Story 2 - Efficient Design Updates (Priority: P2)
+
+As a designer or developer, I want to change a core brand color in one place and have it reflect across the entire application, so that maintaining the visual identity is fast and error-free.
+
+**Why this priority**: Reduces maintenance time and prevents "drift" where slightly different styles are introduced over time.
+
+**Independent Test**: Change a primary color value in the central configuration and verify it updates on multiple distinct pages without individual code changes.
+
+**Acceptance Scenarios**:
+
+1. **Given** the primary brand color is updated in the central theme, **When** I reload the application, **Then** all primary buttons, links, and active states should reflect the new color immediately.
+2. **Given** a new UI element is added, **When** standard style tokens are applied, **Then** it should automatically match the existing design system without manual pixel adjustments.
+
+---
+
+### User Story 3 - Multi-language Support (Priority: P2)
+
+As a user, I want to switch the interface language between Russian and English so that I can work in my preferred language.
+
+**Why this priority**: Expands accessibility and usability for non-Russian speakers (or English speakers).
+
+**Independent Test**: Switch the language using the UI toggle and verify that static text elements on the page update immediately.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am on any page, **When** I switch the language to "English", **Then** all menu items, labels, and button text should change to English.
+2. **Given** I open the application for the first time, **Then** the interface should be in Russian (default).
+3. **Given** I have selected "English", **When** I refresh the page, **Then** the interface should remain in English (persisted via LocalStorage).
+
+## Edge Cases
+
+- **Legacy Components**: What happens to older components that don't fit the new system?
+    - *Handling*: They should be refactored to use the new system. If refactoring is too complex, they should visually approximate the new system as closely as possible until fully replaced.
+- **Theme Conflicts**: What happens if a specific page requires unique styling that contradicts the global theme?
+    - *Handling*: The system should allow for local overrides, but these should be used sparingly and documented.
+- **Browser Compatibility**: How does the new styling behave on different screen sizes?
+    - *Handling*: The unified styles must support responsive behavior, adapting spacing and font sizes appropriately for standard breakpoints (mobile, tablet, desktop).
+- **Missing Translations**: What happens if a translation key is missing for the selected language?
+    - *Handling*: The system should fallback to the default language (Russian) or display the key itself in a non-breaking way.
+
+## Requirements
+
+### Functional Requirements
+
+- **FR-001**: The system MUST use a centralized configuration for all design tokens (colors, typography, spacing, breakpoints).
+- **FR-002**: The system MUST provide standardized, **thin wrapper Svelte components** (e.g., `<Button variant="primary">`) that encapsulate the design system.
+- **FR-003**: The system MUST NOT use hardcoded color values or "magic numbers" for spacing in individual page views; all styling must reference the central design tokens.
+- **FR-004**: The system MUST ensure consistent spacing (margins and padding) between elements across all layouts.
+- **FR-005**: All existing pages (Dashboard, Settings, Tools) MUST be updated to utilize the new centralized design system components.
+- **FR-006**: The system MUST support **Internationalization (i18n)** for all static text elements.
+- **FR-007**: The system MUST provide a **Language Switcher** in the UI (e.g., Navbar or Settings).
+- **FR-008**: Supported languages MUST be **Russian (RU)** and **English (EN)**.
+- **FR-009**: The default language MUST be **Russian**.
+- **FR-010**: The selected language MUST be persisted in **LocalStorage** to survive page reloads (until a user profile system is implemented).
+
+### Key Entities
+
+- **Design System Configuration**: The single source of truth for visual values (colors, fonts, spacing).
+- **Standardized UI Components**: Reusable Svelte components that implement the design tokens.
+- **Translation Dictionary**: A collection of key-value pairs for text strings in each supported language.
+
+## Success Criteria
+
+### Measurable Outcomes
+
+- **SC-001**: Central design configuration contains definitions for all primary, secondary, background, and status (success/error/warning) colors.
+- **SC-002**: 100% of primary UI elements (buttons, inputs, cards) on key pages (Dashboard, Settings) use the standardized Svelte components.
+- **SC-003**: 0 instances of arbitrary hardcoded color values for primary UI elements remain in the codebase.
+- **SC-004**: Visual regression check confirms that Dashboard, Settings, and Task pages share identical styling for common elements (buttons, tables, headers).
+- **SC-005**: User can successfully switch between Russian and English, with 100% of navigation and primary action text translating correctly.
+- **SC-006**: Selected language persists after a page reload 100% of the time.