kahwacss

v1.0.4

Published

12 days ago

KahwaCSS is a lightweight utility-first CSS engine powered by kw-* classes and JavaScript.

0High
0Medium
0Low

nausheenfaiyaz

css utility-css tailwind-like dom javascript

KahwaCSS

KahwaCSS is a lightweight runtime utility engine that parses kw-* classes and applies styles inline with JavaScript.

It is designed for:

Zero-build utility styling
Fast prototyping
Dynamic UIs where nodes/classes change at runtime

Project Links

Live Demo (Hosted): [https://kahwa-css.vercel.app/]
Demo Video: [https://www.youtube.com/watch?v=5OnFs72oE98]
Twitter (X) Post: [https://x.com/codeXninjaDev/status/2049124232349757705]
LinkedIn Post: [https://www.linkedin.com/feed/update/urn:li:activity:7454892854771884032/]

What It Is

KahwaCSS scans the DOM for classes that include the kw- prefix, parses each utility token, and applies the resulting style object directly to the element.

Example:

<div class="kw-p-4 kw-bg-blue kw-rounded-xl kw-text-white">Hello</div>

At runtime this becomes inline styles (for example padding, backgroundColor, borderRadius, color).

Installation

npm

npm i kahwacss

CDN (jsDelivr)

<script src="https://cdn.jsdelivr.net/npm/kahwacss@latest/dist/kahwacss.cdn.min.js"></script>
<script>
  KahwaCSS.init();
</script>

You can also use unpkg:

<script src="https://unpkg.com/kahwacss@latest/dist/kahwacss.cdn.min.js"></script>

Usage

npm (bundler/dev server)

import { initKahwaCSS } from "kahwacss";

initKahwaCSS();

Use this form in apps powered by Vite, Webpack, Parcel, Next.js, etc.

npm (plain browser test without bundler)

If you are testing in a raw HTML file, the browser cannot resolve import ... from "kahwacss" directly. Use the installed file path instead:

<script type="module">
  import initKahwaCSS from "./node_modules/kahwacss/dist/index.js";
  initKahwaCSS();
</script>

Serve the folder over HTTP for testing:

npx serve .

With config (npm)

import { initKahwaCSS } from "kahwacss";

initKahwaCSS({
  scale: 4,
  colors: {
    brand: "#0ea5e9",
    ink: "#111827",
  },
});

How The Engine Works

initKahwaCSS() resolves config and waits for DOM readiness.
scanDOM(document.body, config) applies styles to matching elements.
observeDOM(config) watches:
- added nodes
- class attribute changes
Updates are batched with requestAnimationFrame for efficient flush.
applyStyles() caches applied utility classes in data-kahwa-classes to reduce redundant work.

Configuration

initKahwaCSS({
  scale: 4, // used for spacing/gap/inset numeric transforms
  colors: {
    // merged with defaults
    red: "#ed3c3c",
    blue: "#3b82f6",
    green: "#2cd169",
    pink: "#ff5d8f",
    black: "#000",
    white: "#fff",
    orange: "#f37649",
    gray: "#6b7280",
    yellow: "#ffe566",
    purple: "#deaaff",
    cyan: "#67e8f9",
    brown: "#8d4b28",
    slate: "#64748b",
    zinc: "#71717a",
  },
});

Important: Prefix is intentionally locked to kw- by the engine.

Built-in Utility Coverage

Display + Visibility

kw-block, kw-inline, kw-inline-block
kw-hidden
kw-flex, kw-inline-flex
kw-grid, kw-inline-grid
kw-table, kw-inline-table, kw-table-row, kw-table-cell
kw-contents
kw-visible, kw-invisible

Flexbox + Alignment

kw-flex-col, kw-flex-row, kw-flex-wrap, etc.
kw-flex-1, kw-flex-auto, kw-flex-none, etc.
kw-items-center|start|end|baseline|stretch
kw-justify-start|center|end|between|around|evenly
kw-grow-{n}, kw-shrink-{n}, kw-basis-{token}

Spacing

kw-p-*, kw-pt-*, kw-pr-*, kw-pb-*, kw-pl-*, kw-px-*, kw-py-*
kw-m-*, kw-mt-*, kw-mr-*, kw-mb-*, kw-ml-*, kw-mx-*, kw-my-*
Supports:
- numeric tokens (kw-p-4)
- auto where valid (kw-mx-auto)
- arbitrary values (kw-p-[18px])

Colors + Typography

kw-bg-{color}
kw-text-{color}
kw-text-xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl
kw-fs-{n|[value]}
kw-lh-{n|[value]}
kw-fw-{n}
kw-font-{weightToken|[family]}
kw-bold, kw-italic, kw-underline, kw-line-through, kw-no-underline
kw-uppercase, kw-lowercase, kw-capitalize, kw-normal-case
kw-text-left|center|right|justify

Sizing

kw-w-{token}, kw-h-{token}
kw-min-w-*, kw-max-w-*, kw-min-h-*, kw-max-h-*
Keywords like auto, full, screen, fit, min, max
Fractions where supported (for example kw-w-1/2)
Arbitrary values (for example kw-w-[320px])

Border + Radius + Shadow

kw-border, kw-border-0
kw-border-{n|[value]}
kw-border-t-*, kw-border-b-*, kw-border-l-*, kw-border-r-*
kw-border-color-{color}
kw-rounded, kw-rounded-none|sm|md|lg|xl|2xl|full
kw-rounded-{n|[value]}
kw-shadow-none|shadow|shadow-sm|shadow-md|shadow-lg|shadow-xl

Grid + Gap

kw-grid-cols-{n|none}
kw-grid-rows-{n|none}
kw-gap-*, kw-gap-x-*, kw-gap-y-*

Positioning + Layering

kw-static, kw-relative, kw-absolute, kw-fixed, kw-sticky
kw-top-*, kw-right-*, kw-bottom-*, kw-left-*
kw-z-{n}

Overflow + Interaction + Media

kw-overflow-hidden|auto|scroll|visible
kw-overflow-x-*, kw-overflow-y-*
kw-pointer-none|auto and kw-pointer-*
kw-cursor-pointer|not-allowed|move|default|text
kw-object-contain|cover|fill|none|scale-down and kw-object-*
kw-aspect-auto|square|video, kw-aspect-{w/h}, kw-aspect-[value]
kw-list-none|disc|decimal
kw-whitespace-normal|nowrap|pre|pre-wrap

Effects + Motion

kw-opacity-{n} (0-100 mapped to 0-1)
kw-transition
kw-transition-colors
kw-transition-opacity
kw-transition-transform
kw-duration-{n|[value]}

Utility Syntax Reference

Arbitrary values

Use brackets to inject custom values where supported:

kw-w-[420px]
kw-bg-[#111111]
kw-rounded-[18px]
kw-gap-x-[14px]

Fractions

Where supported:

kw-w-1/2 -> 50%
kw-basis-2/3 -> 66.666...%
kw-aspect-4/3 -> aspect-ratio: 4 / 3

Spacing scale

Spacing and gap numeric tokens use:

value = token * scale

Default scale = 4:

kw-p-2 -> 8px
kw-gap-3 -> 12px
kw-top-4 -> 16px

Examples

Card

<article class="kw-bg-[#fff0c8] kw-p-4 kw-rounded-2xl kw-border-1 kw-border-color-black kw-shadow-md">
  <h3 class="kw-text-xl kw-bold kw-mb-2">Kahwa Card</h3>
  <p class="kw-text-sm">Runtime utility styling, no build required.</p>
</article>

Grid layout

<div class="kw-grid kw-grid-cols-3 kw-gap-3">
  <div class="kw-bg-white kw-border-1 kw-border-color-black kw-p-3">A</div>
  <div class="kw-bg-white kw-border-1 kw-border-color-black kw-p-3">B</div>
  <div class="kw-bg-white kw-border-1 kw-border-color-black kw-p-3">C</div>
</div>

Exports

From package entry:

initKahwaCSS(userConfig?)
scanDOM(root?, config)
applyStyles(el, config)
observeDOM(config)
defaultConfig
resolveConfig(userConfig?)
parseClass(cls, config?)

Current Constraints

Prefix support is intentionally fixed to kw-.
Inline style assignment is the styling strategy (no generated stylesheet).
Utility support is parser-driven; unsupported tokens are ignored safely.

Development

npm test
npm run build

Publish checklist:

npm test
npm run build
npm login
npm publish --access public

License

MIT