You don't have to start over, and you don't have to restructure anything to try Spektral. The Spektral plugin for Claude Code reads your design system where it is and adds a few config files beside it. Nothing inside your library moves or changes. Once you see your own components working, it shows you what converting would add, and converts one component at a time only when you ask.
What you need
- Claude Code, and Spektral installed.
- Your design system checked out locally: a React, Vue, Svelte or Lit component library, or plain HTML and CSS.
- A clean git working tree, or a new branch, so every file the plugin adds shows up in one diff.
Adopt it in place
- Install the plugin
In a Claude Code session, run:
/plugin marketplace add https://spektral.design/claude/marketplace.json /plugin install spektral@spektral
- Ask it to bring your design system in
Start Claude Code from the root of the repo that holds your library (the monorepo root, if it lives in a package) and say:
> Bring this design system into Spektral
- Confirm what it found
It reads your repo first and changes nothing: framework, where the library lives, how components and files are named, how you style, where your tokens come from, your Storybook, and your public exports. It shows you that summary and waits for you to confirm it before writing a file.
- Let it add Spektral's files
Only these, all new, all beside your library:
platforms/<your-library>/platform.yml— where your library is and how it's written, plus rules the agent follows when it edits your code, taken from your own conventions (reference).spektral.yml— project config, and your token stylesheets and CSS prefix (reference).specs/*.spec.yaml— a spec for each component, written from your source. It only states what the code shows; it never guesses a prop.system-guidance.yaml— if you want one: a draft of your system's principles and conventions for your team to edit on the Guidance page.
- Open it in Spektral
Press Open Project and choose your repo's root. Your components appear, Storybook starts, and each component shows its spec. If your tokens are DTCG JSON, Spektral offers a token configuration and previews it before writing anything.
See what works, and what converting would add
The plugin finishes with a report written for your library, one row per Spektral feature: what works now, and what converting would add. Broadly, it splits like this:
| Works in place | Comes with converting |
|---|---|
| The agent builds and edits components in your style, following your conventions | Re-pointing an element to a different token on the canvas, without the agent |
| Storybook preview, and the accessibility audit if you run Storybook's Vitest addon | The token editor and token sync, when your tokens aren't DTCG yet |
| Sync, branches, change requests and version history, with your team | Spektral building and hosting your npm package |
| Hosted docs, Storybook and the design system MCP, from your specs | The CSS audit, when your styles live in CSS-in-JS, CSS Modules or Tailwind |
The report also names anything Spektral can't reach in place: for example a component whose source file doesn't follow the naming the rest of your library uses.
Try converting one component
Before converting anything for real, convert one. The plugin picks a representative component, one with variants and states that's used widely, and converts it next to the original. Then you can compare the two.
- Add your framework as a platform
In the platform picker, add React, Vue, Svelte or Lit. Spektral sets up its own library under
platforms/. Your library is untouched, and the two sit side by side. - Port the component
Open the Matrix tab and press Port on the component, under the new platform. Spektral pairs the two versions, so they stay one component with two implementations.
- Check it's the same component
The plugin checks the converted component against the original. Its public API must be unchanged, every token must resolve to the same value, every story must render the same, and there must be no new accessibility issues. Then open both and try everything the converted one adds.
Convert the rest, when you're ready
Ask the plugin to convert and it works in order:
- Tokens first, into DTCG, keeping the CSS custom property names your components already use.
- Then one component at a time, and each must pass the same four checks before the next one starts.
- If a check fails, it stops and shows you the difference, and your original stays in place.
Your package name and exports never change, so the apps that use your design system don't notice. Both libraries coexist for as long as you like. When everything is converted and your team agrees, retire the original platform; its history stays in the cloud.
Good to know
- One library per platform. In a monorepo with several component packages, adopt the core one first; each other package becomes a platform of its own.
- Specs are worth reviewing. They're written from your source and only state what it shows, but the reasoning behind your components lives in your team's heads. Add it in the spec's
decisions(schema). - The guidance is a draft. It's built from your README, contributing guide and code, and your team owns it from then on.