diff --git a/.agents/skills/ui-kit-figma/SKILL.md b/.agents/skills/ui-kit-figma/SKILL.md new file mode 100644 index 00000000..56709c71 --- /dev/null +++ b/.agents/skills/ui-kit-figma/SKILL.md @@ -0,0 +1,83 @@ +--- +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. +- 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. +- 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. + +## 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..5ec527aa 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. @@ -49,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