Strategy/ADR deep-dives remain maintainer-local (monorepo interne_docs/strategy/; not published)
UPGRADING.md draft for 1.1.0 → 1.2.0 (publish when cutting the minor)
RELEASE_NOTES_1.2.0.md companion overview
Changed
Production dependency isomorphic-dompurify3.13 → 3.21.0 (DOMPurify 3.4.x) so npm audit --omit=dev reports 0 vulnerabilities before the 1.2.0 upload
velinstyle scan and velinstyle perf accept a single HTML/CSS/JS file or a directory (no more ENOTDIR on file paths)
velinstyle init copies vendor assets when framework dist/ is available and scaffolds starter HTML with data-velin-reveal-auto + icon sprite meta
velinstyle create emits zero-warning HTML (no inline styles, label for/id), copies vendor into the target dir, boots via bootFromDOM when the package resolves (vendor full-bundle fallback)
Create vendor copy includes mini WC docs under vendor/velinstyle/docs/
velinstyle build invokes local lightningcss from the package node_modules; --preset lite prints size vs dist/velinstyle.min.css
Unknown CLI commands exit 1 with "Did you mean ...?" instead of dumping help with a success-looking exit
Top-level --help / README CLI tables list all create kinds and wc api / skills doctor
velinstyle meta page --write merges curated goals/intent and warns when dropping non-allowlisted keys
Hero CTA heuristic strips scripts/styles/code-blocks and counts only real <a>/<button> CTAs in hero scope
velin-icon default sprite is relative/configurable (sprite attr → meta/data-velin-icon-sprite → VelinIcon.defaultSprite → velin-icons.svg) instead of hardcoded /dist/velin-icons.svg
Skills templates/demos remap to existing files (samples/ecommerce.html, samples/landing.html, ...)
velin-agent.json and llms.txt include AI skills catalog and workflow discovery hints
Publish inputs include skills packages and schemas; prepublish runs skills:generate, skills:validate, skills:doctor, and check:blueprints
Docs clarify <velin-copy> (value/text + Shadow button), tooltip content, lightbox, icon sprite, attribute vs WC vs bootFromDOM, flex -- naming, breadcrumb __item/__link, Windows/vendor install, and review CTA semantics
README fit statement: landing/docs/simple admin yes; multipage shop + enterprise admin primary not yet; npm circulation note until 1.2.0 cut
🐛
Fixed
velinstyle build: config import uses pathToFileURL (no ERR_UNSUPPORTED_ESM_URL_SCHEME on drive-letter paths)
Duplicate IDs, unknown velin-* classes, invalid WC attributes, and inline document.write in HTML are detected
Official @velinstyle/react coverage for all canonical tags
Release sync guard (release:check / release:sync)
Docs/version/count drift fixes across framework and site
Highlight lexers: Python, YAML, Go, Rust
🚀
Added
<velin-data-table>: progressive enhancement for a light-DOM <table> -- sortable columns via real <button> headers with aria-sort, text/number/date sort types (data-sort, data-sort-value), substring filtering bound to any input (filter-input), optional pagination (page-size), and an empty state (empty-text). Sort, filter and page changes are announced; filtered and off-page rows use hidden so they leave the accessibility tree. Requires a <caption>, aria-label, or label attribute.
<velin-form-summary>: accessible error summary for any <form>. Replaces the transient native validation bubble with a focusable role="alert" panel listing every invalid field, wires aria-invalid and aria-describedby to per-field messages, moves focus to the offending field from summary links, and clears each error as soon as the field becomes valid. Supports data-error-message, data-error-label, data-error-ignore and author-supplied [data-velin-error-for] containers.
Highlight languages: Python, YAML, Go and Rust lexers, lazy-loaded like the existing ones. Aliases py, python3, yml, golang, rs resolve to them; yaml previously fell back to plain text.
Release sync guard:npm run release:check compares every machine-readable version surface (CLI manifest, a11y contracts, velin-agent.json, doc header badges, landing-page version badges, velin-meta blocks, JSON-LD softwareVersion, npm/CDN install pins, generated docs, changelog copies) against package.json. It also checks the component counts quoted in prose across both repos -- English and German -- against components.count / components.loaderCount in velin-agent.json, so adding a component cannot leave the docs claiming the old number. npm run release:sync rewrites the mechanical ones. Wired into ci:checks and the site build; site checks are skipped when the sibling repo is absent.
WCAG matrix: 3.3.1 Error Identification and 3.3.3 Error Suggestion are now tracked and owned by velin-form-summary.
Changed
@velinstyle/react is official (1.1.0): wrappers now cover all 38 canonicalvelin-* elements instead of 12, generated from the component registry so CI fails when they drift. Props map correctly for custom elements -- booleans become presence attributes, objects and arrays are assigned as element properties instead of being stringified, and onVelin* handlers bind the matching custom event (onVelinSearchSelect → velin-search-select). Ships TypeScript definitions and createVelinComponent for your own tags. Deprecated *-wc aliases are intentionally excluded.
CLI version:velinstyle --help reads the version from package.json instead of a hardcoded string that had drifted to 0.9.0.
Demo sync:tools/sync-demos-to-repo.mjs derives its unpkg pin from package.json rather than a hardcoded 0.9.0.
🐛
Fixed
Docs drift: stale @birdapi/velinstyle@0.9.0 install snippets and velin-meta version blocks across the site, plus a @0.4.0 CDN example in the framework docs landing page. The site guide generators now read the framework version instead of embedding it.
Component counts: the docs claimed 36 canonical components and 38 loader entries in 20+ places; both repos now report 38 and 40, and the guard keeps them honest.
Duplicate heading: the site accessibility page shipped the "Component contracts" section twice with the same id="contracts", because a one-shot patch script had been applied twice.
Site changelog copy: the a11y bulk-patch script rewrote a link inside the copied CHANGELOG.md, which made the copy permanently differ from the framework original. Verbatim copies (CHANGELOG.md, docs/generated/) are now excluded from that script.
Docs coverage audit:audit-docs-coverage.py crashed on Windows consoles because its report contains →; it now forces UTF-8 output, and recognises the two new component pages.
Release guard robustness: the repo walk crashed with ENOENT when a file disappeared mid-scan, which made the check fail intermittently alongside tests that use temporary directories. Dot-directories are now skipped and vanished files are ignored.
Build
npm run build regenerates the React wrapper sources; npm run build:react also bundles the package.
New CI gates: React wrapper drift and release sync.
The loader-count gate now derives its minimum from component-contracts.json instead of a hardcoded 36.
Full-bundle JS budget raised from 200 KB to 215 KB (209.4 KB actual, 46.9 KB brotli) to cover the two new components. Applications using register() / bootFromDOM() pay only for what they load.
Component names: canonical tags are <velin-tooltip> and <velin-stepper>; source files components/velin-tooltip.js and components/velin-stepper.js. <velin-tooltip-wc> and <velin-stepper-wc> remain as deprecated aliases (console warning once).
Spacing:.velin-mb-* is margin-bottom only; use .velin-my-* for block-axis spacing.
Visual: default text/primary tokens are darker for AAA — use data-velin-contrast="aa" on <html> if you need the previous lighter palette without retuning tokens.
Migration
Replace <velin-tooltip-wc> → <velin-tooltip> and <velin-stepper-wc> → <velin-stepper> in HTML; legacy tags still work in 0.9.0.
Imports: VelinTooltip / VelinStepper from @birdapi/velinstyle (or component paths); VelinTooltipWC / VelinStepperWC re-exported as deprecated.
🐛
Fixed
Security:velin-secure-field no longer emits plaintext or AES keys; hardened sanitizeURL / sanitizeSearchUrl; DOMPurify SVG sanitization in velin-icon; search result URLs validated.
Audit follow-up:velin-scroll-top declarative attribute; src/base/wc-placeholder.css CLS guards for all loader tags; velin-persist in component-contracts.json; Playwright cross-browser smoke (npm run test:e2e); shared docs theme picker assets (docs/assets/theme-picker.*).
Velin-Meta:velinstyle meta builds dist/velin-agent.json and dist/llms.txt for AI assistants; MIME application/vnd.velinstyle.meta+json; page-level <script id="velin-meta">; velinstyle meta page <file> --write; docs generate --scope meta; export @birdapi/velinstyle/meta.
WCAG 2.2 AAA defaults: OKLCH color tokens (:root, dark, 13 themes) validated at 7:1 via npm run test:contrast; data-velin-contrast="aa" opt-down to AA palette.
A11y runtime:@birdapi/velinstyle/a11y with initA11y() (live announcer, scroll padding); core/a11y/component-contracts.json; docs/generated/a11y/wcag22-aaa-matrix.md; npm run test:a11y:coverage.
Component a11y:a11y-utils.js, fixes for velin-icon, velin-search, velin-theme-toggle, velin-popover (aria-labelledby), dialogs, toasts, and more; scanner rules velin-icon-label, sparkline-label, skeleton-text.
VelinHighlight:core/highlight/ (velinSyntax, highlightElement, highlightAll, initHighlight, registerLanguage, lazyLoadLanguage); lexers for JS/TS, HTML, CSS, JSON, Markdown, Shell, SQL, PHP, Blade; highlight.css with OKLCH/P3 token colors and reduced-motion fade.
<velin-code-block> Web Component (copy, line numbers, line highlight, collapsible); velin-code attribute bridge with lazy in-view highlighting.
VelinSearch:core/search/ API (velinSearch, createSearch, registerSearchProvider), fuzzy offline search, highlight, category filters; optional Web Worker (core/search/worker.js).
<velin-search> Web Component with autocomplete, keyboard navigation, grouped results.
Search benchmark:tests/search-benchmark.test.js — fuzzy query over 10k entries (main thread under 400ms, worker under 500ms in CI); npm run test:search:bench.
Auto-generated reference:velinstyle docs generate / npm run docs:generate writes Markdown to docs/generated/ (components, tokens, utilities, CLI, scanner rules, a11y modules). CI verifies committed snapshots.
Tokens JSON:zIndex block in schema/build/validate; deterministic key order in tokens build; examples/tokens.full.json.
Changed
Documentation and samples: landmark structure (<header role="banner">), AAA migration section, updated docs/getting-started/accessibility.html (formerly docs/a11y.html) and token pages.
test:a11y enables color-contrast-enhanced; JSDOM canvas stub for axe in CI.
Package and CLI version 0.9.0; CI runs tokens:validate, test:security, test:perf, ci:checks (bundle budget, search-index drift, loader drift).
Package:. export → runtime-entry.js; full bundle at @birdapi/velinstyle/bundle; TypeScript dist/velinstyle.d.ts. Subpaths: /search, /motion, /attributes, /highlight, /sanitize. Distribution via velinstyle.info.
velin-reveal.js delegates to core/motion; attribute bridge uses <velin-tooltip> / lazy loaders from renamed component files.
Motion tokens: five new easings (spring, elastic, expo-out, back-out, snappy) and two new durations (slowest 800ms, cinematic 1200ms) in tokens/motion.css.
Filter-effect utilities: new utilities/filter-effects.css with velin-saturate-*, velin-hue-rotate-*, velin-contrast-*, velin-invert, velin-sepia, velin-drop-shadow-*, extended velin-backdrop-*, and velin-glass / velin-glass-strong composites.
Chart-animation utilities: new utilities/chart-animation.css with velin-stroke-draw, velin-sparkline-glow, velin-value-bump, velin-live-pulse, velin-count-fade keyframes and matching velin-chart-line / velin-chart-area / velin-chart-glow / velin-spark-tick / velin-live-pulse classes — all reduced-motion safe.
Three new Web Components:<velin-sparkline> (animated draw-in + live update() API), <velin-counter> (rAF + Intl.NumberFormat count-up with currency/percent/locale), <velin-live-dot> (slotted realtime indicator).
Two motion helpers:velin-reveal.js (initReveal() plus [data-velin-reveal-auto] auto-init) and velin-flip.js (flipReorder(), filterList() plus [data-velin-flip] + [data-velin-filter-value] / [data-velin-filter-input] auto-wiring).
Demo upgrades: crypto dashboard uses sparkline tick + counters + live-dot; forum and shop chips/searches drive real FLIP-animated list filtering; grid/list view toggle on the shop animates layout changes via FLIP.
CLI velinstyle scaffold: prompt-based HTML from blueprint composition (cli/scaffold.js, scaffold-recipes.json); list-intents, -o, --json.
CLI velinstyle layout:audit, suggest, and fix for flex/grid/responsive issues (cli/layout-audit.js).
Docs: new pages docs/utilities/motion.html, docs/utilities/filter-effects.html, docs/utilities/chart-animation.html, docs/components/sparkline.html, docs/components/counter.html, docs/components/live-dot.html; docs/guides/prompt-scaffolding.html, docs/guides/responsive-layout.html; layout and getting-started sections for 0.8.0 CLI.
Changed
src/velinstyle.css imports the new filter-effects + chart-animation utilities.
components/index.js exports the three new WCs and two helpers.
index.html drops the inline scroll-reveal IIFE in favour of the shared velin-reveal helper via data-velin-reveal-auto.
CLI help version 0.8.0; package version 0.8.0.
🚀
Added
velinstyle prefix JSON maps: optional velinstyle-prefix-map.json next to the migrated tree (or --map <file>) supplies explicit token → velin-class replacements; merged after auto map, overrides catalog and --bootstrap-display. Keys _* / $* ignored. Sample: examples/velinstyle-prefix-map.sample.json. Documented in README, README.de, docs/migration.html, docs/guides/existing-project.html.
Vitest / jsdom: tests/setup.js mocks window.matchMedia for velin-theme-toggle tests; velin-popover test now sets trigger="hover" so role="tooltip" is asserted correctly.
Drawer CSS: Fixed side="end" drawer showing content and not closing due to inset-inline-start: 0 leaking to all sides. Each side now explicitly resets opposing inset values.
FOUC Protection: Added :not(:defined) rule in reset.css hiding VelinStyle custom elements until they are registered, preventing flash of unstyled content.
CLI require() bug: Replaced CJS require('fs').unlinkSync with ESM unlinkSync import in cli/index.js.
CLI version: Updated help text to v0.6.1.
CLI a11y layer: security.css now included in the a11y layer file list.
Multi-Provider Icon System: <velin-icon> now supports a provider attribute for CDN-based icons from Lucide, Heroicons, Bootstrap Icons, Material Symbols, Font Awesome, and Tabler Icons.
VelinIcon.registerProvider(): Static method to register custom icon providers at runtime.
cli/icon-providers.js: Provider registry with CDN URL mappings, variant support, license info, and homepage links for 6 providers.
Design Tokens: OKLCH color palette, spacing scale (4px base), typography scale (1.25x Major Third), border-radius, shadows, motion, z-index, and aspect-ratio tokens
Dark Mode: Automatic via prefers-color-scheme and explicit via data-velin-theme="dark" attribute
Modern CSS Reset: box-sizing: border-box, scroll behavior, motion reduction, min font-size for mobile inputs
Accessibility Layer: .velin-sr-only, .velin-skip-link, :focus-visible outlines, prefers-reduced-motion support, forced-colors (Windows High Contrast) support, skeleton loading with CLS protection
Layout System: Responsive container with Container Queries, CSS Grid with auto-fit/auto-fill, Flexbox utilities, stack and cluster patterns
BEM Components: Button (6 variants + 4 sizes), Card, Form inputs, Navigation, Alert, Badge, Table, Tooltip, Modal (CSS)
Utility Classes: Flex, spacing, text alignment, display, visibility, color utilities
Web Components: <velin-modal>, <velin-tabs>, <velin-accordion>, <velin-dropdown>, <velin-toast>, <velin-icon> with full keyboard and screen reader support
Focus Manager: Shared module with trapFocus(), rovingTabindex(), saveFocus(), restoreFocus()
Icon System: 51 essential SVG icons with sprite builder and <velin-icon> component