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

Latest change 0ebc2057fd9a65182855334c219522ae944ad484 - docs: /docs guides for routing, forms, storage, middleware, SEO, styling + dev server 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.

## Status

The engine is a working, tested crate (`crates/css`). Wiring it into the
`serve`/`dev` pipeline — scanning the frontend on build and hot-reload to emit a
`utilities.css` — is the next step; until then it's available as a library. The
hand-written design tokens it builds on are documented under
[Design system → Foundations](/docs/design-system/foundations).