Chainlift LiftKit: a CSS scaling system that says it is not production ready

The problem LiftKit claims to solve, and who it is aimed at

Most component libraries hand you a Button and leave the numbers to you. You pick the padding, the gap, the font step, the hover color. LiftKit takes the opposite position: it exposes a system of formulas for scaling, spacing and color that, in the README's words, "automatically enforce design best practices such as optical symmetry, balanced proportions, and smooth color ramps." The pitch is that you become a better designer by using the framework, because the framework refuses to let you pick arbitrary values.

The audience is narrow and the README is honest about it. Support is currently limited to Next.js without Tailwind. The project is maintained by Chainlift, which the README describes as itself maintained entirely by part-time contributors, and the stated reason for the narrow support matrix is time and availability rather than a technical boundary. If you are a designer who writes some Next.js, or a small team without a dedicated design system owner, the offer is real: you inherit proportions instead of inventing them.

If you are an engineer who wants to control every value, the same offer reads as a constraint. The formulas are the product. There is no escape hatch described for opting out of the scale, which is the trade you are making.

How the formulas, registry and tree-shaking fit together

LiftKit splits into two pieces. LiftKit Core is the base configuration: the scaling, spacing and color definitions. LiftKit Components are the actual UI components plus their CSS. The README is explicit that Core is "just the base config."

The distribution mechanism is a shadcn registry. The repository contains registry.js, registry.json and a registry/ directory, and the package.json defines a script named registry that runs node ./registry.js followed by shadcn build. So the components are not imported from a published runtime package in the usual sense. They are copied into your project by the CLI, which is why the README can say that unused CSS is tree-shaken away at build time: the CSS lands in your source tree and your bundler decides what survives.

That design has a consequence worth naming. Because components arrive as source plus CSS, the framework's updates do not reach you through a version bump. You re-run the add command for a component, or you diff it yourself. The README's FAQ confirms the second half of this: installing one component can pull in others, because some components import others, and installing Badge also brings in Icon. You are not composing a dependency graph, you are copying files that reference each other.

The CSS tooling around this is heavier than the framework's own footprint suggests. package.json includes stylelint with stylelint-no-unsupported-browser-features, plus @eslint/css and @eslint/json in devDependencies. Those are guardrails for the registry's own CSS, and they tell you the maintainers care about browser support in the stylesheets they ship.

Installing LiftKit in an existing Next.js project

The README gives two routes. The fastest is cloning the template repository, which is a blank Next.js project with Core's config files already in place. The second route adds LiftKit to a project you already have, and that is the one worth walking through because it shows what the CLI actually touches.

Start from your project root and install the CLI as a dev dependency. The package name is scoped to the organization, not to the repository name:

npm install @chainlift/liftkit --save-dev

Then initialize. The README says the command adds two files to your project root, components.json and tailwind.config.ts, and that you will be prompted about adding an add script to package.json and about installing shadcn as a devDependency. Say yes to both:

npx liftkit init

The tailwind.config.ts file is the part that surprises people. The README addresses it directly: you do not need Tailwind itself to use LiftKit, only the config file, because the current registry requires one. Tailwind is not a dependency.

With the config in place, install the components you want. The README lists three forms: everything, a single component by kebab-case name, or base for CSS and types only.

npm run add base
npm run add all
npm run add component-name-kebab-case

Finally, import the CSS into your app's globals.css so the styles are reachable from your entry point:

@import url("@/lib/css/index.css");

One operational note from the README: if npm warns you about React 19 compatibility, add --force and continue. The template route has its own quirk, a direnv error during setup that the README says to ignore.

The production warning and the Button variants problem

The most important line in the repository is a warning block at the top of the README. It states that the current version of LiftKit was developed by a designer without consulting professional developers, and that the project is being rewritten to satisfy modern best practices, with new components wrapping Base UI primitives. As of March 4, 2026, the README puts that rewrite at about 50% complete. The heading of the warning is unambiguous: NOT RECOMMENDED FOR PRODUCTION USE.

That is not a hedge added by a cautious lawyer. It is the maintainers telling you the API surface is expected to move. If you build on the current components, plan for the rewrite to be a migration rather than an upgrade.

The Known Issues section backs this up with a concrete example. Button variants are described as out of control. The specific mechanism: buttons adjust their padding based on whether an icon is present, and those padding values are not controllable through props. The README says the only option available was to list every variant explicitly, and calls that a bad idea in hindsight. If your design needs a button whose padding you set yourself, this is the wrong component at the wrong time.

The second known issue is documentation of the Figma local variables. Figma does not support margins or em units, so the variables were converted to pixels on the assumption that 1rem equals 16px. Variables are split into a Global collection holding base LkSizeUnit variables and a Text Spacing Vals collection holding subsets per LkFontClass. If your design work happens at a root font size other than 16px, that assumption is baked into the file.

LiftKit without Tailwind, and what that changes

The README's FAQ answers the Tailwind question plainly: LiftKit does not require Tailwind, only a tailwind.config.ts file, which it calls a requirement of the current registry. This is a meaningful distinction. A shadcn registry expects that config file to exist, so LiftKit writes one and then does not use Tailwind's utility classes.

The practical effect is that you get components with their own CSS rather than a pile of utility classes in your markup. For a team that has avoided Tailwind, that is the selling point. For a team already standardized on Tailwind, it is friction: you now have a tailwind.config.ts in the repo that is not driving your styling, and a second styling system alongside the one you already use.

The community fork points at the same gap. The README lists liftkit-tailwind, owned by a different GitHub account, as a community project that is not officially supported, with support handled by that project's owner. So the Tailwind-native path exists, but it is outside the official repository and outside Chainlift's support boundary. If you need Tailwind integration and official support at the same time, the README does not offer both.

What to use instead, and how the approaches differ

The obvious alternative is shadcn/ui on its own, and the comparison is not abstract because LiftKit's own pipeline runs through shadcn: the package.json pins shadcn at 2.4.0-canary.12 and the registry script ends with shadcn build. The difference is where the design decisions live. shadcn gives you components as source that you own and restyle freely, with no opinion about your spacing scale or color ramp. LiftKit keeps the same copy-into-your-repo distribution model but adds a layer of formulas that decide those values for you.

So the choice is not components versus components. It is whether you want a system that constrains your numbers. If your team already has a spacing scale and a color ramp, shadcn alone is the lower-friction path, and adding LiftKit means maintaining a second set of rules that will disagree with yours somewhere. If you do not have those rules and do not want to write them, LiftKit's formulas are the reason to pick it over plain shadcn.

A second alternative, for teams that want an opinionated system with a longer support horizon, is any established component library with a published runtime package. The trade is different in kind: you get versioned updates through your package manager instead of re-running a CLI, but you give up owning the component source. LiftKit sits at the opposite end of that spectrum, and the README's warning about the rewrite is the cost of sitting there.

Licence, maintenance and what an upgrade costs you

The repository's LICENSE file and the GitHub metadata both point to Apache-2.0, and the README's own badge links to GPL2. That is a real discrepancy in the project's own materials, and it is worth resolving before you rely on either. If you need a definitive answer for your organization, read the LICENSE file in the repository root rather than the badge, and treat the badge as stale. Nothing here is legal advice.

On maintenance: the repository is not archived, and the last push was on 2026-06-10. The README's rewrite note is dated March 4, 2026 and describes the work as roughly half done. Those two data points together describe a project that is moving but has not arrived, and the README says so in its own voice. The project is maintained by part-time contributors, and the README states that Chainlift itself is maintained entirely by part-time contributors.

Upgrade cost is the part most teams underestimate. Because components are copied into your repository, there is no npm update that brings you the rewritten components. You will re-run npm run add for each component you use, then reconcile the diff against your local edits. If you have customized a component, that reconciliation is manual work per component. The README's offer of an email notification list at chainlift.io/liftkit is the maintainers' answer to this, which tells you they expect the rewrite to be a discrete event rather than a rolling release.

Editorial conclusion

Adopt LiftKit if you are prototyping in Next.js without Tailwind and want spacing and color decisions made for you by a formula rather than by hand, and you accept that the README itself says the current version is not recommended for production. Do not adopt it if you need Vue, Svelte, plain HTML, or a Tailwind-based pipeline, because the README states only Next.js without Tailwind is supported today. Before committing, verify three things: that your project is on React 19 and you are willing to pass --force when npm warns about compatibility, that the components you need are not among the ones the README lists under Known Issues, and that you can live with a registry that installs more CSS than you use. The upgrade path is the open question: the README describes a rewrite around Base UI primitives that was about 50% complete as of March 4, 2026, and the last push to the repository was on 2026-06-10, so check the repository and the notify list at chainlift.io/liftkit before you build anything you cannot redo.

Frequently asked questions

Official sources

1. Chainlift/liftkit on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases