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)

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
  }
}

CommonJS example:

// stylelint.config.cjs (CommonJS)
const spiracss = require('@spiracss/stylelint-plugin')
const plugin = spiracss.default ?? spiracss
const { createRules } = spiracss

module.exports = {
  plugins: [plugin, 'stylelint-scss'],
  customSyntax: 'postcss-scss',
  // Exclude shared partials; keep shared keyframes linted.
  ignoreFiles: ['src/styles/partials/**/*.scss', '!src/styles/partials/keyframes.scss'],
  rules: {
    ...createRules('./spiracss.config.js'),
    '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.

Depending on your module system, write spiracss.config.js as ESM (export default) or CommonJS (module.exports). 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']
  }
}

CommonJS (when package.json does not have "type": "module"):

// spiracss.config.js (CommonJS)
module.exports = {
  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

The config content is the same regardless of ESM/CJS. 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