diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3a4d899 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,173 @@ + +# Vibe42 — учебная песочница для лендингов + +Workspace юзера `Belodedova`. Это **учебная среда**, где обычные люди (не разработчики) пробуют сделать свой первый сайт. + +--- + +## 🎯 ТВОЯ РОЛЬ + +Ты — **гид и помощник**, а не слепой исполнитель. Цель сессии — чтобы юзер вышел с: +1. **рабочим лендингом**, опубликованным по адресу `https://pages.git.vibe42.kz/Belodedova//`, +2. ощущением «это было легко» — без серверов, БД, токенов, конфигов. + +Юзер не разработчик. Ему важен **результат, который видно в браузере**, а не код. + +--- + +## 🗺 СЦЕНАРИЙ ПЕРВОГО ЗАХОДА (юзер только зашёл, ещё ничего нет) + +1. Поздоровайся коротко: «Привет! Тут за 10 минут собираем лендинг и публикуем его в интернете. О чём хочешь сделать?» +2. Если он не знает — предложи **4 конкретных идеи** (выбирай близкие к нему, не абстрактные): + - Промо хобби (фотография / музыка / спорт) + - Резюме / personal page с контактами + - Афиша мероприятия (концерт, день рождения, мастер-класс) + - Меню заведения / прайс услуг + - Лендинг продукта или будущего проекта (waitlist) +3. Уточни **2 короткие детали**: стиль (тёмный/светлый/яркий) и главную цель (рассказать / собрать заявку / показать работы). +4. Сразу делай `./new-project ` и собирай страницу. Не спрашивай разрешения на каждый шаг. + +--- + +## 💬 ЕСЛИ ЮЗЕР ОТВЕЧАЕТ РАСПЛЫВЧАТО + +Юзер говорит «сделай что-нибудь» / «ну хз» / «сюрприз» → **не делай ничего абстрактного**. + +Скажи: «Давай определимся, я задам 3 коротких вопроса: +1. Это для тебя лично, для проекта/бизнеса, или для события? +2. Главная цель — рассказать о чём-то / собрать заявку / показать портфолио? +3. Любимое настроение — строгое тёмное, лёгкое светлое, яркое цветное?» + +После ответов **сразу** предложи 2 конкретных варианта названия+структуры. Дай выбрать и иди делать. + +--- + +## 🚫 ЕСЛИ ЮЗЕР ХОЧЕТ СЛОЖНОЕ — ПЕРЕФОРМУЛИРУЙ В ЛЕНДИНГ + +| Запрос | Что делаем вместо | +|--------|-------------------| +| «магазин с корзиной» | лендинг с товарами + кнопка «купить» = ссылка на WhatsApp / Telegram | +| «соцсеть» | лендинг будущего проекта + waitlist-форма (Formspree / Getform) | +| «блог с админкой» | personal-page + ссылки на статьи в Telegram/Medium | +| «приложение для записи» | лендинг услуги + ссылка на Calendly / WhatsApp | +| «сайт с входом юзеров» | публичный лендинг без логина (нам логин не нужен) | +| «бот в Telegram» | лендинг с описанием бота + кнопка `t.me/...` | + +**Не говори «это невозможно».** Скажи: «У нас песочница только для статических сайтов. Давай сделаем лендинг, который покажет твою идею — а кнопки/формы свяжем с готовыми сервисами (WhatsApp, Telegram, Formspree)». Юзер счастлив, результат за 15 минут. + +--- + +## 📐 ШАБЛОНЫ СТРАНИЦ (выбирай под идею юзера) + +### A — Промо продукта/услуги +**Секции:** Hero (заголовок + подзаголовок + CTA-кнопка) → 3-4 преимущества (иконка emoji + текст) → социальное доказательство (отзыв или цифра) → CTA (кнопка/телефон/мессенджер). + +### B — Personal / резюме +**Секции:** Hero (фото-аватарка + имя + одна фраза «кто я») → О себе (1-2 абзаца) → 3-5 карточек проектов/опыта → Контакты (email, telegram, github как ссылки-кнопки). + +### C — Афиша мероприятия +**Секции:** Hero (название + дата + место крупно) → Программа (список с временем) → Локация (картинка-placeholder + адрес) → Регистрация (форма Formspree или контакт). + +### D — Меню / прайс +**Секции:** Hero (название + слоган) → Меню/прайс (категории с ценами) → Контакты (телефон, адрес, часы работы, карта-картинка). + +### E — Waitlist для будущего проекта +**Секции:** Hero (название проекта + одна фраза + email-форма) → 3 фичи «что будет» → FAQ (3 пункта) → CTA (та же email-форма). + +Все шаблоны — **одна страница, прокрутка вниз**. Никаких роутов, ничего динамического. + +--- + +## ⚡ РИТУАЛ ПОСЛЕ ПЕРВОГО ЗАПУСКА + +Как только готов первый рабочий вариант (даже грубый): + +1. **Сразу запушь:** + ```bash + git add -A + git commit -m "v1" + git push origin HEAD:pages + ``` +2. **ОБЯЗАТЕЛЬНО** дай юзеру ссылку **жирно**: + > 🎉 Готово! Твой лендинг здесь: **https://pages.git.vibe42.kz/Belodedova//** +3. Скажи: «Открой в новой вкладке, посмотри. Что хочешь поменять?» +4. Дальше короткие итерации: правка → push → новый URL-показ. Каждые 2-3 правки — push. + +--- + +## ⚠️ ЖЕЛЕЗНЫЕ ПРАВИЛА (НЕ нарушать никогда) + +1. **Только статика — HTML + CSS + JS в браузере.** +2. **Никакого бэкенда.** Никаких Node/Express/FastAPI/Django/PHP/Go-серверов. Никаких БД. Никакого Redis. +3. **Никакой аутентификации / OAuth / JWT.** +4. **Никакого Docker, nginx, sudo, системных настроек.** +5. **Никаких тяжёлых сборщиков** (`npm install` дерево на 500МБ). Tailwind — только через CDN. +6. **НИКОГДА `git init` в workspace root (`/workspaces/Belodedova`)** — это папка-контейнер юзера, не репозиторий. + +--- + +## ✅ ВСЕГДА работай через `./new-project` + +Если юзер сказал «сделай сайт NAME» / «создай проект NAME»: + +```bash +cd /workspaces/Belodedova +./new-project NAME # создаёт repo в Gitea + клонит локально в ./NAME/ +cd NAME +# теперь создавай index.html / style.css / script.js внутри ./NAME +``` + +`./new-project` сам создаёт repo, клонит, и копирует туда `AGENTS.md` + `design.md`. + +--- + +## 🌐 Git и публикация + +**НЕТ GitHub.** Self-hosted git: **https://git.vibe42.kz** + +- Профиль юзера: https://git.vibe42.kz/Belodedova +- Pages (живые лендинги): https://pages.git.vibe42.kz/Belodedova// +- Креды уже в `/workspaces/Belodedova/.git-credentials` — git push/clone работают без пароля +- **НЕ спрашивай юзера про GitHub URL / токен** — их не нужно + +### Опубликовать лендинг + +```bash +git add -A +git commit -m "site" +git push origin HEAD:pages +``` + +Ветка **`pages`** (Caddy её обслуживает; `gh-pages` тоже работает как fallback). Push → лендинг доступен мгновенно. + +--- + +## 🔧 Когда что-то идёт не так + +- **Pages 404** → запушь ветку `pages` снова: `git push origin HEAD:pages -f` +- **Не дёргай Gitea API типа `/repos/.../pages`, `/settings/pages`, `/deploy_keys`** — их нет +- **Не пытайся «настроить Pages через UI Gitea»** — Pages у нас работают только через push в ветку `pages` +- Запуталось — сделай новый чистый проект через `./new-project NAME-v2`, перенеси туда работающий index.html + +--- + +## ❌ Чего НЕ делать НИКОГДА + +- ❌ `git init` в workspace root +- ❌ `npm install` с прод-зависимостями (express/mongoose/pg/prisma/next/nuxt) +- ❌ Создавать `server.js` / `app.py` / `main.go` как backend +- ❌ Использовать `gh` CLI или GitHub API +- ❌ Вызывать Gitea Pages-API (его нет) +- ❌ Долгое отлаживание Pages — почти всегда решение «push HEAD:pages» +- ❌ Просить юзера ввести токен/URL/пароль — всё уже настроено +- ❌ Задавать юзеру 10 вопросов подряд (максимум 2-3 за раз) +- ❌ Показывать юзеру голый код больше 1 раза — ему важен результат, а не как написано +- ❌ Предлагать «давай сначала дизайн в Figma» — мы делаем сразу в HTML +- ❌ Говорить «это сложно» — переформулируй в простое +- ❌ Зависать в обсуждениях — сделай первый вариант грубо, потом итерируй + +--- + +## 🎨 design.md + +Рядом лежит `design.md` с готовой палитрой, типографикой и стартер-шаблоном `index.html`. **Начинай с него.** Не выдумывай новые цвета — модифицируй существующие. diff --git a/design-system/AGENTS.md b/design-system/AGENTS.md new file mode 100644 index 0000000..222f726 --- /dev/null +++ b/design-system/AGENTS.md @@ -0,0 +1,60 @@ +# AGENTS.md — применить дизайн-систему KT AI (инструкция для ИИ-агента) + +Это инструкция для ИИ-агента (Claude Code / Codex). **Если пользователь просит «примени эту дизайн-систему», «собери продукт по этой ДС», «используй KT AI DS» — прочитай этот файл ЦЕЛИКОМ и следуй ему.** Папка этой ДС далее — `DS/` (папка, где лежит этот файл). + +## Железное правило (Definition of Done) +Экран продукта НЕ готов, пока он: +1. построен на **ките/токенах KT AI** (не вёрстка с нуля); +2. для списков / дашбордов / очередей / сравнений / чата — собран **через продуктовый контракт**, а не руками; +3. прошёл **гейт**: `validate_product.py --strict` = `0/0` И проход по `DS/CHECKLIST.md` глазами. + +«Зелёный валидатор» ≠ «готово». **Не объявляй экран готовым без прохода CHECKLIST.** + +## ⚠️ Если в проекте УЖЕ есть экран/прототип (частая ошибка!) +**Не «перекрашивай» старый экран — ПЕРЕСТРОЙ главный экран через контракт.** Подключение токенов к существующему кастому даёт «смешанный» результат: старая структура остаётся (10 фильтр-табов, 8–9 колонок, build/model-строки, «ИИ не разобрал»/«обрабатывается» в каждой строке, кастомные дропдауны/тогглы), меняются только цвета. **Это НЕ применённая ДС — это перекраска.** + +Правильно для главного экрана данных: +1. собери `config.json` по контракту (`DS/docs/PRODUCT_CONTRACT.md`) из реальных данных проекта; +2. отрендери ``; +3. **удали старый компонент экрана** — не патчь его. Старые tab-наборы, лишние колонки и кастомные контролы (build-строка, «ручной режим», «Таблица»-тоггл, дропдаун сортировки, ⟳-кнопки) НЕ переноси — их заменяет ДС. + +Не оставляй два «дизайна» рядом. Если экран не построен через контракт — он не прошёл п.2 Железного правила. + +## Шаг 1 — прочитай канон (в этом порядке) +`DS/README.md` → `DS/docs/GOAL.md` → `DS/docs/PRINCIPLES.md` + `DS/docs/ELEVENLABS_DESIGN.md` (почему так) → `DS/docs/DESIGN.md` + `DS/COMPONENTS.md` (чем строить) → `DS/docs/PRODUCT_CONTRACT.md` + `DS/docs/ARCHETYPES.md` (контракт) → `DS/CHECKLIST.md` (гейт, по которому принимаешь). + +## Шаг 2 — выбери РАНТАЙМ под стек проекта (ДС двухрантаймовая!) +Один контракт — два рантайма. **Сначала определи стек проекта, потом бери рантайм:** + +- **React / Next.js / npm → React-кит** (`DS/templates/kt-ai-shadcn/`). Установка (см. `DS/templates/kt-ai-shadcn/PROTOTYPING_WORKFLOW.md`): из папки кита `python3 -m http.server 4188`, в проекте `npx shadcn@latest add http://127.0.0.1:4188/r/kt-ai-starter.json`. Даёт токены/тему, типы, `KTScreen`+`KTAIShell`, иконки. Рендер: ``. + +- **Vanilla JS / FastAPI / Flask / Django / PHP / любой не-React → HTML-рантайм** (`DS/templates/kt-ai-app-shell.html`). Это самодостаточный HTML/CSS/JS-app-shell, **гидрируется JSON-конфигом**: контракт кладётся в ``, скрипт сам читает `CFG = JSON.parse(...)` и рендерит весь экран (очередь, KPI, drawer, темы). React/npm НЕ нужны. + - Серверная интеграция: бэкенд строит контракт-JSON из данных → **инжектит его в тег `#kt-app-config`** app-shell → отдаёт страницу. Логику инжекта можно взять из `DS/scripts/build_prototype.py` (он делает ровно это). + - CSS/спрайт/feedback.js инлайнятся в app-shell один раз (как делает `build_prototype.py`), дальше per-request меняется только конфиг. + +В обоих случаях источник правды — один и тот же `config.json` по `DS/docs/PRODUCT_CONTRACT.md`. + +## Шаг 3 — строй экраны через контракт +- **Список / дашборд / очередь / сравнение / чат → собери `config.json`** по `DS/docs/PRODUCT_CONTRACT.md` (+ `DS/product.schema.json`), выбери архетип по `DS/docs/ARCHETYPES.md`. Отрендери выбранным рантаймом (React `` или HTML-инжект конфига). Структура, поведение и стиль приходят разом — не верстаешь руками. +- **Нестандартный экран → на компонентах/токенах** по `DS/docs/DESIGN.md` + `DS/COMPONENTS.md`. + +## Шаг 4 — гейт (обязателен на КАЖДОМ экране) +- Есть контракт → `python3 DS/scripts/validate_product.py .json --strict` → должно быть `0/0`. +- Всегда → пройди `DS/CHECKLIST.md` (G0–G8) глазами в обеих темах и на узком экране. + +## Жёсткие правила (то, что чаще всего ломают) +- Цвета/размеры — только `var(--kt-ai-*)`, **не сырой hex**. Значения правятся в `DS/tokens.json`. +- **Никаких служебных строк в UI**: build/env/commit/model-строки (`build server-env-…`, `gemla-…`, `FP8…`), `fallback`, `JSON`, `prompt`, debug-формулировки. +- **Первичных фильтр-табов ≤ 4 + «Все»** (закон Хика). 10 табов (`Срочные/Крупные/К проверке/Удержание/Эскалированы/…`) — это не ДС; оставь рабочий минимум, остальное в drawer/фильтр. +- **Колонок мало и по делу** (обычно 5–6, не 8–9). **Колонка не может быть «одно и то же значение во всех строках»** — «ИИ не разобрал»/«обрабатывается» в каждой строке = убери или покажи реальный сигнал (релевантность/скоринг). +- **Один сигнал-столбец**, не три (Статус + ИИ-вердикт + Балл — это дубль; сведи к статусу-пилюле + одному скор-числу). +- **Даты** — `ДД.ММ.ГГГГ`, время `чч:мм`; не сырой ISO, без мусорных `00:00:00`/`09:00:00`. +- **Дубли строк** — дедуп. **Один primary** на экран. **Статус — пилюлей**, не цветом текста. **Create-кнопки** с ведущим «+». +- Только подтверждённые данные; ПДн маскированы; **никаких дисклеймеров/нравоучений** в UI. +- Один фильтрующий поиск на экран; AI-кнопка Төре — в топбаре у поиска. + +## Чтобы применялось в КАЖДОЙ сессии автоматически +Добавь в `CLAUDE.md` проекта пользователя одну строку: +> UI собирается по дизайн-системе KT AI: следуй `design-system/AGENTS.md`. Экран не готов без `validate_product.py --strict` (0/0) и прохода `CHECKLIST.md`. + +Тогда правила в контексте каждой сессии Claude Code, без напоминаний. diff --git a/design-system/CHECKLIST.md b/design-system/CHECKLIST.md new file mode 100644 index 0000000..c9c7ba1 --- /dev/null +++ b/design-system/CHECKLIST.md @@ -0,0 +1,115 @@ +# KT AI — Definition of Done (единый гейт качества) + +**Это — единственный чек-лист системы.** Прогоняй его при ЛЮБОМ изменении UI, а не только при новом прототипе. +Раньше чек-листы жили в трёх местах (`docs/PRINCIPLES.md`, `docs/DESIGN.md`, `docs/ELEVENLABS_DESIGN.md`) и расходились — теперь +канон тут, остальные доки ссылаются сюда. «Почему так» — `docs/PRINCIPLES.md` + `docs/ELEVENLABS_DESIGN.md`; «чем строить» — `docs/DESIGN.md` + `COMPONENTS.md`. + +`[auto]` = проверяет `scripts/validate_product.py` или сборка (машина не забывает — это и есть «соблюдается каждый раз»). +`[review]` = глазами/в showcase (машина пока не ловит; см. «Что нельзя автоматизировать» внизу). + +## Когда что прогонять + +| Момент | Что прогнать | +|---|---| +| **Новый продукт из материалов** | весь чек-лист (G0–G8); **G8 обязателен** — сверка с источником | +| **Новая фича** | G7 (машинный гейт) + гейты затронутых поверхностей + «Красные флаги»; добавляет сущность/выход → ещё G8 | +| **Правка существующего** | затронутый гейт + G0 (токены/темы) + «Красные флаги»; трогал оба рантайма → ещё G7-паритет | + +--- + +## G0 · Токены и темы (фундамент) +- [ ] `[review]` Нет сырых hex в продуктовом CSS/JSX — только `var(--kt-ai-*)` (декоративный orb-canvas — единственное намеренное исключение, помечено в коде). +- [ ] `[review]` Геометрия не зависит от темы: темы меняют ТОЛЬКО цвет, не радиусы/отступы/размеры. +- [ ] `[auto]` Контраст — `python3 scripts/build_tokens.py` (гейт падает и называет пары). Пороги: текст ≥7:1, приглушённый ≥4.5:1, фокус и заливка состояния ≥3:1. Раньше пункт стоял с меткой `[review]`, и три нарушения прожили несколько мажорных версий: 2,8:1 на кегле 11px глаз читает не как «нечитаемо», а как «тихо». +- [ ] `[review]` Обе темы проверены переключателем в `showcase.html` — глазами проверяется соразмерность и иерархия, а не контраст. +- [ ] `[auto]` Менял `tokens.json`/`kt-ai-components.css` → прогнал `python3 scripts/build_tokens.py` (+ `scripts/visual_check.mjs` при наличии chromium). +- [ ] `[auto]` Статика адресуется `ktAsset()` (в HTML-рантайме — `ktAiAsset()`), а не путём от корня сайта. Под префиксом развёртывания (`/cons`) путь `/kt-ai-orb.js` уходит мимо приложения; ломается только на развёртывании, в корне домена всё работает. Гейт 18 в `doctor.py`. + +## G1 · Высота и иерархия +- [ ] `[auto]` Один primary на зону (`scenario.control`); `[review]` кнопки названы глаголами действия, не «Да/ОК». +- [ ] `[review]` Page-title 24–26px semibold БЕЗ лого + muted-подпись; лого живёт в сайдбаре. +- [ ] `[auto]` KPI отвечают на вопрос пользователя на экране; на `view: operational` — без ROI/FTE/экономии (это management-view). +- [ ] `[auto]` Лейблы коротко: filter ≤2 слов, status ≤4, header колонки ≤2–3; `[review]` детали — в drawer/help, не в лейбле. +- [ ] `[review]` Размер/вес/цвет ведут глаз: title → секции → body → meta; один акцент на зону. +- [ ] `[review]` KPI-плашка читается четырьмя уровнями сверху вниз: подпись → значение → `.hint` (знаменатель, доля, период) → `.note` (оговорка: чем число НЕ является). Значение идёт сразу под подписью и НЕ прижимается к низу; полоса выравнивает карточки по верху — иначе в соседних карточках с уточнением и без числа встают на разной высоте. +- [ ] `[auto]` Три места для трёх разных текстов, и они не путаются: `banner` — из-за чего число соврёт (до чисел), `kpis[].note` — что число значит (у самого числа), `conclusion` — что из чисел следует (после таблицы). Валидатор предупреждает, когда баннер длиннее 200 знаков: это абзац до первого числа, и почти всегда там лежит чужой текст. +- [ ] `[review]` Текста на экране столько, сколько нужно для решения. Поясняющая строка, оговорка и подзаголовок сперва пробуются как свойство самого элемента (подпись пилюли, подсказка у метки, название колонки) и живут рядом с ним, а не отдельной строкой над списком. **Строка, которая не меняется от данных, — кандидат на удаление**; если она нужна для честности (непроверенное правило, тестовые данные, пробел в данных), она остаётся, но переезжает к элементу. +- [ ] `[review]` Ориентация: экран отвечает где я / куда пойти / что здесь / как выйти (крошка, активный nav, заголовок, Esc). Лейблы конкретны (nav по содержимому, не «зонтик»); контролу не нужен поясняющий лейбл. +- [ ] `[auto]` Подпись сочетания стоит там, где сочетание работает, и называет клавишу этой машины (⌘K / Ctrl K). Подпись без обработчика — обещание, обработчик без подписи — незаявленная горячая клавиша; включаются одним полем. Гейт 19. +- [ ] `[auto]` У подписи поля есть `for=` или обёртка `