HTML to SCSS
A VS Code extension that generates SCSS files from HTML or template fragments according to the SpiraCSS Design Principles.
This extension uses the HTML CLI package internally.
<section class="hero-section"> <h1 class="title">Welcome</h1></section>Install
VS Code >= 1.99.0 is required.
Version 0.6.0 integrates the shared source-aware HTML/WebC/JSX/TSX/Astro/Vue engine. It selects the editor language/file format, reports shared original-range diagnostics and repair conditions, and reuses the core parse for generation. Parser assets are bundled; installing parsers in the workspace is not required. The VS Code minimum is unchanged; these additions are not available in 0.5.1. See the source-aware API and source-scope boundaries. Placeholder insertion remains the separate static-HTML feature below.
Reports without a proven source position remain in output only, including the extension’s own unsupported-format report; no squiggle is invented at the start of the document or a non-start selection. Positioned Astro/Vue failures retain their original document UTF-16 range, reason and repair guidance and stop generation. Astro closing-tag omissions that cannot preserve a source tree are local unresolved constraints: independently verified siblings can still be checked, but uncertain regions remain uninspected and document generation is unavailable. They are not evidence of a class-naming or resource failure. See the shared CLI reference for class-composition order, cause-unknown generated failures and supplied-HTML text-boundary constraints.
The shared core also distinguishes actual native Astro attribute emission and component class/list folding, resolves hidden-input type only when classless checking needs it, and preserves verified SVG context. Unknown type or post-parse source relation asks for the relevant evidence, not class changes or resource restoration. Astro closing boundaries require verified original-source correspondence; metadata-only roots are unchanged. Native uppercase close acceptance does not change the external ESLint parser’s pre-rule rejection boundary. See the CLI reference for the precise contracts.
Producing attributes, value ranges and uncertain presence remain separate branch facts; a prohibition without a unique winner invents no repair range. Configured dynamic ARIA is lint-valid in data mode, without forced boolean rewriting. Astro <div class="card-list" {...{"aria-expanded":open}} aria-expanded="true"/> passes lint, generates only the reachable known true selector, and has coverage.generationUnenumeratedSites: 1. Output shows one informational line only when nonzero, reading existing preflight coverage without reparsing/recounting. Old synchronous generated-file arrays do not carry the count. Dynamic configured data values remain unresolved, so results can differ from 0.5.1. Preserve intent when supplying finite values. The shared Fragment handling retains original ranges and independently verified siblings; the extension does not duplicate core decisions. See HTML CLI for full generation and compatibility details.
Install from the VS Code Marketplace or Open VSX by searching for SpiraCSS HTML to SCSS.
→ Install from VS Code Marketplace / Open VSX
Usage
Commands
| Command | Keybinding | Description |
|---|---|---|
| Generate SpiraCSS SCSS from Root | Cmd+Ctrl+A |
Generate SCSS files from the root element |
| Generate SpiraCSS SCSS from Selection | Cmd+Ctrl+S |
Generate SCSS files from the selection |
| Insert SpiraCSS placeholders | Cmd+Ctrl+D |
Insert placeholder classes into HTML |
Root mode
- Select a range that includes the root Block element
- Run
Cmd+Ctrl+Aor choose the command from the context menu - Generates the root SCSS in the same folder as the current file, and child SCSS files under
childScssDir/(default:scss/)
The root element must have a class attribute. If it doesn’t, generation fails.
Selection mode
- Select the Block elements you want to convert to SCSS
- Run
Cmd+Ctrl+Sor choose the command from the context menu - Generates SCSS for each Block under
childScssDir/(default:scss/)
If the selection contains multiple Blocks, each one is generated. If no top-level elements have a class attribute, an error is raised.
Insert placeholders
Adds placeholder classes to HTML without generating SCSS. Useful for aligning the structure before naming classes.
- Select a range that includes the element you want to treat as the root
- Run
Cmd+Ctrl+Dor choose the command from the context menu - Recursively normalizes descendants into a Block > Element structure
Placeholder names (block-box / element) change based on blockCase / elementCase settings.
Configuration
Customize behavior in spiracss.config.js at the project root.
If package.json has "type": "module", use export default instead of module.exports.
SCSS root syntax (v0.5.0+)
The extension uses the HTML CLI’s shared generator.scssRootStyle setting in spiracss.config.js; there is no separate VS Code setting for it.
generator: { scssRootStyle: 'scope-explicit'}The default is scope-explicit: root mode generates @scope (.hero-section) { :scope { ... } } only for the component root. Child Block files loaded with meta.load-css() and selection-mode output retain class selectors. A root without independent children still follows this setting and simply omits the unnecessary meta include. Choose scope for direct scope contents or class for the previous root syntax. Existing files are not migrated automatically.
Child and descendant Block files under configured childDir must use class syntax. Stylelint rejects every child-file @scope, including thematic wrappers, regardless of the root setting. Scope settings require scope on component roots through Stylelint’s createRules() integration, but neither scope setting requires a :scope wrapper in lint. HTML classes and HTML structure are unchanged. See scope configuration. Versions before v0.5.0 do not support this setting.
The child restriction prevents Sass from adding the loading parent’s selector to a child scope and producing the non-matching :scope :scope. Keep the root include placement unchanged to preserve generated child specificity. Existing child scopes require manual migration; see the repair.
Limitations
- The Insert placeholders command does not apply to HTML with template syntax (EJS, Nunjucks, Astro frontmatter, etc.)
- Only static HTML fragments are supported for placeholder insertion
For detailed conversion specs, template support, Block/Element detection rules, and dynamic class limitations, see the HTML CLI documentation.
Example
Input HTML:
<section class="hero-section"> <h1 class="title">Welcome</h1> <div class="feature-card"> <h2 class="heading">Feature</h2> </div></section>Output structure:
your-component/├─ hero-section.scss -> root Block├─ scss/│ ├─ feature-card.scss -> child Block│ └─ index.scss -> @use merged automatically└─ your-template.html