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

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.

// 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 (where possible)
npx stylelint "src/**/*.scss" --fix

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.

Flow overview

Write HTML
    ↓
Set up Stylelint config
    ↓
Generate SCSS (CLI / VS Code)
    ↓
Implement styles
    ↓
Validate with Stylelint
    ↓
Fix errors if any (human or AI agent)

Humans and AI follow the same workflow.