dnanoCSS ⚡

A lightweight utility-first CSS engine powered by Vanilla JavaScript.

dnanoCSS is a lightweight runtime utility-first CSS engine built with Vanilla JavaScript. It scans your DOM, parses utility classes, and dynamically generates real CSS without any build step or external dependency.

Why dnanoCSS?

Most utility-first frameworks require build tools, configuration, or compilation steps.

dnanoCSS explores a different approach: utility classes are interpreted directly in the browser at runtime using pure JavaScript.

The goal of this project is to deeply understand:

• DOM traversal
• token parsing
• dynamic CSS generation
• runtime styling systems
• utility-first architecture

Features

• Stylesheet Injection — Generates real CSS rules in a <style> tag (not inline styles)
• 60+ Utilities — Spacing, flexbox, colors, typography, borders, sizing, and more
• Color Palette — 30+ named colors + semantic tokens (primary, danger, success)
• Responsive Breakpoints — dn-md-p-20 → @media (min-width:768px)
• Pseudo-States — dn-hover-bg-primary, dn-focus-border-blue
• MutationObserver — Auto-styles dynamically added DOM elements
• Modular Architecture — engine, parser, utilities, constants separated cleanly

Installation

npm install dnanocss

Usage

import "dnanocss";

Environment Support

dnanoCSS currently works best in modern ESM/bundler environments such as:

• Vite
• Webpack
• Parcel
• Next.js

For direct browser usage without a bundler, use relative module imports or a future CDN build.

Quick Start

<!-- 1. Add the script -->
<script type="module" src="./index.js"></script>

<!-- 2. Use utility classes -->
<div class="dn-flex dn-items-center dn-justify-center dn-bg-primary dn-text-white dn-p-24 dn-rounded-12">
  Hello dnanoCSS!
</div>

Utility Reference

Spacing

dn-p-{n}    dn-pt-{n}   dn-pb-{n}   dn-pl-{n}   dn-pr-{n}
dn-px-{n}   dn-py-{n}
dn-m-{n}    dn-mt-{n}   dn-mb-{n}   dn-ml-{n}   dn-mr-{n}
dn-mx-{n}   dn-my-{n}   dn-mx-auto

Colors

dn-bg-{color}       dn-text-{color}      dn-border-{color}

Available: black, white, primary, secondary, danger, success, warning, info, red, blue, green, purple, pink, teal, gray, gray-100…gray-900, and more.

Typography

dn-fs-{n}           dn-fw-{weight}       dn-lh-{n}
dn-text-center      dn-text-left         dn-text-right
dn-uppercase        dn-lowercase         dn-capitalize
dn-italic           dn-underline         dn-truncate

Layout / Flexbox

dn-flex      dn-col       dn-grid      dn-block     dn-hidden
dn-justify-center  dn-justify-between  dn-justify-evenly
dn-items-center    dn-items-start      dn-items-end
dn-gap-{n}   dn-wrap      dn-nowrap

Borders

dn-border    dn-border-2   dn-border-4   dn-border-0
dn-rounded-{n}

Sizing

dn-w-{n}   dn-h-{n}   dn-w-full   dn-h-screen   dn-w-screen
dn-max-w-{n}   dn-min-h-{n}

Responsive

Prefix any utility with a breakpoint:

dn-sm-p-20    →  @media (min-width: 640px)  { padding: 20px }
dn-md-p-20    →  @media (min-width: 768px)  { padding: 20px }
dn-lg-p-20    →  @media (min-width: 1024px) { padding: 20px }
dn-xl-p-20    →  @media (min-width: 1280px) { padding: 20px }

Pseudo-States

dn-hover-bg-primary     →  .dn-hover-bg-primary:hover { background-color: #2563eb }
dn-focus-border-blue    →  .dn-focus-border-blue:focus { border-color: #3b82f6 }
dn-active-text-white    →  .dn-active-text-white:active { color: #ffffff }

Architecture

dnanoCSS/
├── index.js            Entry point, boots engine on DOMContentLoaded
│
├── demo/
│   ├── index.html      Main demo page showcasing utilities and features
│   ├── style.css       Demo-specific styles
│   └── examples.html   Utility showcase
│
├── src/
│   ├── engine.js       DOM scanner, style injector, MutationObserver
│   ├── parser.js       Tokenizer — converts "dn-p-20" → { padding: "20px" }
│   ├── utilities.js    All utility mappings
│   └── constants.js    Colors, breakpoints, config
│
├── package.json
├── README.md
├── LICENSE
└── .gitignore

How the Engine Works

1. DOM Ready — DOMContentLoaded fires, initDnanoCSS() is called
2. Scan — Every element's classList is checked for dn- prefixed classes
3. Parse — parser.js splits tokens, extracts breakpoints, pseudo-states, and values
4. Generate — Valid CSS rule strings are built (camelCase → kebab-case)
5. Inject — Rules are inserted into a single <style id="dnano-styles"> tag
6. Observe — MutationObserver handles new elements added dynamically

Future Improvements

• [ ] Dark mode variant (dn-dark-bg-gray-900)
• [ ] CSS custom property output (--dn-spacing-4: 16px)
• [ ] CLI extractor for static HTML → pure CSS file
• [ ] Plugin system for custom utilities
• [ ] Caching layer with localStorage for repeat visits
• [ ] !important modifier (dn-!p-0)

License

MIT — free to use, modify, and extend.