tasks ready
This commit is contained in:
@@ -25,6 +25,8 @@ Auto-generated from all feature plans. Last updated: 2025-12-19
|
||||
- Filesystem (local git repo), SQLite (for GitServerConfig, Environment) (011-git-integration-dashboard)
|
||||
- Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, GitPython (or CLI git), Pydantic, SQLAlchemy, Superset API (011-git-integration-dashboard)
|
||||
- SQLite (for config/history), Filesystem (local Git repositories) (011-git-integration-dashboard)
|
||||
- Node.js 18+ (Frontend Build), Svelte 5.x + SvelteKit, Tailwind CSS, `date-fns` (existing) (013-unify-frontend-css)
|
||||
- LocalStorage (for language preference) (013-unify-frontend-css)
|
||||
|
||||
- Python 3.9+ (Backend), Node.js 18+ (Frontend Build) (001-plugin-arch-svelte-ui)
|
||||
|
||||
@@ -45,9 +47,9 @@ cd src; pytest; ruff check .
|
||||
Python 3.9+ (Backend), Node.js 18+ (Frontend Build): Follow standard conventions
|
||||
|
||||
## Recent Changes
|
||||
- 013-unify-frontend-css: Added Node.js 18+ (Frontend Build), Svelte 5.x + SvelteKit, Tailwind CSS, `date-fns` (existing)
|
||||
- 011-git-integration-dashboard: Added Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, GitPython (or CLI git), Pydantic, SQLAlchemy, Superset API
|
||||
- 011-git-integration-dashboard: Added Python 3.9+ (Backend), Node.js 18+ (Frontend) + FastAPI, SvelteKit, GitPython (or CLI git), Pydantic, SQLAlchemy, Superset API
|
||||
- 011-git-integration-dashboard: Added Python 3.9+, Node.js 18+
|
||||
|
||||
|
||||
<!-- MANUAL ADDITIONS START -->
|
||||
|
||||
42
specs/013-unify-frontend-css/checklists/requirements.md
Normal file
42
specs/013-unify-frontend-css/checklists/requirements.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Checklist: Frontend UI & i18n Requirements Quality
|
||||
|
||||
**Purpose**: Validate the quality, clarity, and completeness of the requirements for the unified frontend CSS and localization feature.
|
||||
|
||||
**Meta**:
|
||||
- **Feature**: 013-unify-frontend-css
|
||||
- **Created**: 2026-01-23
|
||||
- **Focus**: UX Consistency, Component Contracts, i18n Completeness
|
||||
|
||||
## Requirement Completeness
|
||||
- [ ] CHK001 Are all necessary UI components (Button, Input, Select, Card, PageHeader) explicitly identified for standardization? [Completeness, Spec §FR-002]
|
||||
- [ ] CHK002 Are the supported languages (RU, EN) and default language (RU) explicitly defined? [Completeness, Spec §FR-008, §FR-009]
|
||||
- [ ] CHK003 Is the persistence mechanism for language selection (LocalStorage) specified? [Completeness, Spec §FR-010]
|
||||
- [ ] CHK004 Are the specific pages (Dashboard, Settings) targeted for migration identified? [Completeness, Spec §FR-005]
|
||||
|
||||
## Requirement Clarity
|
||||
- [ ] CHK005 Is the "consistent spacing" requirement quantified with specific values or a system (e.g., Tailwind scale)? [Clarity, Spec §FR-004]
|
||||
- [ ] CHK006 Are the specific visual properties (color, padding, hover state) that must be consistent defined in the design system configuration? [Clarity, Spec §SC-001]
|
||||
- [ ] CHK007 Is the behavior of "legacy components" clearly defined (refactor vs. approximate)? [Clarity, Spec Edge Cases]
|
||||
|
||||
## Requirement Consistency
|
||||
- [ ] CHK008 Do the component contracts in `contracts/ui-components.md` align with the visual requirements in the spec? [Consistency]
|
||||
- [ ] CHK009 Is the decision to use Svelte stores for i18n consistent with the requirement for client-side persistence? [Consistency, Research §2]
|
||||
|
||||
## Acceptance Criteria Quality
|
||||
- [ ] CHK010 Can the "consistent visual experience" be objectively verified through the defined independent tests? [Measurability, Spec §User Story 1]
|
||||
- [ ] CHK011 Is the "0 instances of arbitrary hardcoded color values" criterion measurable via static analysis or search? [Measurability, Spec §SC-003]
|
||||
- [ ] CHK012 Is the language persistence requirement testable by reloading the page? [Measurability, Spec §SC-006]
|
||||
|
||||
## Scenario Coverage
|
||||
- [ ] CHK013 Are requirements defined for the scenario where a translation key is missing? [Coverage, Spec Edge Cases]
|
||||
- [ ] CHK014 Are requirements defined for the initial load state (default language)? [Coverage, Spec §User Story 3]
|
||||
- [ ] CHK015 Are requirements defined for switching languages while on a page with dynamic content? [Coverage, Gap]
|
||||
|
||||
## Edge Case Coverage
|
||||
- [ ] CHK016 Is the behavior defined for text that overflows when translated to a longer language (e.g., RU vs EN)? [Edge Case, Gap]
|
||||
- [ ] CHK017 Is the behavior defined if LocalStorage is disabled or inaccessible? [Edge Case, Gap]
|
||||
- [ ] CHK018 Are requirements defined for responsive behavior on mobile devices? [Edge Case, Spec §Edge Cases]
|
||||
|
||||
## Non-Functional Requirements
|
||||
- [ ] CHK019 Are there specific performance targets for language switching (e.g., "instant", "no layout shift")? [NFR, Research §Technical Context]
|
||||
- [ ] CHK020 Are accessibility requirements (ARIA labels, keyboard nav) defined for the new components? [NFR, Gap]
|
||||
50
specs/013-unify-frontend-css/contracts/ui-components.md
Normal file
50
specs/013-unify-frontend-css/contracts/ui-components.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# UI Component Contracts
|
||||
|
||||
This document defines the strict API contracts for the standardized UI components.
|
||||
|
||||
## Button Component
|
||||
|
||||
### Description
|
||||
A standard interactive button element that triggers an action.
|
||||
|
||||
### Props
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `variant` | `'primary' \| 'secondary' \| 'danger' \| 'ghost'` | `'primary'` | Visual style of the button. |
|
||||
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button. |
|
||||
| `isLoading` | `boolean` | `false` | If true, shows a spinner and disables interaction. |
|
||||
| `disabled` | `boolean` | `false` | If true, prevents interaction. |
|
||||
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML button type. |
|
||||
| `onclick` | `(event: MouseEvent) => void` | `undefined` | Click handler. |
|
||||
| `class` | `string` | `''` | Additional CSS classes (use sparingly). |
|
||||
|
||||
### Slots
|
||||
- `default`: The content of the button (text or icon).
|
||||
|
||||
## Input Component
|
||||
|
||||
### Description
|
||||
A standard text input field with support for labels and error messages.
|
||||
|
||||
### Props
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `label` | `string` | `undefined` | Text label displayed above the input. |
|
||||
| `value` | `string` | `''` | The current value (bindable). |
|
||||
| `placeholder` | `string` | `''` | Placeholder text. |
|
||||
| `error` | `string` | `undefined` | Error message displayed below the input. |
|
||||
| `disabled` | `boolean` | `false` | If true, prevents interaction. |
|
||||
| `type` | `'text' \| 'password' \| 'email' \| 'number'` | `'text'` | HTML input type. |
|
||||
|
||||
## Select Component
|
||||
|
||||
### Description
|
||||
A standard dropdown selection component.
|
||||
|
||||
### Props
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| `label` | `string` | `undefined` | Text label displayed above the select. |
|
||||
| `value` | `string \| number` | `''` | The selected value (bindable). |
|
||||
| `options` | `{ value: string \| number, label: string }[]` | `[]` | List of options to display. |
|
||||
| `disabled` | `boolean` | `false` | If true, prevents interaction. |
|
||||
59
specs/013-unify-frontend-css/data-model.md
Normal file
59
specs/013-unify-frontend-css/data-model.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Data Model: Frontend State & Components
|
||||
|
||||
## 1. i18n State (Client-Side)
|
||||
|
||||
The application state for internationalization is transient (in-memory) but initialized from and persisted to `localStorage`.
|
||||
|
||||
### Entities
|
||||
|
||||
#### `Locale`
|
||||
- **Type**: String Enum
|
||||
- **Values**: `"ru"`, `"en"`
|
||||
- **Default**: `"ru"`
|
||||
- **Persistence**: `localStorage.getItem("locale")`
|
||||
|
||||
#### `TranslationDictionary`
|
||||
- **Type**: JSON Object
|
||||
- **Structure**: Nested key-value pairs where values are strings.
|
||||
- **Example**:
|
||||
```json
|
||||
{
|
||||
"common": {
|
||||
"save": "Сохранить",
|
||||
"cancel": "Отмена"
|
||||
},
|
||||
"dashboard": {
|
||||
"title": "Панель управления"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Component Props (Contracts)
|
||||
|
||||
These define the "API" for the standardized UI components.
|
||||
|
||||
### `Button`
|
||||
- **variant**: `"primary" | "secondary" | "danger" | "ghost"` (default: "primary")
|
||||
- **size**: `"sm" | "md" | "lg"` (default: "md")
|
||||
- **isLoading**: `boolean` (default: false)
|
||||
- **disabled**: `boolean` (default: false)
|
||||
- **type**: `"button" | "submit" | "reset"` (default: "button")
|
||||
- **onClick**: `() => void` (optional)
|
||||
|
||||
### `Input`
|
||||
- **label**: `string` (optional)
|
||||
- **value**: `string` (two-way binding)
|
||||
- **placeholder**: `string` (optional)
|
||||
- **error**: `string` (optional)
|
||||
- **disabled**: `boolean` (default: false)
|
||||
- **type**: `"text" | "password" | "email" | "number"` (default: "text")
|
||||
|
||||
### `Card`
|
||||
- **title**: `string` (optional)
|
||||
- **padding**: `"none" | "sm" | "md" | "lg"` (default: "md")
|
||||
|
||||
### `Select`
|
||||
- **options**: `Array<{ value: string | number, label: string }>`
|
||||
- **value**: `string | number` (two-way binding)
|
||||
- **label**: `string` (optional)
|
||||
- **disabled**: `boolean` (default: false)
|
||||
70
specs/013-unify-frontend-css/plan.md
Normal file
70
specs/013-unify-frontend-css/plan.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# Implementation Plan: [FEATURE]
|
||||
|
||||
**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
|
||||
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
|
||||
|
||||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
||||
|
||||
## Summary
|
||||
|
||||
Unify frontend styling using a centralized Tailwind CSS configuration and a set of standardized Svelte wrapper components. Implement internationalization (i18n) with support for Russian (default) and English, persisting language preference in LocalStorage.
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: Node.js 18+ (Frontend Build), Svelte 5.x
|
||||
**Primary Dependencies**: SvelteKit, Tailwind CSS, `date-fns` (existing)
|
||||
**Storage**: LocalStorage (for language preference)
|
||||
**Testing**: Manual verification per User Scenarios (Visual Regression)
|
||||
**Target Platform**: Web Browser (Responsive)
|
||||
**Project Type**: Web application (Frontend)
|
||||
**Performance Goals**: Instant language switching, zero layout shift
|
||||
**Constraints**: Must support existing pages without breaking layout
|
||||
**Scale/Scope**: ~10-15 core UI components, global CSS update
|
||||
|
||||
## Constitution Check
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
|
||||
- **Semantic Protocol Compliance**: PASS. New Svelte components must follow the Component Header standard.
|
||||
- **Causal Validity**: PASS. Design System (Tokens) and Component Contracts will be defined before implementation.
|
||||
- **Immutability of Architecture**: PASS. No changes to backend architecture; strictly frontend presentation layer.
|
||||
- **Design by Contract**: PASS. Components will define strict props/interfaces.
|
||||
- **Everything is a Plugin**: N/A. UI components are not backend plugins, but will be modular.
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```text
|
||||
specs/[###-feature]/
|
||||
├── plan.md # This file (/speckit.plan command output)
|
||||
├── research.md # Phase 0 output (/speckit.plan command)
|
||||
├── data-model.md # Phase 1 output (/speckit.plan command)
|
||||
├── quickstart.md # Phase 1 output (/speckit.plan command)
|
||||
├── contracts/ # Phase 1 output (/speckit.plan command)
|
||||
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```text
|
||||
frontend/
|
||||
├── src/
|
||||
│ ├── lib/
|
||||
│ │ ├── i18n/ # [NEW] Translation dictionaries and stores
|
||||
│ │ └── ui/ # [NEW] Standardized Svelte components
|
||||
│ ├── components/ # [EXISTING] To be refactored to use lib/ui
|
||||
│ ├── routes/ # [EXISTING] Pages
|
||||
│ └── app.css # [EXISTING] Global styles (Tailwind directives)
|
||||
```
|
||||
|
||||
**Structure Decision**: Adopting a standard SvelteKit structure where reusable UI components and logic (i18n) reside in `src/lib`, accessible via `$lib` alias. Existing `components` directory will be gradually refactored or moved to `lib/ui` if generic enough.
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
> **Fill ONLY if Constitution Check has violations that must be justified**
|
||||
|
||||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
||||
|-----------|------------|-------------------------------------|
|
||||
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
|
||||
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
|
||||
63
specs/013-unify-frontend-css/quickstart.md
Normal file
63
specs/013-unify-frontend-css/quickstart.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# Quickstart: Frontend Development
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 18+
|
||||
- npm
|
||||
|
||||
## Setup
|
||||
|
||||
1. Navigate to the frontend directory:
|
||||
```bash
|
||||
cd frontend
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
## Running the Development Server
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The application will be available at `http://localhost:5173`.
|
||||
|
||||
## Using Standard UI Components
|
||||
|
||||
Import components from `$lib/ui`:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import { Button, Input } from '$lib/ui';
|
||||
</script>
|
||||
|
||||
<Input label="Username" bind:value={username} />
|
||||
<Button variant="primary" onclick={submit}>Submit</Button>
|
||||
```
|
||||
|
||||
## Using Internationalization
|
||||
|
||||
Import the `t` store from `$lib/i18n`:
|
||||
|
||||
```svelte
|
||||
<script>
|
||||
import { t } from '$lib/i18n';
|
||||
</script>
|
||||
|
||||
<h1>{$t.dashboard.title}</h1>
|
||||
<button>{$t.common.save}</button>
|
||||
```
|
||||
|
||||
## Adding New Translations
|
||||
|
||||
1. Open `frontend/src/lib/i18n/locales/ru.json` and add the new key-value pair.
|
||||
2. Open `frontend/src/lib/i18n/locales/en.json` and add the corresponding English translation.
|
||||
|
||||
## Adding New Components
|
||||
|
||||
1. Create a new `.svelte` file in `frontend/src/lib/ui/`.
|
||||
2. Define props and styles using Tailwind CSS.
|
||||
3. Export the component in `frontend/src/lib/ui/index.ts`.
|
||||
51
specs/013-unify-frontend-css/research.md
Normal file
51
specs/013-unify-frontend-css/research.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Research: Unify Frontend CSS & Localization
|
||||
|
||||
## 1. Design System & Theming
|
||||
|
||||
**Decision**: Use Tailwind CSS as the engine for the design system, but encapsulate usage within reusable Svelte components (`src/lib/ui/*`).
|
||||
|
||||
**Rationale**:
|
||||
- **Consistency**: Centralizing styles in components ensures that a "Button" always looks like a "Button" without copy-pasting utility classes.
|
||||
- **Maintainability**: Tailwind configuration (`tailwind.config.js`) will hold the "Design Tokens" (colors, spacing), while components hold the "Structure".
|
||||
- **Speed**: Tailwind is already integrated and allows for rapid development.
|
||||
|
||||
**Alternatives Considered**:
|
||||
- *Pure CSS/SCSS Modules*: Rejected because it requires more boilerplate and context switching between files.
|
||||
- *Component Library (e.g., Skeleton, Flowbite)*: Rejected to maintain full control over the visual identity and avoid bloat, but we will use the "Headless UI" concept where we build our own accessible components.
|
||||
|
||||
## 2. Internationalization (i18n)
|
||||
|
||||
**Decision**: Implement a lightweight, store-based i18n solution using Svelte stores and JSON dictionaries.
|
||||
|
||||
**Rationale**:
|
||||
- **Simplicity**: For just two languages (RU, EN) and a moderate number of strings, a full-blown library like `svelte-i18n` or `i18next` adds unnecessary complexity and bundle size.
|
||||
- **Control**: A custom store allows us to easily handle `localStorage` persistence and reactive updates across the app without fighting library-specific lifecycle issues.
|
||||
- **Performance**: Direct object lookups are extremely fast.
|
||||
|
||||
**Implementation Detail**:
|
||||
- `src/lib/i18n/index.ts`: Exports a derived store `t` that reacts to the current `locale` store.
|
||||
- `src/lib/i18n/locales/ru.json`: Default dictionary.
|
||||
- `src/lib/i18n/locales/en.json`: English dictionary.
|
||||
|
||||
**Alternatives Considered**:
|
||||
- *svelte-i18n*: Good library, but overkill for current requirements.
|
||||
- *Server-side i18n*: Rejected because the requirement specifies client-side persistence (LocalStorage) and immediate switching without page reloads.
|
||||
|
||||
## 3. Component Architecture
|
||||
|
||||
**Decision**: Create "Atomic" components in `src/lib/ui` that expose props for variants (e.g., `variant="primary" | "secondary"`).
|
||||
|
||||
**Proposed Components**:
|
||||
- `Button.svelte`: Handles variants, sizes, loading states.
|
||||
- `Card.svelte`: Standard container with padding/shadow.
|
||||
- `Input.svelte`: Standardized text input with label and error state.
|
||||
- `Select.svelte`: Standardized dropdown.
|
||||
- `PageHeader.svelte`: Unified title and actions area for pages.
|
||||
|
||||
**Rationale**: These cover 80% of the UI inconsistency issues identified in the spec.
|
||||
|
||||
## 4. Migration Strategy
|
||||
|
||||
**Decision**: "Strangler Fig" pattern - create new components first, then incrementally replace usage in `src/routes` and existing `src/components`.
|
||||
|
||||
**Rationale**: Allows the application to remain functional at all times. We can migrate one page or one section at a time.
|
||||
102
specs/013-unify-frontend-css/spec.md
Normal file
102
specs/013-unify-frontend-css/spec.md
Normal file
@@ -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.
|
||||
69
specs/013-unify-frontend-css/tasks.md
Normal file
69
specs/013-unify-frontend-css/tasks.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# Implementation Tasks: Unify Frontend CSS & Localization
|
||||
|
||||
**Branch**: `013-unify-frontend-css`
|
||||
|
||||
## Phase 1: Setup & Infrastructure
|
||||
|
||||
**Goal**: Initialize the i18n system and component structure.
|
||||
|
||||
- [ ] T001 Initialize i18n locales directory and JSON files in `frontend/src/lib/i18n/locales/ru.json` and `frontend/src/lib/i18n/locales/en.json`
|
||||
- [ ] T002 Implement i18n store with LocalStorage persistence in `frontend/src/lib/i18n/index.ts`
|
||||
- [ ] T003 Create UI component directory structure in `frontend/src/lib/ui/` and `frontend/src/lib/ui/index.ts`
|
||||
- [ ] T004 [P] Configure Tailwind utility classes for design tokens (if strictly needed beyond defaults) in `frontend/tailwind.config.js`
|
||||
|
||||
## Phase 2: Foundational Components (User Stories 1 & 2)
|
||||
|
||||
**Goal**: Create the core standardized components required for visual consistency.
|
||||
**User Story**: US1 (Consistent Visual Experience) & US2 (Efficient Design Updates)
|
||||
|
||||
- [ ] T005 [P] [US1] Create `Button` component with variants in `frontend/src/lib/ui/Button.svelte`
|
||||
- [ ] T006 [P] [US1] Create `Input` component with label/error support in `frontend/src/lib/ui/Input.svelte`
|
||||
- [ ] T007 [P] [US1] Create `Select` component in `frontend/src/lib/ui/Select.svelte`
|
||||
- [ ] T008 [P] [US1] Create `Card` container component in `frontend/src/lib/ui/Card.svelte`
|
||||
- [ ] T009 [P] [US1] Create `PageHeader` component in `frontend/src/lib/ui/PageHeader.svelte`
|
||||
- [ ] T010 [US1] Export all components from `frontend/src/lib/ui/index.ts`
|
||||
|
||||
## Phase 3: Internationalization Support (User Story 3)
|
||||
|
||||
**Goal**: Enable language switching and translation.
|
||||
**User Story**: US3 (Multi-language Support)
|
||||
|
||||
- [ ] T011 [US3] Create `LanguageSwitcher` component in `frontend/src/lib/ui/LanguageSwitcher.svelte`
|
||||
- [ ] T012 [US3] Integrate `LanguageSwitcher` into the main layout `frontend/src/routes/+layout.svelte`
|
||||
- [ ] T013 [US3] Populate `ru.json` and `en.json` with initial common terms (Save, Cancel, Dashboard, Settings)
|
||||
|
||||
## Phase 4: Migration - Dashboard & Settings (User Story 1)
|
||||
|
||||
**Goal**: Apply new components to key pages to prove consistency.
|
||||
**User Story**: US1 (Consistent Visual Experience)
|
||||
|
||||
- [ ] T014 [US1] Refactor `frontend/src/routes/+page.svelte` (Dashboard) to use `PageHeader` and `Card`
|
||||
- [ ] T015 [US1] Refactor `frontend/src/routes/settings/+page.svelte` (Settings) to use `Button`, `Input`, and `Select`
|
||||
- [ ] T016 [US1] Refactor `frontend/src/routes/tools/*` pages to use standardized components
|
||||
- [ ] T017 [US1] Replace hardcoded text in Dashboard, Settings, and Tools with `$t` store keys
|
||||
|
||||
## Phase 5: Polish & Cross-Cutting Concerns
|
||||
|
||||
**Goal**: Final cleanup and verification.
|
||||
|
||||
- [ ] T018 Verify all hardcoded colors are removed from refactored pages
|
||||
- [ ] T019 Ensure LocalStorage persistence works for language selection
|
||||
- [ ] T020 Check responsiveness of new components on mobile view
|
||||
|
||||
## Dependencies
|
||||
|
||||
1. **Phase 1** (Infrastructure) MUST be completed first.
|
||||
2. **Phase 2** (Components) depends on Phase 1.
|
||||
3. **Phase 3** (i18n UI) depends on Phase 1 (Store) and Phase 2 (Select/Button components).
|
||||
4. **Phase 4** (Migration) depends on Phase 2 and Phase 3.
|
||||
|
||||
## Parallel Execution Examples
|
||||
|
||||
- **Components**: T005 (Button), T006 (Input), T007 (Select), and T008 (Card) can be built simultaneously by different developers.
|
||||
- **Migration**: T014 (Dashboard) and T015 (Settings) can be refactored in parallel once components are ready.
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
1. **MVP**: Build the i18n store and the `Button` component. Refactor one small page to prove the concept.
|
||||
2. **Expansion**: Build remaining components (`Input`, `Select`).
|
||||
3. **Rollout**: Systematically refactor pages one by one.
|
||||
Reference in New Issue
Block a user