CLI 1.2.2

Eigenes CSS bauen, Icons verwalten, HTML-Blueprints ausgeben, Design Tokens kompilieren und dein Projekt auf Sicherheits- und Accessibility-Probleme scannen - alles über die Kommandozeile. English: CLI

Wann verwenden

• Eigenes CSS bauen, HTML scannen, Performance auditieren und Docs / Suchindizes generieren.
• Use plan → scaffold → review for experimental prompt→HTML workflows (beta).

Wann nicht

• Behandle plan/review/meta nicht als fertiges AI-Designsystem oder Studio-Produkt.
• Erfinde keine CLI-Befehle der Utility Engine, die noch geplant sind.

Installation

Installiere VelinStyle global oder führe es bei Bedarf mit npx aus:

# Install the published package
npm install -D @birdapi/velinstyle

# Or run without installing
npx @birdapi/velinstyle
# binary name: velinstyle

Befehlsübersicht

Alle verfügbaren Befehle im Überblick:

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

# Marketing lite layers
velinstyle build --preset lite -o ./velinstyle-lite.css --minify

Velin Experience

Velin Experience ist die Produkt-Schicht hinter dem velinstyle-Einstieg — Output Contract, Event Bus, Registry-Help, Themes/Modes. Die gesamte CLI-Oberfläche rendert über Experience; das Binary ist nur die Tür. Rohes stdout bleibt für Pipes / CI (--json, --sarif, blueprint ohne -o).

• Modi: compact · standard · dashboard · verbose · debug · json · sarif · markdown
• velinstyle dashboard — Projektübersicht
• --record + velinstyle replay <record.json> — Aufzeichnung und Replay
• Config: velinstyle-cli.json

velinstyle doctor .
velinstyle themes
velinstyle skills list
velinstyle dashboard
velinstyle doctor . --record
velinstyle replay .velin/records/doctor-….json --output markdown

Guide: Velin Experience. Content Scanner: .blade.php first-class — Scan your project.

Human- vs. Machine-Output

Experience-Modi: compact · standard · dashboard · verbose · debug · json · sarif · markdown. Mit --quiet / -q unterdrückst du den Branding-Footer (Contract-Body bleibt; für CI --json / --sarif / --compact).

Scan Machine-Output: velinstyle scan … --json oder --sarif / --format sarif umgeht Experience und liefert Scanner-Findings (Rule, Message, Location, fixable, optional diagnostic, optional autoFix). Kein Branding-Footer. Human Experience scan zeigt eine kompakte Tabelle (Sev · Rule · Apply · Why · Message) plus SAFE/Review-Zähler — volle Diagnostics bleiben in --json / --sarif.

Branding-Footer (nur Human-Terminal / Experience-Render):

Built with VelinStyle · Powered by SKYLITE.DESIGN
Danke, dass du VelinStyle nutzt.

Der Footer erscheint nicht bei --json, SARIF, compact, markdown oder --quiet — Pipes und CI bleiben maschinenlesbar.

Velin Security Suite

Velin Security Suite ist die CLI; Velin Security Engine (core/security/) hält Registry und Rules. Auto-Detect Repo vs. Consumer; Subcommands für CI, Deps, Secrets und Publish.

• doctor · scan · audit · publish · ci · deps · secrets · report
• Scores: Security Score · Dependency Health · Release Health · Timeline

velinstyle security doctor .
velinstyle security deps .
velinstyle security publish

Guide: Velin Security Suite · seit 1.2.3.

Velin Motion

Page Motion ist das Motion Design System — volle Registry (Presets, Timelines, Transitions, Physics-Stubs, Composers, Triggers, Policies, Blueprints) plus First-Class Trigger Engine. Studio-ready Datenmodell; Studio-UI später.

• 1.2.6: list · presets · doctor · scan · policy · demo
• 1.2.7: analyze · review · report · optimize · blueprint
• Attribute: velin-motion + velin-trigger

velinstyle motion list
velinstyle motion doctor .
velinstyle motion analyze .
velinstyle motion blueprint landing -o motion.html
velinstyle motion demo

Clip Motion (1.3.0) — Bild→Clip über Package @birdapi/velinstyle-motion (lokal HTML/CSS oder optional PixVerse AI). Getrennt von Page Motion.

AI-Animationen werden über externe Anbieter erzeugt. PixVerse ist ein unterstützter Anbieter.

• Create / Wizard: motion create · Shortcuts zoom · pan · rotate · particles
• Batch / Compose: atelier · transition · sequence · export · usage
• Provider: motion providers · Setup: motion setup pixverse
• Presets: motion presets --clips
• Flags: --ai · --style ai · --yes · --provider

velinstyle motion providers
velinstyle motion setup pixverse
velinstyle motion create hero.png --preset cinematic --yes
velinstyle motion create logo.png --ai --yes
velinstyle motion atelier ./assets --count 10 --yes
velinstyle motion presets --clips
velinstyle motion usage

Guides: Velin Motion · Motion Clips · PixVerse Partner-Setup (Konto · API-Key · Affiliate-Kontext).

Windows-Hinweise

On Windows, velinstyle build loads velinstyle.config.js via pathToFileURL so drive-letter paths do not throw ERR_UNSUPPORTED_ESM_URL_SCHEME. Run velinstyle doctor to smoke-test the config import. Prefer relative vendor paths (vendor/velinstyle/) over absolute /dist/... sprite URLs.

Unknown CLI verbs print Unknown command '…' with suggestions and exit 1 (they no longer dump full help with a success-looking exit).

create landing copies vendor into the target directory and aims for a zero-warning scan (no inline styles; proper label for/id). Prefer bootFromDOM / runtime tree-shake in production; the scaffold falls back to the vendor components bundle offline.

Icons

Manage icon providers and generate optimized icon bundles.

Unterbefehle

# 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.

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 bauen

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

Blueprint-Katalog

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

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

See also Migration guide.

Scaffold beta

Blueprint-HTML aus Textprompt (ohne API-Key). Volle Seiten über Page-Registry; Fragmente über Recipe-Intents. Guide: Prompt scaffolding.

velinstyle scaffold list-intents
velinstyle scaffold "Navbar with logo and search" -o nav.html
velinstyle scaffold "Steuerberater Landingpage mit Kontaktformular" -o out.html --json
velinstyle scaffold --atelier 04,07 -o compose.html --from ./atelier/library

Atelier-Compose (beta): --atelier baut eine Seite aus kuratierten Atelier-Library-IDs (nicht Velin Studio — Studio bleibt planned). Siehe Atelier-Pull weiter unten.

Atelier-Pull

Kuratiertes Library-Showcase per Nummer oder ID pullen (36 → 36-calendar). SEO-Varianten wie 3600-… werden nicht gematcht.

velinstyle atelier list
velinstyle atelier 36 -o ./velin-atelier/36-calendar
velinstyle atelier 04 --format vue -o ./src/atelier/04-pricing

Plan beta

Strukturiertes Page-Plan-JSON (Sections, Constraints) ohne HTML. Foundation für Design Intelligence. Mit --atelier: Library-Compose-Plan (beta).

velinstyle plan "SaaS pricing page with FAQ" --json -o plan.json
velinstyle plan --atelier 04,07 -o atelier-plan.json

Review beta

Heuristic review gate (design, a11y, SEO, performance, conversion, prompt score). Not a substitute for human WCAG or security review.

velinstyle review out.html --prompt "SaaS pricing page with FAQ" --json

Meta beta

Build agent context artifacts. Knowledge Graph embeds are a seed catalog, not a complete design system. Guide: Velin-Meta.

velinstyle meta
velinstyle meta --base-url https://velinstyle.info
velinstyle meta page docs/components/buttons.html --write
velinstyle docs generate --scope meta

Performance-Audit

See Performance-Audit guide.

velinstyle perf audit ./public
velinstyle perf suggest ./public
velinstyle perf fix ./public --write

Docs generieren

Extract Markdown API tables from source (components, tokens, utilities, CLI manifest, scanner rules). Output: docs/generated/ in the framework repo — browse snapshot locally.

npm run docs:generate
velinstyle docs generate
velinstyle docs generate --scope components
velinstyle docs generate --scope tokens

Scopes: all, components, attributes, tokens, utilities, cli, rules, a11y, meta.

Suchindex (Erweiterung)

Build dist/search-index.json for VelinSearch. Merged with site pages via python tools/build-search-index.py.

velinstyle search index --out dist/search-index.json
velinstyle search index --extra-html ../velinstyle-site/docs

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

stable tooling — ergänzend zu beta plan/review; geeignet für CI.

Eingebauter Scanner für HTML, CSS und JavaScript: Security, Accessibility, CSS-Hygiene und lokale Link-Integrität. Mit --severity setzt du die Mindeststufe (Errors lassen CI fehlschlagen).

Pipeline (eine Engine): Detect → Diagnostic → Candidate (Review) → Fixability → Dry-Run → Apply. Ein Finding allein ist keine Apply-Erlaubnis. Diagnostic-Candidates sind nur Review (exact ≠ Auto-Fix). Schreiben darf nur die SAFE-Menge unten, und nur nach fail-closed Re-Validierung.

Im Framework-Repo prüft npm run test:contrast OKLCH-Token-Paare (4.5:1 / 7:1) — ergänzend zu velinstyle scan.

# Scan current directory
velinstyle scan

# Scan a specific path
velinstyle scan ./src

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

# SAFE Apply nur bei Policy + fixable Gates (Candidates ≠ Apply)
velinstyle scan --fix

# Filter by severity
velinstyle scan --only pii --fix

velinstyle scan --severity error

# SAFE-Pläne ohne Schreiben (JSON: autoFix.plans / rejected)
velinstyle scan --fix-dry-run

# Nur lokale Link-Integrität (Detect — keine automatischen Pfad-Rewrites)
velinstyle scan --only links

# Default-lang bei fehlendem <html lang> (BCP 47)
velinstyle scan --fix --fix-lang en

Diagnostics & Candidates

Ausgewählte Regeln liefern ein strukturiertes diagnostic-Objekt (reason, source, resolution, optionale Candidates / related). Candidates zeigen auf bestehende Ziele zur Review. Sie erfinden keine IDs, Labels oder Pfade und autorisieren Apply nie — auch nicht mit Confidence exact.

Es gibt kein Finding-Feld action und kein separates fixability-Objekt. Schreiben entscheidet sich über fixable plus Dry-Run-Pläne.

Link-Integrität

Statische Prüfung gegen den Scan-Root: relative und root-relative lokale HTML-Pfade (Verzeichnisse über index.html / index.htm) sowie #fragment-IDs im Zieldokument. Keine Live-HTTP-Prüfung; externe URLs und Template/Dynamic-Refs werden übersprungen. Beide Regeln bleiben fixable: false — kein automatisches start→index, EN↔DE, Fragment-Erfinden oder Generator-Bulk-Rewrite.

JSON und SARIF

--json gibt das Scanner-Payload aus. --sarif / --format sarif dieselben Findings als SARIF 2.1.0 (ruleId, Level, Message, Artifact-URI + Zeile, Properties: fixable, safeApplyEligible, detectOnly, nested diagnostic). Candidates bedeuten nie Apply. Exit-Code 1 bei Error-Severity (wie Text/JSON).

SAFE Apply (nur diese)

• a11y/html-lang — fehlendes <html lang> setzen
• a11y/skip-link — Skip-Link nur wenn id="main" schon existiert
• security/safe-external-link — rel="noopener noreferrer" ergänzen
• css/z-index-token — rohe numerische z-index → --velin-z-*
• pii/hardcoded-email — auf Placeholder maskieren

links/* und übrige a11y-Detect-Regeln werden nie automatisch angewendet.

Was Scan nicht behauptet

Statischer Scan ist kein vollständiges Accessibility-Audit, kein Screenreader-Test und keine Garantie, dass jeder Link- oder a11y-Fehler gefunden oder behoben wird. Für Ship-Gates mit axe/Lighthouse und manueller AT-Prüfung kombinieren. Generator-/Site-Linkprobleme gehören in den Site-/Generator-Layer, nicht als Scanner-Sonderregeln.

Scanner-Regeln

Severities markieren Findings in Text/JSON. --severity setzt die Mindeststufe (warning blendet nur info aus). Filtern mit --only security, --only a11y, --only links, --only pii, --only css, --only wc. Vollständige IDs: siehe generierte Rules. Performance zusätzlich über velinstyle perf audit. Review bleibt beta / heuristisch — Ship-Gates mit axe/Lighthouse absichern.

Security

PII

Accessibility

Link-Integrität

CSS

Performance

Konfiguration

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'],
  },
};