Create a Platform Plugin

How Platforms Work

A platform is a directory under platforms/ that tells Spektral how to scaffold, build, and generate components for a specific UI framework. Each platform contains:

• platform.yml: Configuration file describing conventions, tooling, and agent rules
• ds-lib/: The scaffolded component library (created automatically on first init)

Create a new directory for your platform. The directory name becomes the platform ID (lowercase, hyphens allowed).

$ mkdir -p platforms/static-html

This is the heart of your platform plugin. It tells Spektral everything it needs to know: file patterns, Storybook configuration, Vite template, and the AI agent rules for generating components.

# platforms/static-html/platform.yml

name: Static HTML
description: Vanilla HTML/CSS/JS components with TypeScript
language: typescript
framework: static-html
version: "1.0"

paths:
  componentsDir: "src/components"

output:
  filePattern: "{ComponentName}.ts"
  storyPattern: "{ComponentName}.stories.ts"
  stylePattern: "{ComponentName}.css"
  indexExport: true

styling:
  approach: css-variables
  tokensFormat: css-custom-properties

componentPattern:
  exportStyle: named

scaffold:
  viteTemplate: vanilla-ts       # npm create vite template

storybook:
  baseUrl: "http://localhost:6006"
  frameworkPackage: "@storybook/html-vite"

indexExportTemplate: |
  export { {ComponentName} } from './{ComponentName}';

agentRules: |
  Framework rules (Static HTML):
  - Export a factory function named after the component that returns an HTMLElement.
  - Use document.createElement and classList for DOM construction.
  - Import the component stylesheet in the module.
  - Use CSS custom properties from design tokens: no hardcoded values.
  - Stories use @storybook/html with Meta/StoryObj.
  - Always include `tags: ["autodocs"]` in the meta object.

Add your platform ID to platforms/platforms.json so the app discovers it.

{
  "active": "react",
  "platforms": ["react", "lit", "vue", "svelte", "static-html"]
}

Open Spektral and navigate to the platform switcher. Your new platform will appear in the list. Click Initialize to scaffold the component library. This will:

1. Run npm create vite@7 ds-lib -- --template vanilla-ts
2. Install Storybook with @storybook/html-vite
3. Set up Style Dictionary for token builds
4. Build design tokens into src/tokens/variables.css
5. Launch Storybook on port 6006

Switch to your new platform and ask the AI to create a component. The agent will read your agentRules from platform.yml and generate code following your conventions:

// Generated: platforms/static-html/ds-lib/src/components/Badge/Badge.ts

import './Badge.css';

export interface BadgeProps {
  label: string;
  variant?: 'default' | 'success' | 'warning' | 'error';
}

export function Badge({ label, variant = 'default' }: BadgeProps): HTMLElement {
  const el = document.createElement('span');
  el.classList.add('badge', `badge--${variant}`);
  el.textContent = label;
  return el;
}

The component uses your design tokens as CSS custom properties, follows the BEM naming convention, and gets a full Storybook story file with all variants.

Key platform.yml Fields

Here's a quick reference for the fields that matter most when creating a new platform. See the full reference for all options.

Tips

• •Use built-in platform.yml files (platforms/react/platform.yml) as templates for your own.
• •The agentRules field directly controls how the AI writes component code. Be specific about patterns, exports, and DOM APIs.
• •All platforms share the same design tokens. Style Dictionary builds variables.css into each platform's ds-lib/src/tokens/ directory.
• •If your framework needs a custom Style Dictionary config, place it at platforms/your-platform/ds-lib/style-dictionary.config.js.