SpiraCSS

https://github.com/zetsubo-dev/spiracss
Admin
SpiraCSS is a resilient CSS architecture designed to maintain consistency by having parents control...
Tokens:92,370
Snippets:889
Trust Score:3
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### 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
<section class="hero-section">  <h1 class="title">Welcome</h1>  <div class="feature-card">    <h2 class="heading">Feature</h2>  </div></section>
```

--------------------------------

### 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
<!-- Selected HTML --><section class="hero-section">  <h1 class="title">Welcome</h1>  <p class="body">Introduction text...</p>  <div class="feature-card">    <h2 class="heading">Feature</h2>  </div>  <div class="cta-box">    <a class="link" href="#">Learn more</a>  </div></section>
```

--------------------------------

### 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;  }}
```

--------------------------------

### 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']
    }
  }
}
```

--------------------------------

### 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;  }}
```

--------------------------------

### 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
```
Tokens:
Raw