Limitations

Blenx is a UI component library styled with Vanilla Extract. It is not an animation framework, a routing library, a data-fetching client, or a state management solution. These boundaries are deliberate.

Animations. Blenx components ship with minimal transitions (opacity fades for overlays, height transitions for accordions). Complex, choreographed animations are outside the scope. Use framer-motion, react-spring, or CSS @keyframes for animation work. Blenx components accept className and style props—wire up animation libraries at the call site.

Data fetching. Blenx does not provide useQuery, useMutation, or any data-layer abstraction. Use React Query, SWR, Apollo, or your framework's data fetching. Blenx components render the data you provide; they do not fetch it.

Heavily animated or interactive UIs. Blenx's composition model and Vanilla Extract's build-time compilation are optimized for static and moderately dynamic UIs. If your application is a design tool, a game, or a data visualization with thousands of animated DOM elements, the component abstraction adds overhead that may not be justified. Use primitives (Box) directly or drop to raw DOM.

Projects without Vanilla Extract build plugin support. If your bundler, framework, or deployment platform does not support the Vanilla Extract plugin, Blenx components will not render styled output. This is a hard requirement. Check that your toolchain supports @vanilla-extract/vite-plugin or @vanilla-extract/next-plugin before adopting Blenx.

Vanilla Extract is not a general-purpose CSS engine. It makes deliberate tradeoffs that affect how you write styles.

Build-time compilation. Vanilla Extract compiles .css.ts files into static CSS files at build time. You cannot dynamically construct a style from user input or API response. Dynamic values must use CSS custom properties (via createThemeContract()) or inline style props.

File separation. Unlike CSS-in-JS solutions that allow colocated styles in .tsx files, Vanilla Extract requires styles to be defined in separate .css.ts files. This enforces a file structure pattern that may feel verbose for small components.

Learning curve. Developers accustomed to runtime CSS-in-JS (styled-components, Emotion) find Vanilla Extract's static extraction model unfamiliar. The .css.ts file convention, sprinkles API, and recipe patterns require ramp-up time for new team members.

No style reuse via className concatenation. Vanilla Extract encourages composition through recipe patterns, not string concatenation of class names. You cannot write className={condition ? 'styleA' : 'styleB'} with raw strings—styles must be composed at build time.

For historical context, Blenx previously used StyleX as its styling foundation. Future documentation will detail StyleX-specific limitations and how the migration to Vanilla Extract addressed them.

Build step required. Registry installation copies files into your project. Those files contain TypeScript and Vanilla Extract code that must be compiled. There is no pre-compiled CSS file to link in your HTML head. Every Blenx installation requires a build pipeline.

No CDN delivery. Because components are source files, there is no Blenx CDN URL to drop into a static HTML page. Blenx is designed for projects with build tooling, not for traditional server-rendered pages or static site generators that lack a build step.

Monorepo required for development. Contributing to Blenx or running the registry locally requires a monorepo setup with the registry server and the CLI. Single-package projects cannot develop components against the registry—they must install from a published registry URL.

No automatic upgrades. Registry installations are snapshots. Upstream fixes do not flow into your project unless you manually diff and merge. This is a feature for customization-minded teams and a burden for teams that prefer "set and forget" dependency management.

More imports. A page composed of Blenx primitives imports Box, Stack, Grid, Text, Surface, and Container across its component tree. Compare to a single <Card> import from a monolithic library. The import overhead is negligible for bundlers with tree-shaking, but the file-level verbosity is real.

Verbose call sites. Composing a Card from primitives takes 7–10 lines. A <Card> component from a monolithic library takes 1 line. The composition approach is more flexible and more explicit, and it is also more code in your source files.

No short-form syntax. Blenx does not provide <HFlex> as an alias for <HStack> or <VFlex> for <VStack>>. Every primitive uses its full name. This is intentional—abbreviations obscure meaning for new readers—but it adds characters to every usage.

Blenx is pre-1.0 software. Breaking changes are possible between minor versions as the API stabilizes. The registry model mitigates the impact (your installed copies do not auto-update), but the upstream API may shift in ways that require manual migration.

Key areas of potential change:

• Contract variable names and organization
• Component prop naming and type signatures
• Registry manifest schema
• CLI command naming

Each breaking change is documented in a migration guide and the registry supports version pinning. You are never forced to update, but staying current may require effort.

Blenx is not mobile-first. The default themes and components are designed for desktop-width viewports with responsive adjustments for mobile. The Stack, Grid, and Container primitives accept responsive values, but you must provide the breakpoint definitions.

If your primary audience is mobile users, or if you are building a mobile-first web application, evaluate whether Blenx's desktop-oriented defaults save you time or add overhead. The primitives are responsive—they do not prevent mobile-first design—but they are not optimized for it out of the box.

Vanilla Extract requires styles to be authored in .css.ts files. These files are evaluated at build time by the VE build plugin, which means:

• Imports from .css.ts files return class name strings (not style objects)
• You cannot conditionally import .css.ts files
• Dynamic values (props, state) must use CSS custom properties (createThemeContract()) or runtime style objects

This file convention differs from colocated CSS-in-JS approaches. If you prefer writing styles directly in component files, Vanilla Extract's file separation may feel restrictive.

Every tool makes tradeoffs. Blenx optimizes for consistency, accessibility, performance, and maintainability. It trades automatic updates, runtime flexibility, and mobile-first defaults to achieve these goals. If those tradeoffs align with your project's constraints, Blenx will serve you well. If they do not, the honesty of this documentation should help you decide before you invest in the tooling.

Choose tools based on your actual constraints, not on what is popular or new. Blenx is unapologetically opinionated about its tradeoffs, and that opinion is not right for every project.