### HTML CLI examples (lint, generate SCSS, format)
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/downloads/spiracss-ai-agent-doc.full.md
Run from the directory containing spiracss.config.js. Examples use npx; npx may auto-install packages, so do not run without explicit approval. Use yarn spiracss-html-lint / spiracss-html-to-scss / spiracss-html-format if that matches the project setup.
```bash
# Lint HTML (root mode)
npx spiracss-html-lint --root path/to/file.html
```
```bash
# Lint HTML (selection mode, stdin)
cat fragment.html | npx spiracss-html-lint --selection --stdin
```
```bash
# Generate SCSS
npx spiracss-html-to-scss --root path/to/file.html
```
```bash
# Format HTML
npx spiracss-html-format path/to/file.html
```
--------------------------------
### Install with pnpm
Source: https://github.com/zetsubo-dev/spiracss/blob/master/packages/stylelint-plugin/README.md
Install the plugin and its dependencies using pnpm.
```bash
pnpm add -D @spiracss/stylelint-plugin stylelint stylelint-scss postcss-scss
```
--------------------------------
### Project customization example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/configuration/index.html
Example configuration showing aliasRoots, selectorPolicy, stylelint, htmlFormat, htmlLint, jsxClassBindings, and generator settings.
```javascript
module.exports = {
aliasRoots: {
components: ['components'],
styles: ['styles']
},
selectorPolicy: {
variant: { mode: 'data', dataKeys: ['data-variant'] },
state: { mode: 'data', dataKey: 'data-state' }
},
stylelint: {
class: {
elementDepth: 4,
childCombinator: true,
rootSingle: true
},
interactionScope: {
pseudos: [':hover', ':focus'],
requireComment: true
},
pseudo: {
enabled: true
},
rel: {
requireScss: true
}
},
htmlFormat: {
classAttribute: 'class'
},
htmlLint: {
classlessTagCheck: true,
classlessTagAllowlist: ['picture', 'source', 'img', 'track', 'map', 'area', 'br', 'wbr']
},
jsxClassBindings: {
memberAccessAllowlist: ['styles', 'classes']
},
generator: {
globalScssModule: '@styles/global',
childScssDir: 'scss'
}
}
```
--------------------------------
### stylelint.class configuration example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/configuration/options/index.html
Example configuration for stylelint.class with all settings and naming sub-items, including customPatterns with RegExp values.
```plaintext
stylelint: { class: { elementDepth: 4, childCombinator: true, childNesting: true, rootSingle: true, rootFile: true, rootCase: 'preserve', childFileCase: 'preserve', childDir: 'scss', componentsDirs: ['components'], external: { classes: [], prefixes: ['swiper-'] }, naming: { blockCase: 'kebab', blockMaxWords: 2, elementCase: 'kebab', modifierCase: 'kebab', modifierPrefix: '-', customPatterns: { block: /^custom-block-.+$/, element: /^icon-.+$/, modifier: /^--[a-z]+(-[a-z]+)?$/ } } }}
```
--------------------------------
### Incorrect: selector does not start with &
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/stylelint-rules/interaction-scope/index.html
Shows an incorrect example where the selector `> &:hover` does not start with `&`, violating the rule that selectors with pseudo/state selectors must start with `&`.
```scss
.sample-block { // --interaction @at-root & { > &:hover { // ❌: does not start with `&` opacity: 0.8; } }}
```
--------------------------------
### notFound error example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/stylelint-rules/rel-comments/index.html
Shows an incorrect example where the @rel path points to a non-existent file, and a correct example where the path exists.
```scss
// ❌// @rel/../components/missing-block.scss.page-home { color: #111;}
```
```scss
// ✅// @rel/../components/card-list.scss.page-home { color: #111;}
```
--------------------------------
### Install with npm
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/tooling/stylelint/index.html
Install the plugin and required dependencies using npm. Requires Stylelint v17+ and Node.js >= 20.19.0.
```bash
npm install -D @spiracss/stylelint-plugin stylelint stylelint-scss postcss-scss
```
--------------------------------
### rootBlockNotFirst error example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/stylelint-rules/rel-comments/index.html
Shows an incorrect example where the root block is not the first rule, and a correct example where it is first.
```scss
// ❌.util-reset { box-sizing: border-box;}.page-home { color: #111;}
```
```scss
// ✅.page-home { color: #111;}.util-reset { box-sizing: border-box;}
```
--------------------------------
### stylelint.config.js example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/packages/stylelint-plugin/README.md
Example configuration for Stylelint using the SpiraCSS plugin. Imports the plugin and a config file, then creates rules with createRules().
```javascript
// stylelint.config.js
import spiracss, { createRules } from '@spiracss/stylelint-plugin'
import spiracssConfig from './spiracss.config.js'
export default {
plugins: [...spiracss, 'stylelint-scss'],
customSyntax: 'postcss-scss',
rules: {
...createRules(spiracssConfig),
'scss/at-rule-no-unknown': true
}
}
```
--------------------------------
### aliasRoots configuration example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/downloads/spiracss-ai-agent-doc.full.md
Example of the aliasRoots configuration object, mapping alias names to arrays of paths. Required for Stylelint, not used by HTML CLI.
```javascript
aliasRoots: {
components: ['src/components'],
styles: ['src/styles'],
assets: ['src/assets']
}
```
--------------------------------
### Example input HTML for conversion
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/tooling/html-to-scss/index.html
Example HTML input for the conversion process, showing a root section with a title and a feature card.
```html
```
--------------------------------
### Directory Structure Example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/architecture/layers/index.html
Shows the recommended directory structure for the three-layer CSS architecture, including styles, components, and assets folders. This is from the 'Directory structure example' section.
```text
src/├── styles/ # Global layer│ └── partials/│ ├── global/│ │ ├── config.scss│ │ ├── function.scss│ │ ├── index.scss│ │ └── mixin.scss│ ├── base.scss│ ├── keyframes.scss│ ├── print.scss│ ├── reset.scss│ ├── utilities.scss│ └── variables.scss├── components/ # Component layer│ ├── common/ # Site-wide shared│ │ └── site-header/│ │ └── site-header.scss│ ├── parts/ # Multi-page shared│ │ └── hero-banner/│ │ └── hero-banner.scss│ └── pages/ # Page-specific│ ├── home/│ │ └── home-hero/│ │ └── home-hero.scss│ └── about/│ └── about-intro/│ └── about-intro.scss└── assets/ └── css/ # Page layer ├── home.scss └── about.scss
```
--------------------------------
### Install SpiraCSS Stylelint plugin
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/introduction/quickstart/index.html
Install the Stylelint plugin and its dependencies using yarn. Run this in a terminal window.
```bash
yarn add -D @spiracss/stylelint-plugin stylelint stylelint-scss postcss-scss
```
--------------------------------
### selectorPolicy configuration example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/configuration/options/index.html
Example configuration for selectorPolicy, showing valueNaming, variant, and state settings. Defaults to variant=data-variant and state=data-state, with aria-expanded, aria-selected, and aria-disabled treated as state.
```json
selectorPolicy: {
valueNaming: {
case: 'kebab',
maxWords: 2
},
variant: {
mode: 'data',
dataKeys: ['data-variant']
},
state: {
mode: 'data',
dataKey: 'data-state',
ariaKeys: ['aria-expanded', 'aria-selected', 'aria-disabled']
}
}
```
--------------------------------
### Selected HTML for conversion
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/tooling/html-cli/index.html
Example HTML input for the conversion spec. The first token in each class attribute is treated as the base class; classes starting with '-', '_', or 'u-' are treated as Modifier/Utility and cannot be base classes.
```html
Welcome
Introduction text...
Feature
```
--------------------------------
### Page Layer Example: Import and Place Components
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/architecture/layers/index.html
Shows how to import global partials and a component, then place the component within a page root class. The comment indicates the component file path. This example is from the Page Layer section.
```scss
@use "@styles/partials/global" as *;@use "@components/hero/hero-container";
.main-container { > .hero-container { // @components/hero/hero-container.scss margin-top: 0; }}
```
--------------------------------
### childMismatch error example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/stylelint-rules/rel-comments/index.html
Shows an incorrect example where the child block name does not match the @rel filename, and a correct example where they match.
```scss
// ❌.page-home { > .card-list { // @rel/scss/hero-banner.scss margin-top: 8px; }}
```
```scss
// ✅.page-home { > .card-list { // @rel/scss/card-list.scss margin-top: 8px; }}
```
--------------------------------
### stylelint.base configuration example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/configuration/options/index.html
Example of the stylelint.base configuration object with comments, external, naming, cache, and paths settings. Subkeys like base/class/placement are optional, but aliasRoots is required. Must be a plain object; arrays or Maps are invalid.
```javascript
stylelint: {
base: {
comments: {
shared: /--shared/i,
interaction: /--interaction/i
},
external: {
classes: [],
prefixes: ['u-']
},
naming: {
blockCase: 'kebab',
blockMaxWords: 2,
elementCase: 'kebab',
modifierCase: 'kebab',
modifierPrefix: '-'
},
cache: {
selector: 1000,
patterns: 1000,
naming: 1000,
path: 1000
},
paths: {
childDir: 'scss',
components: ['components']
}
}
}
```
--------------------------------
### misplacedParentRel error example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/stylelint-rules/rel-comments/index.html
Shows an incorrect example where the parent @rel comment is inside the root block, and a correct example where it is at the top.
```scss
// ❌.page-home { // @rel/../components/page-home.scss color: #111;}
```
```scss
// ✅// @rel/../components/page-home.scss.page-home { color: #111;}
```
--------------------------------
### Use createRulesAsync
Source: https://github.com/zetsubo-dev/spiracss/blob/master/packages/stylelint-plugin/README.md
Example of using createRulesAsync to load configuration from a file path.
```javascript
import { createRulesAsync } from '@spiracss/stylelint-plugin'
const rules = await createRulesAsync('./spiracss.config.js')
```
--------------------------------
### missingParentRel error example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/stylelint-rules/rel-comments/index.html
Shows an incorrect example missing the parent @rel comment and a correct example with the parent @rel comment at the top.
```scss
// ❌.page-home { color: #111;}
```
```scss
// ✅// @rel/../components/page-home.scss.page-home { color: #111;}
```
--------------------------------
### missingChildRel error example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/stylelint-rules/rel-comments/index.html
Shows an incorrect example missing the child @rel comment and a correct example with the child @rel comment as the first node.
```scss
// ❌.page-home { > .card-list { margin-top: 8px; }}
```
```scss
// ✅.page-home { > .card-list { // @rel/scss/card-list.scss margin-top: 8px; }}
```
--------------------------------
### Basic CLI usage: root, selection, and stdin modes
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/tooling/html-cli/index.html
Shows three ways to invoke the CLI: root mode (default), selection mode for fragments, and reading from stdin with --selection and --base-dir.
```bash
# Root mode (generate from the root element)
yarn spiracss-html-to-scss --root path/to/file.html
# Selection mode (treat input as a fragment)
yarn spiracss-html-to-scss --selection path/to/fragment.html
# From stdin
cat file.html | yarn spiracss-html-to-scss --selection --stdin --base-dir src/components/sample
```
--------------------------------
### Run spiracss-html-to-scss, spiracss-html-lint, and spiracss-html-format
Source: https://github.com/zetsubo-dev/spiracss/blob/master/packages/html-cli/README.md
Example commands for generating SCSS, linting, and formatting. Use --root for a single component root and --selection for fragments. If using npm, replace pnpm exec with npx or npm exec. HTML lint and HTML-to-SCSS require spiracss.config.js by default; without it, pass --allow-provisional or the commands fail with CONFIG_MISSING.
```bash
# Generate SCSS from a component root (root mode)
cat file.html | pnpm exec spiracss-html-to-scss --root --stdin --base-dir src/pages
# Generate SCSS from fragments (selection mode)
cat fragment.html | pnpm exec spiracss-html-to-scss --selection --stdin --base-dir src/pages
# Lint a component root
cat file.html | pnpm exec spiracss-html-lint --root --stdin
# Lint fragments
cat fragment.html | pnpm exec spiracss-html-lint --selection --stdin
# Insert placeholders
cat file.html | pnpm exec spiracss-html-format --stdin
```
--------------------------------
### selectorParseFailed error example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/stylelint-rules/pseudo-nesting/index.html
Example for the `selectorParseFailed` error: shows an unparseable selector and the corrected version.
```css
// ❌.button { > : { color: #111; }}
// ✅.button { > .item { color: #111; }}
```
--------------------------------
### needNesting error example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/stylelint-rules/pseudo-nesting/index.html
Example for the `needNesting` error: shows incorrect and correct usage of pseudo nesting.
```css
// ❌.button:hover { opacity: 0.8;}
// ❌& > .button:hover { opacity: 0.8;}
// ✅.button { &:hover { opacity: 0.8; }}
```
--------------------------------
### Install @spiracss/html-cli with npm
Source: https://github.com/zetsubo-dev/spiracss/blob/master/packages/html-cli/README.md
Install the CLI as a dev dependency using npm. Requires Node.js >= 20.
```bash
npm install -D @spiracss/html-cli
```
--------------------------------
### Example hero-section.scss with comment links
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/tooling/comment-links/index.html
Example SCSS file showing usage of @assets and @rel comment links. The @assets link resolves to src/assets/css/home.scss and the @rel link resolves relative to the file's directory.
```scss
@use "sass:meta";
// @assets/css/home.scss
.hero-section {
@include meta.load-css("scss");
> .feature-card {
// @rel/scss/feature-card.scss
}
}
```
--------------------------------
### Install @spiracss/html-cli with pnpm
Source: https://github.com/zetsubo-dev/spiracss/blob/master/packages/html-cli/README.md
Install the CLI as a dev dependency using pnpm. Requires Node.js >= 20.
```bash
pnpm add -D @spiracss/html-cli
```
--------------------------------
### Output example: generated SCSS file structure
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/tooling/html-cli/index.html
Shows the directory structure generated by the CLI, including root Block, child Blocks, and an index.scss with merged @use.
```text
your-component/
├─ hero-section.scss -> root Block
├─ scss/
│ ├─ feature-card.scss -> child Block
│ └─ index.scss -> @use merged automatically
└─ your-template.html
```
--------------------------------
### aliasRoots configuration example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/configuration/options/index.html
Defines root paths for alias resolution. Keys become aliases with '@' prefix (e.g., 'components' becomes '@components/...'). Keys must match [a-z][a-z0-9-]*. Values must be arrays of relative paths (absolute allowed only within project). Required when using createRules() or createRulesAsync() in the Stylelint plugin.
```javascript
aliasRoots: {
components: ['src/components'],
styles: ['src/styles']
}
```
--------------------------------
### generator configuration example
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/configuration/options/index.html
Example configuration for the generator option, showing all fields with sample values. Note that layoutMixins generates one @include block per entry, and pageEntryAlias/pageEntrySubdir control the page entry comment.
```plaintext
generator: { globalScssModule: '@styles/global', pageEntryAlias: 'assets', pageEntrySubdir: 'css', rootFileCase: 'kebab', childFileCase: 'kebab', childScssDir: 'scss', layoutMixins: ['@include breakpoint-up(md)', '@include breakpoint-up(lg)']}
```
--------------------------------
### Install SpiraCSS HTML CLI
Source: https://github.com/zetsubo-dev/spiracss/blob/master/docs/introduction/quickstart/index.html
Install the HTML CLI package for AI agents. Use this in a terminal window.
```bash
yarn add -D @spiracss/html-cli
```