# fold-ng
[](https://www.npmjs.com/package/fold-ng)
[](https://www.npmjs.com/package/fold-ng)
[](https://packagephobia.com/result?p=fold-ng)
[](https://www.npmjs.com/package/fold-ng)
[](./LICENSE)
[](./CHANGELOG.md)
[](https://hugoheynard.github.io/fold-ng/)
[](https://github.com/sponsors/hugoheynard)
**fold-ng** is an accessible, **dark-first Angular 22 UI component library and
design system** — signals-first, standalone, zoneless, and SSR-ready. It ships a
two-tier **design-token** model (themeable to the bone) plus WCAG-minded
components: buttons, forms, overlays/dialogs, navigation, data tables, toasts and
more. No `NgModule`, no `zone.js`, no runtime CSS-in-JS — just standalone
components styled against CSS variables.
### ▶ [Live demo & component gallery](https://hugoheynard.github.io/fold-ng/)
Every component, driven by a live playground — the fastest way to see what
`fold-ng` looks and behaves like.
> **Production-quality, pre-1.0 (`0.x`).** Every component is tested, the package
> builds AOT green, and it's dogfooded as the design system of a real
> application. It stays `0.x` only because the API isn't frozen until `1.0.0` —
> not because it's unstable. **Pin your version**; `0.x` minor bumps may still
> refine the API. See [`CHANGELOG.md`](./CHANGELOG.md) for the road to 1.0.
## Install
```bash
npm install fold-ng
```
Angular 22 (`@angular/core`, `@angular/common`, `@angular/forms`,
`@angular/platform-browser`) is a peer dependency.
> **Bundle size.** Components are standalone and the package is side-effect-free
> except its CSS (`sideEffects: ["**/*.css"]`), so you only ship what you import —
> not the whole library. (No Bundlephobia badge: it can't measure an Angular
> partial-Ivy package, which needs the Angular linker to become final JS — the
> install-size badge above is the honest figure.)
## Quickstart
Import the tokens once, then use any standalone component directly:
```ts
// styles.css
@import "fold-ng/tokens.css";
```
```ts
import { Component } from "@angular/core";
import { FoldButtonComponent, FoldCardComponent } from "fold-ng";
@Component({
standalone: true,
imports: [FoldButtonComponent, FoldCardComponent],
template: `
Cancel
`,
})
export class DemoComponent {
save() {}
}
```
Everything is dark by default; opt into light with `data-theme="lumen"`. See
[`docs/TODO.md`](./docs/TODO.md) for the roadmap and the full component list below.
## Consuming the tokens
Import the CSS once at your app's style entry point:
```css
@import "fold-ng/tokens.css";
```
Everything renders **umbra** (the dark theme) **by default**. To switch a subtree (or the whole app),
set `data-theme` on an ancestor — usually ``:
```html
```
Five themes ship: `umbra` (the dark base, no attribute), `lumen` (light),
`bubbly` (festive lavender, violet brand, rounded), `navi` (dark chrome, light
page) and `titan` (brushed titanium — a light brushed-steel ground with a
frameless top and floating rails, bright cards, a heat-anodized copper-orange
brand, solid steel borders, iPhone-soft corners). The extras exist to prove the point — each
is the umbra or lumen block with its primitive families re-pointed. Adding a
sixth is a new `[data-theme]` block in `semantic.css` plus the primitives it
names.
`bubbly` and `navi` also change their corners, and `navi` its depth — **radius
and elevation are the two scales a theme may re-declare**. The line is not that
one scale is special: a theme may change what a surface **looks like**, never
where it **sits**. Corner softness is a brand axis (friendly vs institutional);
depth is calibrated against a ground, and a shadow tuned for near-black ink is
a grey smear on a light page. Neither moves a box by one pixel. Type, space and
motion stay theme-invariant — those re-flow or re-time a page. The contract
test enforces that split.
`navi` is the interesting one: mixing chrome and page means one theme needs the
`text`/`border`/`surface` roles to differ **per region**, which a single set of
roles cannot express. It gets there by re-declaring those roles on
`[data-surface="chrome"]` — a contract any element opts into with the
`foldSurface` directive (the app-shell stamps it on its rails + header) — so the
theme never names a component's internals. Variables only. If mixed chrome ever
stops being a demo, the catalogue should grow real `*-on-chrome` roles.
## Auto-inverting surfaces
The same `[data-surface]` seam powers an **accent** surface — a region filled
with the brand accent whose entire content sub-tree flips to a compatible
on-accent palette **with no per-component code**. Drop a `fold-card` in a grid
and set `surface="accent"` (or stamp `foldSurface="accent"` on any element):
```html
Studio plan
Everything in Pro, plus shared workspaces.
Compare plans
```
Every nested thing — the text ramp, the hairline border, a raised band, the
badge, the link, the button, even a filled icon tile — reads correctly on the
accent. Not because the card special-cases them, but because the region
**re-points the semantic roles** they already resolve against.
### How it works (and why it survives a solid button)
An inverting surface has to do something a chrome surface never does: **swap the
brand pair**. On the accent, `--fold-color-primary` should become the light ink
(so a link or a filled tile's ground reads), and `--fold-color-on-primary` should
become the accent itself (so the label _on_ that tile reads). Written naively
that's a CSS custom-property cycle (`a: var(b); b: var(a)` → both invalid).
The trick: **capture on the surface, invert on the descendants.** The surface
element records the accent and its ink into two private vars _while the tokens
still hold their normal values_, and the inverted role-set is applied to
descendants from those captures — so a role can reference the pre-inversion value
it is replacing, no cycle:
```css
[data-surface="accent"] {
--_accent-ink: var(--fold-color-on-primary); /* captured here… */
--_accent-fill: var(--fold-color-primary);
}
[data-surface="accent"] * {
--fold-color-text: var(--_accent-ink); /* …consumed here */
--fold-color-primary: var(--_accent-ink); /* fill → light ink */
--fold-color-on-primary: var(--_accent-fill); /* on-fill → the accent */
/* …surfaces/borders as color-mix of the captured pair… */
}
```
Every value is a `color-mix` of the captured pair, so it is **derived, not
authored** — one definition holds on all five themes, and the surface/band steps
stay a lighter shade of the accent (gradation kept in-hue).
### Overriding per theme
None of this is a cage. Writing your own CSS in a card is always free — raw
values don't reference the roles, so a surface never touches them. An _override_
isn't a hack: it re-anchors one **relationship** (text ↔ ground ↔ accent) inside
a controlled frame, and coherence follows because the ratios are preserved. Speak
in roles and gain the adaptation, or paint a pixel and own it — both coexist.
The derived defaults are good, not sacred. A theme that wants a different
on-accent ramp (a light accent might want darker text, say) overrides any role by
nesting its own theme selector under the surface — the same seam chrome uses:
```css
[data-theme="titan"] [data-surface="accent"] * {
--fold-color-text: var(--fold-ref-steel-900); /* dark ink on a light accent */
}
```
The one honest limit: an accent surface is a _single_ ground, so `surface`
stays one axis — there is no `accent` × `sunken`. That is a feature (a card in a
grid has one job: stand out), not a gap.
Then style against the semantic tokens — never a raw colour:
```css
.header {
background: var(--fold-color-bg-header);
}
.cta {
background: var(--fold-color-primary);
color: var(--fold-color-on-primary);
}
.cta:hover {
background: var(--fold-color-primary-strong);
}
```
From TypeScript you get the same tokens, typed:
```ts
import { foldColorVar } from "fold-ng";
el.style.background = foldColorVar("bg-page"); // "var(--fold-color-bg-page)"
foldColorVar("bg-pag"); // ✗ compile error — misspelt token
```
## The two-tier model
Tokens come in two layers. This separation is the whole point — it is what lets
another project re-theme by swapping the palette, and what keeps the app from
hard-coding colours.
| Tier | File | Prefix | Role |
| ------------------ | ---------------- | ---------------- | --------------------------------------------------------------------------- |
| **1 · Primitives** | `primitives.css` | `--fold-ref-*` | The raw palette. The only place a literal hex is allowed. Theme-invariant. |
| **2 · Semantic** | `semantic.css` | `--fold-color-*` | Role tokens (`bg-header`, `primary`…). Point at primitives. Flip per theme. |
**Components consume tier 2 only.** A component never names `--fold-ref-teal-500`;
it names `--fold-color-primary`. Re-theming means re-pointing the semantic layer,
never touching a component.
## The naming convention
```
--fold---[-]
│ │ │ └─ strong · primary · secondary · tertiary …
│ │ └────────── page · header · rail · primary …
│ └───────────────────── color · (space, radius, text … to come)
└───────────────────────────── ref (primitive) · color (semantic)
```
Namespaced with `--fold-` so the package never collides with an app's own tokens.
**The `bg-` rule.** A surface fill role carries a `bg-` marker (`bg-page`,
`bg-rail-primary`); a foreground/brand role does not (`primary`, `on-primary`).
So `bg-` reads as "this paints a background."
## The contract test
`src/tokens/__tests__/tokens.contract.spec.ts` is the lock. It fails the build
if:
- any theme block falls out of parity with the catalogue (the dark `:root` base
and **every** `[data-theme]` override are checked);
- a semantic token points at a primitive that doesn't exist (dangling `var`);
- a semantic token hard-codes a hex instead of referencing a primitive;
- a primitive is declared but never used;
- the CSS drifts from the typed catalogue in `tokens.catalog.ts`.
Add a token → add it to `tokens.catalog.ts` **and** every theme block, or the
test goes red. That is how a theme stays complete.
```bash
pnpm --filter fold-ng test
```
## Current token set
Deliberately small — we grow it together, one confirmed role at a time.
| Semantic token | Role |
| -------------------------------- | ----------------------------- |
| `--fold-color-bg-page` | Page background |
| `--fold-color-bg-header` | Top header bar |
| `--fold-color-bg-rail-primary` | Rail 1 — app menu |
| `--fold-color-bg-rail-secondary` | Rail 2 — workspace menu |
| `--fold-color-bg-rail-tertiary` | Rail 3 — tertiary nav |
| `--fold-color-primary` | Primary / accent (brand teal) |
| `--fold-color-primary-strong` | Primary hover / active |
| `--fold-color-on-primary` | Text / icon on a primary fill |
(plus the status families, neutral surfaces, the two card tints `surface-card` /
`surface-sunken`, glass, and the
radius / text / icon-size / space / motion / blur scales — see
`tokens.catalog.ts` for the full, typed set.)
## Components
All standalone, signals-first, styled against the semantic tokens. Import from
the package root.
### Find one by what you need
The reference table below is keyed by component **name** — but you usually know
your **intent**, not the name (that's how an uppercase mini-title gets hand-rolled
instead of reaching for `fold-element-title`). Start here; **before hand-rolling a
label, field, badge, card or overlay, scan this table** — fold almost certainly
ships it.
| I need to… | Reach for |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| a small **uppercase label / eyebrow** over a group | `fold-element-title` (`variant="eyebrow"` · `bar` · `title`) |
| a **section** with a title + description + actions | `fold-page-section` (semantic `` + `aria-labelledby`) |
| show **read-only label/value pairs** (a recap) | `fold-field-list` / `fold-field` (`dl/dt/dd`) |
| a **text** field | `fold-input` — number → `fold-number-input` · multiline note → `fold-textarea` |
| a **date** / **time** field | `fold-date` (date·datetime-local·month·week) · `fold-time` |
| a **dropdown** | `fold-select` (native) — custom rows → `fold-listbox` · multi → `fold-multiselect` |
| an **on/off** field · a **password** field | `fold-checkbox` · `fold-password-field` |
| a **range** / **debounced search** | `fold-slider` / `fold-range-slider` · `fold-search` |
| a **button** · **icon-only** action · icon **on/off** | `fold-button` (`