AIOZ UI V3 — Figma MCP → Code Mapping Skill
This skill defines exactly how to translate Figma MCP output into production React code using the AIOZ UI V3 design system.
Rule #1: Never guess token names or class names. Always follow the mapping tables below.
How Figma MCP Returns Data
When the Figma MCP agent inspects a node, it returns values in these formats:
| Data Type |
Figma MCP Example |
Action |
| Color / fill |
Onsf/Error/Default, Sf/Pri/Pri |
→ Look up in references/colors.md |
| Typography |
Button/01, Body/02, Subheadline/01 |
→ Look up in references/typography.md |
| Icon layer |
icon/24px/outline/wallet-01 |
→ Look up in references/icons.md |
| Component name |
Button/Primary, Badge/Success, Fields/Default |
→ See Component Map below |
| Variant string |
Type=Primary, Size=Medium, Shape=Square |
→ See Variant → Prop Map below |
| Variable value |
"Onsf/Bra/Default": "#121212" |
Slash-path format, never CSS --var |
| Setup / config |
Project configuration questions |
→ Look up in references/setup.md |
⚠️ Figma MCP always returns token names with slash separators like Onsf/Error/Default.
It does NOT return CSS custom property format like --onsf-error-default.
⚠️ Two Import Paths — Never Mix Them
// Charts — @aioz-ui/core/components
import {
LineChart,
AreaChart,
BarChart,
DonutChart,
CustomLegend,
Separator,
useSeriesVisibility,
} from '@aioz-ui/core/components'
// All other UI components — @aioz-ui/core-v3/components
import {
Button,
Input,
Badge,
Table,
Header,
Body,
Row,
HeadCell,
Cell,
} from '@aioz-ui/core-v3/components'
// Icons — @aioz-ui/icon-react (always PascalCase + "Icon" suffix)
import { Search01Icon, Plus01Icon, Wallet01Icon } from '@aioz-ui/icon-react'
Component Map
Input: Figma MCP name field on a symbol/instance node
Output: React component to use
| Figma Node Name Pattern |
React Component |
Import |
Button/* |
Button |
import { Button } from '@aioz-ui/core-v3/components' |
Fields/* |
Input |
import { Input } from '@aioz-ui/core-v3/components' |
Badge/* |
Badge |
import { Badge } from '@aioz-ui/core-v3/components' |
Tag/* |
Tag |
import { Tag } from '@aioz-ui/core-v3/components' |
Card/* |
Card |
import { Card, CardContent, CardHeader, CardTitle, CardDescription } from '@aioz-ui/core-v3/components' |
Toggle/* |
Switch |
import { Switch } from '@aioz-ui/core-v3/components' |
Checkbox/* |
Checkbox |
import { Checkbox } from '@aioz-ui/core-v3/components' |
Tooltips/* |
Tooltip |
import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@aioz-ui/core-v3/components' |
Tabs/* |
Tabs |
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@aioz-ui/core-v3/components' |
Table/* |
Table |
import { Table, Header, Body, Row, HeadCell, Cell } from '@aioz-ui/core-v3/components' |
Separator/* |
Separator |
import { Separator } from '@aioz-ui/core-v3/components' |
Pagination item/* |
PaginationGroup |
import { PaginationGroup } from '@aioz-ui/core-v3/components' |
Progress bar/* |
Progress |
import { Progress } from '@aioz-ui/core-v3/components' |
Slider/* |
Slider |
import { Slider } from '@aioz-ui/core-v3/components' |
Upload file/* |
UploadFile |
import { UploadFile } from '@aioz-ui/core-v3/components' |
Menu item/* |
MenuItem |
import { MenuItem } from '@aioz-ui/core-v3/components' |
Dropdown item/* |
DropdownMenu |
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@aioz-ui/core-v3/components' |
Modal/* |
Dialog |
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter, DialogClose } from '@aioz-ui/core-v3/components' |
Block/* |
Block |
import { Block } from '@aioz-ui/core-v3/components' |
IconBadge/* |
IconBadge |
import { IconBadge } from '@aioz-ui/core-v3/components' |
Message/* |
Message |
import { Message } from '@aioz-ui/core-v3/components' |
Breadcrumb/* |
Breadcrumb |
import { Breadcrumb } from '@aioz-ui/core-v3/components' |
Date picker/* |
DatePicker |
import { DatePicker } from '@aioz-ui/core-v3/components' |
Variant → Prop Map
Figma MCP encodes variants as comma-separated Key=Value pairs in the node name:
"Type=Primary, Size=Medium, Icon Shape=Square, Danger=False, State=Hover"
| Figma Variant |
React Prop |
Notes |
Type=Primary |
variant="primary" |
|
Type=Secondary |
variant="secondary" |
|
Type=Neutral |
variant="neutral" |
|
Type=Text |
variant="text" |
|
Type=Danger / Danger=True |
variant="danger" |
|
Size=Large |
size="lg" |
|
Size=Medium |
size="md" |
|
Size=Small |
size="sm" |
|
Shape=Circle |
shape="circle" |
|
Shape=Square |
shape="square" |
|
Shape=Default |
shape="default" |
|
State=Default |
(no prop) |
Default render state |
State=Hover |
(no prop) |
CSS handles it |
State=Focused |
(no prop) |
CSS handles it |
State=Pressed |
(no prop) |
CSS handles it |
State=Disabled |
disabled |
|
State=Loading |
loading |
|
Icon> |
size="icon" |
Button only |
Full Translation Example
Given this Figma MCP output:
{
"name": "Type=Primary, Size=Medium, Icon Shape=Square, Danger=False, State=Default",
"fills": [{ "token": "Sf/Pri/Pri" }],
"textColor": "Onsf/Bra/Default",
"typography": "Button/01"
}
Translate to:
import { Button } from '@aioz-ui/core-v3/components'
;<Button variant="primary" size="md" shape="square">
Label
</Button>
Colors and typography are handled by Button internally. Apply color/typography classes manually only when building custom layouts outside of component primitives.
Core Rules
Token-first — Never use raw Tailwind colors or sizing.
❌ text-gray-500 bg-white border-gray-200 text-sm font-medium
✅ text-content-sec bg-sf-screen border-border-neutral text-body-02
Component-first — Use design system primitives over custom divs. See Component Map above.
Typography is atomic — Each text-* class already encodes font-size, line-height, weight, and font-family. Never stack additional font utilities on top.
Icons only from @aioz-ui/icon-react — Never SVG literals, emoji, or other libraries.
import { Search01Icon } from '@aioz-ui/icon-react'
;<Search01Icon size={16} className="text-icon-neutral" />
On-surface text — Text on a bg-sf-* surface must use the matching text-onsf-* class:
bg-sf-pri → text-onsf-text-pri
bg-sf-error-sec → text-onsf-text-error
bg-sf-neutral → text-onsf-text-neutral
Charts — Always import from @aioz-ui/core/components (not -v3). Always wrap in the card shell. Always provide both categories and overwriteCategories. Read references/charts.md before writing any chart code.
Reference Files
Open the relevant file for deep-dive API docs, full token lists, and component examples:
| File |
Open When |
references/colors.md |
Full token → Tailwind class tables for text, background, and border tokens |
references/typography.md |
Full text-* class list with font-size, weight, and line-height specs |
references/icons.md |
Icon name transformation rule, size guide, and common icon import list |
references/components.md |
Full props, all variants, and ready-to-use code examples for every component |
references/charts.md |
LineChart, AreaChart, BarChart, DonutChart — APIs, variants, legend, hidden-series |
1---2name: aioz-ui-v3-23description: Build UI components and pages using AIOZ UI V3 design system. Use this skill whenever the user wants to create, edit, or style React components using AIOZ UI tokens, Tailwind classes, color tokens, typography utilities, icons from @aioz-ui/icon-react, or chart components (LineChart, AreaChart, BarChart, DonutChart). Trigger on any task involving AIOZ UI components, design tokens like --sf-neu-block or --text-neu-bold, brand colors, typography classes (text-title-01, text-body-02), icon imports, data visualization, or translating Figma MCP output into production-ready code.4---56# AIOZ UI V3 — Figma MCP → Code Mapping Skill78This skill defines exactly how to translate **Figma MCP output** into production React code using the AIOZ UI V3 design system.910> **Rule #1:** Never guess token names or class names. Always follow the mapping tables below.1112---1314## How Figma MCP Returns Data1516When the Figma MCP agent inspects a node, it returns values in these formats:1718| Data Type | Figma MCP Example | Action |19| -------------- | --------------------------------------------------- | --------------------------------------- |20| Color / fill | `Onsf/Error/Default`, `Sf/Pri/Pri` | → Look up in `references/colors.md` |21| Typography | `Button/01`, `Body/02`, `Subheadline/01` | → Look up in `references/typography.md` |22| Icon layer | `icon/24px/outline/wallet-01` | → Look up in `references/icons.md` |23| Component name | `Button/Primary`, `Badge/Success`, `Fields/Default` | → See **Component Map** below |24| Variant string | `Type=Primary, Size=Medium, Shape=Square` | → See **Variant → Prop Map** below |25| Variable value | `"Onsf/Bra/Default": "#121212"` | Slash-path format, never CSS `--var` |26| Setup / config | Project configuration questions | → Look up in `references/setup.md` |2728> ⚠️ Figma MCP always returns token names with **slash separators** like `Onsf/Error/Default`.29> It does **NOT** return CSS custom property format like `--onsf-error-default`.3031---3233## ⚠️ Two Import Paths — Never Mix Them3435```tsx36// Charts — @aioz-ui/core/components37import {38 LineChart,39 AreaChart,40 BarChart,41 DonutChart,42 CustomLegend,43 Separator,44 useSeriesVisibility,45} from '@aioz-ui/core/components'4647// All other UI components — @aioz-ui/core-v3/components48import {49 Button,50 Input,51 Badge,52 Table,53 Header,54 Body,55 Row,56 HeadCell,57 Cell,58} from '@aioz-ui/core-v3/components'5960// Icons — @aioz-ui/icon-react (always PascalCase + "Icon" suffix)61import { Search01Icon, Plus01Icon, Wallet01Icon } from '@aioz-ui/icon-react'62```6364---6566## Component Map6768**Input:** Figma MCP `name` field on a symbol/instance node69**Output:** React component to use7071| Figma Node Name Pattern | React Component | Import |72| ----------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |73| `Button/*` | `Button` | `import { Button } from '@aioz-ui/core-v3/components'` |74| `Fields/*` | `Input` | `import { Input } from '@aioz-ui/core-v3/components'` |75| `Badge/*` | `Badge` | `import { Badge } from '@aioz-ui/core-v3/components'` |76| `Tag/*` | `Tag` | `import { Tag } from '@aioz-ui/core-v3/components'` |77| `Card/*` | `Card` | `import { Card, CardContent, CardHeader, CardTitle, CardDescription } from '@aioz-ui/core-v3/components'` |78| `Toggle/*` | `Switch` | `import { Switch } from '@aioz-ui/core-v3/components'` |79| `Checkbox/*` | `Checkbox` | `import { Checkbox } from '@aioz-ui/core-v3/components'` |80| `Tooltips/*` | `Tooltip` | `import { Tooltip, TooltipProvider, TooltipTrigger, TooltipContent } from '@aioz-ui/core-v3/components'` |81| `Tabs/*` | `Tabs` | `import { Tabs, TabsList, TabsTrigger, TabsContent } from '@aioz-ui/core-v3/components'` |82| `Table/*` | `Table` | `import { Table, Header, Body, Row, HeadCell, Cell } from '@aioz-ui/core-v3/components'` |83| `Separator/*` | `Separator` | `import { Separator } from '@aioz-ui/core-v3/components'` |84| `Pagination item/*` | `PaginationGroup` | `import { PaginationGroup } from '@aioz-ui/core-v3/components'` |85| `Progress bar/*` | `Progress` | `import { Progress } from '@aioz-ui/core-v3/components'` |86| `Slider/*` | `Slider` | `import { Slider } from '@aioz-ui/core-v3/components'` |87| `Upload file/*` | `UploadFile` | `import { UploadFile } from '@aioz-ui/core-v3/components'` |88| `Menu item/*` | `MenuItem` | `import { MenuItem } from '@aioz-ui/core-v3/components'` |89| `Dropdown item/*` | `DropdownMenu` | `import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@aioz-ui/core-v3/components'` |90| `Modal/*` | `Dialog` | `import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter, DialogClose } from '@aioz-ui/core-v3/components'` |91| `Block/*` | `Block` | `import { Block } from '@aioz-ui/core-v3/components'` |92| `IconBadge/*` | `IconBadge` | `import { IconBadge } from '@aioz-ui/core-v3/components'` |93| `Message/*` | `Message` | `import { Message } from '@aioz-ui/core-v3/components'` |94| `Breadcrumb/*` | `Breadcrumb` | `import { Breadcrumb } from '@aioz-ui/core-v3/components'` |95| `Date picker/*` | `DatePicker` | `import { DatePicker } from '@aioz-ui/core-v3/components'` |9697---9899## Variant → Prop Map100101Figma MCP encodes variants as comma-separated `Key=Value` pairs in the node name:102103```104"Type=Primary, Size=Medium, Icon Only=False, Shape=Square, Danger=False, State=Hover"105```106107| Figma Variant | React Prop | Notes |108| ----------------------------- | --------------------- | -------------------- |109| `Type=Primary` | `variant="primary"` | |110| `Type=Secondary` | `variant="secondary"` | |111| `Type=Neutral` | `variant="neutral"` | |112| `Type=Text` | `variant="text"` | |113| `Type=Danger` / `Danger=True` | `variant="danger"` | |114| `Size=Large` | `size="lg"` | |115| `Size=Medium` | `size="md"` | |116| `Size=Small` | `size="sm"` | |117| `Shape=Circle` | `shape="circle"` | |118| `Shape=Square` | `shape="square"` | |119| `Shape=Default` | `shape="default"` | |120| `State=Default` | _(no prop)_ | Default render state |121| `State=Hover` | _(no prop)_ | CSS handles it |122| `State=Focused` | _(no prop)_ | CSS handles it |123| `State=Pressed` | _(no prop)_ | CSS handles it |124| `State=Disabled` | `disabled` | |125| `State=Loading` | `loading` | |126| `Icon Only=True` | `size="icon"` | Button only |127128---129130## Full Translation Example131132Given this Figma MCP output:133134```json135{136 "name": "Type=Primary, Size=Medium, Icon Only=False, Shape=Square, Danger=False, State=Default",137 "fills": [{ "token": "Sf/Pri/Pri" }],138 "textColor": "Onsf/Bra/Default",139 "typography": "Button/01"140}141```142143Translate to:144145```tsx146import { Button } from '@aioz-ui/core-v3/components'147;<Button variant="primary" size="md" shape="square">148 Label149</Button>150```151152> Colors and typography are handled by `Button` internally. Apply color/typography classes manually only when building **custom layouts** outside of component primitives.153154---155156## Core Rules1571581. **Token-first** — Never use raw Tailwind colors or sizing.159160 ```161 ❌ text-gray-500 bg-white border-gray-200 text-sm font-medium162 ✅ text-content-sec bg-sf-screen border-border-neutral text-body-02163 ```1641652. **Component-first** — Use design system primitives over custom divs. See Component Map above.1661673. **Typography is atomic** — Each `text-*` class already encodes font-size, line-height, weight, and font-family. Never stack additional font utilities on top.1681694. **Icons only from `@aioz-ui/icon-react`** — Never SVG literals, emoji, or other libraries.170171 ```tsx172 import { Search01Icon } from '@aioz-ui/icon-react'173 ;<Search01Icon size={16} className="text-icon-neutral" />174 ```1751765. **On-surface text** — Text on a `bg-sf-*` surface must use the matching `text-onsf-*` class:177178 ```179 bg-sf-pri → text-onsf-text-pri180 bg-sf-error-sec → text-onsf-text-error181 bg-sf-neutral → text-onsf-text-neutral182 ```1831846. **Charts** — Always import from `@aioz-ui/core/components` (not `-v3`). Always wrap in the card shell. Always provide both `categories` and `overwriteCategories`. Read `references/charts.md` before writing any chart code.185186---187188## Reference Files189190Open the relevant file for deep-dive API docs, full token lists, and component examples:191192| File | Open When |193| -------------------------- | ---------------------------------------------------------------------------------- |194| `references/colors.md` | Full token → Tailwind class tables for text, background, and border tokens |195| `references/typography.md` | Full `text-*` class list with font-size, weight, and line-height specs |196| `references/icons.md` | Icon name transformation rule, size guide, and common icon import list |197| `references/components.md` | Full props, all variants, and ready-to-use code examples for every component |198| `references/charts.md` | LineChart, AreaChart, BarChart, DonutChart — APIs, variants, legend, hidden-series |
dvcrn