# Backgrounds

> Dot and line grids in the current text color: texture that never competes with the content.

Utility · [Docs](https://ui.ssntl.app/docs/components/backgrounds) · `npx shadcn@latest add @ssntl/backgrounds`

Installs `styles/ssntl/backgrounds.css`. Read this file before you use, change or review it.

## When to use it

- Behind a headline, a hero or an empty state, as a quiet texture.

## When not to

- Behind body text, forms or data.

## Usage

```css
/* app/globals.css */
@import "../styles/ssntl/backgrounds.css";

<section class="bg-dots">…</section>
<section class="bg-grid">…</section>
<section data-theme="dark" class="bg-grain-midnight">…</section>
```

## Rules for Backgrounds

- **Grain gradients.** Nine color fields (`bg-grain-midnight`, dusk, eclipse, forest, iris, shore, lagoon, sunrise, orchid) under one shared film grain. The color is a 3 KB image with no grain of its own; the grain is the system's noise tile, the same at any size.
- Each sets readable text for its tone; set `data-theme="dark"` on the dark four so components inside follow. Put text where the field is calm, or on glass.
- **For atmosphere.** A hero, a cover, a launch. Never behind long text, forms or data.
- **Quiet backgrounds.** Patterns draw in the current text color (dots 10%, lines 4%) and fade out toward the edges, so they adapt to light and dark and the surface ends softly.
- **Texture is felt, not read.** If the pattern can be noticed while reading, it is too strong. Lines stay under 6%; dots can go a little darker because they cover less.
- Use a pattern behind a headline or an empty state, never behind body text or data.

## How it is built

Quiet backgrounds: a texture you feel more than see. Both patterns draw in the current text color, so they adapt to light and dark, and fade out toward the edges, so the surface ends softly instead of being cut. A dot covers less of the surface than a line, so it can be a little darker.

- `bg-dots`: a 16px grid of 2px dots at 10%
- `bg-grid`: a 32px grid of 1px lines at 4%
- `[--pattern-strength:…]`: override the opacity (keep lines under 6%)
- `bg-pattern-full`: no fade: the pattern fills the whole surface
- `bg-grain-{name}`: a grain gradient: midnight, dusk, eclipse, forest (dark); iris, shore, lagoon, sunrise, orchid (light)

The pattern is drawn on a ::before layer behind the content, so the element keeps its own background color.

Grain gradients: nine soft color fields under one shared film grain. The color is a 640px image of about 3 KB, blurred so it has no grain of its own, and stretched to cover; the grain is the system's noise tile (--es-grain), laid over in soft-light, so every gradient carries the same texture at any size and in any theme. Put the images in public/gradients/ (download them from ui.ssntl.app/gradients/<name>.webp). Each sets readable text for its tone: light text on the dark four, dark text on the light five. Inside, components follow the page's theme: set data-theme="dark" on the dark ones. With more contrast, the grain goes.

The system's noise tile, for projects without @ssntl/tokens/effects.css.

## UI foundations it applies

- **Quiet backgrounds** (Component details): Keep background patterns faint enough never to compete with content.

## Surfaces

- Static content sits at `elevation-0` and separates by tone; only what floats casts a shadow.
- A shadow used as a ring keeps a 1px transparent border, so forced-colors mode still draws an edge.
- Full-height areas use 100dvh, never 100vh; widths use 100%, never 100vw. Reusable components adapt with container queries (@container), not the viewport.
- Content sets the height; tiles in a row stretch to the tallest.
- **Nested surfaces are concentric.** Inner radius = outer radius − padding.

## Design tokens only

- Use the system's tokens for every design value: type roles (`text-caption` 13, `text-label` 15, `text-body` 17, `text-lead` 20, `text-heading` 22, `text-title` 32, `text-headline` 48, `text-display` 72), radii (`rounded-xs` 8 … xl 44), spacing steps, colors, shadows and motion. If a value doesn't exist, take the nearest token. Never write text-[15px], rounded-[24px] or bg-[#…]; `pnpm lint` rejects them.
- Type roles already carry line height, tracking and weight. Pick the role; never add `leading-*` or `tracking-*` on top.
- **Nested corners are concentric.** Inner radius = outer radius − padding − border width (`rounded-outer`-* p-concentric-* `rounded-inner`). Past 24px of padding, or with deliberately uneven padding, each layer keeps its own radius token.
- Separate surfaces by tone, not borders. A border is for structure (a divider) or state (an input, a selection).

## Accessibility baseline

- Text meets 4.5:1 against its surface (3:1 at 24px and up, or 18.67px bold); input borders, focus rings and chart marks meet 3:1, in light and dark. Text on a translucent color (`white/80`, /50, color-mix) is measured as rendered over its background; the theme pairs are checked in lint.
- Meaning never rides on color alone: a state carries a word, an icon or a pattern as well.
- Every page fits a 320px screen at 200% zoom with no horizontal scroll; a grid that holds content uses grid-cols-[minmax(0,1fr)] and flex children get min-w-0. Never set maximum-scale=1 or user-scalable=no.
- A focused element is never hidden under sticky chrome: set scroll-padding to the header's height (and to footers or banners at the bottom).
- On a client-side route change, update the title and move focus to the new page's main content.
- **Respect prefers-reduced-motion.** Keep opacity and color, drop movement, scale and blur.
- Content is never truncated without a way to read all of it; long names wrap. A hover-only title tooltip doesn't count as a way back.

## Writing

- Sentence case everywhere; no ALL CAPS except the Eyebrow role.
- One concept, one word, across navigation, headings and buttons.
- Buttons are a verb and its object and say what happens (Delete product, not OK).
- An error says what went wrong and how to fix it, in the user's language.
- **Status copy follows one pattern.** In progress is the verb in -ing (Saving changes…), done names the object and the past tense with no “successfully” (Changes saved), a failure gives the next step, partial results give counts. Cut “Please”.
- A confirmation names the action and the object (Delete Ceramic cup?), never “Are you sure?”. Deleting an account, a workspace or a store asks for its name to be typed.
- Show known requirements as helper text before input, not only as an error after it. Links never say “Click here”, and no two links on a page say “Learn more”.
- Build each sentence as one translatable message, never concatenated around a variable; join lists with Intl.`ListFormat`.
- **Use real characters.** An en dash for ranges (09:30–17:45), × for dimensions, curly quotes, an ellipsis (…).

## Fixing

- Take the cheapest fix that works, in this order: delete (a separator space would carry, an animation on a frequent action, an ARIA attribute a native element makes redundant), use the platform (the native element or control, the browser's focus ring), reuse what the system has (a token, a spacing step, a motion curve), correct the value, and only then add something new.
- Code that adds what a deletion would fix is a problem in itself; fix it by removing.
- A documented convention settles matters of taste, but never excuses a release blocker.

## Worst-case content

- Build and test with the worst real values, not the happy ones: long hyphenated names with diacritics, unbreakable emails and URLs, German compounds, translations about 30% longer, emoji and right-to-left names.
- Unbreakable strings wrap anywhere; nothing pushes its siblings off a row or out of a container.
- Every image has a fallback and a box: a failed avatar shows initials, a frame keeps its ratio, so loading never shifts the layout.
- **Show data as data.** Escape HTML, never render null, undefined or NaN, and round floating point before display.
- **Check the environment as well.** A 280px column, a 2560px screen, 200% zoom, dark mode, `dir="rtl"` and touch.

## Icons

- One icon set (Lucide) at one stroke: 1.6, the Essential Design spec, beside regular and medium text; a heavier stroke only where a small glyph must read (a 16px check). (better-ui proposes rendered strokes of 1.5–2px with `absoluteStrokeWidth`; the system's documented stroke takes precedence as a matter of style.)
- Inline icons are 1em–1.25em of the text beside them.
- Icons are 20px beside labels and 16px in dense controls, at the size they were drawn; a well or a button, not a bigger glyph, gives them room.
- One SVG per icon, colored with `currentColor`; hover, selected and disabled states come from color and opacity, never from separate assets.
- Decorative icons are `aria-hidden`; an icon that is the only content of a control gets its name from the control.

## Light, dark and languages

- Design both themes from the tokens; dark mode is chosen, not inverted. Check every new pair in both.
- Pass every visible and accessible string as a prop or child, so the component works in any language; never hard-code copy inside it.
- Use logical properties (ms-, me-, start-, end-) so layouts mirror in right-to-left languages; `translateX` and background-position need a right-to-left override. Mirror only icons whose meaning follows reading direction (arrows, chevrons), and wrap mixed-direction values in `<bdi>`.
- **Visual order matches DOM order.** No order, row-reverse or grid placement that reorders content.
- Switching themes pauses transitions for the switch, so every surface changes at once.

## Before you ship

- [ ] Every interactive control has an accessible name.
- [ ] Every keyboard-reachable control shows a visible focus indicator.
- [ ] Nothing is reachable by pointer but not by keyboard.
- [ ] Motion and auto-playing content respect prefers-reduced-motion.
- [ ] Nothing is clipped, overlapped or unreachable at 320px width or 200% zoom.
- [ ] Body and control text pass their contrast ratio.
- [ ] No state or meaning is carried by color alone.
- [ ] Destructive actions have a confirmation, an undo, or a distinct treatment.
- [ ] No content is truncated without a way to reach the full value.
- [ ] No content or control hides past a scroll edge or disclosure without a visible cue.
- [ ] Every error names a way to recover.
- [ ] Semantic colors are used for their meaning only (danger never on a safe action).
- [ ] No state change is carried by motion alone.
- [ ] Nothing focused hides under sticky chrome, and overlays contain their own scroll.
- [ ] Worst-case values (long, empty, many, missing, right-to-left) don't break the layout.

## Review with these skills

Every interface built with ssntl/ui is reviewed with the same skills the library is. Install them once and keep them current:

```bash
npx skills@latest add https://github.com/jakubkrehel/skills --skill better-interface
npx skills@latest add jakubkrehel/make-interfaces-feel-better
npx skills@latest add emilkowalski/skills
```

- **better-interface** (Jakub Krehel): The full review: accessibility, layout, writing, typography, color and polish. Its escalation triggers block a release.
- **make-interfaces-feel-better** (Jakub Krehel): The details: concentric radii, optical alignment, press scale, interruptible and subtle motion, hit areas.
- **emilkowalski/skills** (Emil Kowalski): Design engineering: easing, durations, springs and gestures (emil-design-eng, review-animations, animation-performance) and the worst-case values that break a UI (break-ui).

## Related

- [Empty state](empty-state.md): An empty screen that says what will appear and offers the action that fills it.
- [Card](card.md): A flat tile separated by tone, not borders, with one brand tone for text on color.

---

Generated from the ssntl/ui source by `scripts/build-rules.mjs`. The whole rulebook is [ssntl-ui.md](ssntl-ui.md); every component's rules are at https://ui.ssntl.app/rules.