Troubleshooting 1.3.0

npx velinstyle → 404

Package name is @birdapi/velinstyle.

npx @birdapi/velinstyle --help

create / check / skills unknown

Those are the 1.2+ ship surface. Install @birdapi/velinstyle@1.4.0 (or later), or run the CLI from a local clone.

Windows path / ESM import errors

Load ESM via pathToFileURL. Run velinstyle doctor. Avoid raw d:\… dynamic imports.

doctor warns about missing vendor CSS

Copy dist/ into vendor/velinstyle/ (or use create), or install the package so node_modules/@birdapi/velinstyle/dist exists.

check . floods findings

You pointed it at a docs/demo monorepo. Use a scaffold or a single file:

velinstyle check ./index.html --profile docs
velinstyle scan ./src --severity error

Review fails on admin pages

Pass the right profile: marketing · app · docs · fragment · ecommerce.

velinstyle check . --profile app

Unknown velin-* classes

Class drift vs CSS. Prefer documented utilities, or run blueprint --strict in the framework repo.

Nested interactive / aria-hidden

Real a11y defects — fix markup; don’t silence the rule.

Blank styles after clone

dist/ is generated — run npm install && npm run build.

Icons missing

Ensure velin-icons.svg is next to CSS, or set <meta name="velin-icon-sprite" content="…">.

Theme CSS 404

Themes live under dist/themes/. Point velin-theme-toggle / data-velin-themes-base there.

Custom element not upgrading

Load the components bundle (or register the tag). Placeholders: wc-placeholder.css reduces CLS before upgrade.

React props not applying

Use @velinstyle/react wrappers — booleans become attributes; objects are properties; onVelin* maps to custom events.

AI clip fails without a key

Create a PixVerse account + API key, then velinstyle motion setup pixverse. CI with --yes + AI and no key exits 1. Guide: PixVerse.

Clip input rejected

Only non-empty .webp / .png / .jpg / .jpeg with real image magic bytes.

Recommended path

1. velinstyle doctor
2. velinstyle check … --json
3. BirdAPI Forum or GitHub issues