Brutalist Design Contract
Visual grammar for the contributor-authored Brutalist style family
Brutalist Design Contract
Section titled “Brutalist Design Contract”This document describes the visual grammar used by the Brutalist foundation and reference Button projection. Base contracts remain authoritative for semantics, keyboard behavior, ARIA, and command wiring.
Geometry
Section titled “Geometry”- Controls and surfaces use square geometry.
- Structural borders are 2px solid ink.
- Small informational surfaces may use a 2px radius only when explicitly cataloged for that family.
Depth and motion
Section titled “Depth and motion”| State | Translation | Hard shadow |
|---|---|---|
| Rest | none | 3px 3px |
| Hover | -1px, -1px | 4px 4px |
| Pressed | 1px, 1px | none |
The base palette is paper plus ink. Flat accent colors carry semantic emphasis: canary for decisive actions, mint for confirmation, lavender for focus or annotation, coral for warning and press feedback, and sky for discovery or selected tracks. Gradients, glass, blur, and soft glow are excluded.
Position, labels, geometry, and state are primary signals; color is supplementary.
Each accent fill is shipped as a fixed background/foreground pair (for example bg-main with text-main-foreground). Accent foregrounds stay ink in both Light and Dark. Theme-dependent surfaces such as paper panels resolve through CSS variables so a host theme change repaints mounted controls without a pointer refresh.
Preset delivery
Section titled “Preset delivery”The package-owned BRUTALIST_THEME manifest is the authoring source for Light and Dark semantic values. Documentation pages and the CLI preset consume generated projections of the same complete key set; examples do not maintain local palette subsets.
Proto UI config v1 enables one project-wide style preset. Start a Brutalist project with proto-ui init --prototypes brutalist. Adding a Brutalist component to a project with another enabled preset fails before installation or generated-file changes; the CLI does not replace the application’s theme automatically. With --no-styles, add succeeds with an ownership note and the application explicitly supplies every required --pui-* semantic token.
Accessibility
Section titled “Accessibility”- Focus uses a visible hard outline with offset.
- Disabled controls preserve border and geometry while reducing emphasis.
- Interactive targets retain accessible names and Base keyboard behavior.
- Portaled surfaces inherit page-level theme variables.