# VelinStyle 1.4.0

> VelinStyle is a CSS framework with WCAG 2.2 AAA-oriented defaults, native JavaScript runtime, and Web Components.
> Full machine context: https://velinstyle.info/dist/velin-agent.json
> MIME: application/vnd.velinstyle.meta+json

## Framework
- npm: @birdapi/velinstyle
- VelinStyle is a CSS framework with WCAG 2.2 AAA-oriented defaults, native JavaScript runtime, and Web Components.
- Pipeline: Core Foundation ??? Design System ??? Knowledge Graph ??? Prompt Engine ??? Review Engine ??? AI Metadata
- Maturity: CSS/Web Components/runtime = stable; plan/review, knowledge graph, page/section registry, agent metadata = beta/foundation (seed, expanding); Studio + Utility Engine generator = planned
- Components: 43 canonical Web Components (`velin-*`); 3 helpers (flip/haptic/reveal); 45 lazy-loader entries (incl. legacy aliases)
- Knowledge graph: 20 component nodes, 17 page types, 12 sections, 3 design constraint packs
- HTML attributes: 36 `velin-*` bridges
- Skills registry: 1.0.0 (58 skills; SoT packages/velinstyle-skills/registry.json)
- CLI: velinstyle (scan, scaffold, plan, review, docs generate, search index, meta, skills, workflow)

## Agent briefing
- Treat plan/review/knowledge graph as beta foundation ??? usable, not a finished AI design system.
- Build pages with plan-first flow: analyze prompt ??? page registry ??? sections ??? design constraints ??? HTML ??? review.
- Prefer tokens (`--velin-color-*`, `--velin-space-*`) over raw hex.
- One H1 per page; form fields need labels + `velin-form-summary` when validating.
- Hero: max 2 CTAs; FAQ uses disclosure (`velin-accordion` / details).
- Do not invent non-`velin-*` utility classes.
- Prefer registry-backed skills/workflows (`velinstyle skills ...`, `velinstyle workflow ...`) before ad-hoc orchestration.

## Skills (from registry)
- Count: 58 ?? registryVersion: 1.0.0
- Full records (id, name, description, prosePath, proseHref, ???): https://velinstyle.info/dist/velin-agent.json ??? skills.items
- Public skill prose (generated mirror of registry SKILL.md): https://velinstyle.info/docs/generated/skills/<skill-id>/SKILL.md
- Package prosePath remains CLI/npm-relative; prefer proseHref for HTTP agents
- CLI: npx velinstyle skills list|show|run|install
- Skill IDs (language-neutral; no per-skill public HTML pages ??? Markdown prose only):
- velin-a11y-focus-keyboard
- velin-a11y-page-checklist
- velin-a11y-scan-fix
- velin-ai-agent-briefing
- velin-ai-plan-scaffold-review
- velin-ai-skill-authoring
- velin-components-accessibility-map
- velin-components-api-contract
- velin-components-recipe
- velin-components-select-compose
- velin-design-hero-compose
- velin-design-section-rhythm
- velin-design-surface-roles
- velin-dev-component-wire
- velin-dev-page-scaffold
- velin-dev-plan-first
- velin-docs-component-guide
- velin-docs-generate-api
- velin-dx-doctor-setup
- velin-dx-project-init
- velin-intelligence-acceptance
- velin-intelligence-classify
- velin-intelligence-inventory
- velin-intelligence-policy
- velin-intelligence-review
- velin-intelligence-stop
- velin-migration-legacy-wc
- velin-migration-plan
- velin-migration-prefix-classes
- velin-migration-review
- velin-migration-scan
- velin-migration-stop
- velin-migration-tailwind
- velin-motion-reduced-safe
- velin-motion-reveal-feedback
- velin-perf-audit-fix
- velin-perf-runtime-tree-shake
- velin-release-changelog-sync
- velin-release-meta-rebuild
- velin-reuse-gate
- velin-review-conversion-hero
- velin-review-page-gate
- velin-review-seo-meta
- velin-rewrite-apply
- velin-rewrite-catalog
- velin-rewrite-dry-run
- velin-rewrite-manifest
- velin-rewrite-preflight
- velin-rewrite-rollback
- velin-security-sanitize-html
- velin-security-scan-pii
- velin-testing-a11y-suite
- velin-testing-visual-smoke
- velin-themes-apply-token
- velin-themes-contrast-check
- velin-utilities-layout-apply
- velin-utilities-prefix-fix
- velin-utilities-token-map

## Conventions
- Positioning: VelinStyle is a CSS framework with WCAG 2.2 AAA-oriented defaults, native JavaScript runtime, and Web Components ??? not a JS-only library or a utility-only CSS kit.
- Use only velin-* utility classes and documented Web Components.
- Prefer data-velin-theme on <html> for theme switching.
- Run velinstyle scan on generated HTML before shipping.
- Prefer registry-first skills (`velinstyle skills`) and workflow graphs (`velinstyle workflow`) before inventing custom pipelines.
- Honor skill status, confidence, compatibility, and onlyIf predicates when automating.
- Do not put secrets, API keys, or raw emails in velin-meta or page meta.
- Resolve doc links against docs root (/docs/), not the current page folder.
- Prefer Velin Transparency Framework (velin-transparency + provenance) for AI/trust/compliance labeling; run `velinstyle transparency doctor`.

## Key guides
- [Velin-Meta](https://velinstyle.info/docs/guides/velin-meta.html)
- [AI Skills](https://velinstyle.info/docs/guides/ai-skills.html)
- [VelinSearch](https://velinstyle.info/docs/guides/velin-search.html)
- [Syntax highlighting](https://velinstyle.info/docs/guides/syntax-highlight.html)
- [Prompt scaffolding](https://velinstyle.info/docs/guides/prompt-scaffolding.html)
- [API reference](https://velinstyle.info/docs/guides/api-reference.html)
- [PixVerse partner setup (EN)](https://velinstyle.info/docs/guides/pixverse.html) ?? [DE](https://velinstyle.info/docs/guides/pixverse-leitfaden.html)
- [Velin Motion Clips (EN)](https://velinstyle.info/docs/guides/velin-motion-clips.html) ?? [DE](https://velinstyle.info/docs/guides/velin-motion-clips-leitfaden.html)
- North star: VELINSTYLE_2030.md
- Architecture: ARCHITECTURE.md

## Partner / affiliate (PixVerse)
- Optional AI video provider for Motion Clips ??? not a VelinStyle skill and not hosted by VelinStyle.
- Guides: https://velinstyle.info/docs/guides/pixverse.html (EN) ?? https://velinstyle.info/docs/guides/pixverse-leitfaden.html (DE)
- Signup links use Impact affiliate URLs with `rel="noopener sponsored"` (keep `noopener`; do not strip `sponsored` or force `noreferrer` ??? attribution).
- Scanner `security/safe-external-link` requires `noopener` on `target="_blank"`; `noopener sponsored` already satisfies detection/SAFE gates.

## Generated reference
- [Components index](https://velinstyle.info/docs/generated/components/) (minimal HTML when SoT allows)
- [Design intelligence](https://velinstyle.info/docs/generated/intelligence/components.json)
- [Scan policy](https://velinstyle.info/docs/generated/rules/scan-policy.json)
- [Tokens](https://velinstyle.info/docs/generated/tokens/)
- [Utilities](https://velinstyle.info/docs/generated/utilities/)
- [CLI commands](https://velinstyle.info/docs/generated/cli/commands.md)
- [AI / Agent Resources](https://velinstyle.info/docs/guides/ai-resources.html)
- [Atelier library](https://velinstyle.info/atelier/library/index.html)
- [Atelier catalog (id/title/href + optional related)](https://velinstyle.info/docs/generated/atelier/catalog.json)
- [Skill prose mirror](https://velinstyle.info/docs/generated/skills/)
- [CSS buttons (not a WC tag)](https://velinstyle.info/docs/components/buttons.html)

## Scanner policy (Phase 5)
- Machine policy: https://velinstyle.info/docs/generated/rules/scan-policy.json
- Candidates never imply fixable; candidates never Apply.
- `links/*` is Detect-only (never auto-fix).
- SAFE Apply only for listed safeApplyRuleIds when finding.fixable and fail-closed gates pass.

## Usage for agents
```
npx velinstyle plan "Steuerberater Landingpage mit Kontaktformular"
npx velinstyle scaffold "Steuerberater Landingpage mit Kontaktformular" -o out.html --json
npx velinstyle review out.html --json
npx velinstyle meta
npx velinstyle docs generate
npx velinstyle skills list --capability review
npx velinstyle skills install frontend
npx velinstyle workflow landingpage --json
```

## Site overlay (velinstyle.info)

## Discovery hierarchy
- Entry: https://velinstyle.info/.well-known/ai.json
- Manifest: https://velinstyle.info/dist/velin-agent.json (MIME application/vnd.velinstyle.meta+json)
- This file: https://velinstyle.info/dist/llms.txt
- Human AI docs EN: https://velinstyle.info/docs/guides/ai-resources.html
- Human AI docs DE: https://velinstyle.info/docs/guides/ai-resources-leitfaden.html

## Locale docs (EN / DE)
- [Introduction (EN)](https://velinstyle.info/docs/getting-started/introduction.html)
- [Einf??hrung (DE)](https://velinstyle.info/docs/getting-started/einfuehrung.html)
- [AI Skills (EN)](https://velinstyle.info/docs/guides/ai-skills.html) ?? [AI Skills (DE)](https://velinstyle.info/docs/guides/ai-skills-leitfaden.html)
- [Agent workflows (EN)](https://velinstyle.info/docs/guides/agent-workflows.html) ?? [Agenten-Workflows (DE)](https://velinstyle.info/docs/guides/agent-workflows-leitfaden.html)
- [CLI (EN)](https://velinstyle.info/docs/extend/cli.html) ?? [CLI (DE)](https://velinstyle.info/docs/extend/cli-de.html)
- [PixVerse partner (EN)](https://velinstyle.info/docs/guides/pixverse.html) ?? [PixVerse (DE)](https://velinstyle.info/docs/guides/pixverse-leitfaden.html)
- [Motion Clips (EN)](https://velinstyle.info/docs/guides/velin-motion-clips.html) ?? [Motion Clips (DE)](https://velinstyle.info/docs/guides/velin-motion-clips-leitfaden.html)
- Skill IDs are language-neutral. Public prose: `https://velinstyle.info/docs/generated/skills/<skill-id>/SKILL.md` (`proseHref` in the agent manifest). Package `prosePath` remains for CLI/npm. Do not invent DE skill pages or IDs.

## Skills discovery (registry is SoT)
- Registry: `@birdapi/velinstyle/skills-registry` (version 1.0.0) ??? full inventory is in `velin-agent.json` ??? `skills`
- CLI: `npx velinstyle skills list|show|run|install` and `npx velinstyle workflow ???`
- Guides: AI Skills + Agent workflows (above). No per-skill public HTML URLs (Markdown prose mirror only).

## Components discovery
- Generated WC API: https://velinstyle.info/docs/generated/components/
- Design intelligence: https://velinstyle.info/docs/generated/intelligence/components.json
- Human component docs: https://velinstyle.info/docs/components/
- CSS primitives (not WC tags): e.g. buttons ??? https://velinstyle.info/docs/components/buttons.html (`.velin-btn`; no `<velin-button>`)

## Atelier (templates / showcases ??? not component API)
- Home: https://velinstyle.info/atelier/index.html
- Library: https://velinstyle.info/atelier/library/index.html
- Machine catalog (public mirror of CLI SoT): https://velinstyle.info/docs/generated/atelier/catalog.json ??? base fields `id`, `title`, `href`; optional `related` only when `match: "direct"` (fail-closed DIRECT CE links). Do not invent attributes, events, or relationships when `related` is absent.
- Package SoT remains `cli/atelier-catalog.json` (mirrored at generate/sync; no second inventory).

## Scanner / diagnostics (Phase 5 frozen)
- Machine policy: https://velinstyle.info/docs/generated/rules/scan-policy.json
- Docs: https://velinstyle.info/docs/extend/cli.html
- Generated rules index: https://velinstyle.info/docs/generated/rules/scanner.md (may lag; prefer scan-policy.json + CLI diagnostics)
- `fixable` is a runtime finding field; candidates never set `fixable: true`
- SAFE Apply only when policy `safeApply` + finding.fixable + fail-closed gates
- `links/*` (`local-href-target`, `local-fragment-target`) = Detect-only ??? never auto-fix
- Candidates / REVIEW / BLOCKED / UNKNOWN ??? Apply

## Accessibility & performance discovery (human)
- EN Accessibility: https://velinstyle.info/docs/getting-started/accessibility.html ??? WCAG 2.2 check, Accessibility Checker guidance
- DE Barrierefreiheit: https://velinstyle.info/docs/getting-started/barrierefreiheit.html ??? Website Barrierefreiheit testen / pr??fen
- A11y patterns: https://velinstyle.info/docs/getting-started/a11y-patterns.html ??? Barrierefreiheit beim Entwickeln
- A11y dashboard: https://velinstyle.info/docs/getting-started/a11y-dashboard.html
- CLI scan (EN/DE): https://velinstyle.info/docs/extend/cli.html ?? https://velinstyle.info/docs/extend/cli-de.html ??? WCAG Check kostenlos via terminal
- Performance audit EN/DE: https://velinstyle.info/docs/guides/performance-audit.html ?? https://velinstyle.info/docs/guides/performance-audit-leitfaden.html ??? Website Performance testen; complements a11y as Lighthouse Accessibility alternative workflow
- Help EN/DE: https://velinstyle.info/docs/help/index.html ?? https://velinstyle.info/docs/help/hilfe.html
- Honest claim: framework defaults and tooling ??? application certification