From 44edfd6aad2f19f5cd98206b271b779a99132cbd Mon Sep 17 00:00:00 2001 From: Alesya Volosach Date: Thu, 13 Aug 2026 15:52:30 +0300 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=20=D0=BD=D0=B0=D0=B2=D1=8B=D0=BA=20UI=20Kit?= =?UTF-8?q?=20Figma?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/ui-kit-figma/SKILL.md | 81 +++++++++++++++++++ .../skills/ui-kit-figma/agents/openai.yaml | 6 ++ .agents/skills/ui-kit-testing/SKILL.md | 18 +++-- .../references/test-authoring.md | 13 +-- AGENTS.md | 7 +- 5 files changed, 113 insertions(+), 12 deletions(-) create mode 100644 .agents/skills/ui-kit-figma/SKILL.md create mode 100644 .agents/skills/ui-kit-figma/agents/openai.yaml diff --git a/.agents/skills/ui-kit-figma/SKILL.md b/.agents/skills/ui-kit-figma/SKILL.md new file mode 100644 index 00000000..bc19baca --- /dev/null +++ b/.agents/skills/ui-kit-figma/SKILL.md @@ -0,0 +1,81 @@ +--- +name: ui-kit-figma +description: > + Implement or sync React Native Prime UI Kit components from Figma + specifications. Use when a Figma node is provided, or when component variants, + local theme-token bindings, documentation links, or Storybook states must be + aligned with Figma. This is read-only toward Figma. +--- + +# UI Kit Figma + +Translate Figma component specifications into this repository's public API, +Unistyles implementation, local tokens, tests, and Storybook conventions. Use +the Figma design-to-code skill for tool workflow and `ui-kit-testing` when tests +change. + +## Workflow + +1. Inspect the component source, public types and barrels, nearest tests and + stories, and relevant files under `src/theme/tokens`. +2. Call Figma design context on the exact component or variant frame. If a page + or section returns sparse context, use metadata only to locate the inner + frame, then call design context on that frame. +3. Read variable definitions for the target frame and map each relevant Figma + variable to the existing runtime theme path. +4. Implement the smallest compatible source change, following the nearest + component pattern and root `AGENTS.md`. +5. Update focused behavioral tests and representative Storybook scenarios when + the public contract or material variants change. +6. Update the component documentation link when its exact Figma frame is known. +7. Run the verification required by root `AGENTS.md`. + +## Token Mapping + +- Treat Figma variable bindings as the source of token intent. Treat resolved + pixel and color values as inspection data, not values to copy into source. +- Reuse tokens from `src/theme/tokens`; do not hardcode a resolved value when a + matching local token exists. +- Prefer a component token when Figma explicitly binds the property to that + component variable. Use a semantic token only when the design intent is + semantic or no component binding exists. +- Do not edit generated token JSON or token-generator output unless the user + explicitly includes token-source changes in scope. +- Do not silently replace a missing component token with an approximate semantic + token. Report the gap and distinguish a component implementation change from a + token-source change. +- Apply severity, size, state, and theme bindings to every affected layer, not + only the outer container. Check text, background, border, icon, and shape + tokens independently. + +## Documentation Links + +- Link a component to its exact Figma component or variant frame, not merely the + file, page, or broad section containing it. +- In a bulk link update, inventory the component documentation first. Update + only confidently matched frames and keep unresolved components explicit. +- Before a requested commit, report updated links first and unresolved links + second. Commit only when the user explicitly asks. + +## Storybook + +- Model independently meaningful usage scenarios and interactions. Use controls + for simple variant axes that do not need dedicated documentation. +- Create separate stories or a composed comparison only when the scenario or + comparison itself adds documentation value. Do not impose a fixed number or + layout of stories per component. +- Keep every story's props valid for discriminated unions. Do not expose a + control that can create an invalid prop combination. +- Hide non-editable or internally composed props with + `parameters.controls.exclude`. Do not use `control: false` with React Native + on-device controls because it renders as `Invalid type`. +- Prefer `.tsx` when a story needs JSX composition. If an existing `.ts` file + must remain `.ts`, use `createElement` and construct typed discriminated props + before passing them to the component. + +## Tests + +Use `ui-kit-testing`. Assert rendered data, interaction logic, callbacks, +controlled behavior, accessibility, and public contracts. Do not assert exact +theme-token values, dimensions, colors, or style objects to prove a Figma +mapping. diff --git a/.agents/skills/ui-kit-figma/agents/openai.yaml b/.agents/skills/ui-kit-figma/agents/openai.yaml new file mode 100644 index 00000000..d5c000d2 --- /dev/null +++ b/.agents/skills/ui-kit-figma/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: 'UI Kit Figma' + short_description: 'Sync UI Kit components from Figma tokens' + default_prompt: + 'Use $ui-kit-figma to implement or sync a UI Kit component from its Figma + specification.' diff --git a/.agents/skills/ui-kit-testing/SKILL.md b/.agents/skills/ui-kit-testing/SKILL.md index 7f89c652..31ef73ae 100644 --- a/.agents/skills/ui-kit-testing/SKILL.md +++ b/.agents/skills/ui-kit-testing/SKILL.md @@ -2,9 +2,8 @@ name: ui-kit-testing description: > Write or refactor React Native Prime UI Kit Jest and RNTL tests for - components, hooks, controlled behavior, timers, animations, snapshots, - accessibility, and public TypeScript contracts. Do not use for whole-suite - audits + components, hooks, controlled behavior, timers, animations, accessibility, and + public TypeScript contracts. Do not use for whole-suite audits --- # UI Kit Testing @@ -18,8 +17,8 @@ inspect the implementation and nearest tests before choosing helpers or mocks. 1. Search existing tests and Jest setup before adding a helper, mock, provider, timer utility, or console suppression 2. Load only the references required by the test: - - test cases, render helpers, selectors, accessibility, snapshots, types, or - naming: `references/test-authoring.md` + - test cases, render helpers, selectors, accessibility, types, or naming: + `references/test-authoring.md` - child, external, native, animated, or console mocks: `references/mocks-and-native-ui.md` - timers, debounce, animations, delayed updates, or manual promises: @@ -34,6 +33,15 @@ inspect the implementation and nearest tests before choosing helpers or mocks. 5. Before finishing, remove avoidable mocks, oversized helpers, redundant waits, and assertions that do not prove the public contract +## Assertion Boundaries + +- Assert rendered data, presence or absence, callbacks, controlled behavior, + accessibility, and public contracts +- Do not assert exact colors, dimensions, theme-token values, or style objects +- Do not add or update snapshots to verify component appearance or structure. + Replace affected visual snapshots with explicit behavioral assertions +- Use the normal build to validate public TypeScript contracts and token access + ## Verification Run focused Jest and the applicable build or lint checks from `AGENTS.md`. diff --git a/.agents/skills/ui-kit-testing/references/test-authoring.md b/.agents/skills/ui-kit-testing/references/test-authoring.md index a8de0471..726bb857 100644 --- a/.agents/skills/ui-kit-testing/references/test-authoring.md +++ b/.agents/skills/ui-kit-testing/references/test-authoring.md @@ -1,7 +1,8 @@ # Test Authoring Read this reference when creating or changing test cases, render helpers, -selectors, accessibility assertions, snapshots, public types, or test names. +selectors, accessibility assertions, public types, test names, or replacing +snapshots with behavioral assertions. ## Placement And Helpers @@ -37,7 +38,9 @@ normal build. ## Snapshots -Snapshot only small, stable output whose complete structure is the behavior. -Prefer explicit assertions for interaction, state, accessibility, layout, and -animations. Update snapshots only for intentional UI changes. Do not snapshot -mocked child trees, large style objects, or ordinary prop forwarding. +Do not add or update snapshots for component appearance, structure, styles, or +theme-token values. When a change invalidates a visual snapshot, replace it with +explicit assertions for rendered data, presence or absence, interaction, +controlled state, callbacks, or accessibility. Use a snapshot only when the user +explicitly requests one and the contract cannot be stated more clearly with +behavioral assertions. diff --git a/AGENTS.md b/AGENTS.md index e1dd105d..f3003419 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,8 +15,11 @@ Use only top-level skills under `.agents/skills/`; nested `vendor/` skills are source material, not runtime instructions. - Use `$ui-kit-testing` to write or refactor focused Jest/RNTL tests, including - controlled behavior, accessibility, mocks, timers, animations, snapshots, and - public TypeScript contracts. + controlled behavior, accessibility, mocks, timers, animations, and public + TypeScript contracts. +- Use `$ui-kit-figma` to implement or sync components from Figma, map design + variables to local theme tokens, and align material variants and Storybook + scenarios. - Use `$ui-kit-review` for diffs and local changes or explicit architecture, onboarding, test-suite, debt, health, agent-instruction, and diagnostic audits. It is read-only unless the user requests fixes. From 3fc16b6ffe7cdfd5cb8c3c3eb618245018af9ea7 Mon Sep 17 00:00:00 2001 From: Alesya Volosach Date: Fri, 14 Aug 2026 11:03:59 +0300 Subject: [PATCH 2/3] =?UTF-8?q?docs(skill):=20=D0=B7=D0=B0=D0=BF=D1=80?= =?UTF-8?q?=D0=B5=D1=89=D0=B5=D0=BD=D0=BE=20=D0=B8=D0=B7=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D1=8F=D1=82=D1=8C=20=D1=84=D0=B0=D0=B9=D0=BB=D1=8B=20=D1=82?= =?UTF-8?q?=D0=BE=D0=BA=D0=B5=D0=BD=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/ui-kit-figma/SKILL.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/.agents/skills/ui-kit-figma/SKILL.md b/.agents/skills/ui-kit-figma/SKILL.md index bc19baca..56709c71 100644 --- a/.agents/skills/ui-kit-figma/SKILL.md +++ b/.agents/skills/ui-kit-figma/SKILL.md @@ -34,16 +34,18 @@ change. - Treat Figma variable bindings as the source of token intent. Treat resolved pixel and color values as inspection data, not values to copy into source. +- Treat `design-tokens/input/tokens.json` as the latest immutable export from + the designer. Never edit it during component or Figma synchronization work. +- Treat `src/theme/tokens/**` as immutable generated output. Never edit or + regenerate these files during component or Figma synchronization work. - Reuse tokens from `src/theme/tokens`; do not hardcode a resolved value when a matching local token exists. - Prefer a component token when Figma explicitly binds the property to that component variable. Use a semantic token only when the design intent is semantic or no component binding exists. -- Do not edit generated token JSON or token-generator output unless the user - explicitly includes token-source changes in scope. -- Do not silently replace a missing component token with an approximate semantic - token. Report the gap and distinguish a component implementation change from a - token-source change. +- If an exact Figma value has no matching existing token, do not hardcode it, + change token files, or silently substitute an approximate token. Report the + gap and explain which part cannot be matched exactly with the current tokens. - Apply severity, size, state, and theme bindings to every affected layer, not only the outer container. Check text, background, border, icon, and shape tokens independently. From 1147b0702e2d65d892efda1525661419733e15c5 Mon Sep 17 00:00:00 2001 From: Alesya Volosach Date: Thu, 13 Aug 2026 16:08:14 +0300 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20=D0=B7=D0=B0=D0=BA=D1=80=D0=B5?= =?UTF-8?q?=D0=BF=D0=BB=D1=91=D0=BD=20=D1=80=D1=83=D1=81=D1=81=D0=BA=D0=B8?= =?UTF-8?q?=D0=B9=20=D1=8F=D0=B7=D1=8B=D0=BA=20=D1=81=D0=BE=D0=BE=D0=B1?= =?UTF-8?q?=D1=89=D0=B5=D0=BD=D0=B8=D0=B9=20=D0=BA=D0=BE=D0=BC=D0=BC=D0=B8?= =?UTF-8?q?=D1=82=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index f3003419..5ec527aa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,7 +52,8 @@ Do not load every skill preemptively; use the one matching the request. ## Git Do not commit or push unless explicitly asked. Use Conventional Commits for -requested commits. +requested commits. Keep the conventional type and optional scope in English; +write the commit subject in Russian. ## Safety