Анатомія CONTEXT.md — Специфікація, яку агент читає першою

Кожен експорт figmascope починається з .zip, що містить сім артефактів. CONTEXT.md читається першим — навмисно. Це не README. Це не згенерована документація. Це компіляторний контракт між дизайном та агентом, який перетворить його на код.

У цій статті ми розберемо, що в ньому є, чому він структурований саме так і що відбувається, якщо його пропустити.

Чим контракт відрізняється від документації

Документація описує те, що існує. Контракт визначає те, що має бути правдою. Ця різниця має значення, коли вашим читачем є LLM, який із задоволенням вигадає значення відступів, сплощить ієрархію макета або захардкодить hex-кольори, щойно не матиме кращого варіанту.

CONTEXT.md починається з оголошення цільової платформи:

# CONTEXT.md — Jetpack Compose target

This file is the authoritative spec for generating UI code from this bundle.
Read it before reading any other file.

"Jetpack Compose target" — не декорація. Агент використовує її для вибору примітивів composable, роботи з одиницями dp/sp, розуміння того, що Modifier.padding() є правильною абстракцією для відступів, а Box із Alignment — для overlay-макетів. Цільова платформа React/Tailwind генерує інший CONTEXT.md з іншими примітивами.

Інструкція "читайте це першим" теж навмисна. Агенти обробляють контекст послідовно. Якщо правило токена з'явиться після того, як агент уже почав розмірковувати про компонент, обмеження прийде надто пізно. Контракт на початку означає, що правила активні з першого токена генерації.

Розділ жорстких обмежень

Найважливіша частина CONTEXT.md — блок обмежень:

## Strict constraints (must follow)

- Never hardcode dp values if a token exists within ±2dp
- Never flatten layout hierarchy — preserve every stack/overlay/absolute node
- Use stringRef values from strings.json, never inline literal text
- Treat missing fields as absent, not zero
- Do not invent component names not present in components/inventory.json

Кожне обмеження існує тому, що ми бачили, як агенти його порушують. Правило ±2dp — найнаочніший приклад. Без нього агент, зустрівши gap: 14 у вузлі стека, напише Arrangement.spacedBy(14.dp). З правилом він перевіряє, чи spacing.16 або spacing.12 потрапляє в межі 2dp, і використовує токен. Це різний результат: той, що залишається коректним при зміні значення токена, без пошуку-заміни по всій кодовій базі.

Правило ієрархії існує тому, що Compose — це дерево макетів. Коли агент сплощує вкладений стек у плоский список позиційованих елементів, він руйнує адаптивну поведінку, закладену в початкову структуру. IR зберігає кожен рівень вкладеності з причини — дивіться Per-Screen IR — Stack, Overlay, Absolute, Leaf, щоб зрозуміти, як вкладеність кодує наміри макета.

Обмеження — це не "використовуй токени, якщо хочеш". Це "ніколи не хардкоди, якщо токен існує". Це заборона, а не рекомендація. LLM реагують на заборони інакше, ніж на рекомендації.

Правило stringRef важливе для i18n. Якщо агент вставить рядковий літерал "Speed Test" замість посилання на ключ ресурсу, ви отримаєте діру в локалізації. Обмеження явно вказує агенту на strings.json.

Як агент читає CONTEXT.md послідовно

Контекстне вікно LLM обробляє токени зліва направо. Структура CONTEXT.md використовує це. Порядок такий:

1. Оголошення цільової платформи (задає весь фрейм генерації)
2. Жорсткі обмеження (заборони, що діють для кожного рішення)
3. Карта бандлу (які файли існують і що в кожному)
4. Правила використання токенів (як розв'язувати відступи, кольори, радіуси, типографіку)
5. Примітки щодо обсягу (чесні прогалини — що цей бандл покриває, а що ні)

Розділ карти бандлу вказує агенту, які файли читати і в якому порядку:

## Bundle contents

- tokens.json — design tokens (spacing, radius, color, typography)
- screens/*.json — per-screen IR in stack/overlay/absolute/leaf format
- components/inventory.json — component identity list
- strings.json — i18n resource keys
- _meta.json — generation metadata and warnings

Без цієї карти агент може не знати, що components/inventory.json існує, або вважати _meta.json основною специфікацією. Явне перерахування задає порядок читання.

Примітки щодо обсягу — що версія v0.4 чесно не охоплює

Розділ приміток щодо обсягу — місце, де figmascope документує власні обмеження. Це навмисне і не підлягає обговоренню. Агент, який не знає, що специфікація неповна, впевнено заповнить прогалини вигадками. Це гірше, ніж знати про прогалину.

## Scope notes (v0.4)

- Gradient fills are not supported. Nodes with gradient fills emit a warning
  in _meta.json under warnings. Treat as a solid fill approximation or TODO.
- Typography tokens require Figma Variables to be populated. If tokensSource
  is "inferred-from-frequency" or "none", typography coverage may be partial.
- This bundle covers UI structure only. Navigation, state management,
  and network calls are outside scope.
- Component instances are identified by componentId. Full component
  source props are not included — the inventory gives identity, not implementation.

Попередження про градієнти особливо важливе. Figma підтримує складні градієнтні заливки, для яких немає прямого еквівалента в Compose без спеціального рендерингу. Замість того, щоб мовчки прибирати градієнти або генерувати зламаний код, figmascope емітує попередження background-gradient-not-supported:<name> у _meta.json і зазначає це тут, щоб агент знав: це відома прогалина, а не помилка у власному виводі.

Примітка про типографіку пов'язана з полем tokensSource у _meta.json. Коли у файлі Figma немає Variables, figmascope виводить токени за частотністю — поширені значення стають токенами, рідкісні — ні. Примітка повідомляє агенту, що цей вивід недосконалий і не слід припускати повного покриття типографіки. Дивіться tokens.json Explained, щоб зрозуміти, як працює резервний вивід.

Приклади WRONG / RIGHT

Зробимо це конкретним. Дано вузол стека з gap: 16 і файл токенів, що містить spacing.16: 16:

Без обмежень CONTEXT.md (WRONG):

Column(
    modifier = Modifier.padding(horizontal = 24.dp),
    verticalArrangement = Arrangement.spacedBy(16.dp)
) {

З обмеженнями CONTEXT.md (RIGHT):

Column(
    modifier = Modifier.padding(horizontal = Spacing.spacing24),
    verticalArrangement = Arrangement.spacedBy(Spacing.spacing16)
) {

Правильний результат посилається на токени. Коли дизайн-система змінює spacing.16 з 16dp на 14dp, код залишається коректним без пошуку-заміни по всій кодовій базі.

Інший приклад — обробка рядків. Дано листовий вузол з text: "Speed Test" і stringRef: "speed.test":

WRONG:

Text(text = "Speed Test")

RIGHT:

Text(text = stringResource(R.string.speed_test))

Обмеження вказує на strings.json, ключ — speed.test, агент знає, як відобразити нотацію з крапками на Android resource ID. Це можливо лише якщо агент прочитав обмеження до генерації компонента.

Навіщо не написати це в промпт самостійно?

Можна написати ці інструкції вручну у своєму промпті. figmascope виносить їх у файл з кількох причин:

• Обмеження похідні від реального бандлу. Правило ±2dp має сенс лише якщо tokens.json існує. CONTEXT.md генерується з урахуванням наявних токенів.
• Примітки щодо обсягу змінюються для кожного проєкту. Файл Figma з повним покриттям Variables отримає іншу примітку про типографіку, ніж файл з виведеними токенами.
• Файл є у zip-архіві. Можна посилатися на нього як на контекст без копіювання. Cursor, Claude Code та подібні інструменти підтримують @-посилання на файли.
• Він відтворюваний. Кожен експорт одного і того самого файлу Figma генерує той самий CONTEXT.md. Агент вашої команди читає той самий контракт щоразу.

Мета — не обходити стандартну поведінку агента через prompt engineering. Мета — надіслати специфікацію, яка робить стандартну поведінку неактуальною.

Порівняння зі структурними альтернативами

Dev Mode у Figma виводить розміри, змінні та фрагменти коду. Це не специфікація. Агент, що працює з виводом Dev Mode, змушений виводити правила з прикладів — а отже, виводитиме неправильні правила для крайніх випадків.

Locofy та подібні інструменти генерують код безпосередньо. У них немає аналога CONTEXT.md, бо вони не очікують, що агент читатиме специфікацію — вони самі є агентом. Це працює, коли генерація коду інструменту точно відповідає вашому стеку. Це не працює, коли у вас є специфічні конвенції іменування, власна бібліотека компонентів або дизайн-система з токенами, які інструмент не знає.

CONTEXT.md — це машиночитний дизайн-бриф. Це те, що існувало як сторінка Confluence або документ Notion у кожному передаванні дизайну до епохи LLM, просто структуроване для аудиторії, яка насправді дотримується правил.

Що з цим робити

Коли ви відкриваєте експорт figmascope у Cursor або Claude Code:

1. Додайте @CONTEXT.md до контексту перед будь-яким промптом про дизайн.
2. Посилайтесь на JSON екрану, з яким працюєте: @screens/home.json.
3. Якщо торкаєтеся токенів, додайте @tokens.json.
4. Якщо працюєте з рядками, додайте @strings.json.

Обмеження CONTEXT.md застосовуються до всієї сесії після завантаження. Їх не потрібно повторно додавати до кожного промпту — додайте один раз на початку і дайте їм задати фрейм для кожної наступної генерації.

Інші артефакти бандлу розглянуті в решті цієї серії. Почніть з tokens.json Explained, щоб дізнатися, як система токенів обробляє файли з Variables і без, або з Per-Screen IR, щоб зрозуміти, як макети Figma відображаються у вузли stack/overlay/absolute/leaf. Готові спробувати? Вставте URL Figma на figmascope.dev і експортуйте свій перший бандл.