busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
c9a53578fd753abeedf17e0884579dfa44c20faf
ss-tools/specs/013-unify-frontend-css/spec.md
busya c9a53578fd tasks ready
2026-01-23 14:56:05 +03:00

7.2 KiB
Raw Blame History

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.