platform.yml Reference

Top-Level Fields

paths

output

File naming patterns. Each accepts a name token that is replaced with the component's name in the casing the token asks for, so a library that spells its files in kebab, camel or snake case is described as it is. A pattern with no token at all is a literal filename, index.ts is valid.

A component is reachable by any spelling, asking for AlertDialog and for alert-dialog resolves to the same files.

Describing a library you didn't scaffold

componentDir and the name tokens above exist so Spektral can read and edit an existing library where it already is. You do not move files, rename directories, or restructure a repo to adopt it: you describe the shape it already has.

Three shapes cover most real design systems:

paths:
  componentsDir: "src/components"
  componentDir: "{component-name}"

output:
  filePattern: "{component-name}.tsx"
  stylePattern: "{component-name}.module.css"
  storyPattern: "{component-name}.stories.tsx"

storybook:
  # Your library's own Storybook, run where it lives.
  cwd: "../../../packages/ui"

validation:
  # It is not your code. Do not have Spektral audit it as if it were.
  composition: false
  css: false

styling

componentPattern

scaffold

storybook

validation

Toggle individual audits the agent runs after generating or iterating on a component. Disabling an audit keeps edits surgical: useful for messy legacy codebases where broad auditing nudges the agent to clean up adjacent code instead of staying within the area you asked about. Disabled audits also remove the corresponding manual audit button from the UI.

Note: the previous validation.accessibility toggle has been replaced by the new audits list. Declare a check_accessibility entry in audits to enable it, or omit it to disable. The old field is parsed but ignored for backwards compatibility.

composition

Tells the agent how to shape components that naturally have sub-parts (Tabs + Tab + TabPanel, Navigation + NavigationItem, Table + TableRow + TableCell, etc.). The agent decides whether to decompose; this field decides what the resulting file layout looks like.

• siblings: one folder per component. Navigation/, NavigationItem/, NavigationSection/ each get their own .tsx / .css / .stories.tsx / spec. Shared state moves into a small Context module the siblings import. Easiest to reuse later.
• compound: a single folder whose component file exports all parts as named exports (Accordion-style). Use when children only ever appear inside the parent and depend on its Context.
• auto: the agent picks per request. Defaults to siblings when the child can stand alone.

composition:
  pattern: siblings

scripts

Whitelist of shell commands the agent can run via the run_script tool without prompting the user. Anything the agent invokes that is not on this list still works: the agent loop pauses and an inline approval card appears in the UI so you can Allow once or Deny. Use this to authorize routine commands you've already approved (lint, build, test) so the agent doesn't interrupt you for them.

Two ways to call run_script

• Whitelisted (auto-runs). The agent passes id; the runner uses the declared command, args, and cwd. No prompt.
• Free-form (gated). The agent passes command + optional args/cwd/reason. The agent pauses; you click Allow once or Deny in the inline approval card. Denied requests return as a tool error so the agent can adjust its approach.

Example

scripts:
  - id: lint
    description: Run ESLint on the React component library
    command: npm
    args: ["run", "lint"]
    cwd: platforms/react/ds-lib

  - id: build_tokens
    description: Rebuild design tokens (Style Dictionary)
    command: npm
    args: ["run", "build:tokens"]
    cwd: platforms/react/ds-lib

Disable entirely: add scripts under features.disabled to remove the run_script tool from the agent's tool list. The agent then can't ask to run anything.

audits

Custom checks the agent can run after writing a component. Each entry registers as its own named tool in the agent's tool list: the agent picks it directly from the description without an extra discovery step. Use this to expose platform-specific tests like an axe-core a11y audit, an iOS xcodebuild test run, an ESLint pass, or any shell command. Audits also appear as buttons in the manual audit panel beside the live preview.

Each audit has three required fields:

runner.type: vitest-storybook

Runs npx vitest run --project <project> --reporter=json in the platform's ds-lib/, filtered to the component's stories file. Used by the React platform's built-in check_accessibility audit.

runner.type: shell

Universal escape hatch: runs an arbitrary command. Stdout and stderr are returned to the agent verbatim alongside the exit code, so any check that prints actionable output works. Commands are spawned without a shell (no globbing or piping); arguments are passed as literal argv entries.

Example

A platform that runs an a11y audit (built-in) and a shell-based test command:

audits:
  - id: check_accessibility
    description: Run axe-core via Storybook's Vitest addon against all stories for a component.
    runner:
      type: vitest-storybook
      project: storybook
      filter: "{ComponentName}.stories.tsx"
      reportType: a11y

  - id: run_xcodebuild_tests
    description: Build and test the iOS package for this component.
    runner:
      type: shell
      command: xcodebuild
      args: ["test", "-scheme", "DesignSystem", "-only-testing:DesignSystemTests/{ComponentName}Tests"]
      cwd: ios
      timeout: 300000

Full Example (React)

name: React
description: React 18+ components with TypeScript
language: typescript
framework: react
version: "18.x"

paths:
  componentsDir: "src/components"

output:
  filePattern: "{ComponentName}.tsx"
  storyPattern: "{ComponentName}.stories.tsx"
  stylePattern: "{ComponentName}.css"
  testPattern: "{ComponentName}.test.tsx"
  indexExport: true

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

componentPattern:
  exportStyle: named
  propsInterface: "{ComponentName}Props"
  forwardRef: true
  displayName: true

scaffold:
  viteTemplate: react-ts

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

validation:
  composition: true
  css: true

composition:
  pattern: siblings

scripts:
  - id: lint
    description: Run ESLint
    command: npm
    args: ["run", "lint"]
    cwd: platforms/react/ds-lib
  - id: build_tokens
    description: Rebuild design tokens
    command: npm
    args: ["run", "build:tokens"]
    cwd: platforms/react/ds-lib

audits:
  - id: check_accessibility
    description: Run axe-core via Storybook's Vitest addon against all stories for a component.
    runner:
      type: vitest-storybook
      project: storybook
      filter: "{ComponentName}.stories.tsx"
      reportType: a11y

agentRules: |
  Framework rules (React):
  - Use forwardRef with displayName and named export.
  - Props interface named {ComponentName}Props extending HTMLAttributes.
  - Stories use @storybook/react with Meta/StoryObj.