# Foundations — tokens, colour, type, materials, motion
Source: https://ui.barua.tz/docs/foundations.html
Rules and conventions: https://ui.barua.tz/llms.txt
## Color System
Every color token is a light-dark() pair, so a single name is always correct in either scheme. The accent family drives buttons, links, focus and selection; re-tint the whole system with data-accent="indigo|purple|pink|teal|green" on .
- Documentation: https://ui.barua.tz/docs/foundations.html#color-system
- Classes: `b-badge` `b-badge--accent` `b-btn` `b-btn--ghost` `b-btn--glass` `b-btn--primary` `b-btn--sm` `b-card` `b-card--glass` `b-card--neutral` `b-card__body` `b-card__header` `b-card__title` `b-footnote` `b-gap-2` `b-gap-3` `b-hstack` `b-link` `b-stack` `b-stack--wrap` `b-text-secondary` `b-wall` `b-wallpaper-scope`
```html
Glass needs a backdrop
Live
Change the wall and watch the material, the ink and the
accent all answer to the picture.
Glass needs a backdropLiveChange the wall and watch the material, the ink and the accent all answer to the picture.
```
## Typography
A text style is a whole set of metrics, not a size: every role below states its own size, weight, leading and tracking together. Small text is not body text made smaller — a caption opens its tracking slightly and tightens its leading, which is why inheriting those values from the page would be wrong. Headings of the same size as a role use the same metrics as that role, so
and .b-headline are typographically identical.
- Documentation: https://ui.barua.tz/docs/foundations.html#typography
- Classes: `b-table` `b-table-wrap`
## Font Scale
The Apple HIG scale, exposed as one class per role. Elements h1 – h6 map onto it automatically; use the classes when semantics and size need to differ — a card title that is an h3 but should read as a headline, for instance.
- Documentation: https://ui.barua.tz/docs/foundations.html#font-scale
- Classes: `b-body` `b-callout` `b-caption` `b-footnote` `b-headline` `b-large-title` `b-overline` `b-subheadline` `b-tabular-nums` `b-text-tertiary` `b-text-uppercase` `b-title1` `b-title2` `b-title3` `b-truncate`
## Spacing
A 4px base scale. Use 1–3 for padding inside controls, 4–6 between related elements, 8–12 between groups, and 16–24 between page sections. If a gap isn't on the scale, it isn't in the system.
- Documentation: https://ui.barua.tz/docs/foundations.html#spacing
## Grid
.b-grid is 12 columns by default; set --b-cols or use .b-grid--2/3/4/6 for equal tracks, and span with .b-col-span-* . .b-grid--auto auto-fills against --b-col-min , and .b-card-grid / .b-masonry handle card walls without media queries. Gaps come from the spacing scale via .b-gap-* .
- Documentation: https://ui.barua.tz/docs/foundations.html#grid
- Classes: `b-col-span-4` `b-col-span-6` `b-col-span-full` `b-footnote` `b-grid` `b-grid--3` `b-panel` `b-text-center`
```html
1 / 3
1 / 3
1 / 3
span 6
span 6
span 4
span 4
span 4
span full
```
```tsx
import { Footnote, Grid } from "barua-ui";
1 / 3
1 / 3
1 / 3
span 6
span 6
span 4
span 4
span 4
span full
```
## Layout
SwiftUI-style primitives: .b-vstack and .b-hstack flow content with a token gap, and .b-spacer absorbs the leftover space — that trio builds most toolbars and headers. .b-container centers a page column, .b-section spaces bands of content, and .b-split + .b-panel make resizable multi-pane layouts.
- Documentation: https://ui.barua.tz/docs/foundations.html#layout
- Classes: `b-btn` `b-btn--primary` `b-btn--sm` `b-footnote` `b-gap-1` `b-headline` `b-hstack` `b-panel` `b-spacer` `b-table` `b-table-wrap` `b-text-secondary` `b-vstack`
```html
Inbox
VStackChildren flow vertically; the gap comes from --b-gap.
```
```tsx
import { Button, Footnote, Spacer } from "barua-ui";
Inbox
VStackChildren flow vertically; the gap comes from --b-gap.
```
## Breakpoints
Custom properties can't drive @media , so breakpoints are a convention: six shared stops, written by value, always mobile-first with @media (min-width: …) . Base styles serve the phone; each stop only adds.
- Documentation: https://ui.barua.tz/docs/foundations.html#breakpoints
- Classes: `b-table` `b-table-wrap`
## Border Radius
Corners grow with the surface, Apple-style: xs for inline code and checkboxes, sm for chips and kbd, md for buttons, inputs and menus, lg for panels and toolbars, xl for cards and modals, 2xl for sheets, and full for pills and avatars. Never give a small control a bigger radius than the surface it sits on.
- Documentation: https://ui.barua.tz/docs/foundations.html#border-radius
- Classes: `b-caption2` `b-gap-1` `b-stack` `b-stack--center` `b-text-tertiary`
```html
--b-radius-xs4px
--b-radius-sm6px
--b-radius-md10px
--b-radius-lg14px
--b-shadow-xs
--b-shadow-sm
--b-shadow-md
--b-shadow-lg
--b-shadow-xl
--b-shadow-accent
```
## Elevation
The elevation ladder pairs each shadow with a 1px hairline ring ( --b-ring ) so edges stay crisp on any background. Use the utilities: 1 for resting cards, 2 for raised cards and glass toolbars, 3 for menus and popovers, 4 for modals and drawers, 5 for the command palette. Level 0 removes elevation for flush surfaces.
- Documentation: https://ui.barua.tz/docs/foundations.html#elevation
- Classes: `b-elevation-1` `b-elevation-2` `b-elevation-3` `b-elevation-4` `b-elevation-5` `b-gap-2` `b-radius-lg` `b-stack` `b-stack--center`
```html
.b-elevation-1
.b-elevation-2
.b-elevation-3
.b-elevation-4
.b-elevation-5
```
## Opacity
Three stops, three meanings. hover (0.85) dims media and imagery under the pointer, muted (0.6) de-emphasizes without disabling, and disabled (0.4) is applied automatically by :disabled and .is-disabled — never hand-roll a disabled look.
- Documentation: https://ui.barua.tz/docs/foundations.html#opacity
- Classes: `b-caption2` `b-gap-1` `b-stack` `b-stack--center` `b-text-tertiary`
```html
base1
--b-opacity-hover0.85
--b-opacity-muted0.6
--b-opacity-disabled0.4
```
## Blur
The blur scale feeds the glass materials. Rather than using raw blur values, reach for the composite filters: --b-glass-light (blur-sm + saturate 1.6), --b-glass (blur-lg + saturate 1.8) and --b-glass-heavy (blur-xl + saturate 2) — the saturation boost is what makes color glow through the pane.
- Documentation: https://ui.barua.tz/docs/foundations.html#blur
- Classes: `b-caption2` `b-gap-1` `b-stack` `b-stack--center` `b-text-tertiary`
```html
--b-blur-xs4px
--b-blur-sm8px
--b-blur-md16px
--b-blur-lg24px
Aa
.b-material-ultrathin
Aa
.b-material-thin
Aa
.b-material-regular
Aa
.b-material-thick
Aa
.b-material-chrome
```
```tsx
import { Callout } from "barua-ui";
Aa
.b-material-ultrathin
Aa
.b-material-thin
Aa
.b-material-regular
Aa
.b-material-thick
Aa
.b-material-chrome
```
## Borders & Dividers
Four weights of edge, all translucent so they sit naturally on any surface: --b-hairline for glass edges and elevation rings, --b-separator for list rows and card borders, --b-border for inputs and controls, and --b-border-strong for their hover state. .b-divider draws separator rules — vertical inside an hstack, labeled for timeline breaks, and inset to align with list content.
- Documentation: https://ui.barua.tz/docs/foundations.html#borders-dividers
- Classes: `b-divider` `b-divider--label` `b-divider--vertical` `b-hstack`
```html
ReplyForwardArchive
Yesterday
```
```tsx
import { Divider } from "barua-ui";
ReplyForwardArchive
Yesterday
```
## Motion
Motion is quick, physical and quiet: five durations, five curves, and nothing animates that doesn't communicate. Small state changes use instant and fast ; surfaces that move use slow with the spring curve. Everything collapses to near zero under prefers-reduced-motion — see Accessibility.
- Documentation: https://ui.barua.tz/docs/foundations.html#motion
- Classes: `b-btn` `b-btn--primary` `b-card` `b-card--interactive` `b-card__body` `b-chip` `b-footnote` `b-progress` `b-progress--indeterminate` `b-progress__fill` `b-spinner` `b-spinner--lg` `b-table` `b-table-wrap`
```html
instant · 100msfast · 150msnormal · 250msslow · 350msslower · 500msstandard · defaultout · entrancesin · exitsspring · sheetsbounce · overshoot
```
```tsx
import { Chip } from "barua-ui";
instant · 100msfast · 150msnormal · 250msslow · 350msslower · 500msstandard · defaultout · entrancesin · exitsspring · sheetsbounce · overshoot
```
## Iconography
Icons are inline SVG — no font, no sprite request. Draw on a 20×20 viewBox with a 1.5 stroke, stroke="currentColor" and round caps and joins, so every icon inherits text color and matches the SF Symbols weight. .b-icon sizes the box ( --sm 16, default 20, --lg 24, --xl 32) and .b-icon-tile seats an icon on an accent-soft tile for list leaders and feature rows. Decorative icons take aria-hidden="true" .
- Documentation: https://ui.barua.tz/docs/foundations.html#iconography
- Classes: `b-icon` `b-icon--lg` `b-icon--sm` `b-icon--xl` `b-icon-tile`
```html
```
```tsx
import { Icon, IconTile } from "barua-ui";
```
## Accessibility
Accessibility is baked into the tokens, not bolted on. The focus ring ( --b-focus-ring , a 3.5px accent halo) appears on :focus-visible only — keyboards get it, mouse clicks don't. Tab through this demo to see it.
- Documentation: https://ui.barua.tz/docs/foundations.html#accessibility
- Classes: `b-btn` `b-btn--primary` `b-input`
```html
```
```tsx
import { Button, Input } from "barua-ui";
```
## Dark Mode & Light Mode
The root declares color-scheme: light dark and every color token is a light-dark() pair, so the whole system follows the OS by default. Set data-theme="light|dark" on to force a scheme — the topbar's data-b-theme-toggle button does exactly that and persists the choice, which the inline script restores before first paint to avoid a flash.
- Documentation: https://ui.barua.tz/docs/foundations.html#dark-light
- Classes: `b-card` `b-card__body` `b-card__subtitle` `b-card__title`
```html
```
## Responsive Rules
Mobile first, always: base styles serve the smallest screen, and each of the six breakpoints only adds. Most layouts shouldn't need media queries at all — .b-grid--auto , .b-card-grid and the stack primitives reflow on their own. When you do write one, use min-width at a shared stop.
- Documentation: https://ui.barua.tz/docs/foundations.html#responsive-rules
## View Transitions
Two things, on the platform's View Transitions API. Opt in with data-vt on and same-origin navigations cross-fade on the system's motion tokens (180ms out, 220ms in). Off by default, disabled automatically under reduced motion, and inert in browsers without the API.
- Documentation: https://ui.barua.tz/docs/foundations.html#view-transitions
- Classes: `b-btn` `b-btn--ghost` `b-btn--glass` `b-btn--sm` `b-card` `b-card__body` `b-card__subtitle` `b-card__title` `b-code` `b-code__header` `b-footnote` `b-gap-3` `b-hstack` `b-stack` `b-text-secondary` `b-thumb`
```html
Page transitions
<html data-vt> <!-- pages now cross-fade on navigation -->