Utility API 1.2.2

Shipping utilities follow a consistent naming grammar, map to design tokens, and live in @layer utilities. A complete Utility Engine generator remains planned. Deutsch: Utility-API

Maturity: Documented as stable in VelinStyle 1.2.0. Studio and the complete Utility Engine remain planned — shipping utilities are hand-authored under @layer utilities, not a full variant generator.

When to use

Compose layouts with the documented velin-* classes (display, spacing, flex, grid, …).
Override look-and-feel via CSS variables from src/tokens/, not one-off hex in components.
Consult generated utility Markdown for exhaustive class lists.

When not

Do not invent Tailwind-style hover: / dark: prefixes — not in the shipping API.
Do not assume every token has a utility, or every breakpoint × property combo exists — coverage is curated until the Utility Engine lands.

Naming convention

Canonical grammar (ADR 0004):

.velin-{property}-{value}
.velin-{bp}-{property}-{value}

Breakpoint segments come before the property: .velin-md-flex, not .velin-flex-md.

<div class="velin-flex">…</div>
<div class="velin-md-flex">…</div>
<div class="velin-p-4 velin-lg-p-8">…</div>

Breakpoints

Tokens in src/layout/breakpoints.css. Responsive utilities currently emit through xl; 2xl is grammar + token only (ADR 0016).

Infix	Min-width	CSS variable
none (base)	0	—
`sm`	`36rem` (576px)	`--velin-bp-sm`
`md`	`48rem` (768px)	`--velin-bp-md`
`lg`	`62rem` (992px)	`--velin-bp-lg`
`xl`	`80rem` (1280px)	`--velin-bp-xl`
`2xl`	`96rem` (1536px)	`--velin-bp-2xl`

Customization

Override real tokens — examples from src/tokens/:

:root {
  --velin-color-primary: oklch(38% 0.18 250);
  --velin-space-4: 1rem;
  --velin-radius-md: 0.5rem;
}

.my-section {
  --velin-color-primary: oklch(45% 0.16 20);
}

Framework utility modules

Narrative pages cover common patterns; auto-generated lists sync from source via velinstyle docs generate --scope utilities.

Module	Generated reference	Related docs
`display.css` + `responsive.css`	responsive.md	Display
`spacing.css`	spacing.md	Spacing
`state.css`	state.md	Interactions
`gradient.css`	gradient.md	Background
`scroll-animation.css`	scroll-animation.md	Scroll-driven
`view-transition.css`	view-transition.md	View transitions

Full index: utilities/README.md · Generated hub.

CSS layers

@layer tokens — design tokens
@layer velin.base / base — reboot and typography
@layer velin.components — components
@layer utilities / velin.utilities — utilities (win without !important)

Important flag

Utilities do not use !important by default. Prefer layers for overrides. A full important / variant budget belongs to the planned Utility Engine (ADR 0008).