artefact-design-system 0.1.0

package/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md — using `artefact-design-system`
+
+Ты работаешь в проекте, который установил `artefact-design-system` как зависимость (`npm install artefact-design-system`). Этот файл — про то, как этой системой пользоваться в ЭТОМ проекте.
+
+## Два файла правды — при любой задаче на UI сначала сюда
+
+Оба лежат прямо в этом пакете, в `node_modules/artefact-design-system/context/`:
+
+| Вопрос | Файл |
+|---|---|
+| Какой компонент уже есть, что он принимает, брать его или писать свой | `context/COMPONENTS.md` |
+| Какое значение (цвет/отступ/радиус/шрифт) использовать, какие есть правила («не больше одной accent-кнопки на экран» и т.п.) | `context/DESIGN.md` |
+
+Порядок: **`COMPONENTS.md`** (есть ли уже готовое) → **`DESIGN.md`** (каким токеном это красить) → код. Не изобретай инлайновый цвет/отступ, если для него есть токен — `DESIGN.md` перечисляет их все.
+
+Эти два файла обновляются вместе с версией пакета — после `npm update` они у тебя тоже актуальные, не нужно искать их где-то отдельно от кода. В самом пакете (не у тебя в проекте, а при разработке `artefact-design-system`) оба проверяются автоматически перед каждым релизом — линтером формата и скриптом, сверяющим их с реальным кодом токенов/компонентов. Из-за этого в `DESIGN.md`'s frontmatter могут встретиться на первый взгляд странные, но осознанные вещи — не чини их сам:
+- Контраст `button-accent` (белый текст на оранжевом) ниже общего порога 4.5:1 — это ок, порог для крупного/полужирного текста кнопок ниже (3:1), а не баг.
+- Многие цвета в `colors` не привязаны к конкретному пункту в `components` того же файла — это не значит, что они не используются в реальных компонентах (используются, просто `components`-блок — небольшая репрезентативная выборка, не полное отображение кода).
+
+## Подключение
+
+```tsx
+import { Button, Surface, Box, Flex } from "artefact-design-system"
+import "artefact-design-system/style.css" // один раз, в корне приложения
+```
+
+Стили — уже скомпилированный CSS (Tailwind собран при публикации пакета), настраивать Tailwind у себя не нужно. `react`/`react-dom` — peer-зависимости, должны уже быть в проекте (см. `package.json` пакета за точными версиями).
+
+## Как устроена система — что можно строить сверху
+
+Компоненты идут четырьмя тирами, снизу вверх: **Foundation** (`Box`/`Flex`/`Grid`/`Stack`/`Surface` — чистое поведение и токены, без идентичности) → **Primitives** (`Icon`/`Text`/`Button`/`Input` и т.п. — атомарные контролы) → **Components** (`Toolbar`/`AdviceCard`/чарты — сборки из примитивов) → **Sections** (`SidebarNav`/`AssistantDock` — готовые bespoke-блоки). Если строишь что-то новое в своём проекте — собирай это ИЗ них (`Box`+токен, не сырой `<div style={{padding: 16}}>`), тогда оно визуально не расходится с остальной системой без дополнительных усилий.
+
+`Sections` — намеренно короткий список (сейчас всего два компонента). Пакет обслуживает несколько продуктов сразу, поэтому туда попадает только то, что реально повторяется в нескольких из них, а не любой удобный блок с одной страницы — если тебе нужен похожий bespoke-блок именно в твоём проекте, собери его у себя из Foundation/Primitives/Components, а не жди, что он появится в пакете.
+
+Список вариантов/токенов (например, вариантов `Surface`, семантических цветовых ролей) — всегда смотри в реестре, который экспортирует сам пакет (`SURFACE_VARIANTS`, `semanticRoles`, `chartKeys`, `ICON_NAMES` и т.п.), а не угадывай по `COMPONENTS.md`/`DESIGN.md` — реестр гарантированно совпадает с тем, что реально работает в этой версии пакета.
+
+## CSS-специфичность — если переопределяешь стили компонента
+
+Инлайн `style` на React-элементе побеждает внешний CSS-класс всегда, независимо от специфичности CSS-селектора. Если пытаешься переопределить внешний вид компонента из пакета через свой CSS-класс, а компонент внутри уже задаёт то же CSS-свойство инлайново — твой класс не сработает молча, без ошибки. Проверяй computed-стиль в браузере, если переопределение не подействовало, а не считай это багом пакета.
+
+## Ограничения
+
+- **Не редактируй файлы внутри `node_modules/artefact-design-system`.** Если чего-то не хватает или что-то ведёт себя не так — это повод завести задачу на обновление самого пакета, а не патчить установленную копию (правки потеряются при следующем `npm install`).
+- **Не изобретай второй способ задать цвет/отступ.** Если нужного токена нет в `DESIGN.md` — это либо повод расширить пакет (отдельная задача, не эта), либо использовать нейтральное значение проекта вне этой системы — но не выдумывать хардкод, который выглядит как токен, но им не является.
+- **Не собирай компонент, который уже есть в `COMPONENTS.md`, заново.** Если существующий не подходит по API — сначала посмотри, можно ли обернуть его, а не дублировать логику с нуля.
+- **Обязательные пропсы без дефолта — это осознанно, не недосмотр.** Например, `SidebarNav`'s `items` ничего не подставляет сам за тебя — пакет обслуживает несколько продуктов, у него нет «одного правильного» набора пунктов навигации по умолчанию.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gpogrebnyak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# artefact-design-system
+
+Дизайн-система «Артефакт»: Foundation/Primitives/Components/Sections на базе shadcn/ui + Radix, публикуемая как обычный npm-пакет.
+
+## Установка
+
+```bash
+npm install artefact-design-system
+```
+
+```tsx
+import { Button, Surface, SidebarNav } from "artefact-design-system"
+import "artefact-design-system/style.css" // один раз, в корне приложения
+```
+
+Стили — один скомпилированный файл (`dist/style.css`), собранный при публикации пакета через Tailwind CLI. Устанавливать/настраивать Tailwind у себя не нужно — все нужные классы уже внутри.
+
+## Разработка
+
+```bash
+npm install
+npm run storybook   # витрина — читает src/ напрямую, живой reload
+npm run build        # lint:design → check:context → typecheck → dist/*.js+*.d.ts → dist/style.css
+```
+
+## Документация
+
+- Для агента, который ИСПОЛЬЗУЕТ этот пакет в другом проекте — [`/AGENTS.md`](./AGENTS.md).
+- Токены/правила и каталог компонентов — [`context/DESIGN.md`](./context/DESIGN.md), [`context/COMPONENTS.md`](./context/COMPONENTS.md) (оба публикуются вместе с пакетом).
+- Устройство самого формата `DESIGN.md` — [`context/README.md`](./context/README.md).

package/context/COMPONENTS.md

@@ -0,0 +1,90 @@
+# COMPONENTS.md — каталог
+
+Что здесь, а что в `DESIGN.md`: `DESIGN.md` — токены и правила визуального языка (Foundation-уровень). Этот файл — конкретные React-компоненты: что это, какой API, когда брать, когда — нет. Значения (цвета/отступы/радиусы) не повторяются здесь — они указаны по имени токена, расшифровка — в `DESIGN.md`.
+
+Источник правды — код (`src/foundation`, `src/primitives`, `src/components`, `src/sections`). Этот файл описывает его состояние на момент написания; если он расходится с кодом — прав код, этот файл нужно поправить.
+
+**Обозначения тира:**
+- 🟢 **своё** — написано в этом проекте, полный контроль над API.
+- 🔵 **shadcn/vendored** — стандартный shadcn-компонент (`components/ui/*`),
+  используется как есть + иногда токен-оверрайд. Полный список пропсов — в
+  документации shadcn (не переписываем её здесь, она устареет быстрее кода).
+- ⚠️ **демо, не компонент** — существует только как демонстрационный код,
+  ничего не экспортируется для импорта. Если нужно использовать —
+  сначала превратить в реальный компонент.
+
+---
+
+## Foundation
+
+Чистое поведение, без цвета/идентичности. Всё выше строится на этом.
+
+| Компонент | Тир | Что делает | Когда брать |
+|---|---|---|---|
+| `Box` | 🟢 | Базовый контейнер: `p/px/py`, `radius`, `width/maxWidth/minWidth`, `grow`. Всё остальное (включая `onClick`, `aria-*`) прокидывается на элемент напрямую. | Всегда, когда нужен `<div>` с паддингом/радиусом из шкалы — никогда не пиши `style={{padding: 16}}` вручную. |
+| `Flex` | 🟢 | `Box` + `display:flex`, `direction`, `gap`, `align`, `justify`, `wrap` (по умолчанию `true` — оборачивается сам). | Ряд элементов, которым можно перенестись на новую строку. |
+| `Stack` | 🟢 | `Flex` с `direction="column"` по умолчанию. | Вертикальная колонка — самый частый кейс, есть отдельным именем, чтобы не писать `direction="column"` каждый раз. |
+| `Grid` | 🟢 | `Box` + `display:grid`, `auto-fit`/`minmax` реflow по `minColWidth` (default 280) ИЛИ фиксированное число `columns`. | Сетка карточек, которая сама решает, сколько колонок влезает — не считай breakpoints руками. |
+| `Container` | 🟢 | `Box` + `max-width` (default 1280) + `margin-inline:auto`. | Центрированная колонка контента заданной ширины. |
+| `Surface` | 🟢 | `Box` + один из 5 background-вариантов (`glass/paper/muted/plain/scrim`, реестр `SURFACE_VARIANTS` в `surface.tsx`). | Любая поверхность с фоном из системных токенов. См. `DESIGN.md` → Elevation про разницу `glass` и `scrim`. |
+| `TitledRow` | 🟢 | Секция title-rail + main + опциональный side-rail (`rail`/`gap` в px). Настоящий CSS (`row.css`), не инлайн-стили — брейкпоинт ~1120px требует media query. | Заголовок раздела страницы с (опционально) правой колонкой-советом. Не давай `side`, если контента для side нет — есть модификатор `--no-side`. |
+| `AppShell` | 🟢 | `{sidebar, children}` → флекс сайдбар + колонка `max-width:1280, padding:26px 24px 90px`. Инвариант для всех страниц продукта, не одноразовое решение. | Корень любой реальной страницы. Не пересобирай эти значения руками на уровне страницы — это ровно тот баг, который уже был (сайдбар прилипал не туда). |
+
+## Primitives
+
+### Свои (полный контроль)
+
+| Компонент | Что делает | Когда брать / не брать |
+|---|---|---|
+| `Icon` | `<Icon name="..." size weight color label />`. Имя — ключ из governed-реестра `REGISTRY` (Phosphor-глифы; полный список в `ICON_NAMES`). | Всегда через `name`, никогда не импортируй Phosphor-глиф напрямую в компонент выше — тогда список иконок остаётся одним управляемым словарём. Если нужной иконки нет в `REGISTRY` — добавь её туда, не инлайни SVG на месте использования. |
+| `Image` | `<Image src alt width height fit radius loading />`. Настоящий пробел ни у Radix, ни у shadcn (Avatar покрывает только круглый fallback-кейс, не фото/иллюстрацию). | Любое `<img>` в продукте. `alt` обязателен — decorative-картинка получает `alt=""` явно, а не отсутствие атрибута. |
+| `Text` | `<Text as size color weight align truncate />`. `size` — шаг шкалы типографики (`footnote…display`), резолвится в px+lineHeight из `tokens.ts`. | Любая строка текста в компоненте выше должна идти через `Text`, не через сырой `<span className="text-sm">` — единственное место, которое знает, что означает `caption` в px. `weight` не запечён в шаг шкалы — ставь явно (600 — единственное другое реально самохостящееся начертание, см. `DESIGN.md`). |
+
+### shadcn/vendored (стандартный API — см. shadcn-документацию)
+
+`Avatar`, `Badge`, `Button`, `Checkbox`, `Input`, `RadioGroup`, `Select`, `Switch`, `Toggle`/`ToggleGroup`, `Tooltip`, `NavigationMenu`, `Progress`, `Separator`, `Dialog`.
+
+Используются как есть, без правки исходников. Наши оверрайды — на уровне темы/атрибутов, не пропсов:
+- `[data-slot="button"]`/`[data-slot="input"]`/`[data-slot="select-trigger"]` — высота/радиус пересчитаны в `brand-overrides.css` (см. `DESIGN.md` → Components).
+- Если конкретному месту нужно другое поведение (например, `Select`, который умеет очищаться крестиком) — это уже не «просто shadcn Select», это новый Components-тир композит (см. `FilterSelect` ниже), а не проп на самом `Select`.
+
+**⚠️ `Sparkline`/`ScoreRing` — не компоненты.** Демонстрационный код в `src/stories/Chart.stories.tsx` показывает, что Recharts+`ChartContainer` покрывает то, что раньше было кастомным SVG (mini-график, круговой индикатор прогресса). Ничего не экспортируется — если понадобится настоящий спарклайн-компонент, его нужно сначала выделить в реальный файл.
+
+## Components
+
+Primitives + Foundation, собранные в конкретную повторяемую сущность.
+
+### Свои композиты
+
+| Компонент | Props | Когда брать |
+|---|---|---|
+| `AdviceCard` | `icon, tone("ink"\|"accent"), value, text, note?` | Карточка-совет в side-rail (`TitledRow`'s `side`) — иконка + крупное значение + текст. `tone="accent"` — редкость, для настоящего хайлайта (новый рекорд и т.п.), не дефолт. Не путать с `Alert` (тот — плоское уведомление, без слота под значение) и `EmptyState` (тот — про отсутствие иконки-как-идентичности). |
+| `FilterSelect` | `label, placeholder, value?, onValueChange?, onClear?, options[]` | Пилюля-селект, которая обзаводится крестиком-очисткой при выбранном значении. Обычный `Select` не умеет очищаться — не пытайся добавить это пропом на `Select`, это отдельный композит. |
+| `Toolbar` + `ToolbarGroup` + `ToolbarToggleGroup` + `ToolbarToggleItem` + `ToolbarSeparator` + `ToolbarButton` | `Toolbar({orientation, bare})`; `ToolbarToggleGroup({value, onValueChange})` | Построено на `radix-ui`'s `Toolbar` напрямую (у shadcn нет тулбар-рецепта) — roving-focus между кнопками/тоглами. **`bare=true` обязателен**, если внутри ровно одна уже самоокрашенная группа (`ToolbarToggleGroup` рисует свою pill-плашку) — иначе получится пилюля-в-пилюле (реальный баг, который уже чинили). |
+| `Chip` | Все пропсы `<button>` (`ButtonHTMLAttributes`) | Кликабельная пилюля на `glass`-поверхности — сработала только после того, как `Box` начал прокидывать `onClick` (см. Foundation). Не для статичных тегов без реакции — см. правило «выглядит кликабельным → обязано реагировать» из `DESIGN.md`. |
+| `MessageBubble` | `from("user"\|"bot")`, children | Пузырь чата с «зарезанным» уголком (5px) в сторону отправителя. `user` = тёмная заливка, `bot` = paper. |
+| `TypingIndicator` | без пропсов | Три пульсирующих точки — статус «ассистент думает» перед ответом. |
+| `FormField` (Field.tsx) | `label, htmlFor?, description?, error?, children` | Обёртка shadcn-примитивов `Field/FieldLabel/FieldDescription/FieldError` вокруг любого контрола (Input/Select/Checkbox). Используй это, а не собирай label+control+error руками на месте — тогда ошибка/описание всегда в одном месте разметки. |
+| `Search` | `placeholder?, value?, onChange?, className?` | `InputGroup` (shadcn) + `Icon` как leading addon. Всегда для полей поиска — не собирай Input + абсолютно-позиционированную иконку вручную. |
+| `BarChart` / `LineChart` / `AreaChart` | `data, xKey, series: {key,label,color}[], height?, showLegend?` (+`stacked?` у Area) | Настоящий Recharts через shadcn's `ChartContainer`. `showLegend` по умолчанию `series.length > 1`. Grid/оси — `color.input`, никогда `color.border` (тот прозрачный по правилу). |
+| `DonutChart` | `data: {key,label,value,color}[], height?, showLegend?` | Категориальная разбивка (Pie, `innerRadius:"60%"`). |
+| `DistributionChart` | `groups: {name,total,segments:{label,count,widthPct}[]}[], rowHeight?` | Горизонтальный stacked-bar на группу; если сегменты не сумма в 100% — остаток дорисовывается приглушённым `rest`. Заменил старый самописный `SegmentedBar` (визуально выглядел дешевле настоящих чартов). |
+
+### shadcn/vendored, но на уровне Components (не Primitives)
+
+`Card`, `EmptyState` (`empty.tsx`), `Tabs`, `Alert`, `Menu` (`dropdown-menu.tsx`), `Pagination`, `Table`, `Notification` (`sonner.tsx`).
+
+Это тоже стандартные shadcn-компоненты, но они — композиционные оболочки (слоты Header/Content/Footer, список пунктов и т.п.), а не атомарный контрол — поэтому классифицированы как Components, не Primitives. API — см. shadcn-документацию.
+
+**⚠️ Карточка-метрика (`Card` + `Text` + `LineChart`) — не компонент.** Демонстрационный код в `src/stories/ChartAdvanced.stories.tsx` показывает такую композицию вручную — не экспортируется, есть только как образец, скопируй руками, если нужен такой паттерн.
+
+⚠️ **Известный пробел:** `Notification` (`sonner.tsx`) использует `next-themes`, но `ThemeProvider` в приложении не смонтирован — тема тостов всегда резолвится в `"system"`. Не чинилось, низкий приоритет.
+
+## Sections
+
+Секции — намеренно немногочисленные (стоящее правило: `Sections` остаётся компактным, а не превращается во вторую копию `Components`; странично-специфичный блок без повторяющегося прецедента на нескольких реальных экранах продукта не пакуется в новую секцию раньше времени — он остаётся кодом конкретной страницы в потребляющем приложении).
+
+| Компонент | Props | Что это |
+|---|---|---|
+| `SidebarNav` | `active?, items (обязателен, NavItem[]), avatarInitials?, avatarTitle?, showSettings?, clientLabel?, clientInitial?` | Левый рейл приложения. `items` — обязательный проп, без дефолта (пакет обслуживает несколько продуктов/клиентов Артефакта — ни один конкретный набор пунктов не может быть «тем самым» дефолтом). `clientLabel` — опциональный чип «какой это клиент»; чип не рендерится вообще, если его не передать, никогда не показывает чьё-то конкретное имя по умолчанию. `EXAMPLE_NAV_ITEMS` экспортирован как пример/фикстура, не как рабочий дефолт. |
+| `AssistantDock` | `title?, intro?, chips?(ChipQuestion[]), fallbackAnswer?, placeholder?` | Плавающий AI-ассистент. Настоящий стейт-мачин (`idle → open → orb`), не статичный снэпшот — `orb` включается, если пользователь скроллит вниз и закрывает панель (`window.scrollY > 120`). `intro`/`fallbackAnswer` — placeholder-дефолты без привязки к конкретному продукту/клиенту, передавай реальный текст явно. Единственный наравне с `SidebarNav` «органический» (bespoke) компонент — блюр-панель/градиентная кнопка/спиннер-иконка — реальный CSS в `AssistantDock.css`, не выражен через Foundation-примитивы (не всё честно сводится к токенам без выдумывания). |

package/context/DESIGN.md

@@ -0,0 +1,242 @@
+---
+name: Артефакт
+version: "1.0"
+description: >
+  Дизайн-система «Артефакт» для аналитических продуктов. Тёплый, спокойный,
+  без визуального шума интерфейс поверх shadcn/Radix — токенами и одним
+  override-слоем, без правки исходников компонентов. Источник правды для
+  этого файла: src/index.css + src/foundation/tokens.ts +
+  src/brand-overrides.css.
+colors:
+  # --- страница / поверхности ---
+  background: "#f9f6f0"
+  foreground: "#2c2c2a"
+  card: "rgba(255, 255, 255, 0.6)"
+  card-foreground: "#2c2c2a"
+  popover: "#fffdf8"
+  popover-foreground: "#2c2c2a"
+  ink-3: "#a3a094"
+
+  # --- контролы ---
+  primary: "#2c2c2a"
+  primary-foreground: "#f9f6f0"
+  secondary: "#ffffff"
+  secondary-foreground: "#2c2c2a"
+  muted: "#f1ece1"
+  muted-foreground: "#6c6a63"
+  border: "transparent"
+  input: "#e4e2da"
+  ring: "#f75506"
+  destructive: "#b23a2e"  # shadcn-слот, всегда == danger, отдельного значения нет
+
+  # --- brand + semantic roles (каждая: base/foreground/hover/soft/soft-foreground) ---
+  accent: "#f75506"
+  accent-foreground: "#ffffff"
+  accent-hover: "color-mix(in srgb, #f75506 85%, black)"
+  accent-soft: "#fdeee5"
+  accent-soft-foreground: "#f75506"
+
+  green: "#1f7a54"
+  green-foreground: "#ffffff"
+  green-hover: "color-mix(in srgb, #1f7a54 85%, black)"
+  green-soft: "#eaf2ea"
+  green-soft-foreground: "#1f7a54"
+
+  warn: "#b8862f"
+  warn-foreground: "#2c2c2a"
+  warn-hover: "color-mix(in srgb, #b8862f 85%, black)"
+  warn-soft: "#f6edda"
+  warn-soft-foreground: "#b8862f"
+
+  plum: "#7a4d7d"
+  plum-foreground: "#ffffff"
+  plum-hover: "color-mix(in srgb, #7a4d7d 85%, black)"
+  plum-soft: "#f1e6f0"
+  plum-soft-foreground: "#7a4d7d"
+
+  danger: "#b23a2e"
+  danger-foreground: "#ffffff"
+  danger-hover: "color-mix(in srgb, #b23a2e 85%, black)"
+  danger-soft: "#f6e1df"
+  danger-soft-foreground: "#b23a2e"
+
+  # --- data-viz ---
+  chart-1: "#f75506"
+  chart-2: "#1f7a54"
+  chart-3: "#c9805e"
+  chart-4: "#b3a48f"
+  chart-5: "#6c6a63"
+  chart-surface: "#fbfaf7"
+
+  # --- оверлеи ---
+  scrim: "rgba(0, 0, 0, 0.1)"
+typography:
+  footnote:
+    fontFamily: "Struve, system-ui, sans-serif"
+    fontSize: 12px
+    fontWeight: "400"
+    lineHeight: 1.45
+  caption:
+    fontFamily: "Struve, system-ui, sans-serif"
+    fontSize: 14px
+    fontWeight: "400"
+    lineHeight: 1.45
+  body:
+    fontFamily: "Struve, system-ui, sans-serif"
+    fontSize: 16px
+    fontWeight: "400"
+    lineHeight: 1.55
+  subhead:
+    fontFamily: "Struve, system-ui, sans-serif"
+    fontSize: 18px
+    fontWeight: "400"
+    lineHeight: 1.35
+  title:
+    fontFamily: "Struve, system-ui, sans-serif"
+    fontSize: 20px
+    fontWeight: "400"
+    lineHeight: 1.3
+  headline:
+    fontFamily: "Struve, system-ui, sans-serif"
+    fontSize: 24px
+    fontWeight: "400"
+    lineHeight: 1.25
+  display:
+    fontFamily: "Struve, system-ui, sans-serif"
+    fontSize: 32px
+    fontWeight: "400"
+    lineHeight: 1.15
+rounded:
+  sm: 8.4px
+  md: 11.2px
+  lg: 14px
+  xl: 19.6px
+  2xl: 25.2px
+  pill: 9999px
+spacing:
+  none: 0px
+  xs: 4px
+  sm: 8px
+  md: 12px
+  base: 16px
+  lg: 20px
+  xl: 24px
+  2xl: 32px
+  3xl: 40px
+  4xl: 56px
+components:
+  surface-glass:
+    backgroundColor: "{colors.card}"
+    rounded: "{rounded.xl}"
+  surface-paper:
+    backgroundColor: "{colors.secondary}"
+    rounded: "{rounded.xl}"
+  surface-muted:
+    backgroundColor: "{colors.muted}"
+    rounded: "{rounded.xl}"
+  surface-plain:
+    backgroundColor: transparent
+    rounded: "{rounded.xl}"
+  surface-scrim:
+    backgroundColor: "{colors.scrim}"
+    rounded: "{rounded.xl}"
+  control:
+    height: 40px
+    rounded: "{rounded.lg}"
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    rounded: "{rounded.pill}"
+    height: 40px
+    padding: 0 16px
+  button-accent:
+    backgroundColor: "{colors.accent}"
+    textColor: "{colors.accent-foreground}"
+    rounded: "{rounded.pill}"
+    height: 40px
+    padding: 0 16px
+  # Единственный градиент во всей системе — сюда, а не в `colors`: та карта
+  # проверяется линтером как чистые CSS-цвета, градиент туда не проходит
+  # (`design.md lint` кидал ошибку на colors.accent-gradient). В коде это
+  # тот же токен, `color.accentGradient` в tokens.ts — здесь он просто
+  # переехал под конкретный компонент, который его использует.
+  assistant-dock-btn:
+    backgroundColor: "linear-gradient(135deg, #ffb88c 0%, #f75506 50%, #ff5e62 100%)"
+    textColor: "{colors.accent-foreground}"
+    rounded: "{rounded.pill}"
+    height: 40px
+  toolbar-toggle-active:
+    backgroundColor: "{colors.foreground}"
+    textColor: "{colors.background}"
+  assistant-dock-panel:
+    backgroundColor: "{colors.scrim}"
+    rounded: "{rounded.2xl}"
+---
+
+# Артефакт — правила дизайна
+
+Токены во frontmatter выше дают агенту точные значения. Ниже — *почему* они такие и как их применять. Меняешь систему на уровне значений — правишь frontmatter; меняешь правило — правишь прозу. Страницы правишь только после того, как поправлен этот файл, а не параллельно с ним.
+
+## Overview
+
+Тёплый, спокойный интерфейс с минимумом визуального шума: кремовая нейтральная база, тёмно-серый (не чёрный) текст, и **один** громкий акцентный цвет — оранжевый, используемый редко и целенаправленно (одна filled-CTA такого цвета на экран, не больше). Каждый токен либо реально используется где-то в системе, либо явно помечен как осознанное расширение (см. `danger`, `accent-gradient`, `scrim` ниже) — никаких «запасных» значений на будущее.
+
+Технически система лежит **на shadcn/ui + Radix**, не заменяет их: токены и один override-слой (`src/brand-overrides.css`) дают наш вид без единой правки исходников компонентов — так система остаётся синхронизируемой с апстримом shadcn, а не форкает его.
+
+## Colors
+
+- **Нейтральная база — тёплая, не серая.** `background`/`card`/`popover` — оттенки cream/paper, не белый и не серый. `card` — 60%-стекло (`rgba(255,255,255,.6)`), а не сплошной белый: острова на странице должны просвечивать фон.
+- **`primary` (дефолтная filled-кнопка) — тёмный ink, не оранжевый.** Обычное заметное действие — тёмное. Оранжевый — это отдельная, более редкая роль.
+- **`accent` — редкость: одна на экран, максимум пара.** Каждая brand/semantic-роль (`accent`, `green`, `warn`, `plum`, `danger`) несёт полный набор из пяти токенов — `base/foreground/hover/soft/soft-foreground` — никогда просто `base` + произвольный фон.
+  - `foreground` подобран по **измеренному** WCAG-контрасту, не по предположению «всегда белый» (у `warn` это тёмный ink, а не белый — белый давал хуже контраст).
+  - `hover` всегда через `color-mix()` от `base` — пересчитывается сам, никогда не второй захардкоженный hex, который может разойтись с базой.
+  - `soft`/`soft-foreground` — бледная плашка-беджик (светлый фон + текст цветом базы).
+- **`danger` (красный) — осознанное расширение палитры.** Подобран так, чтобы читаться как отдельный цвет, а не «грустный оранжевый» (другой тон и насыщенность, приземлённая к семье `accent/green/warn`, а не к выбивающейся насыщенности `accent`).
+- **Единственный градиент во всей системе** — `components.assistant-dock-btn` (кнопка AI-ассистента). Живёт в `components`, не в `colors` — градиент не проходит как CSS-цвет (см. `Do's and Don'ts`). Не заводи второй градиент без такой же осознанной причины — иначе это быстро превращается в декоративный шум.
+- **`scrim` — тёмная подложка низкой прозрачности позади тяжёлого блюра** (панель ассистента). Отличается от `card` (светлое стекло) — не путать.
+- **`border: transparent` — правило, не забытое значение.** Разделение поверхностей — прозрачностью/тенью фона, а не рамкой. Если разделитель реально нужен видимым (инпут, `<hr>`-подобный разделитель) — используй `input` (единственный «настоящий» hairline-токен), никогда не включай `border` обратно.
+- **Известный пробел: тёмная тема не оформлена.** В коде она существует (`.dark` в `index.css`), но это дефолтные нейтральные серые shadcn, не тема бренда — их пока не трогали, при работе с dark mode это нужно сделать осознанно, а не считать готовым.
+
+## Typography
+
+- **Один семейный шрифт — Struve**, self-hosted (`public/fonts/`, `src/brand-overrides.css`), подключён ПОВЕРХ дефолтного пресета Geist (Geist — то, что даёт `shadcn`/Tailwind-тема по умолчанию; Struve грузится позже и выигрывает каскад через `--font-sans`). На данный момент самохостятся только два начертания — 400 и 600 (полужирный); отдельного Medium (500) файла нет (CDN-ссылка отдавала 404) — не проси третье начертание, пока файл не появится.
+  - Начертание **не** запечено в шкалу размеров — по умолчанию 400, полужирный (600) ставится на конкретных местах через `weight` пропу примитива `Text`, а не как атрибут самого шага шкалы.
+  - Глобальная фича шрифта: `font-feature-settings: "ss10" 1` (одноэтажная «a») — включена на `body`, это правило бренда, не убирать.
+- **Шкала — 7 шагов** (`footnote/caption/body/subhead/title/headline/display`, 12–32px). `body` (16px) — «самый важный текст блока»: если решаешь показать что-то крупнее — сначала проверь, действительно ли его смысловой вес выше, чем у остального `body`-текста на этой же поверхности, а не просто «чтобы выделялось».
+- `subhead/title/headline` — реальные, используемые шаги (`Foundation/Row`, страничные шапки, `AssistantDock`), а не проектные заготовки на будущее.
+
+## Layout & Spacing
+
+- Шкала отступов (`spacing` во frontmatter) — единый согласованный шаг (0/4/8/12/16/20/24/32/40/56) — бери значение из шкалы, не изобретай промежуточный пиксель под конкретный случай.
+- Радиус (`rounded`) — все шаги производные от одного `--radius` (14px, роль `lg`): `sm`/`md` — доли базового, `xl`/`2xl` — кратные. `pill` — это настоящий pill (9999px), не отдельное число — используется на CTA-кнопках и переключателях.
+- Основная страничная сетка — сайдбар слева (см. `Foundation/AppShell`) + колонка контента `max-width: 1280px`, `padding: 26px 24px 90px` — это инвариант для ЛЮБОЙ страницы продукта, не одноразовое решение под одну конкретную страницу.
+
+## Elevation & Depth
+
+- **Тени выключены глобально**, кроме фокус-кольца. Реализовано не через `box-shadow: none` (это убило бы и ring — в Tailwind v4 drop-shadow и focus-ring компилируются в один и тот же `box-shadow` через разные CSS-переменные), а точечно: `--tw-shadow: 0 0 #0000 !important` на `[data-slot]`, оставляя `--tw-ring-shadow` живым.
+- **Фокус всегда виден**: focus-ring — `ring` (брендовый оранжевый). Не убирай ring вместе с тенями — это разные слои одного CSS-свойства.
+- **Стеклянные острова**: `card`-поверхности получают `backdrop-filter: blur(10px) saturate(1.1)` — это про физическую многослойность (полупрозрачный остров над фоном), не декоративный эффект сам по себе.
+- **`scrim` (панель ассистента)** — гораздо сильнее: `blur(40px) saturate(1.4)` на тёмной, почти прозрачной (`rgba(0,0,0,.1)`) подложке — самый глубокий уровень в системе, использовать только для оверлея, который реально перекрывает контент под собой.
+
+## Shapes
+
+- Скругления консервативные и последовательные (`sm→2xl`, одна прогрессия от одного базового числа) — не смешивай острые (`radius:0`) и pill-элементы на соседних по смыслу поверхностях.
+- **Pill-радиус — только для действий/переключателей** (кнопки, toggle-групп), не для контентных карточек — карточки используют `xl`/`2xl`.
+
+## Components
+
+Компоненты строятся на Radix-примитивах (через `shadcn`, где для задачи есть готовый рецепт, либо напрямую через пакет `radix-ui`, где рецепта нет — например, `Toolbar`) плюс токены этого файла, применяемые СНАРУЖИ через тему и `data-slot`-атрибуты, без правки исходников самих компонентов:
+
+- `[data-slot="button"]`/`[data-slot="input"]`/`[data-slot="select-trigger"]` — высота и радиус подтянуты к нашим 40px/pill и 40px/14px соответственно (shadcn ставит собственную шкалу — 32px, туже — по умолчанию, мы её переопределяем на уровне атрибута, не в разметке).
+- `[data-slot="separator"]` — единственное место, где `border` намеренно подменяется на `input`: иначе все внутренние разделители (в `DropdownMenu`, `Select`, `Field`) стали бы невидимыми из-за правила «border transparent».
+- Полный перечень готовых Primitives/Components/Sections, что каждый принимает и когда его брать/не брать — не здесь, это отдельный каталог (`context/COMPONENTS.md`), этот файл описывает только токены и правила их применения.
+
+## Do's and Don'ts
+
+- **Don't** — заводить второй захардкоженный hex-цвет там, где нужен brand или semantic оттенок. Всегда через `color.<role>` — единственное исключение — `danger`, который явно помечен как добавленный, а не извлечённый.
+- **Don't** — возвращать `box-shadow` на карточки/острова. Единственный штатный «глубокий» эффект — `backdrop-filter` на `glass`/`scrim`.
+- **Don't** — включать `border` обратно ради видимого разделителя. Нужен видимый — бери `input`.
+- **Don't** — заводить второй градиент без такой же осознанной причины, как у `assistant-dock-btn`; сейчас в системе он ровно один. И держи градиент в `components`, не в `colors` — линтер (`npm run lint:design`) не пропускает нецветовые значения в `colors`.
+- **Don't** — использовать больше одной `accent`-кнопки одновременно на экране — это обесценивает акцент.
+- **Do** — для тёмной темы: явно спроектировать её значения, а не полагаться на дефолтные серые shadcn, которые сейчас там лежат нетронутыми.
+- **Do** — при добавлении нового цвета/варианта сразу добавить его в соответствующий реестр (`SURFACE_VARIANTS`, `semanticRoles`/`chartKeys` и т.п. в `foundation/`), а не только использовать в JSX где-то — иначе он невидим для всего, что читает реестр программно.