User Guide

What is Design System Sync?

Design System Sync is a Figma plugin that automatically exports your design tokens (variables, text styles) and components to GitHub or Bitbucket, keeping your code and design perfectly in sync.

Getting Started

GitHub Setup

Create a Personal Access Token

1. Go to GitHub Settings → Tokens
2. Click "Generate new token (classic)"
3. Name it: Design System Sync
4. Select scopes:
   • ✅ repo (Full control of private repositories)
   • ✅ workflow (Update GitHub Actions workflows)
5. Click "Generate token"
6. Copy the token (you won't see it again!)

Configure in Plugin

1. Go to GitHub Tab
2. Paste your Personal Access Token
3. Enter repository: username/repo-name
4. Choose base branch (usually main or master)
5. Click "Export to GitHub"

Bitbucket Setup

Create an API Token

1. Go to Atlassian Account → Security → API Tokens
2. Click "Create API token"
3. Name it: Design System Sync
4. Click "Create"
5. Copy the token (you won't see it again!)
6. Note: This token has full access to Bitbucket

Configure in Plugin

1. Go to Bitbucket Tab
2. Enter your Bitbucket username
3. Paste your API Token
4. Enter workspace name
5. Enter repository name
6. Choose base branch
7. Click "Export to Bitbucket"

Export Formats

Variables (Design Tokens)

Exported as JSON with multiple format options:

• JSON: Raw token data
• CSS Variables: --color-primary: #0066ff;
• Style Dictionary: DTCG-compliant format for design tokens
• W3C Design Tokens: $type / $value with alias references like {color.primary}

Text Styles v2

Text styles are now first-class tokens. The plugin reads every local text style, resolves any bound variables on properties like fontSize, fontFamily or lineHeight, and exports them in the same formats your variables already use.

• W3C output uses $type: "typography" and emits aliases like {font.size.lg} instead of hard literals
• Style Dictionary output is DTCG-compatible and references the same alias paths
• CSS output flattens to readable custom properties such as --text-heading-h1-font-size
• Units are normalized — letterSpacing, lineHeight and textCase map to standard CSS values (e.g. AUTO → normal, PERCENT → %, PIXELS → px)
• Collection names are intentionally stripped from token paths so output stays portable across Figma file structures

Components

Exported as structured JSON with:

• Component metadata (name, description, URL)
• All variants and properties
• Style information
• Change history

Unwired Value Detection v2

The Unwired report scans every component, variable and text style in your file and lists the exact properties that still hold a raw value instead of pointing at a token. Use it as a checklist when migrating an existing design system to variables, or as an ongoing coverage metric.

How to use it

1. Run a Scan on the current Figma file
2. Open the Unwired tab
3. Each row shows the component (or variable / text style), the property, and the literal value still in use
4. Wire the variable in Figma, re-scan, and watch the row disappear

What it covers

• Colors — fills, strokes, effect colors
• Layout — spacing, gaps, padding, radii
• Typography — font size, family, weight, line height, letter spacing on text styles
• Variables that reference other variables — alias chains are followed once

Token-Aware AI Code Generation v2

The AI code generator was rewired so output preserves your token references end-to-end. Instead of inlining #10B981 or 16px, generated components consume your variables directly through var(--color-primary) and friends — meaning a refactor in Figma propagates straight into your codebase.

What changed

• System prompt now instructs the model to preserve var() references verbatim instead of resolving them to hex
• Components, variables and text styles all flow into the same prompt context, so the model has the full token vocabulary available
• Multi-variant component sets generate every variant, not just the first one
• Generation state persists across tabs — long generations are no longer lost when you switch to the Variables or Components view

How to use it

1. Open the Code Gen tab (Pro feature)
2. Pick a component or component set from your scan
3. Choose React or HTML/CSS output
4. The generated code references your tokens — copy it straight into your repo

Subscription Plans

Three plans. Free covers individuals exploring the plugin; Pro adds the AI codegen and one-click Unwired wiring; Studio is the choice when you work across multiple computers.

Free 1 device

• 5 exports per month
• All export formats (W3C, Style Dictionary, CSS)
• Text Styles export
• Unwired report (read-only — see hardcoded values, upgrade to wire them)
• GitHub & Bitbucket auto-PRs
• Community support

Pro $10/mo · 1 device

Billed annually at $120/yr — save 17% vs monthly. Monthly available at $12/mo.

• ✨ Unlimited exports per month
• ✨ Token-aware AI code generation — output uses your var(--token) references instead of raw hex
• ✨ Connect Unwired — one click wires every exact-match hardcoded value to its design token (see section below)
• ✨ Everything in Free

Studio $16.67/mo · multi-device

Billed annually at $200/yr — save 33% vs monthly. Monthly available at $25/mo.

• 🎟️ Everything in Pro
• 🎟️ Multi-device access — register the same email on Mac, PC, work + home, all under one subscription. No DEVICE_MISMATCH locks.
• 🎟️ Priority support — direct email response within 24 hours
• 🎟️ Beta access to upcoming features (Tailwind v3/v4 export, Flutter, …)

How to Upgrade

1. Click the ⭐ Upgrade button in the plugin's top-right corner (visible whenever you're on Free or Pro)
2. Choose between Annual (recommended — saves 17-33%) and Monthly
3. Pick Pro or Studio
4. Complete payment through Stripe — promo codes are accepted (ANNUALDEAL, DSSYNC30, DSSYNC20)
5. The plugin polls Stripe and updates your tier automatically — you'll see confetti and a "Welcome to Pro/Studio!" toast within a few seconds

Multi-device join (Studio only)

Once you're on Studio, simply open the plugin on your second device and enter the same email you used for your first. The plugin recognizes the existing Studio subscription, joins this device to it automatically, and you're ready to go — no extra payment, no re-registration friction.

If you previously hit "license is tied to one device" on a Pro plan, upgrading to Studio unlocks the device restriction for every machine under the same email.

Manage Subscription

After upgrading, click "My Account" to:

• View subscription status & tier
• Update payment method
• Change plan (Pro ↔ Studio, monthly ↔ annual)
• Cancel subscription (you keep access until period end)
• View invoices

Connect Unwired Pro / Studio

The Unwired report flags every hardcoded value in your file that could be wired to a design token. Connect Unwired turns that report into a one-click action: for every exact-match suggestion, the plugin binds the hardcoded value to the matching variable in your Figma file.

What it does

• Scans every component, variant, and inner layer for hardcoded values
• Looks up each value against your local variables (colors via hex match, numbers via exact match)
• If exactly one match exists, suggests var(--variable-name)
• The Wire N matches button binds every suggestion to its variable in one go — no manual rewiring per layer

Supported properties

• Colors — fills, strokes, text color
• Spacing — padding (4 sides or shorthand), gap, itemSpacing
• Radius — per-corner or shorthand
• Typography — fontSize, lineHeight (text nodes)
• Other — strokeWeight, opacity

How to use it

1. Click Scan Changes in the plugin
2. If the dashboard shows an Unwired card with a count, click Show Details
3. The Unwired modal opens. If you have exact-match suggestions, the top bar shows "Wire N matches" in emerald
4. Click → the plugin walks every match and applies the binding. Result appears as "✓ Wired X of Y" in the bar
5. The plugin auto-re-scans afterwards so the Unwired count visibly drops

Limitations

• Exact matches only. If a hardcoded value doesn't match any variable in your file, no suggestion is offered. Fuzzy color matching (e.g. #181818 → close-to gray/900 at #18181B) is planned for a future release.
• If multiple variables share the same value (common in semantic + primitive layered systems), the plugin picks the first one (typically the primitive). You can manually re-route in Figma if needed.
• Some Figma properties don't support variable binding via the API (e.g. font weight); those will show a clear failure reason in the console.

Troubleshooting

GitHub Token Not Working

Bitbucket Token Not Working

No Variables Detected

Make sure your Figma file has:

• Design variables created (not just styles)
• Variables published in a library (for shared files)
• You have access to view the variables

Export Limit Reached

Free tier allows 5 exports per month. To continue:

• Wait until next month (resets automatically)
• Upgrade to Pro for unlimited exports

Payment Not Processing

Plugin Not Detecting Upgrade

After upgrading:

1. Close and reopen the plugin
2. Wait 10-30 seconds for webhook to process
3. Check "My Account" shows Pro status
4. Contact support if issue persists

Frequently Asked Questions

Is my data secure?

Yes! We use industry-standard encryption. Your design data is only exported to repositories you specify. Payment info is handled securely by Stripe (we never see your credit card).

Can I use this with private repositories?

Absolutely! The plugin works with both public and private repositories. Just ensure your access token/password has the correct permissions.

What happens to my subscription if I cancel?

You keep Pro access until the end of your billing period. After that, you return to the free tier (5 exports/month). Your data is kept for 30 days in case you resubscribe.

Can I export to multiple repositories?

Yes! You can export to different GitHub and Bitbucket repositories. Just update the repository name before each export.

Do I need to review Pull Requests before merging?

Yes! Always review the generated PR before merging. The plugin exports what it detects, but you should verify the changes are correct.

How do I get support?

• Pro users: Priority support via email
• All users: GitHub Issues
• Email: alexanderburgouk82@gmail.com

Can I get a refund?

Yes! We offer a 30-day money-back guarantee. If you're not satisfied, contact us within 30 days of your purchase for a full refund.

Best Practices

Organize Your Variables

• Use consistent naming: color/primary, spacing/md
• Group related variables in collections
• Add descriptions to document purpose

Before Exporting

• Review changes in the Scan tab
• Ensure variable names are production-ready
• Check component variants are correct
• Test in a development branch first

After Exporting

• Review the Pull Request carefully
• Run your CI/CD tests
• Check for breaking changes
• Update documentation if needed

Security

• Never share your access tokens
• Use tokens with minimum required permissions
• Rotate tokens periodically
• Revoke tokens you're not using

Need More Help?

We're here to help you succeed!

• GitHub Issues: Report bugs or request features
• Email Support: alexanderburgouk82@gmail.com
• Documentation: Full documentation