| name | oceanbase-figma-code-connect |
| internal | true |
| description | Incrementally create or update Figma Code Connect mappings in packages/**/index.figma.tsx. Use when the user mentions Code Connect, index.figma.tsx, Figma Dev Mode snippets, design-to-code mapping, or publishing component connections for @oceanbase/design / @oceanbase/ui. |
Figma Code Connect (OceanBase Design)
When to use this skill
- User asks to update / fix / add Code Connect for a component (e.g. "同步 Alert 的 Figma 映射").
- Figma component properties changed (new variant, renamed layer).
- New in-scope component needs its first
index.figma.tsx.
Do not bulk-rewrite all 38 mappings unless explicitly asked. One component per task (incremental).
Source of truth
There is no sources/ or generate step. Edit the colocated file in packages/.
Agent workflow (incremental update)
1. Scope one component
Identify target directory, e.g. alert → packages/design/src/alert/index.figma.tsx.
If the file exists, read it first and apply minimal diff. If missing, copy structure from a similar component (e.g. skeleton for simple, breadcrumb for multi-connect).
2. Gather context
| Need | Tool |
|---|
| OB component props | ob-design info <Component> or MCP ob_info |
| Figma property names / types | Figma MCP get_context_for_code_connect (see CONVENTIONS.md) |
| Existing patterns | Read sibling index.figma.tsx in repo |
| Draft scaffold | npx @figma/code-connect connect create "<figma-url>" --outFile ... (then refine) |
3. Edit mapping
- Import from
@oceanbase/design / @oceanbase/ui / @oceanbase/icons only.
- Use
figma.connect(RealComponent, '<FIGMA_OCEANBASE_*>' | url, { props, example }).
- New
<FIGMA_*> placeholder → add to figma.config.json documentUrlSubstitutions.
- Follow CONVENTIONS.md (no style/className in mapping, Figma typo values, etc.).
4. Validate (single file first)
pnpm run figma:parse:file -- packages/design/src/alert/index.figma.tsx
Fix until exit code 0. Then optional full check:
pnpm run figma:parse
5. Config housekeeping (only if needed)
pnpm run figma:sync-include
6. Publish (human / maintainer with token)
pnpm run figma:publish:dry-run
pnpm run figma:publish
Requires .cursor/skills/figma-code-connect/.env (FIGMA_ACCESS_TOKEN, FIGMA_FILE_KEY).
Commands (repo root)
pnpm run figma:sync-include
pnpm run figma:parse
pnpm run figma:publish:dry-run
pnpm run figma:publish
In-scope components (38)
design: alert, badge, breadcrumb, button, card, checkbox, date-picker, descriptions, divider, drawer, dropdown, empty, filter, form, input, input-number, menu, message, modal, notification, pagination, popconfirm, progress, radio, result, segmented, select, skeleton, spin, steps, switch, table, tabs, tag, tooltip, upload.
ui: FooterToolbar, PageContainer.
Out of scope: packages/icons icon matrix (separate effort).
Minimal example (single connect)
See packages/design/src/alert/index.figma.tsx:
figma.connect(Alert, '<FIGMA_OCEANBASE_ALERT>', {
props: {
type: figma.enum('type', {
info: 'info',
warning: 'warning',
success: 'success',
error: 'error',
}),
message: figma.textContent('Text'),
},
example: ({ type, message }) => <Alert type={type} message={message} />,
});
PR merge gate
- Only touched component(s)'
index.figma.tsx (+ figma.config.json if placeholders changed).
pnpm run figma:parse passes.pnpm build no regression.
Anti-patterns
- Editing all mappings in one PR without request.
- Copying from
antd Code Connect examples.
- Putting layout/preview styles in
props instead of component API props.
- Forgetting
documentUrlSubstitutions for new <FIGMA_*> keys.
- Running
figma:publish without local figma:parse success.
