Tollerud User Interface

License

MIT applies to source code only — not to Tollerud trademarks, the monogram, avatars, or other brand assets.

| Document | What it covers | |----------|----------------| | LICENSE | MIT for software + trademark and brand asset notice | | brand/LICENSE | Terms for files under brand/ (logos, monogram exports, avatars) |

The npm "license": "MIT" field refers to the software components. Brand assets remain proprietary. Usage guidelines: BRAND.md.

Dark, monochrome React components with a single yellow accent. Noir aesthetic meets modern utility.

Live docs → · React ≥ 18 · TypeScript included · Tailwind v4 (v3 via globals-v3.css)

30-second start

npm install @tollerud/ui clsx tailwind-merge tailwindcss@4 \
  @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-progress \
  @radix-ui/react-slot @radix-ui/react-tabs @radix-ui/react-tooltip \
  lucide-react framer-motion sonner

Looks long — most apps only do this once. Peers stay in your app so you control versions. See peer dependencies by family if you want to know what each group is for.

/* app/globals.css */
@import '@tollerud/ui/globals.css';
@import '@tollerud/ui/source.css';

import { Button, Card } from '@tollerud/ui'

export function Home() {
  return (
    <Card>
      <Button variant="primary">Deploy</Button>
    </Card>
  )
}

Starter template: examples/next-starter/ — copy, npm install, npm run dev. See GETTING_STARTED.md for the full guide, AI agent prompts, and migration from copied components.

Full setup, migration, and edge cases: GETTING_STARTED.md.

Which doc should I use?

| Resource | Use for | |----------|---------| | GETTING_STARTED.md | Install, Tailwind, paths, migration, audit — start here | | COMPONENTS.md | Usage examples, CSS patterns, homelab/dashboard recipes | | SKILL.md | Export catalog and gotchas (source of truth for agents) | | PROPS.generated.md | Machine-checked prop tables | | BRAND.md | Logo, nav lockup, trademark rules | | Live docs | Browse every component with copy-paste demos |

Choose your path

| Path | Install | CSS / setup | |------|---------|-------------| | Full design system (most users) | @tollerud/ui + required peers (see 30-second start) | globals.css + source.css | | Footer only | @tollerud/footer | Still need Tollerud tokens — @tollerud/ui/globals.css or equivalent | | Tailwind v3 (legacy) | Same peers as full system | globals-v3.css + @tollerud/ui/preset in tailwind.config.ts — details | | NoirGlowBackground only | Add @paper-design/shaders-react | Optional peer — all other components work without it |

| Package | When | |---------|------| | @tollerud/ui | Components, tokens, preset, brand assets | | @tollerud/footer | Branded footer without Radix, Lucide, Framer Motion, or Sonner peers |

@tollerud/ui exports Footer from the same source as @tollerud/footer (npm run sync:footer keeps them lockstep). @tollerud/footer bundles clsx and tailwind-merge on purpose for the lean path.

Peer dependencies by family

| Family | Packages | Needed for | |--------|----------|------------| | Always | react, react-dom, clsx, tailwind-merge, tailwindcss | Every integration | | Overlays & navigation | @radix-ui/react-dialog, @radix-ui/react-dropdown-menu, @radix-ui/react-tabs, @radix-ui/react-tooltip, @radix-ui/react-slot, @radix-ui/react-progress | Dialog, Sheet, Drawer, DropdownMenu, Tabs, Tooltip, Progress, Button asChild | | Icons | lucide-react | Components with built-in icons | | Motion | framer-motion | Animated components (e.g. GlowCard, charts) | | Toasts | sonner | <Toaster /> / toast API — mount once at app root | | Optional — glow | @paper-design/shaders-react | NoirGlowBackground only |

The design system bundles only class-variance-authority. Radix, Lucide, Framer Motion, and Sonner have been peers since v2.0.0.

Philosophy

Clean lines. Sharp contrast. Yellow where it counts.

Tollerud UI is minimal but not cold. It uses a near-black foundation with warm yellow accents for interaction points. Every element has purpose — nothing decorative for its own sake.

Setup details

CSS (source.css)

source.css resolves @source inside the installed package — works with npm, pnpm, Yarn workspaces, and Bun. Without it (or a correct manual @source path), component styles can be purged in production. See GETTING_STARTED.md for monorepo paths.

Optional preset shim

If you need utilities from @tollerud/ui/preset beyond what tokens.css provides:

// tailwind.config.ts
import tollerudPreset from '@tollerud/ui/preset'
export default { presets: [tollerudPreset] }

@import 'tailwindcss';
@config './tailwind.config.ts';
@import '@tollerud/ui/tokens.css';
@import '@tollerud/ui/globals-layers.css';
@import '@tollerud/ui/source.css';

Tailwind v3 (legacy)

import type { Config } from 'tailwindcss'
import tollerudPreset from '@tollerud/ui/preset'

export default {
  presets: [tollerudPreset],
  content: [
    './app/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    './node_modules/@tollerud/ui/dist/**/*.{js,mjs}',
  ],
} satisfies Config

@import 'tailwindcss/preflight';
@import 'tailwindcss/utilities';
@import '@tollerud/ui/globals-v3.css';

Imports and tree-shaking

import { Button, Card, Badge, cn, PageShell, Section } from '@tollerud/ui'
// or subpaths:
import { Button } from '@tollerud/ui/button'

cn and buttonVariants are safe to import from Server Components — they do not force your file to become a Client Component. Prefer @tollerud/ui/utils only when tree-shaking cn without the barrel.

TypeScript types are included. SKILL.md lists every export; PROPS.generated.md has machine-checked prop tables; COMPONENTS.md has usage examples.

Do not copy package internals

Use the npm package in consumer apps. Do not vendor components/, lib/utils.ts, or a local components/ui clone from this repo — copied files drift from the published API and make agents rebuild Tollerud UI by hand. If you already copied components, follow the migration checklist in GETTING_STARTED.md.

Usage example

Prefer component-first composition — layout primitives and screen patterns before raw Tailwind soup:

import { Button, Card, CodeBlock, HeroBlock, StatusDot } from '@tollerud/ui'

<HeroBlock
  eyebrow="homelab control plane"
  title="Run your stack like production."
  description="Deploy, monitor, and roll back from one keyboard-first console."
  actions={<Button variant="terminal" size="lg">open_dashboard</Button>}
/>
<Card accent>
  <StatusDot status="online" label="Emma — ready" />
</Card>
<CodeBlock>{`❯ systemctl status tollerud-agent`}</CodeBlock>

Consumer styling policy

Tailwind is allowed inside @tollerud/ui and as small app-level glue. In consumer apps, prefer exported components and layout primitives first; do not rebuild buttons, cards, panels, navs, dashboards, or branded page structure with raw utilities. See GETTING_STARTED.md for allowed and discouraged examples.

Plain CSS

Include tokens.css or globals.css for CSS custom properties and utility classes. This path is for static HTML/prototyping; React apps should prefer the package components above.

<link rel="stylesheet" href="globals.css">
<div class="tollerud-card">
  <h2 class="tollerud-display--secondary">Tollerud User Interface</h2>
  <button class="tollerud-btn tollerud-btn--primary tollerud-btn--md">Get Started</button>
</div>

Brand assets

Import via @tollerud/ui/brand/tollerud-avatar.svg (and .png / full-figure variants). Prefer <Monogram /> for nav lockups. See BRAND.md.

Consumer audit

After setup, self-audit consumer apps with:

npx tollerud-ui-audit

The command ships with @tollerud/ui and flags missing source.css, copied components/ui clones, hardcoded brand colors, and invalid Button/Link nesting. See GETTING_STARTED.md for the full error-code reference and --warn-only flag.

Palette Summary

| Token | Hex | Usage | |-------|-----|-------| | --tollerud-yellow / --tollerud-acid | #FFFF00 | Primary actions, highlights, links, focus, key data | | --tollerud-yellow-warm | #E8D500 | Secondary yellow, gradients, warm states | | --tollerud-amber | #FFB800 | Warmth accents, secondary highlights | | --tollerud-black | #0A0A0A | Default background | | --tollerud-noir-900 | #121212 | Card / raised surface | | --tollerud-noir-800 | #1A1A1A | Overlay / modal surface | | --tollerud-noir-700 | #252525 | Hover state surface | | --tollerud-noir-600 | #333333 | Borders | | --tollerud-noir-400 | #666666 | Muted text, disabled | | --tollerud-noir-200 | #AAAAAA | Secondary text | | --tollerud-noir-50 | #E5E5E5 | Subtle dividers (light) | | --tollerud-white | #F5F5F5 | Primary text |

Typography

• Display / Body: Inter — clean, highly readable, Swiss-inspired
• Monospace: JetBrains Mono — for code, metrics, and terminal aesthetics
• Scale: 2xs (0.625rem) → 9xl (8rem)
• Weights: 400 (normal), 500 (medium), 600 (semibold), 700 (bold), 900 (black)

CSS class reference

These classes are available for package internals, docs examples, and static HTML/prototyping. React consumers should prefer the exported components and use Tailwind only as small local glue.

Buttons

<button class="tollerud-btn tollerud-btn--primary tollerud-btn--md">Action</button>
<button class="tollerud-btn tollerud-btn--secondary tollerud-btn--md">Cancel</button>
<button class="tollerud-btn tollerud-btn--ghost tollerud-btn--md">More</button>

Cards

<div class="tollerud-card">
  <h3 class="font-semibold mb-1">Title</h3>
  <p class="text-tollerud-text-secondary text-sm">Content</p>
</div>

Badges

<span class="tollerud-badge tollerud-badge--accent">New</span>
<span class="tollerud-badge tollerud-badge--success">Online</span>
<span class="tollerud-badge tollerud-badge--error">Offline</span>

Code

<code class="font-mono text-sm text-tollerud-text-secondary">const x = 42;</code>

Principles

1. Dark-first — Light mode is secondary. Design starts in the dark.
2. Yellow is the signal — Yellow is for interaction. If it's yellow, you can click it.
3. One color pop — No rainbows. Yellow carries the weight. State colors (green, red, blue) are muted to avoid noise.
4. Sharp when it counts — Radius is subtle. Full round only for pills. Sharp corners for the noir feel.
5. Glow with purpose — Yellow glow only on hover/active states. Never decorative.

File Structure

design-system/
├── .nvmrc                    # Node 24 for local dev / CI parity
├── package.json              # @tollerud/ui — version, exports, scripts
├── registry.json             # Repo-only drift manifest (`test:drift`; not in npm tarball)
├── CHANGELOG.md              # Version history (synced to docs on build)
├── SKILL.md                  # AI agent catalog — source of truth for exports
├── COMPONENTS.md             # Usage guide + export index (props: PROPS.generated.md)
├── PROPS.generated.md        # Auto-generated prop tables (`npm run test:props`)
├── AGENTS.md                 # Contributor / release guide
├── brand/                    # Logo + Tia avatars (npm: @tollerud/ui/brand/*)
├── components/               # React components (*.tsx) + index.ts barrel
├── globals.css               # Tailwind v4 entry (tokens + component layers)
├── globals-v3.css            # Tailwind v3 legacy
├── globals-layers.css        # Shared component CSS layers
├── tokens.css                # Design tokens
├── tollerud-preset.cjs       # Tailwind preset (CJS)
├── scripts/                  # Build, validate, docs, and release helpers
├── docs-app/                 # Next.js docs site (static export → _site/)
│   ├── app/                  # App Router + globals.css
│   ├── components/           # Page demos + docs shell
│   ├── styles/docs.css       # Docs chrome + light theme
│   └── public/CNAME          # design.tollerud.dev
└── fixtures/consumer/        # npm tarball install smoke test (CI)

CSS utilities and generated classes

These lower-level classes and Tailwind utilities are available for package internals, docs demos, static HTML, and custom escape hatches. React consumers should still prefer exported components and use utilities only as small local glue.

| Area | CSS Class | Implementation utility | Description | |-----------|-----------|---------------------|-------------| | Noir Glow Background | .tollerud-noir-glow-* | bg-tollerud-noir-glow | Tollerud.no-inspired acid-yellow glow fallback | | Grid Background | .tollerud-grid-bg | bg-tollerud-grid bg-[length:40px_40px] | Subtle yellow grid pattern | | Terminal Button | .tollerud-btn--terminal | — | Monospace CTA with ❯ prefix | | Pill Tag | .tollerud-pill--outline / --muted | — | Tiny label/tag components | | Accent Bar | .tollerud-accent-bar | bg-tollerud-gradient-bar h-[1px] | Gradient divider bar | | Gradient Text | .tollerud-gradient-text | bg-tollerud-gradient-soft bg-clip-text text-transparent | Yellow → amber gradient text | | Display Heading | .tollerud-display | tracking-tightest leading-[0.95] font-semibold text-white | Tight, impactful display heads | | Display Shimmer | .tollerud-display-shimmer | — | Animated yellow gradient sweep clipped to hero accent text (dark surfaces) |

Publishing (contributors)

Bump version in package.json and push to main — the publish-npm GitHub Action runs npm publish --provenance via npm Trusted Publishers (OIDC) and creates a matching GitHub Release. See AGENTS.md.