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:

⚠️ 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

---

Variant → Prop Map

Figma MCP encodes variants as comma-separated Key=Value pairs in the node name:

"Type=Primary, Size=Medium, Icon Only=False, Shape=Square, Danger=False, State=Hover"

---

Full Translation Example

Given this Figma MCP output:

{
  "name": "Type=Primary, Size=Medium, Icon Only=False, 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

1. 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
   

2. Component-first — Use design system primitives over custom divs. See Component Map above.

3. Typography is atomic — Each text-* class already encodes font-size, line-height, weight, and font-family. Never stack additional font utilities on top.

4. 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" />
   

5. 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
   

6. 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: