Install

How to add @smaller-earth/ui to a new SE app. Written for a fresh Next.js project.

Pre-release note. The library isn't published on npm yet. Until it is, SE apps in this monorepo import it via the workspace link.

01Prerequisites

React 19, Next.js 15, Tailwind v4, Node 20+.

02Install

npm install @smaller-earth/ui @base-ui/react lucide-react

The first is the library. The other two are peer dependencies the library declares but doesn't ship.

03Configure Tailwind and import brand styles

In your app's globals.css:

@import "tailwindcss";
@source "../node_modules/@smaller-earth/ui/dist/**/*.js";

@import "@smaller-earth/ui/styles.css";

@import "@smaller-earth/ui/styles.css" loads all five brand themes, each gated by a .brand-<key> selector.
@source tells Tailwind to scan the library's bundled JS for utility class names. Adjust the path depending on where globals.css lives relative to node_modules.

04Pick a brand

Set className="brand-<key>" on <html> in your root layout:

<html lang="en" className="brand-campfront">

The relevant brand tokens activate. Swap the class to switch brands. Combine with .dark for dark mode (e.g. via next-themes).

05Load the font

Set up next/font/google with Inter in app/layout.tsx, apply its variable to <html>. The brand CSS references var(--font-inter).

06Use a component

import { Button } from "@smaller-earth/ui"

export default function Page() {
  return <Button>Save changes</Button>
}

07Tell Claude Code about the library

If the app uses Claude Code, add the block below to the app's CLAUDE.md. Append it if the file already exists, or create one at the repo root if it doesn't. The snippet is deliberately thin: it points agents at https://ui.smallerearth.com/llms-full.txt as the canonical reference so this file doesn't need updating when the library changes.

## Smaller Earth UI

This app consumes `@smaller-earth/ui`, a themed shadcn Base UI Vega component library.

### Before writing UI code

Fetch the current rules, tokens, component catalogue, and writing guide:

- https://ui.smallerearth.com/llms-full.txt — canonical reference, one file
- https://ui.smallerearth.com/components/<slug> — examples for a specific component (e.g. /components/button)
- https://ui.smallerearth.com/docs/writing — copy rules for voice, language, and UI microcopy

Treat those URLs as the source of truth.

### The one rule that never changes

Never write raw interactive HTML: no `<button>`, `<input>`, `<select>`, `<textarea>`, or `<dialog>`. Always import from `@smaller-earth/ui`. The only exception is `<form>`.

If the docs site is password-protected, append Vercel's Protection Bypass token to each URL: ?x-vercel-protection-bypass=YOUR_BYPASS_TOKEN. Generate the token in Vercel Project Settings → Deployment Protection → Protection Bypass for Automation. Paste the real token into the snippet before committing to the consuming app's repo. Rotate it in Vercel when needed and update consumer repos.

Troubleshooting

Components render unstyled: the Tailwind @source path is wrong, or @import "@smaller-earth/ui/styles.css" is missing from globals.css.
Brand colours don't change: confirm <html> has the right brand-<key> class.
Font doesn't load: confirm next/font is wired in layout.tsx and its variable is applied to <html>.