How to use Tailwind Studio

Tailwind Studio is a Figma plugin that keeps your design system and Tailwind CSS in sync. You edit tokens visually in Figma; the plugin writes Variables, paint/text styles, and generated files developers can use in code.

The workflow has three layers:

• Core — raw scales (colors, spacing, type, shadows, radii, …).
• Semantic — named aliases for UI meaning (background, text, border, accent, status).
• Component — tokens scoped to buttons, inputs, cards, and badges.

When you are ready, use Sync with development to publish into Figma, push to GitHub, or download files to your machine.

1. Install Tailwind Studio from Figma Community, or load the development plugin from this repo.
2. Open a Figma file that should own your design tokens.
3. Run Plugins → Tailwind Studio. The window is a dark editor with Core, Semantic, Component, and Sync tabs.

Each brand is a theme package (for example Light and Dark, or separate product brands). The header brand menu lets you switch the active brand, add a new brand, or delete one (you must keep at least one).

Semantic and component values are stored per brand / mode so designers can tune Light and Dark independently while sharing the same Core scales.

Core is the foundation: color palettes, spacing, font sizes, line heights, radii, shadows, and related scales. Secondary tabs in Core group each scale type. Values map to Figma Variables under the Studio collections.

• Edit numbers and colors directly in the accordion sections.
• Use Reset to Tailwind Defaults (top-right, danger text) to restore the built-in Tailwind-aligned starter scales for that Core area.
• Prefer changing Core when you need a new step on a scale; prefer Semantic when you only need a different meaning alias.

Semantic tokens point at Core (or other aliases) with names that match product language: backgrounds, text, borders, accent, danger, success, warning, focus, and related groups.

• Accordion groups organize aliases so you can scan by purpose.
• Typeahead fields resolve token references — pick existing Core / Semantic paths instead of hard-coding hex when possible.
• Reset Semantic restores the default alias map for the current brand setup.

Component tokens describe Button, Input, Card, and Badge surfaces — fill, text, border, radius, and related states. They usually alias Semantic tokens so a brand change ripples through UI primitives automatically.

Use Reset Component to restore default component bindings after experiments.

The Preview control in the header opens a live side pane that renders sample UI with your current tokens. Close it (or press Esc) when you want the full editor width again.

Preview is for design feedback — it does not replace Sync. Use it while tuning Semantic / Component aliases so you can see Light and Dark brands before exporting.

Open the main Figma tab. You get two accordions:

Styles — choose Color styles, Text styles, and whether to remove orphan Studio styles, then sync. Semantic colors become paint styles designers can apply on the canvas.

Variables — restore missing Core, Semantic, and/or Component variables if a file drifted or was created before a feature shipped.

The main Sync with development tab has two destinations for shipping tokens to engineering:

• GitHub — commit or open a PR with generated token files in a repository.
• Local Drive — download the same generated files to your machine.

Publishing paint/text styles and repairing Variables lives on the separate main Figma tab (next to Component).

GitHub sync uploads generated design-token files to a repository so engineering can import Tailwind config / CSS without copying from Figma by hand. The plugin tab stays minimal — use this section for the full setup.

1. Project link

Paste your GitHub project URL. The plugin parses owner, repo, and optional branch from links like:

• github.com/acme/website
• https://github.com/acme/website/tree/develop
• git@github.com:acme/website.git

Do not paste a settings or personal-access-token page into the project field — that belongs in the access key field.

2. Create a fine-grained access key

1. Open GitHub → Settings → Developer settings → Fine-grained personal access tokens (or use the Create access key link in the plugin).
2. Generate a new token.
3. Under Repository access, choose Only select repositories and pick the repo you will sync to.
4. Under Repository permissions → Contents, set Read and write (Read-only is not enough — the plugin must commit files).
5. If you use Open a pull request, also set Repository permissions → Pull requests to Read and write.
6. Generate and copy the key (it typically starts with github_pat_).

Create a token here: github.com/settings/personal-access-tokens/new.

3. Connection options

• Edit on the publishing summary to override account, repo, branch, or folder path (default folder: design-tokens/).
• Tap Save, then Check connection to verify the token can reach the repo with write access.

4. Send tokens

Under Send Tokens:

• How to share tokens — CSS variables (recommended) or per-brand config. See Export formats. All generated files for that strategy are included automatically.
• Open a pull request — creates a PR for review instead of committing straight to the branch. Good for teams; turn off for solo / scratch repos.

1. Choose a share strategy and whether to open a pull request.
2. Tap Send to GitHub. If nothing changed since the last sync, the plugin skips a useless commit.

Recent Updates lists commits / PRs with links back to GitHub.

Sync → Local Drive generates the same token package without needing GitHub. Choose an export format, download individual files or Download All, and inspect content in File Preview.

Use Local Drive when you want to drop files into a repo by hand, attach them to a ticket, or verify output before enabling GitHub sync.

Both GitHub and Local Drive support two packaging strategies:

• CSS variables (recommended) — One Tailwind config plus a tokens.css file with [data-theme] blocks for Light / Dark (and brands). Developers switch themes in the app; values stay tokenized.
• Per-brand config — Separate Tailwind configs per brand with literal values baked in. Use only when each brand ships as its own build and your team explicitly wants that layout.