| name | sfnext-create-figma-kit |
| description | Build or sync a Storefront Next vertical's Figma design kit — duplicate the official kit, update Brand variable collections from brand.css, edit components at the correct layer, and publish Figma Code Connect mappings. Use when asked to set up, duplicate, or sync a Figma kit, update Figma brand variables, or keep design and code tokens aligned. Requires the Figma MCP server. |
Create a Figma Kit Skill
This skill is the entrypoint for setting up or syncing the Figma design kit for a Storefront Next vertical, so the kit stays aligned with the brand tokens defined in code.
It is the design-kit companion to sfnext-create-vertical (in the storefront-next plugin): create or change the brand tokens in code first, then run this skill to mirror them in Figma.
Step 0 — Verify prerequisites (required)
This workflow uses the Figma MCP server. Before proceeding, confirm:
If the Figma MCP server is not connected, stop here. Configure it (see your IDE's MCP docs), then return to this skill.
Getting a node-id: in Figma, right-click any frame or component → Copy/Paste as → Copy link. The URL contains node-id=<value>.
Source kit
Duplicate the official Storefront Next Design System community kit:
https://www.figma.com/community/file/1646023293012114166
Open the community file in Figma and use Open in Figma → Duplicate to copy it into your own drafts, then move it into your team project. Record the new file key in your project's design-system notes (e.g. docs/design-system/FIGMA_FILE_KEYS.md) so the mapping is reproducible.
Workflow
Phase 1 — Duplicate the official kit
Do this in Figma (API duplication needs elevated OAuth scopes):
- Open the official kit.
- File menu → Duplicate to your drafts.
- Move the duplicate into the correct team project.
- Rename it:
Storefront NEXT — [Vertical Name].
- Copy the new file key from the URL (
figma.com/design/<FILE_KEY>/...) and record it.
Phase 2 — Update variable collections (tokens first)
Update only the Brand collection values to match src/theme/tokens/brand.css. Do not edit Semantic/Core values directly — they alias the Brand values.
CSS variable (brand.css) | Figma variable |
|---|
--brand-black | Brand / black |
--brand-white | Brand / white |
--brand-gray-50 … --brand-gray-950 | Brand / gray-* |
--brand-primary | Brand / primary |
Non-negotiable color rule: all fills/strokes/effects bind to variables. No raw hex/RGB. If no existing variable fits, stop, document the node and reason, propose a name/value, and get approval before creating it. See Figma Component Editing Reference.
Phase 3 — Typography
If the vertical uses custom fonts, update the text styles (text/body, text/label, text/heading) and make sure the fonts are available via the Figma Font Service or uploaded custom fonts.
Phase 4 — Component edits at the correct layer
When a component needs to change, edit at the right layer and respect the instance/component boundary — you cannot append children to an instance; edit the source component. See Figma Component Editing Reference for the layer table and the extend-before-create rule, and Vertical → Figma Kit Sync Reference for tracing code changes to the right Figma node.
Phase 5 — Code Connect
Maintain .figma.ts mappings for components and publish them after changes.
import { figma } from '@figma/code-connect'
import { ComponentName } from './<component>'
figma.connect(ComponentName, 'FIGMA_FILE_URL', {
props: {
variant: figma.enum('Variant', {
default: 'default',
secondary: 'secondary',
}),
},
example: ({ variant }) => <ComponentName variant={variant} />,
})
Replace FIGMA_FILE_URL with the full Figma URL including node-id, then publish:
FIGMA_ACCESS_TOKEN=<your-token> npx figma connect publish
Phase 6 — Publish and maintain
- Publish the Figma library.
- Notify the design team to accept updates.
Ongoing: token change in brand.css → update Brand variables → republish. Component prop/variant change → update .figma.ts → republish Code Connect.
Execution modes
- Assisted (Figma MCP automation): validate target nodes before mutation (component vs instance), apply one logical batch at a time (tokens → logo → components), screenshot after each batch, keep every color operation variable-bound. Best for bulk token updates and repeated component edits.
- Manual: use this workflow as a checklist while editing directly in Figma; keep a change log (file key · pages/components changed · variables touched · publish timestamp); run Code Connect publish from the terminal. Best for one-off or design-led sessions without MCP access.
Required outcomes
- Vertical Figma file duplicated, renamed, and its key recorded.
- Brand variables synced from
src/theme/tokens/brand.css; no detached hex/RGB.
- Source component edits propagate to instances (verified by screenshot).
- Code Connect mappings updated and published when components changed.
- Library republished and announced to the design team.
Verification
If you changed .figma.ts mappings or component code as part of the sync, run from the monorepo root:
pnpm typecheck
pnpm lint
pnpm test-storybook:snapshot:agent
All three must pass with zero errors and zero warnings.
Related Skills
storefront-next:sfnext-create-vertical - Define the brand tokens in code (run this first)storefront-next:sfnext-create-component - Author the React component a Code Connect mapping points to
Reference Documentation
