kuips

Читать по-русски →

KUIPS puts every screen of an app on one sheet and draws how they connect: which button leads where, which process a screen belongs to, which states hide behind a tap. An AI agent describes the screens and the links in a JSON manifest and captures the screen images with kuips shoot — from the live app or from HTML mock-ups. KUIPS then builds one HTML file: zoom and pan, colour connector lines (pipes) with direction arrows, screens grouped into rows by process, a component library and the design tokens read from the app's own styles. The file opens with a double click — no server, no account, no internet.

Sections: 1 What it does · 2 Quick start · 3 The manifest · 4 Commands · 5 For AI agents: CLI, API, MCP · 6 Checking the sheet · 7 Project map · 8 History · 9 Credits and licence.

1. What it does

1. Lays screens out by a rule: a row is a process, a column is a step of the user's path, a tier above or below holds alternative states. The agent writes the table of rows; KUIPS computes the coordinates.

2. Draws links as pipes, the way a plumber would: right angles, rounded turns, one colour per source screen, parallel lanes in shared corridors, a direction triangle every 300 px of the sheet. Labels find a free place by themselves and never overlap a pipe, a screen or another label.

3. Puts every screen in a card: name and address on top, the screen image in the middle, a note below with the paths out (→) and in (←); a screen with no way out says so in its note.

4. Takes screens of any size on one sheet: phones of 390 × 900 px and 390 × 860 px, landscape 860 × 390 px, tablets. A column is as wide as its widest screen; a screen image is never cropped.

5. Captures the screen images itself with Playwright: from a live app (an address, a selector to wait for, clicks and typing for states that have no address) or from an HTML mock-up page (one element per screen). Images are WebP by default. When an error page opens instead of the screen, or the app quietly redirects elsewhere, kuips shoot skips the image and reports it — a wrong image never appears under a screen's name.

6. Builds the Components and Design tokens pages from the real product: components are cut-outs of real elements grouped by Atomic Design (atoms, molecules, organisms), tokens are read from computed styles in the light and the dark theme.

7. Has a gear menu at the top right of the sheet: Settings (theme, interface language: English or Russian) and About (KUIPS version, its build number and build date, the time the sheet was built, the manifest path).

8. Checks the sheet with one command and names every defect by class (section 6).

2. Quick start

Install KUIPS into the project, and Chromium, the browser KUIPS captures screens with:

npm install --save-dev github:MikalaiKryvusha/KUIPS#v1.0.0
npx playwright install chromium

Create the manifest, describe the screens in it (section 3), then capture the images, lay the screens out, build and check the sheet:

npx kuips init --lang en          # design/flow-map/flow-map.json
npx kuips shoot                   # frames → design/flow-map/screens/*.webp
npx kuips layout                  # coordinates from the table of rows
npx kuips build                   # design/flow-map.html
npx kuips check                   # 0 defects

The examples/brewlog folder holds a complete example: an HTML mock-up page, the manifest and the built sheet. Open examples/brewlog/design/flow-map.html in a browser to see it.

3. The manifest

The manifest design/flow-map/flow-map.json is the single source of the sheet. KUIPS builds design/flow-map.html from it: edit the manifest and rebuild, never edit the HTML by hand. Keys are written in English or in Russian with the same meaning, and a sheet from a Russian manifest of KUIPS 0.9 builds unchanged.

{
  "title": "Brewlog — screens and flows",
  "lang": "en",
  "screen": { "width": 390, "height": 900 },
  "shoot": { "base": "design/mockups.html", "format": "webp" },
  "screens": [
    { "id": "home", "name": "Home", "address": "tab: Home", "selector": "[data-screen=\"home\"]",
      "note": "Week stats and recent brews" },
    { "id": "timer", "name": "Brew timer", "selector": "[data-screen=\"timer\"]", "width": 860, "height": 390 }
  ],
  "links": [{ "from": "home", "to": "timer", "label": "Start" }],
  "layout": [{ "name": "Brewing", "places": [["home", 0, 0], ["timer", 1, 0]] }]
}

4. Commands

Every command takes --root DIR (the project root), --manifest P (the manifest path, relative to the root) and --json. Exit codes: 0 — done, 1 — defects or errors, 2 — wrong call.

5. For AI agents: CLI, API, MCP

CLI. --json prints a machine-readable result with stable English keys:

npx kuips check --json
# { "command": "check", "ok": true, "defects": [], "warnings": [], "summary": { "screens": 8, "links": 9, … } }

API. The CLI's functions can be imported from the kuips package:

import { build, layout, check } from 'kuips';
const r = check({ root: process.cwd() });
if (!r.ok) console.log(r.defects);

MCP. kuips mcp serves six tools — kuips_build, kuips_check, kuips_layout, kuips_screens, kuips_shoot, kuips_crop — to clients of MCP revision 2026-07-28 (server/discover, per-request _meta) and of the earlier revisions (initialize). kuips_crop returns a PNG of one screen card or one row, so the agent shows a person exactly the place under discussion. To connect Claude Code, put this .mcp.json into the project root:

{ "mcpServers": { "kuips": { "command": "node", "args": ["node_modules/kuips/bin/kuips.mjs", "mcp"] } } }

6. Checking the sheet

kuips check reads the same geometry the sheet draws and reports each defect with a class code:

Warnings (frame-unused, sheet-missing) do not fail the check.

7. Project map

bin/kuips.mjs          the CLI
src/index.mjs          the API
src/manifest.mjs       manifest keys in English and Russian, validation
src/geometry.mjs       pipes, lanes, direction triangles, label placement
src/layout.mjs         the table of rows → coordinates
src/sheet.mjs          the HTML sheet, the gear menu, the pages
src/check.mjs          kuips check
src/shoot.mjs          the screen and library shooters
src/mcp.mjs            the MCP server
examples/brewlog/      a complete example
test/                  node:test units; the shooter and render tests drive a real Chromium

8. History

KUIPS was born on 4 September 2026. Mikalai Kryvusha asked for one page where he could see a whole app from above — screens side by side, arrows between them, the way designers do it in Figma, but open and local. The next day the sheet got pipes, rows, pages, the component library and the name KUIPS. On 16 October 2026 KUIPS moved into its own repository as version 0.9.0; version 1.0.0 works in any project. The changes are in CHANGELOG.md.

9. Credits and licence

MIT © 2026 Mikalai Kryvusha (KOT KRINIK). Frames are shot with Playwright (Apache-2.0). The project is run with KAIF, the author's framework for work with AI agents.

Read in English →

KUIPS кладёт все экраны приложения на один лист и рисует, как они связаны: какая кнопка куда ведёт, к какому процессу относится экран, какие состояния прячутся за нажатием. ИИ-агент описывает экраны и связи в манифесте JSON и снимает кадры экранов командой kuips shoot — с живого приложения или с HTML-макетов. Из манифеста и кадров KUIPS собирает один HTML-файл: зум, панорама, цветные линии связей (трубы) со стрелками направления, ряды экранов по процессам, библиотека компонентов и дизайн-схема, прочитанная из стилей самого приложения. Файл открывается двойным щелчком, без сервера, без учётной записи и без интернета.

Разделы: 1 Что умеет · 2 Быстрый старт · 3 Манифест · 4 Команды · 5 Для ИИ-агентов: CLI, API, MCP · 6 Проверка листа · 7 Карта проекта · 8 История · 9 Благодарности и лицензия.

1. Что умеет

1. Раскладывает экраны по правилу: ряд — это процесс, колонка — шаг пути пользователя, ярус над или под экраном — его альтернативное состояние. Агент пишет таблицу рядов, координаты считает KUIPS.

2. Рисует связи трубами, как водопровод: прямые углы, скруглённые повороты, свой цвет у каждого экрана-источника, параллельные полосы в общих коридорах, треугольник направления каждые 300 пикселей листа. Подпись связи сама находит свободное место и не ложится на трубу, экран или другую подпись.

3. Кладёт каждый экран в карточку: сверху имя и адрес, посередине кадр, внизу заметка и пути «→ куда ведёт» и «← откуда приходят». Если у экрана нет путей наружу, заметка говорит об этом словами.

4. Держит на одном листе экраны любого размера: телефоны 390 × 900 и 390 × 860 пикселей, альбомные 860 × 390, планшеты. Ширина колонки равна ширине самого широкого экрана в ней; кадр не обрезается.

5. Снимает кадры сам, через Playwright: с живого приложения (адрес, селектор элемента, которого съёмщик ждёт, клики и ввод для состояний без адреса) или со страницы HTML-макетов (один элемент на экран). Кадры по умолчанию в WebP. Если вместо экрана открылась страница ошибки или приложение незаметно ушло на другой адрес, kuips shoot такой кадр не снимает и называет экран: чужой кадр под именем экрана не окажется.

6. Собирает страницы Компоненты и Дизайн-схема с живого приложения: компоненты — вырезки настоящих элементов, разложенные по Atomic Design (атомы, молекулы, организмы); токены прочитаны из вычисленных стилей в светлой и тёмной теме.

7. Справа вверху листа — меню-шестерёнка: Настройки (тема, язык надписей: русский или английский) и О приложении (версия KUIPS, номер и дата её сборки, время сборки листа, путь к манифесту).

8. Проверяет лист одной командой и называет каждый дефект его классом (раздел 6).

2. Быстрый старт

Установите в проект KUIPS и браузер Chromium, которым KUIPS снимает кадры:

npm install --save-dev github:MikalaiKryvusha/KUIPS#v1.0.0
npx playwright install chromium

Заведите манифест, опишите в нём экраны (раздел 3), затем снимите кадры, разложите экраны, соберите и проверьте лист:

npx kuips init                    # design/flow-map/flow-map.json, ключи по-русски
npx kuips shoot                   # кадры → design/flow-map/screens/*.webp
npx kuips layout                  # координаты по таблице рядов
npx kuips build                   # design/flow-map.html
npx kuips check                   # дефектов 0

Папка examples/brewlog — готовый пример: страница HTML-макетов, манифест и собранный лист. Откройте examples/brewlog/design/flow-map.html в браузере.

3. Манифест

Лист строится из манифеста design/flow-map/flow-map.json. Файл design/flow-map.html KUIPS собирает из манифеста: правьте манифест и пересобирайте лист, HTML руками не правьте. Ключи пишутся по-русски или по-английски, смысл у них один; лист по русскому манифесту KUIPS 0.9 собирается без правок.

{
  "название": "Brewlog — экраны и переходы",
  "язык": "ru",
  "экран": { "ширина": 390, "высота": 900 },
  "съёмка": { "адрес": "design/mockups.html", "формат": "webp" },
  "экраны": [
    { "id": "home", "имя": "Главная", "адрес": "вкладка «Главная»", "селектор": "[data-screen=\"home\"]",
      "заметка": "Сводка недели и последние заварки" },
    { "id": "timer", "имя": "Таймер", "селектор": "[data-screen=\"timer\"]", "ширина": 860, "высота": 390 }
  ],
  "связи": [{ "от": "home", "к": "timer", "подпись": "Старт" }],
  "раскладка": [{ "имя": "Заварка", "места": [["home", 0, 0], ["timer", 1, 0]] }]
}

Полная таблица ключей с английскими парами — в английской половине. Адрес экрана, который начинается с /, ? или #, съёмщик открывает; адрес другого вида остаётся подписью на карточке.

4. Команды

У каждой команды есть --root DIR (корень проекта), --manifest P (путь к манифесту от корня) и --json. Коды возврата: 0 — готово, 1 — дефекты или ошибки, 2 — неверный вызов.

5. Для ИИ-агентов: CLI, API, MCP

CLI. --json печатает машиночитаемый результат с постоянными английскими ключами:

npx kuips check --json
# { "command": "check", "ok": true, "defects": [], "warnings": [], "summary": { "screens": 8, "links": 9, … } }

API. Функции CLI можно импортировать из пакета kuips:

import { build, layout, check } from 'kuips';
const r = check({ root: process.cwd() });
if (!r.ok) console.log(r.defects);

MCP. kuips mcp отдаёт шесть инструментов — kuips_build, kuips_check, kuips_layout, kuips_screens, kuips_shoot, kuips_crop — клиентам ревизии MCP 2026-07-28 (server/discover, _meta в каждом запросе) и более ранних ревизий (initialize). kuips_crop возвращает PNG одной карточки экрана или одного ряда: агент показывает человеку ровно то место, о котором разговор. Чтобы подключить Claude Code, положите в корень проекта файл .mcp.json:

{ "mcpServers": { "kuips": { "command": "node", "args": ["node_modules/kuips/bin/kuips.mjs", "mcp"] } } }

6. Проверка листа

kuips check читает ту геометрию, которую рисует лист, и называет каждый дефект кодом класса:

Предупреждения (frame-unused, sheet-missing) проверку не валят.

7. Карта проекта

bin/kuips.mjs          CLI
src/index.mjs          API
src/manifest.mjs       ключи манифеста по-русски и по-английски, проверка
src/geometry.mjs       трубы, полосы, треугольники направления, места подписей
src/layout.mjs         таблица рядов → координаты
src/sheet.mjs          HTML-лист, меню-шестерёнка, страницы
src/check.mjs          kuips check
src/shoot.mjs          съёмщики экранов и библиотеки
src/mcp.mjs            MCP-сервер
examples/brewlog/      готовый пример
test/                  юниты node:test; тесты съёмщика и листа гоняют настоящий Chromium

8. История

KUIPS родился 4 сентября 2026 года. Николай Кривуша попросил одну страницу, на которой видно всё приложение сверху: экраны рядом, стрелки между ними, как у дизайнеров в Figma, но открыто и локально. На следующий день у листа появились трубы, ряды, страницы, библиотека компонентов и имя KUIPS. 16 октября 2026 года KUIPS переехал в свой репозиторий с версией 0.9.0. Версия 1.0.0 работает в любом проекте. Изменения — в CHANGELOG.md.

9. Благодарности и лицензия

MIT © 2026 Николай Кривуша (KOT KRINIK). Кадры снимает Playwright (Apache-2.0). Проект ведётся по KAIF — фреймворку автора для работы с ИИ-агентами.