The UI Framework for Perfectionists

🎢

Install • Documentation

Figma • Webflow Template

This is a community project. It is not officially supported by Chainlift. However, this may change in the future. To get notified about official updates, sign up at chainlift.io/liftkit.

Features

<div class="mt-md bg-primary text-onprimary"> Liftkit </div>

<div class="mt-4 bg-amber-900 text-black"> Tailwind v4 </div>

• Full Tailwind v4 support - Complete compatibility with the latest Tailwind CSS features
• Golden ratio spacing utilities - Intuitive spacing with classes like mt-md, p-lg, etc.
• Dynamic color utilities - Smart color system with bg-primary, text-onprimary, etc.
• Custom LiftKit utility classes - Enhanced utilities that work alongside standard Tailwind
• Dynamic color system - Powered by Material Design 3 color principles

Installation

Prerequisites

• A Next.js project set up
• Tailwind v4 installed and configured

Step 1: Install the Liftkit CLI

Add the LiftKit CLI to your project as a development dependency:

npm install @chainlift/liftkit --save-dev

Initialize LiftKit in your project:

npx liftkit init

Note: When prompted, accept both options to:

• Add the script to your package.json
• Install shadcn/ui as a dev dependency

Step 2: Import Import LiftKit Styles:

Add the LiftKit CSS import to your globals.css file:

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

Step 3: Add Components

Install all available components from the LiftKit registry:

npx liftkit add https://lk-tw.pages.dev/r/all.json

That's it! Now you can use Tailwind CSS(v4) with Liftkit utility classes.

What is LiftKit?

LiftKit is a UI framework based on the golden ratio. at the core, set of formulas provide golden values with material 3 color system.

It fully supports Tailwind v4 plus LiftKit's custom utility classes and remains fully backward-compatible.

How It Works

The CSS layer structure ensures proper precedence:

• theme: Tailwind's CSS custom properties and design tokens
• lk-base: LiftKit's core styles and Tailwind's preflight/reset
• components: Component-specific styles
• utilities: Utility classes (highest precedence)

This setup allows you to use both standard Tailwind utilities and LiftKit's golden ratio utilities together:

<div class="mt-md bg-primary text-onprimary"> Liftkit </div>

<div class="mt-4 bg-amber-900 text-black"> Tailwind v4 </div>

The utilities layer has the highest precedence, allowing Tailwind utilities to override LiftKit base styles when needed, while still preserving LiftKit's golden ratio system and Material 3 colors.

Utility Classes

Use both standard Tailwind utilities and custom golden ratio utilities:

Tailwind v4

<div class="mt-4 w-40 bg-amber-900 rounded-lg">
  Standard Tailwind styling
</div>

LiftKit Golden Ratio Classes

<div class="mt-md p-lg bg-primary text-onprimary">
  Golden ratio spacing with dynamic colors
</div>

Available LiftKit Utilities

Spacing (Golden Ratio Based):

• m-xs, m-sm, m-md, m-lg, m-xl
• p-xs, p-sm, p-md, p-lg, p-xl
• mt-md, mb-lg, ml-sm, etc.

Dynamic Colors (Material 3):

• bg-primary, bg-secondary, bg-tertiary
• text-onprimary, text-onsecondary
• border-outline, bg-surface

The CSS layer structure ensures proper precedence:

/* Left to right, right has most power */
@layer theme, lk-base, lk, utilities;

Configuration

Configuration is done through the components.json file and optional tailwind.config.ts. The system is designed to work seamlessly whether you use Tailwind or not.

Preview example configuration

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

Common Issues

React 19 compatibility warnings

If you see warnings about React 19 compatibility when installing components, add --force to your install command:

npm run add button --force

This is a known issue with the current registry system and doesn't affect functionality.

Why did it install CSS for components I'm not using?

This is by design to let you experiment freely with different components. Unused styles are automatically removed at build time through tree-shaking.

Tailwind classes not working with LiftKit

Ensure your CSS layer structure is correct in globals.css. The utilities layer should come last to have proper precedence over LiftKit base styles.

FAQ

Do I need Tailwind CSS to use LiftKit?

No—LiftKit works independently. However, Tailwind v4 integration provides additional utility classes for enhanced flexibility.

Can I use LiftKit with other CSS frameworks?

Yes, LiftKit is designed to be framework-agnostic, though it works best with modern CSS-in-JS solutions and PostCSS.

How does the golden ratio improve my UI?

The golden ratio (1.618) creates naturally pleasing proportions. LiftKit applies this mathematically to spacing, sizing, and color relationships for more harmonious interfaces.

What's the difference between LiftKit utilities and Tailwind utilities?

LiftKit utilities are based on the golden ratio and Material 3 design principles, while Tailwind utilities use standard linear scales. You can use both together.

Contributing

Currently repo is maintained by me.

We welcome contributions to LiftKit! Here are some guidelines:

• Submit feature requests before implementing major changes
• Use the dev branch for new features and bug fixes
• Maintain compatibility with existing utility classes
• Follow the golden ratio principles in new components
• Provide screenshots for UI-related changes
• Keep bundle size minimal - avoid unnecessary dependencies

Building from Source

Development Setup

Requirements: Node.js >= 16, npm

# Clone the repository
git clone https://github.com/jellydeck/liftkit-tailwind
cd liftkit-tailwind

# Install dependencies
npm install

# Build the project
npm run build

# Run development server
npm run dev

---

Thank you

Garett Mack

Liftkit Team