@f12io/maple

v2.0.17

Published

12 days ago

0High
0Medium
0Low

onuradsay

maple utility-classes css css-engine runtime-css atomic-css-engine

TL;DR

Maple is a runtime CSS engine that generates atomic styles from utility classes only when they appear in the DOM.

Instead of shipping pre-compiled stylesheets, Maple ships a small JavaScript file that observes the DOM and constructs CSSOM incrementally as your application renders. If a class is never used, its style is never generated.

This shifts styling cost from upfront network transfer to demand-driven runtime generation. It eliminates build steps, complex configuration, and unused CSS, while keeping styles encapsulated.

Quick Start

Add Maple to your project by including the script below in the document <head> and start styling with utility classes.

<!doctype html>
<html lang="en">
  <head>
    <!-- Include Maple in the head -->
    <script src="https://cdn.jsdelivr.net/npm/@f12io/maple/dist/maple.js"></script>
  </head>
  <body>
    <!-- Start styling -->
    <div class="bgc-blue-500 c-white p-4 rad-2">Hello World</div>
  </body>
</html>

[!IMPORTANT] Load Maple as a blocking script in the document head.
Maple replaces a render-blocking stylesheet with a small render-blocking runtime. Loading it with async, defer, type="module", or at the end of the body allows the browser to paint elements before Maple has generated their styles, which can cause a Flash of Unstyled Content.

[!TIP] For production, pin Maple to a specific version:
<script src="https://cdn.jsdelivr.net/npm/@f12io/[email protected]/dist/maple.js"></script>

Why Maple?

Instead of generating or optimizing CSS files ahead of time, Maple generates styles on-demand as the browser encounters classes.

That model creates benefits across delivery, developer experience, and styling power.

Delivery & Performance

Constant Transfer Size: Maple ships as a single ~12kb gzipped JavaScript file.
Incremental CSSOM: CSS is constructed incrementally based on what appears on the page.
Automatic Code Splitting: If a component is not on the screen, its styling cost is zero.
No Unused Styles: Styles cannot exist "just in case"; they are generated only from classes that appear in the DOM.

Developer Experience

No Build Step: Include the script and start styling.
No Configuration Files: Maple observes the DOM using a MutationObserver instead of scanning source files.
No Special SSR Treatment: Maple behaves the same whether HTML is produced by Next.js, Remix, Nuxt, PHP, or served as a static file.
Universal Portability: If you can add a <script> tag, you can use Maple.

Styling Power

Dynamic Data as CSS: Maple treats dynamic data exactly like static class names.
Variable-first Architecture: Utilities map to semantic fallback chains of CSS variables.
Dynamic Color Manipulation: Color utilities resolve through CSS variables in the OKLCH color space.
True Encapsulation: Selector logic can live inside the class name itself.

Syntax

Every Maple class name follows a colon-separated structure:

media-query:selector:utility

The first two parts are optional, so Maple scales from simple utilities to advanced state management.

<div class="bgc-red"></div>
<div class="&:hover:bgc-red"></div>
<div class="@md:^.active:bgc-red"></div>

Learn the full syntax in the Syntax Reference.

Examples

Variable-first Utilities

Maple maps utility classes to cascading CSS variables rather than hardcoded values. You can also define variables directly in HTML using class syntax.

<div class="--primary=blue bgc-primary-200 c-primary-700">I am blue.</div>

When you want to bypass the variable system, use = to inject a literal value directly:

<div class="w=86% c=#ff0000"></div>

Dynamic Classes

Because Maple observes the DOM directly, dynamically generated class names work naturally.

<div className={`md:bg-${userColor} w=${progress}%`}></div>

Dynamic Colors

Maple color utilities resolve through CSS variables in the OKLCH color space, making lightness, chroma, hue, and alpha adjustable at runtime.

<div class="bgc-primary-320/70 c-white/80"></div>
<div class="c-coral-600"></div>
<div class="bg-teal/70"></div>
<div class="c-slateblue-500/20"></div>

Read more in Dynamic Color Manipulation and try the Native Palette.

Inline Selectors

Maple supports selector logic inside utility classes.

<button class="c-red ^.card:c-green ^.nav:c-blue">
  Text is green when in a card and blue when in a navigation bar.
</button>

<button class="&:hover:c-black">The text becomes black on hover</button>

<div class="/>span:fw=700">
  <span>This text is bold</span>
</div>

Read more in True Encapsulation and Selectors.

Limitations & Trade-offs

Maple's architecture offers unique benefits but also introduces constraints you should understand before adoption.

JavaScript is Required. Maple runs entirely in the browser and does not generate static CSS. If JavaScript is disabled, the page will render without styles.
Runtime Cost Scaling. Maple's generation work scales with the number of unique utility classes that appear in the DOM.
Not all CSS fits in Utilities. Certain patterns, such as keyframes, font-face declarations, and global resets, are often better expressed in traditional CSS.
Relative OKLCH Colors. As of May 2026, global support for relative color syntax is about 89%, with broader support for plain OKLab and OKLCH colors. Browsers that do not support relative color syntax ignore those generated color declarations.

Documentation

Contributing

If you're interested in contributing to Maple, please read our contributing docs before submitting a pull request.

License

Released under the Root Source License (ROOT), an MIT-style permissive license with an additional distribution condition for systems that can recreate the source on demand. © f12.io