Specra for VS Code

Bring Specra design system outputs into your editor.

The extension connects a local workspace to a Specra project so you can:

• sign in to Specra from VS Code
• link a workspace to a Specra project with .specra.json
• pull generated artifacts into your codebase
• sync reference images from your local references directory
• run extraction without leaving the editor
• open the linked project in the Specra web app

Commands

• Specra: Login
• Specra: Logout
• Specra: Configure Project
• Specra: Generate
• Specra: Pull Reference Images
• Specra: Push Reference Images
• Specra: Run Extraction
• Specra: Push and Run Extraction
• Specra: Open Project Online

Typical Flow

1. Run Specra: Login.
2. Run Specra: Configure Project.
3. Choose the Specra project to link to the current workspace.
4. Put reference screenshots in the configured references directory.
5. Run Specra: Push and Run Extraction.
6. Run Specra: Generate to pull the latest artifacts into the workspace.

Workspace Config

The extension writes a .specra.json file at the workspace root.

It also reads .secra.json as a fallback for older setups, but .specra.json is the canonical file name.

Example:

{
  "projectId": "your-project-id",
  "projectName": "Specra demo",
  "outputsDir": "src/generated",
  "referencesDir": ".specra/references"
}

Generated Outputs

By default, artifacts are written under .specra/generated.

Default output files:

• design-system.json
• design-system.css
• tailwind-theme.css
• design-system.prompt.md
• example-ui.tsx

You can override any of those paths with the outputs field in .specra.json.

Example:

{
  "projectId": "your-project-id",
  "outputsDir": "src/generated",
  "outputs": {
    "design-system-prompt": "src/generated/specra.prompt.md",
    "tailwind-theme-css": "src/generated/theme/specra-theme.css"
  }
}

Reference Sync

The extension treats referencesDir as the local source of truth for screenshots.

• Specra: Push Reference Images scans that directory recursively
• only supported image types are uploaded: PNG, JPEG, WebP
• obvious duplicates are skipped
• Specra: Pull Reference Images downloads remote references back into that directory

If you want to keep light and dark references separate, use subfolders like:

• .specra/references/light
• .specra/references/dark

Authentication

Login uses your browser and returns to VS Code through the URI handler.

Build behavior:

• local development builds point at http://localhost:3000
• production VSIX builds point at https://specra.tech

Publishing

Before publishing:

1. bump the version in package.json
2. make sure the publisher value matches your Marketplace publisher
3. set VSCE_PAT or run vsce login <publisher>

Build and publish:

bun run publish:marketplace

That command:

1. builds the extension in production mode
2. creates specra.vsix
3. publishes that VSIX to the Visual Studio Marketplace

Local Development

Build:

bun run build

Watch mode:

bun run dev

Package a local VSIX:

bun run package:vsix