Quickstart

import { Badge } from ‘@astrojs/starlight/components’;

Current beta release — View changelog

How to set up SpiraCSS tooling.

Want to try a ready-to-run project first? See Starters.

Required files

For SpiraCSS workflows, prepare these two items:

spiracss.config.js (project root)
AI agent documentation (download and use as a reference document for AI-agent workflows)
Stylelint v16 users: v0.3 AI agent documentation

If any of them are missing, decisions become uncertain and error-prone, so verify their presence before starting work (do not assume defaults).

SpiraCSS Stylelint Plugin

Automatically validates SCSS structure and naming.

Install

yarn add -D @spiracss/stylelint-plugin stylelint stylelint-scss postcss-scss

Configure

Create stylelint.config.js.

// stylelint.config.js (ESM)
import spiracss, { createRules } from '@spiracss/stylelint-plugin'
import spiracssConfig from './spiracss.config.js'

export default {
  plugins: [...spiracss, 'stylelint-scss'],
  customSyntax: 'postcss-scss',
  // Exclude shared partials; keep shared keyframes linted.
  ignoreFiles: ['src/styles/partials/**/*.scss', '!src/styles/partials/keyframes.scss'],
  rules: {
    ...createRules(spiracssConfig),
    'scss/at-rule-no-unknown': true
  }
}

When using createRules(), aliasRoots is required in spiracss.config.js. The stylelint sub-sections fall back to defaults when omitted. See spiracss.config.js for details.

Run

yarn stylelint "src/**/*.scss"

SpiraCSS HTML CLI

CLI for AI agents (Codex, Claude Code, etc.). Generates SCSS from HTML and validates HTML structure. For manual use, prefer the VS Code extension.

yarn add -D @spiracss/html-cli

# Generate SCSS
echo "$HTML" | yarn spiracss-html-to-scss --stdin

# Validate HTML
echo "$HTML" | yarn spiracss-html-lint --stdin

# Add HTML placeholders
echo "$HTML" | yarn spiracss-html-format --stdin

Note: For fragment HTML, use --selection with spiracss-html-to-scss / spiracss-html-lint. spiracss-html-format does not support --selection / --root.

VS Code Extensions

Comment Links

Link comments (such as @rel) let you jump to related files with a single click. Without them, you have to trace targets manually, which adds friction.

→ Install from VS Code Marketplace / Open VSX

HTML to SCSS

Generates SCSS templates from HTML.

→ Install from VS Code Marketplace / Open VSX

Shared configuration

All tools read spiracss.config.js. Create it at the project root. When using Stylelint’s createRules(), aliasRoots is required. The stylelint sub-sections are optional; defaults apply when omitted.

See spiracss.config.js for details.

Minimal configuration (required)

aliasRoots is required (used for alias resolution in spiracss/rel-comments).

// spiracss.config.js (ESM)
export default {
  aliasRoots: {
    src: ['src'],
    components: ['src/components'],
    common: ['src/components/common'],
    pages: ['src/components/pages'],
    parts: ['src/components/parts'],
    styles: ['src/styles'],
    assets: ['src/assets']
  }
}

Optional project policies

Add these only if they match your project:

generator.rootFileCase: align generated SCSS filenames (and Stylelint root filename checks) with your convention
htmlFormat.classAttribute: output className (React/JSX) instead of class when using spiracss-html-format

Customize other options to match your project or team guidelines. See spiracss.config.js for details.

Next
Starters