# 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.