feat(design-system): layout & typography primitives [Phase 1b]

[barach6662001-bit]

Phase 1b — Layout & Typography Primitives

Шість токенізованих примітивів, що замінять випадкові div-и та inline-типографіку у застосунку.

Layout	Typography
Box	Heading
Stack	Text
Cluster
Container

Чому

Phase 1a дав нам TS source-of-truth для токенів + згенерований tokens.css. Але без примітивів кожен новий екран знов плодив <div style={{ display: 'flex', gap: 16 }}> і <h2 style={{ fontSize: 24 }}>. Цей PR закриває нижній шар: вся візуальна семантика — тільки через ці компоненти, всі значення — тільки через CSS-змінні з токенів.

Дизайн API (короткий зріз)

import { Stack, Cluster, Container, Heading, Text, Box } from '@/design-system';

<Container size="lg">
  <Stack gap="6">
    <Heading level={1}>Дашборд</Heading>
    <Text size="md" tone="secondary">Огляд за сезон 2026</Text>

    <Cluster gap="3" justify="between">
      <Heading level={3} as="h2">KPI</Heading>
      <Cluster gap="2"><Button/><Button/></Cluster>
    </Cluster>

    <Box p="4" /* …дочірні компоненти */ />
  </Stack>
</Container>

Архітектурні рішення

• Polymorphic as на кожному примітиві + forwardRef.
• CSS Modules + data-attribute селектори для варіантів — нуль конкатенації className, нуль string-юніонів, що протікають у CSS.
• Inline CSS-змінні для токенозалежних значень: style={{ '--ds-stack-gap': 'var(--space-4)' }}. Це SSR-safe, легко переоприділяється, дешево.
• Семантика за замовчуванням: Heading level={N} рендерить <hN>, Text → <p>, Container → <div> з адаптивним side-padding (16/24/32 px на 0/600/1024+).
• Fluid типографіка успадковується з токенів (clamp()), тож масштабується між брейкпоінтами без додаткової логіки.
• Zero-deps — лише React. Жоден існуючий компонент не змінено.

Що доступно публічно

import { Box, Stack, Cluster, Container, Heading, Text, space, cx } from '@/design-system';

Перевірки

• ✅ eslint — 0 errors (warnings успадковані з main)
• ✅ tsc -b — clean
• ✅ vitest — 134 / 134 passed (із них 36 нових)
• ✅ vite build — OK

Що далі (Phase 1c)

Перевести AppHeader, Sidebar та одну еталонну сторінку (Dashboard) на ці примітиви. Жодного нового токена — лише міграція візуальних значень.

Це additive-PR: жодного існуючого файлу не змінено, безпечно мерджити одразу.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 76e71d5026

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Map danger/accent tones to existing token variables

The new tone mappings use var(--danger) and var(--accent), but those CSS variables are not defined in the design-token output (only tokens like --error and --accent-* exist). When Text is rendered with tone="danger" or tone="accent", --ds-text-color resolves to an undefined variable and the color declaration becomes invalid at compute time, so text falls back/inherits instead of applying the requested semantic tone.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Allow label attributes when Text renders as label

Text explicitly supports as="label", but its props extend HTMLAttributes<HTMLElement>, which excludes label-specific fields such as htmlFor. In strict TypeScript usage, <Text as="label" htmlFor="field" /> fails type-checking (TS2322), which blocks accessible label wiring even though the component API advertises label rendering.

Useful? React with 👍 / 👎.