SCSS Token Guard

SCSS Token Guard helps you enforce token naming rules in SCSS, inspect variable usage in the active file, and generate a workspace-level report for token adoption.

It is built for teams that keep design tokens in shared SCSS files and want components to use the right token groups consistently.

What It Does

• Parses the active .scss file and lists variable definitions and usages in a dedicated sidebar.
• Validates variable names against prefix rules from a project config file.
• Highlights valid token usages in the editor and reports invalid usages in the Problems panel.
• Reads a shared SCSS variables source file and shows tracked tokens that are still unused in the current file.
• Generates an HTML workspace report with per-file coverage, invalid occurrences, token groups, and export support.

How It Works

The extension looks for the nearest .scss-token-guard.json by walking up from the active SCSS file. That config decides:

• which shared SCSS file contains the source tokens
• which files should be checked
• which token prefixes are allowed for each file pattern

The first matching rule wins.

Configuration

Create a .scss-token-guard.json file in your workspace or feature directory:

{
  "variablesSource": "src/styles/tokens/_variables.scss",
  "rules": [
    {
      "pattern": "src/components/button/**/*.scss",
      "prefixes": ["$button-", "$action-"]
    },
    {
      "pattern": "src/components/card/**/*.scss",
      "prefixes": ["$card-"]
    }
  ]
}

Config Fields

• variablesSource: Relative path to the SCSS file that defines your shared tokens.
• rules: Ordered list of file-matching rules.
• rules[].pattern: Glob pattern matched against the SCSS file path relative to the config file.
• rules[].prefixes: Allowed token prefixes for matching files. Prefixes are normalized to start with $.

Sidebar And Commands

When an SCSS file is active, the extension provides:

• SCSS Variables tree view with definitions, usages, and unused tracked tokens
• SCSS Token Guard: Refresh
• SCSS Token Guard: Generate Workspace Token Report
• SCSS Token Guard: Export Workspace Token Report

The workspace report opens in a webview and can be exported as HTML.

Typical Workflow

1. Add .scss-token-guard.json.
2. Point variablesSource at your shared token file.
3. Define prefix rules for each component area.
4. Open an SCSS file to inspect definitions, usages, and violations.
5. Generate the workspace report to review adoption and cleanup opportunities.

Development

npm install
npm run compile
npm run test:unit

License

MIT. See LICENSE.

Notes

• The extension activates on SCSS files.
• If no matching config or prefixes are found, validation is skipped.
• The report generator ignores common build and dependency directories such as node_modules, dist, coverage, .next, and out.