Installation
The install guide from the pack’s README, in 5 steps. Then pick components from the overview.
Install with your agent
Unzip the pack into your project as guibrief-pack/, then tell your coding agent:
INSTALL.md walks the agent through the steps below, removes the starter styles that would override the house style, then builds the project and runs guibrief check. Your agent will likely ask you to approve the copy and install commands. To do it by hand instead, follow steps 1–3.
1. Copy the files into your project
Drop these into your own React / Next.js project, keeping the folder names:
tokens/→ your project (e.g. alongside your existing styles)components/→ your project's component directory, including itslib/folder (the components import from it). These are components, not a page or a demo.GUI.md→ your project rootdocs/→ your project root (GUI.md, the skill and the components citedocs/design-system/foundation.md)
The tokens are plain CSS custom properties, with no dependency. The components need these packages: lucide-react for icons, @base-ui/react for the behavior of interactive components (focus, keyboard, pressed state), react-resizable-panels for Resizable, cmdk for Command, react-day-picker and date-fns for Calendar and Date Picker, @tanstack/react-table for Data Table, recharts and react-is for Chart, embla-carousel-react for Carousel, shiki for Code Block, @shadcn/react for Message Scroller, Questionnaire and Conversation, and anser for Terminal. Install them in your project:
Leave out the packages for components you don't use: the first two are needed by most components; each of the others is needed only by the components named above.
2. Wire tokens into Tailwind v4
Guibrief's tokens are CSS custom properties (--color-*, --type-*, --radius-*, --shadow-*, --duration-*, --ease-*) in tokens/*.css. tokens/tailwind-theme.css maps every one of them into Tailwind v4's @theme, so utilities like bg-brand, text-body, rounded-md, shadow-sm, duration-base and ease-standard exist. Import the token files and the theme once in your global stylesheet:
Adjust the paths to wherever you put tokens/. That's the whole wiring.
tailwind-theme.css also sets the page's background, text color and font. A new project's starter stylesheet (e.g. create-next-app's) sets those too, outside any CSS layer, so it wins: remove its default :root colors, its dark-mode block for them, its body rule, and the @theme entries that point at them or at a starter font. INSTALL.md step 4 lists them exactly. The theme file explains its choices in its header comment: @theme inline keeps light/dark mode live; the motion keys make the components' transitions respect reduced motion; spacing is Tailwind's own default scale, so it isn't redeclared. The Guibrief site imports this exact file, so what you get is what the site runs.
3. Install the agent skill
The same skill folder works in Claude Code and in Cursor. Copy the whole skills/guibrief-house-style/ folder into your project's skill directory for the agent you use (create the parent folder first if it doesn't exist):
Each agent reads the skill's description field to decide when it's relevant, so no extra registration step is needed once the file is in place.
Claude Code, one more step: paste snippets/CLAUDE.md into your project's CLAUDE.md (create it at the project root if needed), so every session starts with the house-style rules.
If your agent reads `AGENTS.md` (not tested yet): paste snippets/AGENTS.md into your project's AGENTS.md (create it at the project root if needed). It carries the same rules and points the agent at GUI.md. It works whether or not your agent also loads the skill.
4. Read GUI.md every UI session
Before generating or editing any UI — a component, a page, a form, a button, a link, any color/spacing/radius/shadow/motion class — read GUI.md first. It's short on purpose: design principles, the anti-patterns list, and where every primitive lives. The agent skill installed in step 3 points agents at it automatically; if you're working with a different agent or by hand, read it yourself before touching styles.
DESIGN.md
DESIGN.md is the same house style in Google's open DESIGN.md format: the tokens as machine-readable frontmatter, plus the rules as prose. Put it at your project root. Tools that read DESIGN.md can use it directly; for example, the shadcn agent skill maps a DESIGN.md onto your shadcn theme. It's generated from tokens/, so the two always agree, and it passes npx @google/design.md@0.4.0 lint with 0 errors (its "Known Gaps" section explains the remaining warnings).
Using shadcn/ui
If your project uses shadcn/ui, give its components the Guibrief look with one command:
(Point it at wherever you put the pack's registry/ folder.) The shadcn CLI writes the theme into your global stylesheet. Or import tokens/shadcn-theme.css after your shadcn theme block; it has the same values. Every shadcn variable maps to a Guibrief role (primary = brand, accent = hover fill, ring = focus ring, …), for light and dark (.dark or [data-theme="dark"]). Keep using shadcn's components; run guibrief check to catch drift.
Your brand: the pack ships one blue and one set of corners. From the folder that contains tokens/, rebuild them and regenerate DESIGN.md and the shadcn theme together:
--brand is oklch(L% C H). --radius is sharp, default, soft or round. The command writes nothing if the new palette fails the same contrast pairs the pack is tested against.
Corners: --radius is 0.5rem, which gives Guibrief's 8px buttons and inputs in current shadcn styles (such as base-nova, the CLI default), because they derive the radius scale by multiplying --radius. Older styles (new-york) subtract instead: if your global stylesheet has --radius-md: calc(var(--radius) - 2px), set --radius: 0.625rem after the theme to get 8px buttons.
5. Check your code (guibrief check)
Agents drift. bin/guibrief-check.mjs scans your code and reports where it left the house style. It needs Node and nothing else. Copy bin/ into your project (for example as guibrief/bin/), then:
It exits 1 when there are errors, so it can gate CI. Warnings don't fail it. It exits 2 for usage problems (a path that doesn't exist, nothing to scan, a bad guibrief-check.json), so a typo never looks like a clean pass. --help prints the same rules as below.
| Rule | Severity | What it catches |
|---|---|---|
token/color | error | hard-coded colors (hex, rgb, hsl, oklch…) in classes, CSS or style objects |
token/palette | error | Tailwind palette colors (bg-blue-500) instead of Guibrief roles |
token/arbitrary | warning | arbitrary spacing or radius (p-[13px], rounded-[10px]) |
mobile/* | error | desktop-first patterns: max-* variants, max-width queries, break-all, fixed sizes ≥ 320px on the base layout |
a11y/target-size | warning | a raw <button>, <a>, <input>, <textarea> or <select> with both dimensions fixed under 44px. It's a heuristic: it misses controls sized only by padding, sizes set in CSS, and classes held in variables or props; it never applies to the pack's own components |
state/focus-visible | warning | a raw control that removes the focus outline (outline-none/outline-0/outline-hidden) and adds no focus-visible: style back. It reads className="…" and the strings inside className={cn(…)}/clsx(…), not variables or props |
anti/* | warning | gradients, glass (backdrop-blur), heavy shadows, oversized radii, emoji |
Colors are checked in class names, .css files, JSX style={{…}} objects and SVG fill/stroke attributes. Other objects ({ href: "#add" }) aren't CSS and aren't checked, and neither are style objects kept in a variable and spread in (const s = { color: "#fff" }). Custom-property declarations (--brand: …) are never flagged, so you can override tokens. Next.js metadata files (manifest, icon, opengraph-image) are skipped, because they need literal values.
Intentional exceptions need a reason, and every ignore is listed in the output. An ignore without a reason (written -- why), or naming a rule that doesn't exist, is itself an error:
The comment covers its own line and the next; anti/* covers a group. For whole folders, use a guibrief-check.json at your project root:
Agents should run that same command on the files they changed before they hand UI back, fix every error, and report warnings they leave. The skill and snippets/CLAUDE.md / snippets/AGENTS.md say so. To fail a pull request on errors, copy snippets/github-action.yml to .github/workflows/guibrief-check.yml and commit the guibrief/bin/ folder with your code. Warnings do not fail the job.