AkurAI-Framework / site/content/docs/styling.md

Latest change e888012a38cfe0d4c47ddf4b3eecfba5ad6b8ac1 - Wire CSS engine + asset pipeline into serve/dev by Ólafur Búi Ólafsson

# Styling: the CSS engine

The framework includes a from-scratch atomic/utility CSS engine — Tailwind-style
in spirit, but pure Rust with zero dependencies and no Node toolchain. It emits
**only the utilities your markup actually uses**, so the shipped stylesheet stays
small by construction.

## How it works

Two steps, both pure `std`:

1. **Scan** — read your HTML/template source and collect the class tokens used in
   `class="…"` attributes.
2. **Generate** — for each recognised utility class, emit its CSS rule. Unknown
   classes (your hand-written component classes) are left alone.

The public entry point takes your sources and returns a compact stylesheet:

```rust
let css = akurai_css::build(&sources);   // sources: &[&str] of markup
// e.g. ".flex{display:flex}.p-2{padding:8px}"
```

## Utility grammar

The starter grammar covers the everyday cases:

- **Spacing (4px scale, parametric):** `p-{n}`, `m-{n}`, `px/py/pt/pr/pb/pl-{n}`,
  `mx/my-{n}`, `gap-{n}`. So `p-2` → `padding: 8px`, `px-4` →
  `padding-left: 16px; padding-right: 16px`.
- **Display / flex:** `flex`, `block`, `hidden`, `flex-col`, `items-center`,
  `justify-center`.
- **Text:** `text-center`, `font-bold`, `text-sm`, `text-lg`.
- **Colour (CSS variables):** `text-accent`, `text-muted`, `bg-accent` — these
  reference the design tokens, so they follow your theme.

Malformed classes (`p-`, `p-x`, `p--1`) are ignored rather than emitting broken
CSS.

## Using it: `/utilities.css`

The engine is wired into `akurai serve` and `akurai dev`. On startup the server
scans every `.html`/`.js` source under your frontend dir for the utility classes
you actually use, generates the minimal stylesheet, and serves it at:

```
/utilities.css
```

Link it from your `<head>` (the starter template already does):

```html
<link rel="stylesheet" href="/utilities.css" />
```

It is **opt-in and harmless**: if your markup references no utility classes the
file is simply empty, and a project that never links it behaves exactly as
before. Hand-written component classes are left untouched — only recognised
utilities are emitted. Note the scanner reads `class="…"` attributes, so utility
classes used inside JS template literals (e.g. `` `<div class="flex">` ``) are
picked up, while classes added via `classList.add("flex")` are not.

### Production vs. dev

- **`akurai serve`** renders `utilities.css` **once at startup** and caches it in
  memory (nothing is written to disk; your source files are never modified).
- **`akurai dev`** regenerates it **fresh on every request**, so adding or
  removing a utility class in your markup shows up on the next reload — together
  with live-reload, no restart and no build step.

The generated stylesheet is also folded into the [asset pipeline](/docs/assets),
so it is additionally available under a fingerprinted, immutably cached URL —
see the manifest at `/api/_assets`.

The hand-written design tokens it builds on are documented under
[Design system → Foundations](/docs/design-system/foundations).