Workflow

A practical “generate and validate” workflow for SpiraCSS.

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).

Flow overview

Standardize policy (spiracss.config.js)
    ↓
Set up Stylelint config
    ↓
Prepare HTML (manual / Figma MCP etc.)
    ↓
Generate SCSS (CLI / VS Code)
    ↓
Implement styles (manual / Figma MCP etc.)
    ↓
Validate with Stylelint
    ↓
Fix errors if any (manual / AI agent)

Humans and AI follow the same workflow.

1. Standardize policy

At project start, decide the following with your team and record them in spiracss.config.js.

Decision	Options	Notes
Naming convention	Default (Block=2 words, Element=1 word) / Custom	Configure to match project rules
Class attribute	class (default) / className (React/JSX)	Match JSX syntax, etc.
Variant/State expression	data-* attributes (recommended) / class-based	Match project conventions
Margin direction	margin-top only (recommended) / margin-bottom only
Validation strictness	All rules enabled / gradual adoption
External library exclusions	Specify class names from libraries in use	Swiper, Splide, etc.

Note

There is no single “correct” choice above.
What matters is that your team picks one and stays consistent.

// spiracss.config.js (example)
module.exports = {
  selectorPolicy: {
    variant: { mode: 'data', dataKeys: ['data-variant'] },
    state: { mode: 'data', dataKey: 'data-state' }
  },
  stylelint: {
    class: { elementDepth: 4 }
  }
}

See spiracss.config.js for details.

2. Configure lint

Before generating SCSS, set up Stylelint so SpiraCSS rules run with your policy.

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

export default {
  plugins: [...spiracssPlugin, '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
  }
}

Details: Stylelint setup.

3. Generate structure

After writing HTML, auto-generate SCSS templates.

Actor	Tool	Command / Action
Human	VS Code extension	Command Palette → SpiraCSS: Generate SCSS
AI agent	CLI	npx spiracss-html-to-scss src/components/card-list.html

The generated SCSS includes @rel comments and basic structure.

See Tooling for details.

4. Validate automatically

Stylelint detects violations with the same criteria for humans and AI.

# Run validation
npx stylelint "src/**/*.scss"

# Auto-fix (formatting rules only; SpiraCSS structural violations require manual or AI-agent fixes)
npx stylelint "src/**/*.scss" --fix

Tip

Exclude shared partials via Stylelint ignoreFiles; keep shared keyframes linted.

Example ignore pattern (exclude shared partials, keep shared keyframes linted):

// stylelint.config.js (excerpt)
export default {
  rules: { ...createRules(spiracssConfig) },
  ignoreFiles: [
    'src/styles/partials/**/*.scss',
    '!src/styles/partials/keyframes.scss'
  ]
}

Error messages include the correct pattern and fix instructions, helping AI agents fix issues autonomously.
To understand the reason behind errors, see the rule pages:

• class-structure - Block/Element structure rules
• property-placement - Property placement rules
• page-layer - Page entry SCSS boundaries
• rel-comments - @rel comment rules

5. Keep navigation cheap

@rel comments let you jump between files quickly.

// @rel/../components/card-list  ← Ctrl+Click to jump

.page-home {
  > .card-list {
    // @rel/scss/card-list  ← Jump to child Block's SCSS
    margin-top: 24px;
  }
}

See Comment Links for details.