tags:

• documentation
• figma
• frontend
• v0
• ai

@dancingteeth/rep-design

REP design tokens as CSS (Tailwind v4 @theme / @utility), TypeScript mirrors, plus AI / v0 integration packs: DESIGN.md, AGENTS.md, CLAUDE.md, brandbook.pen (Pencil), design-tokens.json, and a one-line rep-agent-globals.css import.

Published on npm. Release process: docs/TEAM_BRANDBOOK.md.

Working example (this monorepo)

The npm package is CSS + tokens + Leaderboards raster/SVG + docs. To run the Leaderboards screen on localhost with the same stack as production:

pnpm install
pnpm dev:leaderboards-example

See examples/rep-leaderboards-vite/README.md — it uses @dancingteeth/rep-design plus the workspace React package @dancingteeth/rep-leaderboards-ui (RepLeaderboardsScreen). The main app **pnpm dev** (apps/web) imports that package too so there is a single source for the screen.

AI agents & v0 — read this first

| Artifact | Purpose | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | CLAUDE.md | Full xflow_frontend-aligned agent guide (Figma MCP → tokens, repo map, release checklist) — also at monorepo root as a pointer file | | brandbook.pen | Pencil brandbook source (typography / colors / artifacts boards); pencil.exports.json in the repo points at this path | | DESIGN.md | Full DESIGN.md-style spec for tools that ingest a single markdown design file | | AGENTS.md | Short rules for codegen (semantic shadcn classes vs REP rep-* utilities) | | STATES_AND_PRIMITIVES.md | System-wide state tokens + Button / Input / Tabs / Badge / Banner / Skeleton primitives — start here for new UI | | ./leaderboard-assets | repLeaderboardAssets — new URL(…, import.meta.url) map for Leaderboards binaries under src/assets/rep-leaderboards/ (bundler-friendly, not Vite-only); sync from apps/web via pnpm rep-design:sync-leaderboard-assets | | LEADERBOARDS_DS.md | Leaderboards pixel checklist + v0 prompt to ship this screen and similar layouts | | skills/rep-figma-handoff/ | Agent Skill (Cursor / Claude Code / Codex CLI) — Figma → REP tokens workflow with inventory, measurements, asset, and release prompts for any new REP screen | | skills/rep-html-styling/ | Agent Skill — standalone HTML + REP styling; Vite scaffold + standalone export; LOCAL_SETUP.md | | skills/rep-html-styling-setup/ | Agent Skill — bootstrap Node/pnpm/Vite for PMs with no local dev env (pairs with rep-html-styling) | | pr-office-bundle/SLIDES_COM.md | Slides.com / reveal.js handoff guide for PR/comms decks without a Tailwind compiler | | design-tokens.json | JSON: hex aliases, CSS var names, class lists, webAssetsSourceOfTruth (Leaderboards 21631:2239), import snippets | | rep-agent-globals.css | One import chaining fonts → Tailwind → theme → primitives → layout → shadcn bridge |

Why “npm install changed nothing”: the package does not auto-inject styles. You must import CSS (see below). For v0 / shadcn output, **rep-shadcn-v0-bridge.css is required** so bg-background, text-foreground, etc. map to REP.

Install the Figma handoff skill (Cursor / Claude Code)

After pnpm add @dancingteeth/rep-design, link the shipped skill into your tool's discovery folder so the agent picks up the Figma → REP workflow automatically:

# Cursor
mkdir -p .cursor/skills && ln -s ../../node_modules/@dancingteeth/rep-design/skills/rep-figma-handoff .cursor/skills/rep-figma-handoff

# Claude Code
mkdir -p .claude/skills && ln -s ../../node_modules/@dancingteeth/rep-design/skills/rep-figma-handoff .claude/skills/rep-figma-handoff

The skill covers any new REP screen (not just Leaderboards): inventory, exact measurements for 1:1 parity, asset download/sync, and the package release flow. Full install + usage details: skills/rep-figma-handoff/README.md.

Standalone HTML (product / comms): link skills/rep-html-styling/ the same way (rep-html-styling instead of rep-figma-handoff). PMs paste from PROMPT_PACK.md.

Prompt snippet for v0 / ChatGPT:

After pnpm add @dancingteeth/rep-design tailwindcss@^4, add @import "@dancingteeth/rep-design/rep-agent-globals.css"; to globals.css, add @source to node_modules/@dancingteeth/rep-design/src, and use shadcn semantic classes (bg-background, text-foreground, border-border, bg-primary) — do not hard-code light-theme grays for the app shell.

Install

pnpm add @dancingteeth/rep-design
# or
npm install @dancingteeth/rep-design

tailwindcss >= 4 is an optional peer dependency (use it whenever you consume @theme / @import "tailwindcss").

Option A — single CSS import (best for v0 / AI prototypes)

@import "@dancingteeth/rep-design/rep-agent-globals.css";

Then ensure Tailwind sees REP utilities (same file or project root CSS):

@source "../node_modules/@dancingteeth/rep-design/src";

Option B — explicit imports

@import "@dancingteeth/rep-design/graphik-fonts.css";
@import "tailwindcss";
@import "@dancingteeth/rep-design/rep-design-system.css";
/* System primitives (Button / Input / Tabs / Badge / Banner / Skeleton + state tokens). */
@import "@dancingteeth/rep-design/rep-primitives.css";
@import "@dancingteeth/rep-design/rep-components.css";
/* Required for shadcn/ui + v0 primitives (bg-background, text-foreground, …): */
@import "@dancingteeth/rep-design/rep-shadcn-v0-bridge.css";

TypeScript

import {
  repBrand,
  REP_TYPE_SCALE,
  REP_FIGMA,
  REP_WEB_ASSETS_SOURCE,
  REP_LAYOUT_COMPONENT_UTILITIES,
  REP_PRIMITIVE_UTILITIES,
  REP_PRIMITIVE_DEFAULTS,
  REP_STATE_TOKENS,
  REP_VALIDATION_TOKENS,
  repTypeUtilityClass,
} from "@dancingteeth/rep-design";

repTypeUtilityClass("graphik", "hero"); // "rep-type-hero"
repTypeUtilityClass("inter", "body"); // "rep-type-body-inter"

const primaryButtonClass = REP_PRIMITIVE_DEFAULTS.button.primary;
// "rep-btn rep-btn-primary rep-btn-md rep-focus-ring"

const errorRing = `0 0 0 ${REP_STATE_TOKENS.focusRingWidth} ${REP_VALIDATION_TOKENS.error.fg}`;

Files in the package

| File | Role | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | src/rep-design-system.css | @theme, @utility — core --color-rep-*, type ramp, gradients, state tokens (focus / hover / active / disabled / validation / motion / skeleton) | | src/rep-primitives.css | System @utility — rep-btn, rep-input, rep-tabs, rep-badge, rep-banner, rep-skeleton, rep-focus-ring, rep-pressable | | src/rep-components.css | Layout @utility — rep-cmp-* (sidebar, leaderboard, chips, segments, progress) + rep-text-gradient-leaderboard-title | | src/rep-shadcn-v0-bridge.css | Maps shadcn/v0 semantics → REP (v0 design systems, shadcn theming) | | src/rep-agent-globals.css | Bundled import order for agents (single entry) | | src/graphik-fonts.css | Graphik LCG @font-face | | src/rep-brand-tokens.ts | repBrand, REP_FIGMA, repTypeUtilityClass, palette arrays | | src/leaderboard-assets.ts | repLeaderboardAssets — import.meta.url URLs for Leaderboards PNG/SVG under src/assets/rep-leaderboards/ (standard bundler asset pattern) | | src/assets/rep-leaderboards/*| Leaderboards binaries shipped on npm (sync from apps/web/public/rep-leaderboards/ via pnpm rep-design:sync-leaderboard-assets) | | CLAUDE.md | Agent guide (monorepo workflows + npm); monorepo root CLAUDE.md is a short pointer here | | brandbook.pen | Pencil document (schema 2.10); paired with repo pencil.exports.json | | DESIGN.md / AGENTS.md | Human + AI design spec | | pr-office-bundle/SLIDES_COM.md | PR/comms guide for using REP tokens in Slides.com / reveal.js | | design-tokens.json | Machine-readable token map + monorepo / figmaSandbox registry | | src/brand-artifacts/README.md | Where durable brand SVG/PNG sources live before mirroring to apps/web/public/ |

Foreground on dark: text-rep-foreground / repBrand.cssVars.color.foreground.

Fonts

The npm package ships CSS (graphik-fonts.css with @font-face rules) and Leaderboards raster/SVG under src/assets/rep-leaderboards/ — not Graphik .otf binaries (Commercial Type license). Consumers must place licensed files at **/fonts/graphik/*.otf** as documented in graphik-fonts.css.

Inter is referenced as --font-inter in rep-design-system.css; the package does not bundle Inter files. Either load Inter from a CDN, add **@fontsource/inter** (as in this repo’s apps/web), or self-host woff2 and define matching @font-face rules before utilities that use var(--font-inter).

Git sparse checkout (tokens only)

git clone --filter=blob:none --sparse https://github.com/inf0riaorg/xflow_frontend.git
cd xflow_frontend
git sparse-checkout set packages/rep-design

Naming in this monorepo

See TEAM_BRANDBOOK.md: --{category}-rep-*, repBrand.cssVars, REP_* exports.