CLI

Build custom CSS, manage icons, print HTML blueprints, compile design tokens, and scan your project for security and accessibility issues — all from the command line.

Installation

Install VelinStyle globally or run it on-demand with npx:

# Install globally
npm install -g velinstyle

# Or run without installing
npx velinstyle

Commands Overview

All available commands at a glance:

Command	Description
`velinstyle init`	Create a `velinstyle.config.js` configuration file
`velinstyle build`	Build custom CSS with selected layers
`velinstyle themes`	List available themes
`velinstyle add <name>`	Add a single component CSS file
`velinstyle icons <subcommand>`	Manage icon providers
`velinstyle scan [path]`	Security and accessibility scanner
`velinstyle prefix [path]`	Codemod utility classes to `velin-*` (optional `--write`, `--map`)
`velinstyle blueprint [name]`	Print a documented HTML blueprint (e.g. modal, login form, dashboard shell)
`velinstyle scaffold "prompt"`	Compose blueprints from natural language (`list-intents`, `--json`, `-o`)
`velinstyle layout <sub>`	Responsive layout `audit`, `suggest`, `fix` for HTML files
`velinstyle tokens build`	Generate `:root` CSS variables from a `tokens.json` file

Init

Creates a velinstyle.config.js file in the current directory. The interactive prompt lets you select which CSS layers to include:

velinstyle init

This generates a config file with your chosen layers, theme, output path, and scan settings.

Build

Builds a custom CSS bundle based on the layers defined in your config file.

# Build using velinstyle.config.js
velinstyle build

# Specify output file
velinstyle build --output dist/styles.css
velinstyle build -o dist/styles.css

# Minify the output
velinstyle build --minify

Option	Alias	Description
`--output`	`-o`	Output file path (default: `./velinstyle-custom.css`)
`--minify`		Minify the generated CSS

Icons

Manage icon providers and generate optimized icon bundles.

Subcommands

# List all available icon providers
velinstyle icons list

# Add icons from several providers (downloads into icons/svg/ in the package)
velinstyle icons add lucide --icons menu,search,check
velinstyle icons add heroicons --icons arrow-left --variant outline

# Rebuild the combined sprite used by the framework
velinstyle icons build

# Remove every SVG that was downloaded from one provider, then rebuild
velinstyle icons remove heroicons
velinstyle icons build

Run these commands from the root of a VelinStyle clone (or ensure icons/svg/ resolves to your project). After icons build, referenced sprites are updated for local development.

Subcommand	Description
`list`	List all available icon providers
`add <provider>`	Add icons from a provider (`--icons` names, `--variant` style)
`remove <provider>`	Remove a previously added provider
`build`	Build the final icon bundle from all added providers

Blueprint

Print copy-paste HTML wired for VelinStyle classes and tokens. Run velinstyle blueprint list for the machine-readable list, then emit one fragment with blueprint <id> (stdout or -o).

velinstyle blueprint list
# Example output shape (IDs only — exact order may vary):
#   alert-stack
#   breadcrumb-bar
#   card-grid
#   footer-simple
#   form-contact
#   form-login
#   hero-section
#   layout-dashboard
#   modal
#   navbar-header
#   pagination-bar
#   search-field
#   sidebar-layout
#   table-responsive
#   bottom-nav-mobile
#   cookie-consent
#   empty-state
#   filter-bar
#   notification-center
#   onboarding
#   pricing-table
#   settings-panel

velinstyle blueprint hero-section -o snippets/hero.html
velinstyle blueprint sidebar-layout -o snippets/sidebar.html

Tokens build

Reads JSON with a tokens map (keys become --kebab-case custom properties) and prints CSS or writes --output.

velinstyle tokens build --input tokens.json --output src/tokens-from-json.css

Note: Default input path is tokens.json in the current working directory if --input is omitted.

Blueprint catalog

Run velinstyle blueprint list for the authoritative list. Each id prints a static HTML fragment you can paste into a page or Storybook.

ID	Description
`modal`	Accessible modal shell (`role="dialog"`, header, footer actions)
`form-login`	Login form with Velin field classes and validation hooks
`layout-dashboard`	Dashboard shell: header, aside, main regions
`alert-stack`	Stack of status alerts (info / success / warning)
`breadcrumb-bar`	Horizontal breadcrumb trail
`card-grid`	Responsive card grid (auto-fit)
`footer-simple`	Simple footer with links and copyright
`form-contact`	Contact form (name, email, message)
`hero-section`	Hero block with heading, lead text, CTAs
`navbar-header`	Top navigation bar with brand and links
`pagination-bar`	Pagination control strip
`search-field`	Search input with button
`sidebar-layout`	Two-column layout: sidebar + content
`table-responsive`	Wrapped responsive table
`bottom-nav-mobile`	Mobile tab bar shell (pairs with `<velin-bottom-nav>`)
`cookie-consent`	Cookie consent banner with actions
`empty-state`	Empty state with icon, text, and CTA
`filter-bar`	Filter chips and search row
`notification-center`	Notification list panel
`onboarding`	Onboarding step layout
`pricing-table`	Pricing tier comparison grid
`settings-panel`	Settings form sections

Prefix

Mechanical migration of class / className attributes in HTML, Vue, JSX, and TSX. Dry-run by default; use --write to apply.

velinstyle prefix ./src
velinstyle prefix ./src --write
velinstyle prefix ./src --bootstrap-display --write
velinstyle prefix ./src --map ./velinstyle-prefix-map.json --write

Scaffold

Compose blueprint HTML from a text prompt (no API key). Full guide: Prompt scaffolding.

velinstyle scaffold list-intents
velinstyle scaffold "Navbar with logo and search" -o nav.html
velinstyle scaffold "Confirmation modal" --json

Layout audit

Static checks for flex, grid, containers, and mobile visibility. Full guide: Responsive layout.

velinstyle layout audit ./src
velinstyle layout suggest page.html
velinstyle layout fix page.html --dry-run
velinstyle layout fix page.html --write

Scan

A built-in scanner that walks HTML, CSS, and JavaScript for security, accessibility, and CSS hygiene. Use --severity to set the minimum level shown (errors always fail CI when present). --fix applies a small set of safe transforms; --fix-dry-run lists candidate files without writing.

In the framework repository, npm run test:contrast verifies OKLCH token pairs (4.5:1 / 7:1) — complementary to velinstyle scan.

Trusted Types & XSS: The scanner flags common XSS footguns (javascript: URLs, eval, raw innerHTML, inline handlers, unsafe target="_blank"). It does not parse CSP or Trusted Types policies — use HTTP headers plus the guidance in Security and getTrustedPolicy() for runtime hardening.

# Scan current directory
velinstyle scan

# Scan a specific path
velinstyle scan ./src

# Output as JSON (useful for CI/CD)
velinstyle scan --format json

# Auto-fix issues where possible
velinstyle scan --fix

# Filter by severity
velinstyle scan --severity error

# Preview auto-fix targets without writing
velinstyle scan --fix-dry-run

# Default lang when fixing missing <html lang> (BCP 47)
velinstyle scan --fix --fix-lang en

Option	Description
`--format json`	Output results as JSON (for CI ingestion)
`--fix`	Automatically fix issues where the scanner can do so safely (writes files)
`--fix-dry-run`	List files that would be modified by `--fix`; no writes
`--fix-lang <code>`	Default language tag for the HTML `lang` auto-fix (default `de`)
`--severity`	Filter by level: `error`, `warning`, or `info`

CI exit code: scan exits with code 1 when findings at or above the configured severity include errors. Review auto-fix output in a branch before relying on --fix on main.

Scanner rules

Severities are how findings are labelled in text/JSON output. The --severity flag sets the minimum level included in the report (e.g. warning hides info only).

Rule ID	Category	Severity	Fixable (`--fix`)
`security/safe-external-link`	Security	Warning	yes — adds `rel="noopener noreferrer"` to unsafe `target="_blank"` links
`security/no-javascript-url`	Security	Error	no
`security/no-inline-handler`	Security	Warning	no — replace with `addEventListener`
`security/no-raw-innerhtml`	Security	Warning	no — use `escapeHTML()` / `textContent`
`security/no-document-write`	Security	Error	no
`security/no-eval`	Security	Error	no
`security/no-function-constructor`	Security	Error	no
`security/csp-meta`	Security	Info	no — informational when no CSP `<meta>` detected
`a11y/html-lang`	Accessibility	Error	yes — sets `lang` on `<html>` (see `--fix-lang`)
`a11y/img-alt`	Accessibility	Error	no — add `alt` or `alt=""`
`a11y/button-label`	Accessibility	Warning	no — add visible text or `aria-label`
`a11y/input-label`	Accessibility	Warning	no — pair with `<label for>` or `aria-label`
`a11y/skip-link`	Accessibility	Warning	yes — inserts skip link when `id="main"` exists
`a11y/heading-order`	Accessibility	Warning	no — fix skipped heading levels (h1→h3)
`a11y/landmark-main`	Accessibility	Warning	no — add `<main>` or `id="main"`
`a11y/interactive-aria-hidden`	Accessibility	Error	no — remove `aria-hidden` from controls
`a11y/iframe-title`	Accessibility	Error	no — add `title` on `<iframe>`
`css/z-index-token`	CSS	Warning	yes — maps raw integers toward `--velin-z-*` tokens
`css/var-fallback`	CSS	Info	no
`css/no-important`	CSS	Info	no — allowlist skips a few safe cases
`css/vendor-prefix`	CSS	Info	no

Configuration

The velinstyle.config.js file controls all CLI behaviour. Here is the full structure:

export default {
  layers: ['tokens', 'reset', 'base', 'a11y', 'layout', 'components', 'utilities', 'security', 'helpers'],
  theme: null,
  output: './velinstyle-custom.css',
  minify: true,
  scan: {
    enabled: true,
    severity: 'warning',
    fix: false,
    ignore: ['node_modules', 'dist'],
  },
};

Key	Type	Default	Description
`layers`	`string[]`	all layers	CSS layers to include in the build
`theme`	`string \| null`	`null`	Theme name to apply (e.g. `'neon'`, `'ocean'`)
`output`	`string`	`'./velinstyle-custom.css'`	Output file path
`minify`	`boolean`	`true`	Whether to minify the output CSS
`scan.enabled`	`boolean`	`true`	Enable the scanner
`scan.severity`	`string`	`'warning'`	Minimum severity: `error`, `warning`, or `info`
`scan.fix`	`boolean`	`false`	Auto-fix issues when possible
`scan.ignore`	`string[]`	`['node_modules', 'dist']`	Directories to skip during scanning