---
name: tds
description: Use when writing, modifying, reviewing, or translating Figma designs into UI code in any project that consumes @tatumio/tatum-design-system (TDS, Tatum Design System). Pushes toward existing TDS components (Button, Badge, Card, Dialog, Table, Alert, Tabs, Tooltip, Input, Field, Dropdown, Checkbox, Switch, Toaster, Combobox, MultiSelect, RadioGroup, Pagination, Skeleton, etc.) instead of custom div-based markup, and toward TDS Tailwind-plugin tokens (semantic colors like text-primary/bg-brand-solid for automatic dark mode; primitive tatum-* classes for spacing, radius, typography) instead of raw hex, px values, or generic Tailwind color scales. Apply proactively for any UI work in a TDS-consuming project even if the user does not mention TDS, Tatum, or "design system" — requests like "add a modal", "build a settings page", "implement this figma design", "create a dashboard card", "add a form field", "make a table", or any component/layout request qualify. Composes with any available Figma skill (e.g. figma-use): after Figma context is retrieved, this skill handles the translation to TDS components and tokens.
---

# TDS — Tatum Design System consumer guide

Use this skill when writing or modifying UI in any project that consumes `@tatumio/tatum-design-system`. The goal is simple: **use what TDS already provides, and don't reinvent it in raw JSX or raw Tailwind.** That means preferring existing TDS components over custom markup and preferring TDS Tailwind-plugin tokens over hand-rolled colors, spacings, and type sizes.

Without this skill, models routinely build custom `<div>`-based cards, badges, modals, etc., and use raw hex codes or generic Tailwind color classes that freeze the UI in light mode. This costs design consistency and breaks dark mode.

## Step 1 — Component-first gate (the most important habit)

Before writing any UI markup, ask: **"Does TDS already ship this?"** Consult the component index at `references/component-index.md` for the full list with one-line purposes and key variants. Most common UI patterns are already covered:

| You want to build… | Use this TDS component |
|---|---|
| Clickable action (button, link-styled button) | `Button`, `IconButton`, `CopyButton` |
| A pill / tag / status chip | `Badge` |
| A modal / popup / confirm dialog | `Dialog` (+ `DialogHeader`, `DialogBody`, `DialogFooter`, `DialogTitle`, `DialogDescription`) |
| A hover tooltip | `Tooltip` |
| A contextual menu | `DropdownMenu` (+ its sub-parts) |
| A surface / panel / tile | `Card` |
| A banner / inline warning | `Alert` |
| A tabbed section | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` |
| A data grid / list with columns | `Table` |
| Form controls | `Input`, `TextArea`, `Checkbox`, `RadioGroup`, `Switch`, `Combobox`, `MultiSelect`, `DatePicker`, `DateRangePicker`, `Slider`, `Autosuggest` |
| Form composition (label + control + hint/error) | `Field` with `Label`, `Hint` |
| Toast notification | `Toaster` + the `toast` helper |
| Loading placeholder | `Skeleton` |
| Progress indicator | `ProgressBar` |
| Pagination controls | `Pagination` |
| Truncated wallet address | `AddressHandle` |
| Chain/network logo | `ChainIcon` |
| Calendar picker | `Calendar` |
| Code block display | `CodeHighlight` |
| Shell / install command | `CommandLine` |

Only fall back to raw JSX when the pattern genuinely isn't covered. If it's not obvious, read `references/component-index.md` in full before writing markup.

## Step 2 — Discover the exact API from the installed package

The skill deliberately does **not** ship per-component prop docs, because TDS evolves and they would go stale. Instead, for every component you actually use, read the type declarations from the consuming project's `node_modules`:

```
<project>/node_modules/@tatumio/tatum-design-system/dist/types/components/<Name>/<Name>.d.ts
```

That file gives you exact prop names, prop types, enum values, and sub-component composition. For usage examples, the storybook file in the TDS source at `src/components/<Name>/<Name>.stories.tsx` (if the user has the TDS repo checked out) shows realistic patterns. For behavior questions not answered by types, read the source `.tsx`.

Compound components (`Dialog`, `DropdownMenu`, `Tabs`, `Popover`, `Field`) need their sub-parts composed correctly. The `.d.ts` plus the per-component notes in `references/component-index.md` cover the gotchas — don't guess sub-component names or required wrappers.

Good habit: when you pick a component, do a single grep/read of its `.d.ts` before writing the call site. That's cheaper than guessing props and fixing errors.

## Step 3 — Styling: semantic tokens first

TDS's Tailwind plugin adds two families of utility classes. Using the right family is what gives the UI automatic dark-mode support without extra work.

### Semantic tokens — the default

Semantic tokens are CSS variables that resolve to different values in light and dark mode. Reach for these first for any color, surface, border, or focus ring. Examples:

```tsx
// Good: dark-mode-safe
<div className="bg-primary border border-secondary">
  <p className="text-primary">Title</p>
  <p className="text-tertiary">Subtitle</p>
  <Icon className="text-fg-brand-primary" />
  <button className="bg-brand-solid text-white">Save</button>
</div>
```

The class families are `text-*` (label colors), `text-fg-*` / `bg-fg-*` (foreground/icon colors), `bg-*` (backgrounds), `border-*` (borders), `ring-*` (focus rings), `shadow-*` (elevations). Utility status colors like `text-utility-error-600` and `bg-utility-brand-100` are also semantic.

### Primitive `tatum-*` colors — the exception

`tatum-gray-100`, `tatum-primary-500`, etc., are hardcoded and don't change between themes. Use these **only** when a color must stay exactly the same in light and dark mode — brand logos, specific illustrations, third-party badges. Default to semantic.

```tsx
// Bad: frozen in light mode, breaks in dark mode
<p className="text-tatum-gray-900 bg-tatum-white">Label</p>
// Also bad: generic Tailwind scale — not a TDS token at all
<p className="text-gray-900 bg-white">Label</p>
```

### Spacing, radius, typography — use `tatum-*`

For padding, margin, gap, radius, text sizes, weights, shadows, and border widths, use the `tatum-*` scale defined by the plugin (see `references/tokens.md` for the pixel → class mapping). The mistake to avoid is hand-rolling a value the scale already defines — a generic Tailwind step (`p-4`) or an arbitrary `[…]` value (`p-[16px]`, `rounded-[8px]`, `text-[14px]`) where a token exists — because it drops out of the token system.

Raw / arbitrary values are fine where **no token applies**: structural sizing (element widths and heights, `grid-cols-*`, positioning, `size-*` icons) uses Tailwind's normal utilities, and computed or genuinely one-off values (chart geometry, a progress fill's width, animated transforms, a specific `max-h-[…]`) are inlined. If such a hand-picked value starts repeating as UI chrome, that's a token request, not a habit — see the design manual's "When explicit values are allowed" for the full policy.

## Step 4 — `tailwind-merge` needs the TDS extension

TDS defines custom utilities that share the `text-` prefix for both font sizes (`text-tatum-heading-xs`) and colors (`text-tatum-primary-500`). A vanilla `twMerge` cannot tell them apart and will silently drop one of the classes, producing subtly broken styling.

When a consuming project uses `tailwind-merge`, the `twMerge` instance must be extended with `withTds` from the TDS package:

```ts
import { extendTailwindMerge } from 'tailwind-merge'
import { withTds } from '@tatumio/tatum-design-system'
const twMerge = extendTailwindMerge(withTds)
```

If the project already has a `clsxm` or `cn` utility, update it in place — don't create a second one.

## Step 5 — Figma → code

When implementing a Figma design (often via an available Figma skill such as `figma-use`), the Figma MCP output is a **reference**, not final code. Translate it to TDS tokens. Full step-by-step checklist at `references/workflows.md` (Figma section). Key rules:

- Raw hex from Figma → semantic token if possible (`text-primary`, `bg-brand-solid`), primitive (`tatum-gray-*`) only for brand-locked colors.
- Pixel values (`16px`, `24px`) → `tatum-*` class via the spacing/radius tables in `references/tokens.md`.
- Font sizes/line heights → `text-tatum-text-md`, `text-tatum-heading-sm`, etc.
- Icons → never guess from the screenshot. Fetch `data-name` from `get_design_context` and map kebab → PascalCase against the project's own icon set (`lucide-react` is the recommendation) — TDS exports no icons, they're passed in via `icon` props. See the Icons subsection in `references/workflows.md`.
- Any visual pattern that matches a TDS component → use the component, not a pixel-perfect `<div>` copy.

## Step 6 — Self-check before reporting done

Run this mental checklist after implementing any UI change. When a check fails, fix it.

1. Does each section of new JSX correspond to an existing TDS component where one exists? (No custom `<div>`-based Card/Badge/Modal etc.)
2. Any raw hex codes (`#FFFFFF`, `rgb(...)`)? Replace with semantic or primitive tokens.
3. Any `px` values in className arbitrary values (`p-[16px]`, `rounded-[8px]`) where the scale already has that step? Replace with `tatum-*`. (A genuine one-off with no token — e.g. `max-h-[…]` for an animation — is fine.)
4. Any generic Tailwind color classes (`text-gray-900`, `bg-white`, `border-gray-200`)? Replace with semantic tokens.
5. If the project uses `tailwind-merge`, is it extended with `withTds`?
6. For dialogs / dropdowns / tabs / fields: are sub-components composed correctly (verified against the `.d.ts`)?
7. If Figma was involved: did every spacing, radius, color, and type value come from a TDS token rather than a raw value?

This mirrors the "Figma says" pattern — making the check explicit catches the mistakes that slip by silently.

## Reference files

- [`references/component-index.md`](references/component-index.md) — full list of TDS components with one-line purpose, sub-components, and typical variants. Read when you're unsure whether a pattern is covered or which component fits.
- [`references/tokens.md`](references/tokens.md) — complete Figma-pixel-value → `tatum-*` class mapping for spacing, radius, typography, shadows, and border widths, plus the semantic color families. Read when translating Figma designs or when unsure which class to use for a given value.
- [`references/workflows.md`](references/workflows.md) — the full Figma-to-code checklist and an expanded self-check for larger changes.