Документация Maketa

Maketa — конструктор экранов приложений и лендингов. Рисуете мышкой, делитесь ссылкой вместо ТЗ. А ещё — программно: ИИ и код читают и меняют каждый объект, а экраны Flutter выгружаются в макет автоматически.

Эта страница — для тех, кто интегрируется с Maketa: разработчиков, ИИ-агентов и любопытных. Просто порисовать можно в редакторе без всякой документации.

Быстрый старт

1. Откройте редактор и нарисуйте экран (или вставьте скриншот через Ctrl/⌘+V).
2. Нажмите «🔗 Поделиться» — макет сохранится на сервере, появятся ссылки на просмотр и редактирование.
3. Чтобы подключить ИИ или код — там же откройте «🔑 Ключи для ИИ и кода» и создайте проектный ключ.
4. Дальше: MCP-сервер для ИИ или maketa_sync для Flutter.

Аккаунт не обязателен, но с ним макеты собираются в «Мои макеты» и не теряются. Клиенты demda.pro входят той же учётной записью — вкладка «Клиент demda» в окне входа.

Основные понятия

Доска (проект) и экраны

Доска — единица хранения (один макет). В ней несколько экранов. Модель сцены — наш собственный JSON maketa.board.v1, единый источник истины для редактора, ИИ и нативных клиентов.

Экраны «из кода» и «дизайн»

Ветки

У code-экрана нельзя менять объекты руками — но можно создать ветку: редактируемую design-копию, связанную с оригиналом (как в GitHub). Навигация двусторонняя: с оригинала — к веткам, из ветки — «← Оригинал». Когда код обновляется, ветки от старой версии помечаются «⚠ база обновилась». Всё дерево видно по кнопке «🌳 Дерево».

Проектные ключи

Проектный ключ (mk_pk_…) разрешает ИИ и коду пушить экраны в конкретную доску — без вашего пароля и сессии. Отдельно от ссылок просмотра/редактирования.

Создать в кабинете

В редакторе: «🔗 Поделиться» → «🔑 Ключи для ИИ и кода». Кнопка «Создать ключ» — ключ показывается один раз, скопируйте сразу. Там же список ключей и «Отозвать».

Или через API

curl -X POST https://maketa.pro/maketa/api/project/key \
  -H 'content-type: application/json' \
  -d '{"id":"BOARD_ID","edit":"EDIT_TOKEN","label":"CI"}'
# → {"key":"mk_pk_..."}

MCP-сервер (для ИИ)

MCP даёт нейросети (Claude, ChatGPT и др.) инструменты читать и менять объекты макета и синхронизировать экраны из кода. Два способа подключения:

1. Удалённый коннектор (как Figma) — рекомендуется

Добавьте в Claude (Settings → Connectors → Add custom connector) один URL:

https://maketa.pro/maketa/api/mcp

Claude откроет вход Maketa (OAuth 2.1) — авторизуйтесь единым аккаунтом (Maketa или клиент demda), подтвердите доступ. Дальше ИИ работает только с вашими досками — начните с maketa_list_boards. Ключи и токены прописывать не нужно, доступ отзывается в аккаунте. Тот же URL работает и в других ИИ с поддержкой MCP.

2. Локальный сервер (stdio) — для CI и своих сценариев

Zero-dependency файл на Node ≥18 — tools/maketa-mcp/maketa-mcp.mjs, конфигурируется env (доска + токены + проектный ключ).

Инструменты

Подключение (Claude Code / Desktop)

{
  "mcpServers": {
    "maketa": {
      "command": "node",
      "args": ["/path/to/tools/maketa-mcp/maketa-mcp.mjs"],
      "env": {
        "MAKETA_BOARD": "BOARD_ID",
        "MAKETA_EDIT":  "EDIT_TOKEN",
        "MAKETA_PKEY":  "mk_pk_..."
      }
    }
  }
}

Правка code-экранов запрещена (источник — код) — ИИ делает maketa_branch_screen и правит ветку-предложение.

3. Headless — без OAuth и браузера

Тот же URL принимает вместо OAuth-токена ключи напрямую: Authorization: Bearer mk_pk_… (проектный ключ — инструменты в рамках своей доски, boardId обязателен) или Bearer mk_sb_… (песочный ключ агента — в рамках досок песочницы). Ключ принимается и в заголовке x-maketa-key.

Автономные агенты

Автономный ИИ-агент проходит путь «регистрация → доска → экран → ссылка → повторное чтение» без человека. «Без регистрации» на лендинге относится к браузеру; агенту нужен песочный ключ — он выдаётся мгновенно, без почты и оплаты.

Полная машиночитаемая схема всех ручек и ошибок — /openapi.json (OpenAPI 3.1).

Путь агента (curl)

# 1. Регистрация (лимит 3/сутки с IP; ключ показывается один раз, живёт 14 дней)
curl -s -X POST https://maketa.pro/maketa/api/agent/register \
  -H 'content-type: application/json' \
  -d '{"name":"my-agent","purpose":"макет для клиента"}'
# → {"key":"mk_sb_…","expiresAt":…,"quotas":{"boards":5,"savesPerDay":200},…}

# 2. Создать доску (доска привязывается к ключу)
curl -s -X POST https://maketa.pro/maketa/api/create \
  -H 'content-type: application/json' -H 'x-maketa-key: mk_sb_…' \
  -d '{"doc":{"name":"Демо","screens":[{"id":"s_1","name":"Главная","device":"iphone-15","w":390,"h":844,"bg":"#FFFFFF","objects":[]}]}}'
# → {"id":"BOARD_ID","edit":"…","view":"…"}

# 3. Сохранить экран с объектами (edit-токен не нужен — своя доска по ключу)
curl -s -X POST https://maketa.pro/maketa/api/save \
  -H 'content-type: application/json' -H 'x-maketa-key: mk_sb_…' \
  -d '{"id":"BOARD_ID","doc":{"name":"Демо","screens":[{"id":"s_1","name":"Главная","w":390,"h":844,"bg":"#FFFFFF","objects":[
    {"id":"o_1","type":"rect","x":20,"y":40,"w":350,"h":120,"fill":"#EEF1F6","radius":16},
    {"id":"o_2","type":"text","x":36,"y":64,"text":"Привет!","fontSize":24,"weight":700},
    {"id":"o_3","type":"ellipse","x":300,"y":700,"w":56,"h":56,"fill":"#3A5BD9"}]}]}}'

# 4. Ссылка для людей: https://maketa.pro/app/?b=BOARD_ID
# 5. Чтение: curl -s 'https://maketa.pro/maketa/api/load?id=BOARD_ID'
# Свои доски: GET /agent/boards; сверка ревизии: GET /rev?id=BOARD_ID

Квоты и ошибки

Каждая ошибка API несёт машинный код error и русскую подсказку hint — агент понимает, что делать дальше, без чтения документации.

Политика времени жизни

• Песочный ключ — 14 дней; квоты: 5 досок, 200 сохранений/сутки. ИИ-функции (/ai/*) и оплата песочному ключу недоступны.
• Доски песочницы живут, пока жив ключ, плюс 30 дней; затем удаляются (навсегда, ответ 410). Доска, которую забрал живой аккаунт, становится обычной и не удаляется.
• Повышение до постоянного доступа — проектный ключ mk_pk_: его выдаёт владелец доски в кабинете, он не истекает, пока не отозван.
• Доски по заданиям студии demda.pro при миграциях сохраняются.

Flutter · maketa_sync

Dev-пакет maketa_sync обходит render-дерево текущего экрана Flutter и пушит его в Maketa как code-экран — каждый виджет отдельным объектом (не скриншот).

Подключение

# pubspec.yaml
dependencies:
  maketa_sync:
    path: ../path/to/tools/maketa-sync-dart

final _sync = MaketaSync(
  apiBase: 'https://maketa.pro/maketa/api',
  boardId: const String.fromEnvironment('MAKETA_BOARD'),
  projectKey: const String.fromEnvironment('MAKETA_PKEY'),
);

// на корне экрана:
KeyedSubtree(key: _sync.rootKey, child: MyScreen());

// пуш (dev-кнопка / хоткей / хук на hot-reload):
await _sync.capture(screenKey: '/search', name: 'Поиск', route: '/search');

flutter run \
  --dart-define=MAKETA_BOARD=BOARD_ID \
  --dart-define=MAKETA_PKEY=mk_pk_...

Таблица соответствий

Работает на Android и iOS. Для Flutter Web (dart:io недоступен) — см. Веб-приложения.

Веб-приложения

Для веба Flutter не нужен — большинство сайтов нативные (React, Vue, обычный DOM). maketa-sync-web — небольшой JS без сборки: обходит DOM и getComputedStyle, превращает элементы в объекты maketa.board.v1 и пушит тем же /screen/push по проектному ключу (CORS разрешён).

<script src="https://maketa.pro/maketa-sync-web.js"></script>
<script>
  MaketaSyncWeb.push({
    boardId: 'BOARD_ID', projectKey: 'mk_pk_...',
    screenKey: location.pathname, name: document.title
  });
</script>

Или букмарклетом — на любом своём экране одним кликом. Круглые элементы → ellipse, текст → text, картинки → плейсхолдер. Подробнее — tools/maketa-sync-web/README.md.

REST API

База: https://maketa.pro/maketa/api. Ответы — JSON. Доступ к доске — по токенам edit/view (из ссылки «Поделиться») или проектному ключу (заголовок x-maketa-key).

Доски

Автономные агенты

Полная схема запросов, ответов и ошибок ({error, hint}, 410 для удалённого) — /openapi.json.

Экраны из кода и ветки

curl -X POST https://maketa.pro/maketa/api/screen/push \
  -H 'content-type: application/json' \
  -H 'x-maketa-key: mk_pk_...' \
  -d '{"id":"BOARD_ID","key":"/search",
       "screen":{"name":"Поиск","w":390,"h":844,"bg":"#F4F4EF","objects":[...]},
       "meta":{"route":"/search","commit":"abc","method":"widget-tree"}}'
# → {"ok":true,"screenId":"s_...","version":1}

Проектные ключи

Лимиты: сцена ≤ 12 МБ, ≤ 200 экранов, ≤ 4000 объектов на экран. Есть rate-limit.

window.Maketa (в редакторе)

В открытом редакторе доступен объект window.Maketa — им пользуются встроенные ИИ-сценарии и автотесты. Основное:

Maketa.getDocument()            // вся сцена board.v1
Maketa.setDocument(doc)         // заменить сцену
Maketa.listScreens()            // [{id,name,kind,locked,parentId,branches,...}]
Maketa.setActiveScreen(id)
Maketa.createScreen(name, dev)  // → screenId
Maketa.branchScreen(id)         // ветка экрана
Maketa.listElements(screenId)   // объекты экрана
Maketa.addElement(spec [,sid])  // → elementId (на code-экране → null)
Maketa.updateElement(id, patch)
Maketa.moveElement(id, x, y)
Maketa.removeElement(id)
Maketa.exportPNG()

Модель maketa.board.v1

{
  "screens": [{
    "id": "s_home", "name": "Главная",
    "device": "iphone-15", "w": 390, "h": 844, "bg": "#FFFFFF",
    "kind": "design",              // design | code
    "locked": false,
    "parentId": null,              // id родителя, если это ветка
    "branches": [],                // id веток (двусторонняя связь)
    "objects": [
      {"id":"o_1","type":"rect","x":20,"y":40,"w":120,"h":70,
       "fill":"#3A5BD9","radius":12,"stroke":"none","rot":0},
      {"id":"o_2","type":"text","x":20,"y":120,"text":"Привет",
       "fontSize":20,"color":"#111827","weight":600},
      {"id":"o_3","type":"ellipse","x":300,"y":40,"w":48,"h":48,"fill":"#EEE"},
      {"id":"o_4","type":"tabs","x":0,"y":782,"w":390,"h":62,"active":0,
       "bg":"#FFFFFF","color":"#3A5BD9","muted":"#B7BECC",
       "items":[{"text":"Главная","icon":"🏠"},{"text":"Профиль","icon":"👤","link":"s_profile"}]}
    ]
  }]
}

Координаты абсолютные (px), начало — верхний-левый угол экрана. Цвета — hex или none. Общие поля любого объекта: id, x, y, rot (градусы), opacity (0–1), group (id логического блока — так группируются кнопка, карточка, пункт меню), locked, link (id экрана-цели — переход в режиме прототипа).

Для ИИ-агентов

Если вы ИИ и нашли эту страницу: Maketa — программируемый конструктор экранов. Вы можете:

• Работать полностью автономно: песочный ключ через POST /agent/register — без человека, почты и оплаты.
• Подключиться MCP-сервером (OAuth или headless по ключу) и вызывать инструменты maketa_*.
• Ходить прямо в REST API — схема /openapi.json; постоянный проектный ключ выдаёт владелец доски в кабинете.
• Читать и писать сцену в модели maketa.board.v1.

Краткая машиночитаемая сводка — /llms.txt, подробная — /llms-full.txt. Правило: code-экраны не редактируются напрямую — создавайте ветку.

Поддержка

Вопросы, доступ к проектам, нативный веб-адаптер: Telegram @demda · сайт студии demda.pro.

Maketa — продукт студии заказной разработки demda.pro. Нужен не только макет, а готовое приложение — приходите к нам.