78 lines
4.9 KiB
Markdown
78 lines
4.9 KiB
Markdown
# KT AI Design System
|
||
|
||
Дизайн-система для внутренних продуктов ИИ-команды КТ. Прототип и продакшн-фронтенд — один и тот же код: продуктовый контракт (`config.json`) рендерится либо React-китом, либо самодостаточным HTML app-shell.
|
||
|
||
Одна папка, внешних зависимостей нет.
|
||
|
||
## Быстрый старт
|
||
|
||
Систему не нужно изучать — её читает ИИ-агент. Положите папку в проект как `design-system/` и дайте задачу:
|
||
|
||
> Примени дизайн-систему из `design-system/` — прочитай `design-system/AGENTS.md` целиком и следуй ему.
|
||
> Затем собери экран «Реестр договоров».
|
||
|
||
Дальше агент делает всё сам: выбирает рантайм под ваш стек, собирает экран через контракт, а не вёрсткой руками, и прогоняет гейт качества.
|
||
|
||
Работает с Claude Code, Codex, Cursor и любым агентом, который читает файлы репозитория.
|
||
|
||
**Чтобы не повторять это каждую сессию** — добавьте в `CLAUDE.md` проекта одну строку:
|
||
|
||
```
|
||
UI собирается по дизайн-системе KT AI: следуй `design-system/AGENTS.md`.
|
||
```
|
||
|
||
## Если проект уже существует
|
||
|
||
Самая частая ошибка — «перекрасить» имеющиеся экраны токенами. Структура остаётся старой, меняются только цвета — это не применённая ДС.
|
||
|
||
Как правильно — раздел [«Если в проекте УЖЕ есть экран»](AGENTS.md) в `AGENTS.md`: главный экран данных пересобирается через контракт, старый компонент удаляется. Агент читает это сам.
|
||
|
||
## Посмотреть и проверить
|
||
|
||
```bash
|
||
open showcase.html # галерея компонентов, светлая и тёмная темы
|
||
python3 scripts/doctor.py # 10 секунд: всё ли на месте и цело
|
||
```
|
||
|
||
`examples/` — 16 готовых продуктов, каждый парой «контракт + собранный прототип». Прототипы открываются двойным кликом.
|
||
|
||
## Подключить как зависимость
|
||
|
||
Чтобы проект всегда работал на свежей ДС, а не на копии, которая тихо отстаёт:
|
||
|
||
```bash
|
||
npm i github:erjan-A/kt-ai-design-system
|
||
```
|
||
|
||
```tsx
|
||
import { KTAIShell, KTScreen } from "kt-ai-design-system/kit";
|
||
```
|
||
|
||
Обновление — `npm update kt-ai-design-system`. Настраивать сборщик не нужно: кит приезжает собранным, с типами. Нужен доступ к репозиторию у всех и в CI — [`docs/SETUP.md`](docs/SETUP.md).
|
||
|
||
## Подключить как копию
|
||
|
||
Проекту нужно править компоненты под себя — скопируйте папку к себе и дальше ведите её сами. Система в этом не участвует: копия становится ответственностью проекта, включая обновления.
|
||
|
||
Коротко, если без React:
|
||
|
||
```html
|
||
<link rel="stylesheet" href="kt-ai-tokens.css"> <!-- значения -->
|
||
<link rel="stylesheet" href="kt-ai-components.css"> <!-- компоненты -->
|
||
<link rel="stylesheet" href="kt-ai-fonts.css"> <!-- Inter, кириллица + ₸ -->
|
||
<body class="kt-ai-app"> <!-- тёмная тема: data-theme="dark" -->
|
||
```
|
||
|
||
## Что где лежит
|
||
|
||
| | |
|
||
|---|---|
|
||
| [`AGENTS.md`](AGENTS.md) | инструкция ИИ-агенту — главный документ |
|
||
| [`CHECKLIST.md`](CHECKLIST.md) | Definition of Done: экран не готов, пока не прошёл |
|
||
| [`COMPONENTS.md`](COMPONENTS.md) | анатомия компонентов и компоновка экрана |
|
||
| [`docs/`](docs/) | канон: токены и API, принципы, контракт, архетипы |
|
||
| [`docs/RELEASE.md`](docs/RELEASE.md) | как выпускается ДС — правка в каноне до продуктов доезжает только релизом |
|
||
| [`examples/`](examples/README.md) | 16 готовых продуктов |
|
||
| `tokens.json` | единственный источник значений |
|
||
| `templates/` | React-кит и HTML app-shell |
|