CT
ChaiTailwind v2.0
GitHub

ChaiTailwind 2.0

Developer Documentation

A lightning-fast, runtime-optimized CSS-in-JS utility engine. Styled like standard Tailwind but executed purely in the browser under 1ms.

Getting Started #

ChaiTailwind is incredibly easy to set up. It doesn't require a build step; instead, it generates utility classes on-the-fly right in the browser.

1. Installation 

npm i chai-tailwind-lemi

2. Usage

Initialize the runtime in your main JavaScript file. Once init() is called, ChaiTailwind will:

  • Scan the DOM for any classes matching the chai-* prefix.
  • Generate CSS dynamically for exactly those specific utility classes.
  • Inject styles directly into a dedicated <style> tag in your browser's head. 
import { init } from 'chai-tailwind-lemi';

// Start the runtime observer
init();

Simple Visual Demo

Write your HTML using the chai- prefixed utility classes. The styles are applied instantly! 

<button class="chai-px-6 chai-py-2 chai-bg-purple-600 chai-text-white chai-rounded-lg chai-font-bold chai-hover-bg-purple-700 chai-transition">
  Interactive Button
</button>

How It Works #

ChaiTailwind is a Lightning-fast JIT (Just-In-Time) engine running entirely within your browser. There are no build tools, node pipelines, or CLI watchers required.

The Execution Flow

code DOM
arrow_forward
search chai-*
arrow_forward
psychology Parse
arrow_forward
build Generate CSS
arrow_forward
html Inject
  • Runtime CSS Generation When a chai- prefixed class is discovered on an element, the engine translates the semantic class name (e.g., chai-bg-blue-500) directly into raw CSS representing that specific utility on the fly.
  • Class Parsing System ChaiTailwind features a robust regex and dictionary-based parser to decode variants (like hover- or md-) and match colors or spacing values efficiently against a strict internal token map.
  • Style Injection & <style> Tag Instead of modifying inline styles, standard CSS rules are concatenated and automatically injected into a managed <style data-chai-runtime="true"> element located inside the document's <head>.
  • MutationObserver Upon initialization, ChaiTailwind attaches a native MutationObserver to the document body. Moving forward, anytime a developer manipulates the DOM (like adding a new element via JavaScript), the engine automatically detects it, parses its classes, and injects any newly required CSS.
  • Caching System To ensure optimal performance and avoid duplicate CSS rules, every generated and injected class is tracked in an internal Set cache. A class is only ever processed and injected once per session.

Display & Position #

Discover all core display and positioning utilities available in ChaiTailwind. Use these to structure and position elements effortlessly.

Display

Class CSS Output Visual Example
chai-flex display: flex;
chai-grid display: grid;
chai-block display: block; Block Level Element
chai-inline display: inline-block; Text with inline-block styles applied.
chai-hidden display: none;
Visible Element Hidden Element

Position

Class CSS Output Visual Example
chai-relative position: relative;
Relative Container
chai-absolute position: absolute;
Absolute
chai-fixed position: fixed;
Fixed element (rendered inline here for preview)

Position Offsets #

ChaiTailwind includes specific utilities for pinning and nudging elements that have been taken out of standard document flow (using relative, absolute, or fixed positioning).

Properties Covered

  • Top: chai-top-{0-300}
  • Right: chai-right-{0-300}
  • Bottom: chai-bottom-{0-300}
  • Left: chai-left-{0-300}

How Offsets Work

These utilities map against the exact same proportional scale used for spacing and sizing. The numeric index is multiplied by exactly 4px. For example, applying chai-left-10 compiles to left: 40px; in CSS. Using these utilities perfectly positions elements marked as absolute or fixed relative to their nearest positioned ancestor container.

Examples

Offset Positioning Demo
Relative
Parent
chai-top-4 (16px)
chai-left-4 (16px)
chai-bottom-8 (32px)
chai-right-8 (32px)
chai-top-0
chai-right-0

Flex & Alignment #

ChaiTailwind makes building flexible layouts extremely seamless using Flexbox utilities.

How Flex Works

By applying the chai-flex utility to a container, it generates a flexible container block context. Once established, you can use directional arrows (like chai-flex-col) or alignment helpers (like chai-justify-between) to predictably configure and perfectly position the child elements along either the primary or cross axis.

How Alignment Utilities Affect Layout

Alignment utilities instruct the browser on how to distribute free space within the flex container. For instance, chai-justify-between pushes the first child to the start, the last child to the extreme end, and evenly distributes remaining items along the main axis. Using chai-items-center aligns the items perfectly centralized along the cross-axis, ensuring they are vertically centered if it's a standard horizontal row setup.

Flex Utilities

Class CSS Output Visual Example
chai-flex-col flex-direction: column;
1
2
3
chai-justify-between justify-content: space-between;
Start
End
chai-items-center align-items: center;

Spacing #

ChaiTailwind uses a highly predictable proportional spacing scale for all padding and margin utilities. The scale runs steadily from 0 to 300.

Scale Calculation: Multiply the utility index by 4px.
Scale Value = Index × 4px (e.g., 10 = 40px, 20 = 80px).

Properties Covered

  • Padding: chai-p-{0-300}, chai-px-{0-300}, chai-py-{0-300}
  • Margin: chai-m-{0-300}, chai-mx-{0-300}, chai-my-{0-300}

Examples & Visual Demos

chai-p-20 padding: 80px;
Content Area
padding (80px)
chai-mx-10 margin-left: 40px; margin-right: 40px;
Element
mx (40px)
mx (40px)

Sizing #

ChaiTailwind includes precise utilities directly focused on setting absolute widths and heights.

Full Sizing

Force an element to span 100% of its parent container's width or height.

Class CSS Output Visual Preview
chai-w-full width: 100%;
100%
chai-h-full height: 100%;
100%
height

Dynamic Scale

Scale Calculation: The scale runs dynamically from 0 to 300.
Scale Value × 4px = Final Size
  • Widths: chai-w-{0-300}
  • Heights: chai-h-{0-300}
chai-w-50 width: 200px;
50 × 4px = 200px
chai-h-100 height: 400px;
100 × 4px = 400px

Colors #

ChaiTailwind includes a predefined set of beautiful colors. Apply them to backgrounds, text, and borders effortlessly.

Supported Colors & Shades

  • Colors: gray, red, green, blue, indigo, purple, pink
  • Shades: Ranges from 50 (extremely light) to 900 (extremely dark). Note that gray also includes a 950 shade.

Color Utilities

  • Backgrounds: chai-bg-{color}-{shade}
  • Text: chai-text-{color}-{shade}
  • Borders: chai-border-{color}-{shade}
  • Core Colors: chai-bg-white, chai-bg-black, chai-bg-transparent

Examples Showcase

chai-bg-blue-500

Background Blue

chai-text-red-600

Danger Text

chai-border-purple-500

Purple Border

Core Base Backgrounds

chai-bg-black
chai-bg-white
chai-bg-transparent

Color Palette Grid

gray-500
red-500
green-500
blue-500
indigo-500
purple-500
pink-500

Shade Scale Validation (Gray with 950)

50
100
200
300
400
500
600
700
800
900
950

Color Opacity #

ChaiTailwind natively supports controlling the alpha channel (opacity) of any color directly within the utility class name.

Syntax & Conversion

To apply an opacity modifier, append a forward slash / followed by a percentage value (from 0 to 100) to any color class (e.g., chai-bg-blue-500/50).

Under the Hood: The engine automatically detects this fractional modifier, checks its internal token dictionary map for the corresponding mapped color hex code, effortlessly converts that flat hex code to RGBA on the fly, and injects the requested percentage as the alpha channel value.

Examples

Background Highlights (chai-bg-blue-500/*)

/10
/30
/50
/70
100%

Alpha Text Reading (chai-text-black/*)

black/20
black/50
black/80

Typography #

ChaiTailwind features a streamlined typographic scale and effortless alignment tools for text.

Font Sizes

Use the chai-fs-* utilities to scale font sizes proportionately. Here is the font size scale comparison:

Class CSS Output Visual Preview
chai-fs-10 font-size: 3rem; Hero Text
chai-fs-6 font-size: 1.5rem; Heading Text
chai-fs-5 font-size: 1.25rem; Large Text
chai-fs-4 font-size: 1.125rem; Medium Text
chai-fs-3 font-size: 1rem; Base Text
chai-fs-2 font-size: 0.875rem; Small Text
chai-fs-1 font-size: 0.75rem; Extra Small Text

Weight & Alignment

Apply text alignment and font weight adjustments to your text elements.

Class CSS Output Visual Example
chai-font-bold font-weight: 700;

The quick brown fox jumps over the lazy dog.

chai-text-center text-align: center;

The quick brown fox jumps over the lazy dog.

Border Radius #

ChaiTailwind provides simple and effective utilities for rounding the corners of your elements.

Supported Utilities

  • Large Radius: chai-rounded-lg compiles to border-radius: 12px;.
  • Full Radius: chai-rounded-full compiles to border-radius: 9999px;.

Visual Examples

chai-rounded-lg

12px

chai-rounded-full

9999px
(Circle)

Grid System #

ChaiTailwind provides a powerful foundational 12-column CSS Grid system for building rigid and predictable layouts.

Properties Covered

  • Columns: chai-cols-1 to chai-cols-12
  • Gaps: chai-gap-{0-300}
How it works:

▪ chai-cols-{n} compiles to grid-template-columns: repeat({n}, minmax(0, 1fr));.

▪ chai-gap-{n} sets the gutter size between rows and columns based strictly on the proportional scale (Index × 4px).

Layout Examples

2 Column Layout: chai-cols-2 chai-gap-4

1
2

3 Column Layout: chai-cols-3 chai-gap-4

1
2
3

4 Column Layout: chai-cols-4 chai-gap-4

1
2
3
4

Transitions #

ChaiTailwind includes a straightforward utility for applying smooth transitions to elements, particularly useful for hover and focus states.

Properties

  • chai-transition compiles strictly to transition: all 0.3s ease;.

Interactive Example

Hover the button below

Animations #

ChaiTailwind ships with powerful built-in CSS keyframes categorized for standard interactions. Add the chai-animate-* utility to instantly bring elements to life.

Entry Animations

Designed to gracefully transition elements into the viewport or component tree.

chai-animate-fade

Smooth opacity transition from 0 to 1.

fade

chai-animate-slide-up

Translates upward on the Y-axis while fading in.

slide
up

chai-animate-slide-down

Translates downward on the Y-axis while fading in.

slide
down

chai-animate-slide-left

Translates horizontally to the left while fading in.

slide
left

chai-animate-slide-right

Translates horizontally to the right while fading in.

slide
right

Transform Animations

Modifiers focusing on scale and rotation manipulation.

chai-animate-scale

Pops the element into view by scaling up from 0.

scale

chai-animate-scale-out

Scales down out of view back to 0.

scale
out

chai-animate-rotate

Spins seamlessly 360 degrees infinitely.

rotate

chai-animate-zoom-in

Starts small and scales up to 1 over time.

zoom
in

chai-animate-zoom-out

Starts at native size and scales further out.

zoom
out

3D Perspectives

Create 3D flip card visual effects natively.

chai-animate-flip-x

Rotates via 3D perspective along the X axis.

flip x

chai-animate-flip-y

Rotates via 3D perspective along the Y axis.

flip y

Attention Seekers

Designed to immediately draw user focus to a specific element on the page.

chai-animate-swing

Swings from an upper origin.

chai-animate-pulse

Expands scaling up rhythmically.

chai-animate-bounce

Bounces vertically.

chai-animate-heartbeat

Sharp double-scale pulse.

chai-animate-flash

Flashes in and out rapidly.

chai-animate-shake

Shakes horizontally violently.

Animation Modifiers #

Fine-tune the behavior of ChaiTailwind's built-in animations and transitions seamlessly. These utilities modify native CSS custom variables --chai-duration, --chai-delay, and --chai-ease under the hood to ensure fluid orchestration.

Supported Modifiers

Timing Control

  • Duration chai-duration-{50-5000} configures how long an animation takes to complete. Steps mimic milliseconds.
  • Delay chai-delay-{75-1000} configures the resting threshold before playback begins.

Curves & Speed

  • Easing chai-ease-linear, chai-ease, chai-ease-in, chai-ease-out, chai-ease-in-out modify the acceleration curve.
  • Semantic Speed chai-ultra-fast, chai-very-fast, chai-fast, chai-normal, chai-slow, chai-very-slow, chai-ultra-slow map safely to predefined MS ranges.

Combined Examples

See how combining these utilities manipulates the animate-bounce loop.

Fast & Linear

duration-300
ease-linear

Ultra Slow Delay

ultra-slow
delay-500

High Duration Smooth

duration-2000
ease-in-out

Variants #

Variants are powerful prefixes that tell the ChaiTailwind engine to conditionally apply styling based on interaction or theme states.

How Selectors are Modified

When the Chai parser parses a class prefixed with a variant like chai-hover:bg-red-500, it escapes the special characters and modifies the generated CSS selector before heavily injecting it into the stylesheet.

  • Interaction state variants append pseudo-classes explicitly to the end of the selector (e.g., .chai-hover\:bg-red-500:hover).
  • Theme variants prepend a parent scope selector to ensure it only cascades down conditionally (e.g., .dark .chai-dark\:bg-black).

Hover & Group Hover Mechanisms

Use chai-hover:* to style an element on :hover mouseover. To style an element dynamically based on an ancestor's interaction state, tag the ancestor with the group class and apply chai-group-hover:* on the target child. This compiles to the CSS syntax: .group:hover .chai-group-hover\:*.

chai-hover:bg-red-500
chai-group-hover:text-blue-500
verified Hover the wrapper

The .dark Class Modifier

Use the chai-dark:* prefix to serve specific utility properties only when Dark Mode is fully active. Instead of media queries, ChaiTailwind tightly binds dark variants to the .dark parent class selector. This dictates that you seamlessly apply or drop the class="dark" label on the <html> element to safely orchestrate a global theme toggle manually.

Card Subject to System Theme

This card leverages chai-dark-bg-gray-800 and chai-dark-text-white heavily. Because the documentation site typically injects .dark on the root when in dark mode natively, these styles override the light defaults seamlessly.

class="chai-bg-white chai-dark-bg-gray-800 ..."

Responsive Design #

ChaiTailwind uses a mobile-first breakpoint system. Unprefixed utilities take effect on all screen sizes, while responsive prefixes conditionally apply styles at specific breakpoints and above.

Supported Breakpoints

Prefix Minimum Width CSS Equivalent
sm: 640px @media (min-width: 640px)
md: 768px @media (min-width: 768px)
lg: 1024px @media (min-width: 1024px)
xl: 1280px @media (min-width: 1280px)

How Media Queries are Generated

When the Chai library encounters a responsive prefix like chai-md:p-20, it:

  1. Strips the prefix to identify the base utility payload (chai-p-20).
  2. Generates the raw CSS payload mapping to the base utility.
  3. Wraps that generated CSS rule uniquely inside a @media (min-width: [breakpoint]) block.
  4. Injects it safely into the dynamic runtime stylesheet.

Examples in Action

Resize your browser window tightly to see these utility transitions take effect conditionally.

chai-p-4 chai-md:p-20

Applies strict padding universally, then upgrades to severe padding starting at 768px.

Padding Resizes on MD Breakpoint
chai-block chai-lg:grid chai-cols-3 chai-gap-4

Stacks elements block-level cleanly, then elegantly shifts to a 3-column grid layout permanently at 1024px.

Item 1
Item 2
Item 3

Dark Mode #

ChaiTailwind natively supports manual scheme toggling via the .dark class strategy. By appending chai-dark: or dark: prefixes, utility styles will strictly activate only when the <html> element possesses the class="dark" modifier.

API & Persistence

To simplify theme handling, ChaiTailwind heavily relies on the implementation logic below which you can bind to your toggle buttons:

  • toggleDarkMode(): A custom global function that forcibly toggles the .dark class natively on the root <html> element.
  • localStorage: Upon toggling, the function securely sets theme='dark' or theme='light' into browser localStorage enforcing seamless persistence across page reloads.

Interactive Demo

chai-bg-white chai-dark:bg-black
Contrast Card

Click the button below to invoke toggleDarkMode()

Responsive Design #

ChaiTailwind embraces a strict mobile-first architecture. Unprefixed utilities apply universally across all screen sizes, while breakpoint prefixes override styles at specific screen widths.

Core Breakpoints

Prefix Media Query Ideal Target
sm: 640px Large mobile phones in landscape & small tablets.
md: 768px Standard tablets (e.g., iPad portrait) & small laptops.
lg: 1024px Standard desktop monitors and laptops.
xl: 1280px Large desktop displays and ultrawide setups.

Responsive Scaling Examples

You can chain breakpoints iteratively. Resize your browser window horizontally to watch the examples below dynamically adapt!

chai-p-4 chai-md:p-10 chai-xl:p-20
Padding scales intelligently
from 16px to 80px.
chai-flex chai-flex-col chai-lg:grid chai-lg:cols-3
1
2
3

Stacks on mobile, snaps to a 3-column grid on desktop (lg).

Combining Utilities #

ChaiTailwind fundamentally relies on class stacking. Because there are no pre-built monolithic components, developers construct interfaces by combining primitive utilities that independently inject strictly layered layout logic.

The Utility Stack

<div class="chai-bg-blue-500 chai-p-20 chai-rounded-lg chai-animate-fade">

Each primitive dynamically acts as an isolated rendering instruction:

  • chai-bg-blue-500 Applies the primary background hue heavily tied to --chai-bg-opacity overrides.
  • chai-p-20 Injects 5rem (80px calculated) of mathematically uniform padding structure.
  • chai-rounded-lg Adds structurally pleasing 0.5rem border-radius to the node boundaries.
  • chai-animate-fade Locally scopes and triggers the built-in fade CSS keyframes.

Real UI Construct

Combining vast sums of utilities is entirely what empowers developers to rapidly prototype beautiful, interactive UI modules natively in standard HTML.

class="chai-bg-blue-500 chai-p-10 chai-md-p-16 chai-rounded-2xl chai-animate-fade
       chai-shadow-xl chai-transition-transform chai-hover-scale-105
       chai-flex chai-flex-col chai-items-center chai-text-white group cursor-pointer"
cloud_download

Download Package

Stacks background, scalable responsive padding, rounded variants, shadows, flex alignments, & interactive scale transitions completely simultaneously.

Performance & Architecture #

ChaiTailwind was fundamentally engineered from the ground up to guarantee a sub-millisecond footprint on your web applications. It achieves zero build-step instant rendering using a triad of highly optimized techniques running natively in the browser.

memory

Strict Caching

Internally, every generated class is securely mapped to a global Javascript Set cache. Once a class reaches the cache, it bypasses the Regex core entirely on future hits.

library_add_check

Generate Once

Even if duplicate utility classes are scattered across a thousand disparate nodes, they inherently only yield exactly one distinct CSS rule block being physically injected to the style tag.

visibility

Mutation Efficiency

ChaiTailwind exploits the native DOM MutationObserver API. It only bothers scanning explicitly new nodes hitting the tree natively without ever unnecessarily locking the main thread.

JavaScript API Reference #

Method Description
ChaiCSS.init() Bootstraps the MutationObserver and injects keyframe rules. Called automatically if window is present.
ChaiCSS.scan(node) Force scans a specific DOM node or document for unparsed classes.
ChaiCSS.destroy() Disconnects the MutationObserver safely. Useful for SPA unmounting.
window.toggleDarkMode() Toggles the `dark` class on html and saves states to localStorage.