Umbra

by Aid Beisembin

Tokens, components and rules that people and AI agents use to build interfaces

ShadeNotesPortfolioBuilt with Umbra

Sections

Get started

Quick start

Connect the registry, a product theme and your first component, then check the build

Example screen

A finished screen built from Umbra components: how the parts work together

Foundations

Color and contrast

The colors, what each one is for and how to check legibility

Typography

The type scale: sizes, weights and when to use each

Spacing and grid

The spacing scale, radii and the inner-outer rule

IconsIcon

The Phosphor set: weight, sizes and what not to do

Product themes

The base and the product layer: how to add the ShadeNotes, portfolio or a new theme

Glass and motion

Glass for the control layer, springs, morphing and entrances

Components

Structure

Window, Page, Tile, Sidebar

Controls

Button, Chip, Field, Select, Toggle, Search, Counter, List row

Loading and notifications

Spinner, Skeleton, Toast, Notice card

Recording

Recording dock

Screens

First run, Processing, Showcase

For AI agents

Connect an agent

What to give the agent in a product: DESIGN.md, the registry via MCP, llms.txt and a snippet

“Screen in Umbra” skill

A Claude Code skill: how to build a screen and the report checklist

Characters and logos

Product marks

Product characters and logos, their sizes and how to add a mark

Portfolio’s live character

Emotions, moves and gestures of the portfolio’s live character

For developers

Code checks (ESLint)

Umbra rules in ESLint: what they catch and how to add them

Class merging (cn)

The cn function: merge Tailwind classes without conflicts

Add Umbra to a product

npx shadcn@latest add @umbra/theme-base @umbra/theme-shadenotes @umbra/eslint

The registry, a product theme, CSS, your first component and checks, step by step, in “Quick start”

Version 0.1.0