103 lines
7.2 KiB
Markdown
103 lines
7.2 KiB
Markdown
# 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.
|