Skip to content

Workflow

A practical “generate and validate” workflow for SpiraCSS.

Required files

For SpiraCSS workflows, prepare these two items:

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

Terminal window
# 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

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:

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.