kuips
README.md
<a name="english"></a>
<h2 align="center">KUIPS</h2>
<p align="center">
<a href="#english"><img src="https://img.shields.io/badge/English-2C7BE5?style=for-the-badge" alt="English"></a>
<a href="#russian"><img src="https://img.shields.io/badge/Русский-C0392B?style=for-the-badge" alt="Русский"></a>
</p>
<p align="center"><b>Krinik User Interface Prototyping System</b><br>
A local Figma-like sheet where AI agents lay out an app's screens and the wiring between them</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.0.0-FF1A8C.svg" alt="version 1.0.0"></a>
<a href="#en-5"><img src="https://img.shields.io/badge/MCP-2026--07--28_and_legacy-6A5ACD.svg" alt="MCP 2026-07-28 and legacy"></a>
<a href="#en-4"><img src="https://img.shields.io/badge/CLI-kuips-0EA5E9.svg" alt="CLI: kuips"></a>
<a href="#en-2"><img src="https://img.shields.io/badge/Node.js-%E2%89%A518-3DDC84.svg" alt="Node.js 18 or newer"></a>
<a href="https://github.com/MikalaiKryvusha/KAIF"><img src="https://img.shields.io/badge/framework-KAIF-7F52FF.svg" alt="framework: KAIF"></a>
</p>
[Читать по-русски →](#russian)
**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.
<p align="center">
<img src="docs/images/sheet-row.webp" width="100%" alt="A row of the Brewlog example: phone screens, a 390 × 860 px phone screen and a landscape timer, wired by colour pipes inside a framed row">
</p>
<p align="center">
<img src="docs/images/cards-closeup.webp" width="49%" alt="Close-up: screen cards with name and address on top, the frame, and a note with the paths out and in below">
<img src="docs/images/components.webp" width="49%" alt="The Components page: atoms, molecules and organisms cropped from the mock-ups">
</p>
Sections: [1 What it does](#en-1) · [2 Quick start](#en-2) · [3 The manifest](#en-3) · [4 Commands](#en-4) ·
[5 For AI agents: CLI, API, MCP](#en-5) · [6 Checking the sheet](#en-6) · [7 Project map](#en-7) ·
[8 History](#en-8) · [9 Credits and licence](#en-9).
<a name="en-1"></a>
### 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).
<a name="en-2"></a>
### 2. Quick start
Install KUIPS into the project, and Chromium, the browser KUIPS captures screens with:
```bash
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:
```bash
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.
<a name="en-3"></a>
### 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.
```json
{
"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]] }]
}
```
| Key | Russian key | What it holds |
|---|---|---|
| `title`, `subtitle` | `название`, `подпись` | the sheet's heading |
| `lang` | `язык` | interface language of the sheet: `en` or `ru` |
| `screen` | `экран` | default screen size, `{ width, height }` |
| `screens[]` | `экраны[]` | `id`, `name`, `address`, `file`, `note`, `width`, `height`, `x`, `y`; for the shooter `wait`, `selector`, `steps`, `pause`, `errorOk`, `redirectOk` |
| `links[]` | `связи[]` | `from`, `to`, `label` |
| `layout[]` | `раскладка[]` | rows: `name`, `places: [[id, column, tier], …]` |
| `shoot` | `съёмка` | `base` (app URL or mock-up page), `format`, `scale`, `locale`, `storage`, `theme`, `out` |
| `library` | `библиотека` | `components[]`: `id`, `name`, `layer`, `selector`, `address`; `schemeAddress` |
| `rows[]`, `sheet` | `полосы[]`, `лист` | written by `kuips layout` |
<a name="en-4"></a>
### 4. Commands
| Command | What it does |
|---|---|
| `kuips init [--lang en\|ru] [--title T]` | creates the manifest skeleton |
| `kuips shoot [--base URL] [--only id,…]` | shoots the frames of the screens |
| `kuips library [--base URL]` | shoots the components and reads the design scheme |
| `kuips layout` | computes coordinates from the table of rows |
| `kuips build` | builds the sheet |
| `kuips check [--max-age-days N]` | checks the sheet |
| `kuips mcp` | starts the MCP server on stdio |
| `kuips version` | prints the version, the build number and the build date |
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.
<a name="en-5"></a>
### 5. For AI agents: CLI, API, MCP
**CLI.** `--json` prints a machine-readable result with stable English keys:
```bash
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:
```js
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:
```json
{ "mcpServers": { "kuips": { "command": "node", "args": ["node_modules/kuips/bin/kuips.mjs", "mcp"] } } }
```
<a name="en-6"></a>
### 6. Checking the sheet
`kuips check` reads the same geometry the sheet draws and reports each defect with a class code:
| Class | What it looks like on the sheet |
|---|---|
| `pipe-through-card` | a pipe crossing a screen |
| `pipe-off-border` | a pipe that starts or ends in the air next to a screen |
| `triangle-under-card` | a direction arrow hidden under a screen |
| `label-overlap` | a label lying on a pipe, a screen or another label |
| `shelf-on-frame` | a pipe running along the frame of a row |
| `missing-frame` | a screen without its frame |
| `aspect-mismatch` | a frame whose proportions differ from the screen size |
| `external-link` | a sheet that needs the internet |
| `sheet-stale` | a sheet built before the last change of the manifest or the frames |
| `frames-old` | frames older than `--max-age-days` |
Warnings (`frame-unused`, `sheet-missing`) do not fail the check.
<a name="en-7"></a>
### 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
```
<a name="en-8"></a>
### 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](CHANGELOG.md).
<a name="en-9"></a>
### 9. Credits and licence
MIT © 2026 Mikalai Kryvusha (KOT KRINIK). Frames are shot with [Playwright](https://playwright.dev) (Apache-2.0). The
project is run with [KAIF](https://github.com/MikalaiKryvusha/KAIF), the author's framework for work with AI agents.
---
<a name="russian"></a>
<h2 align="center">KUIPS</h2>
<p align="center">
<a href="#english"><img src="https://img.shields.io/badge/English-2C7BE5?style=for-the-badge" alt="English"></a>
<a href="#russian"><img src="https://img.shields.io/badge/Русский-C0392B?style=for-the-badge" alt="Русский"></a>
</p>
<p align="center"><b>Krinik User Interface Prototyping System</b><br>
Локальная «фигма» для ИИ-агентов: экраны приложения и связи между ними на одном листе</p>
[Read in English →](#english)
**KUIPS** кладёт все экраны приложения на один лист и рисует, как они связаны: какая кнопка куда ведёт, к какому
процессу относится экран, какие состояния прячутся за нажатием. ИИ-агент описывает экраны и связи в манифесте JSON и
снимает кадры экранов командой `kuips shoot` — с живого приложения или с HTML-макетов. Из манифеста и кадров KUIPS
собирает один HTML-файл: зум, панорама, цветные линии связей (трубы) со стрелками направления, ряды экранов по
процессам, библиотека компонентов и дизайн-схема, прочитанная из стилей самого приложения. Файл открывается двойным
щелчком, без сервера, без учётной записи и без интернета.
<p align="center">
<img src="docs/images/sheet-dark.webp" width="100%" alt="Ряд примера Brewlog в тёмной теме: экраны телефона, экран 390 × 860 пикселей и таймер в альбомной ориентации, связанные цветными трубами внутри рамки ряда">
</p>
<p align="center">
<img src="docs/images/menu-about.webp" width="49%" alt="Меню-шестерёнка, раздел «О приложении»: версия, номер сборки, дата сборки">
<img src="docs/images/cards-closeup.webp" width="49%" alt="Карточки экранов крупно: имя и адрес сверху, кадр, внизу заметка и пути">
</p>
Разделы: [1 Что умеет](#ru-1) · [2 Быстрый старт](#ru-2) · [3 Манифест](#ru-3) · [4 Команды](#ru-4) ·
[5 Для ИИ-агентов: CLI, API, MCP](#ru-5) · [6 Проверка листа](#ru-6) · [7 Карта проекта](#ru-7) ·
[8 История](#ru-8) · [9 Благодарности и лицензия](#ru-9).
<a name="ru-1"></a>
### 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).
<a name="ru-2"></a>
### 2. Быстрый старт
Установите в проект KUIPS и браузер Chromium, которым KUIPS снимает кадры:
```bash
npm install --save-dev github:MikalaiKryvusha/KUIPS#v1.0.0
npx playwright install chromium
```
Заведите манифест, опишите в нём экраны (раздел 3), затем снимите кадры, разложите экраны, соберите и проверьте лист:
```bash
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` в браузере.
<a name="ru-3"></a>
### 3. Манифест
Лист строится из манифеста `design/flow-map/flow-map.json`. Файл `design/flow-map.html` KUIPS собирает из манифеста:
правьте манифест и пересобирайте лист, HTML руками не правьте. Ключи пишутся по-русски или по-английски, смысл у них
один; лист по русскому манифесту KUIPS 0.9 собирается без правок.
```json
{
"название": "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]] }]
}
```
Полная таблица ключей с английскими парами — в [английской половине](#en-3). Адрес экрана, который начинается с `/`,
`?` или `#`, съёмщик открывает; адрес другого вида остаётся подписью на карточке.
<a name="ru-4"></a>
### 4. Команды
| Команда | Что делает |
|---|---|
| `kuips init [--lang ru\|en] [--title T]` | заводит заготовку манифеста |
| `kuips shoot [--base URL] [--only id,…]` | снимает кадры экранов |
| `kuips library [--base URL]` | снимает компоненты и читает дизайн-схему |
| `kuips layout` | считает координаты по таблице рядов |
| `kuips build` | собирает лист |
| `kuips check [--max-age-days N]` | проверяет лист |
| `kuips mcp` | запускает MCP-сервер на stdio |
| `kuips version` | печатает версию, номер сборки и дату сборки |
У каждой команды есть `--root DIR` (корень проекта), `--manifest P` (путь к манифесту от корня) и `--json`. Коды возврата: 0 — готово, 1 — дефекты
или ошибки, 2 — неверный вызов.
<a name="ru-5"></a>
### 5. Для ИИ-агентов: CLI, API, MCP
**CLI.** `--json` печатает машиночитаемый результат с постоянными английскими ключами:
```bash
npx kuips check --json
# { "command": "check", "ok": true, "defects": [], "warnings": [], "summary": { "screens": 8, "links": 9, … } }
```
**API.** Функции CLI можно импортировать из пакета `kuips`:
```js
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`:
```json
{ "mcpServers": { "kuips": { "command": "node", "args": ["node_modules/kuips/bin/kuips.mjs", "mcp"] } } }
```
<a name="ru-6"></a>
### 6. Проверка листа
`kuips check` читает ту геометрию, которую рисует лист, и называет каждый дефект кодом класса:
| Класс | Как это выглядит на листе |
|---|---|
| `pipe-through-card` | труба идёт сквозь экран |
| `pipe-off-border` | труба начинается или кончается в воздухе рядом с экраном |
| `triangle-under-card` | треугольник направления спрятан под экраном |
| `label-overlap` | подпись лежит на трубе, экране или другой подписи |
| `shelf-on-frame` | труба идёт вдоль рамки ряда |
| `missing-frame` | у экрана нет кадра |
| `aspect-mismatch` | пропорции кадра не совпадают с размером экрана |
| `external-link` | листу нужен интернет |
| `sheet-stale` | лист собран раньше последней правки манифеста или кадров |
| `frames-old` | кадры старше срока `--max-age-days` |
Предупреждения (`frame-unused`, `sheet-missing`) проверку не валят.
<a name="ru-7"></a>
### 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
```
<a name="ru-8"></a>
### 8. История
KUIPS родился 4 сентября 2026 года. Николай Кривуша попросил одну страницу, на которой видно всё приложение сверху:
экраны рядом, стрелки между ними, как у дизайнеров в Figma, но открыто и локально. На следующий день у листа появились
трубы, ряды, страницы, библиотека компонентов и имя KUIPS. 16 октября 2026 года KUIPS переехал в свой репозиторий с
версией 0.9.0. Версия 1.0.0 работает в любом проекте. Изменения — в [CHANGELOG.md](CHANGELOG.md).
<a name="ru-9"></a>
### 9. Благодарности и лицензия
MIT © 2026 Николай Кривуша (KOT KRINIK). Кадры снимает [Playwright](https://playwright.dev) (Apache-2.0). Проект ведётся
по [KAIF](https://github.com/MikalaiKryvusha/KAIF) — фреймворку автора для работы с ИИ-агентами.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues