@jeremyfuksa/campfire

v2.0.0

Published

14 days ago

Campfire Design System – reusable React components and tokens.

Downloads

1,359

0High
0Medium
0Low

jeremyfuksa

design-system react tailwind campfire ui

Campfire Design System

A React component library and design language built on layered design tokens, semantic theming, and accessible Radix primitives. The repo ships:

the publishable npm package @jeremyfuksa/campfire (~70 components, tokens, the editorial typography system, the Spark accent, and a Claude Code skill),
a Storybook docs site deployed to GitHub Pages.

Storybook is the only docs/dev surface. The hand-coded Vite playground that lived alongside it was retired in v0.9.x; everything has been ported to Storybook stories or MDX docs pages.

Live docs

Storybook is deployed to GitHub Pages at https://jeremyfuksa.github.io/campfire. It auto-generates per-component variants and controls from the stories under src/components/ui/, plus MDX docs pages in src/docs/ covering the design rules (Welcome, Foundations / Typography, Foundations / Spark, Foundations / Tokens, Foundations / Layout). The authoritative ruleset is design.md, which also ships in the npm tarball.

Getting Started

Option 1 — Install via npm

npm install @jeremyfuksa/campfire
# or
yarn add @jeremyfuksa/campfire

Then add the CSS tokens once (usually in your root entry file) and import components as needed:

import '@jeremyfuksa/campfire/styles.css';
import { Button } from '@jeremyfuksa/campfire';

export function Example() {
  return <Button>Campfire</Button>;
}

Note on the stylesheet. @jeremyfuksa/campfire/styles.css is opinionated. It sets a base font-family, applies border-color defaults to every element via *, ::before, ::after, styles bare h1–h6 / p / button / input elements, and includes a custom scrollbar theme. If you're mixing Campfire into an app with its own reset or another design system, you may want to scope these styles by either importing @jeremyfuksa/campfire/tokens.css (CSS variables only — no resets, no element styling) or wrapping Campfire-using regions in a class and gating these rules at the consumer level. The component JS itself is framework-neutral; the stylesheet is the opinionated part.

Next.js App Router. The published bundle marks every entry as "use client" so components that use hooks (Dialog, Popover, Sheet, ThemeProvider, etc.) work inside the app/ directory. Import as usual.

Loading the fonts in Next.js

Campfire's default styles.css pulls fonts via Google Fonts @import url(...) — fine in Vite or any plain bundler, but render-blocking and not ideal under Next.js. In a Next.js project, prefer next/font to self-host the families and let the framework handle preload + display swap. The Campfire CSS variables consume whatever family stack you provide, so you just need to point --font-sans, --font-body, and --font-heading-editorial at the next/font-generated CSS variables.

// app/fonts.ts
import { Space_Grotesk, Hanken_Grotesk, Fraunces, Fira_Code } from "next/font/google";

export const spaceGrotesk = Space_Grotesk({ subsets: ["latin"], variable: "--campfire-space-grotesk" });
export const hankenGrotesk = Hanken_Grotesk({ subsets: ["latin"], variable: "--campfire-hanken-grotesk" });
export const fraunces = Fraunces({
  subsets: ["latin"],
  variable: "--campfire-fraunces",
  axes: ["opsz", "SOFT", "WONK"],
});
export const firaCode = Fira_Code({ subsets: ["latin"], variable: "--campfire-fira-code" });

// app/layout.tsx
import "@jeremyfuksa/campfire/styles.css";
import "./globals.css"; // your overrides (see below)
import { spaceGrotesk, hankenGrotesk, fraunces, firaCode } from "./fonts";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html
      lang="en"
      className={`${spaceGrotesk.variable} ${hankenGrotesk.variable} ${fraunces.variable} ${firaCode.variable}`}
    >
      <body>{children}</body>
    </html>
  );
}

/* app/globals.css — point Campfire's font tokens at next/font's CSS variables */
:root {
  --font-sans: var(--campfire-space-grotesk), -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  --font-body: var(--campfire-hanken-grotesk), var(--font-sans);
  --font-heading-editorial: var(--campfire-fraunces), "Georgia", serif;
  --font-mono: var(--campfire-fira-code), ui-monospace, SFMono-Regular, Menlo, monospace;
}

This gives you next/font's automatic optimization (preload, self-hosting, no FOUT) while keeping Campfire's role-split rules — body prose still uses --font-body, UI still uses --font-sans, etc.

Option 2 — Clone + run locally

git clone https://github.com/jeremyfuksa/campfire.git
cd campfire
npm install
npm run storybook        # Storybook dev server (port 6006) — docs + component sandbox
npm run build-storybook  # Static Storybook build (output: storybook-static/)
npm run typecheck        # tsc --noEmit
npm test                 # Vitest smoke suite
npm run test:full        # Full vitest suite (~73 component tests)

The deployed docs at https://jeremyfuksa.github.io/campfire come from storybook build (predeploy → build-storybook, deploy → gh-pages -d storybook-static).

Claude Code skill (optional)

Campfire ships a Claude Code skill that teaches Claude the design system's rules — the Spark "Rule of One," the Fira Code scope, when Fraunces is allowed, editorial-theme boundaries, etc. — so suggestions and reviews stay aligned with design.md instead of drifting into generic Tailwind defaults.

The skill is a directory (SKILL.md entry plus reference/ rules and examples/ code) so Claude can load focused context on demand without pulling the whole design system into every prompt. Three install options, pick whichever fits your environment:

Option A — Drop in the .skill bundle (most portable). Campfire ships a pre-built .skill archive (zip with SKILL.md + supporting files at the canonical layout) in the package's dist/ directory.

mkdir -p .claude/skills
unzip -o node_modules/@jeremyfuksa/campfire/dist/campfire-design-system.skill -d .claude/skills/

Option B — Symlink the source directory (auto-updates with npm update).

mkdir -p .claude/skills
ln -sfn ../node_modules/@jeremyfuksa/campfire/skills/campfire-design-system .claude/skills/

Option C — Copy the source directory (works where symlinks don't).

mkdir -p .claude/skills
cp -r node_modules/@jeremyfuksa/campfire/skills/campfire-design-system .claude/skills/

The skill auto-activates on any TSX/TS/JSX/JS/CSS/SCSS file in the project, and on any prompt that mentions Campfire, Spark, editorial themes, Hanken Grotesk, Space Grotesk, Fraunces, or Fira Code. Claude reads the entry SKILL.md first, then pulls focused reference docs (reference/typography.md, reference/spark.md, reference/editorial.md, reference/tokens.md) and example snippets (examples/spark-correct.tsx, examples/spark-violation.tsx, etc.) only when relevant. The package's bundled design.md remains the canonical source of truth if anything in the skill ever needs to be cross-checked.

The .skill archive is produced by npm run build:skill (a vendored stdlib-Python adaptation of Anthropic's skill-creator packager). It's regenerated as part of npm run build:lib, so every published version of @jeremyfuksa/campfire ships a fresh .skill.

Building the Library Locally

The reusable components live under src/components and are re‑exported from src/lib/index.ts. Run:

npm run build:lib

This generates ESM, CJS, and type declarations in dist/.

Publishing / Installing

npm run release (runs build:lib then npm publish --access public)

Because the components rely on CSS custom properties and Tailwind‑style utility classes generated inside styles/globals.css, importing the stylesheet (as shown in Option 1) is required before using any components.

Cutting a Release

npm version patch   # or minor/major according to changes
npm run release     # builds dist/ and publishes to npm

Ensure you're logged in (npm login) and have registry permissions.

Design Tokens

Tokens are authored as W3C DTCG-format JSON under src/tokens/ and built with Style Dictionary into multiple distribution formats. Run npm run tokens to rebuild after editing.

Consuming tokens outside Tailwind

Three published entrypoints, pick whichever matches your tool:

// 1. Plain CSS custom properties (works in any environment)
import '@jeremyfuksa/campfire/tokens.css';
//   :root { --primary-500: #607a97; ... }
//   .dark { --bg-base: var(--neutral-950); ... }

// 2. Typed JS object (for runtime access in React, Node, etc.)
import tokens from '@jeremyfuksa/campfire/tokens';
console.log(tokens.color.primary['500'].value); // "#607a97"

// 3. Raw W3C DTCG JSON (for Figma Make, design-tool importers)
import tokensJson from '@jeremyfuksa/campfire/tokens.json';
//   { "color": { "primary": { "500": { "$value": "#607a97", "$type": "color" } } } }
//
// Dark-mode override values are available at:
import darkTokens from '@jeremyfuksa/campfire/tokens.dark.json';

Importing the full library stylesheet (@jeremyfuksa/campfire/styles.css) already includes these tokens — the standalone ./tokens.css export is for projects that want tokens without the component bundle.

Docs page export

In the docs app (Design Tokens page) you can also click Export JSON to download campfire-palettes.json, a flat palette snapshot kept for backward compatibility.

Editor & Terminal Themes

Campfire colors are available as themes for popular editors and terminals! See the themes/ directory for:

VS Code - Full color themes (light & dark)
iTerm2 - macOS terminal themes
Windows Terminal - Windows terminal color schemes
Hyper - Cross-platform terminal themes
Alacritty - GPU-accelerated terminal themes
Kitty - Fast terminal emulator themes
Color Exports - JSON, CSS for custom integrations

📖 Installation Guide

Theme Customization

Campfire includes a powerful theming system that supports light, dark, and system preference modes.

Using the Theme Provider

Wrap your app with the ThemeProvider:

import { ThemeProvider } from '@jeremyfuksa/campfire';

function App() {
  return (
    <ThemeProvider defaultTheme="system" storageKey="my-app-theme">
      {/* Your app */}
    </ThemeProvider>
  );
}

Theme Hooks

useTheme - Access and control the theme:

import { useTheme } from '@jeremyfuksa/campfire';

function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
      Toggle Theme
    </button>
  );
}

useResolvedTheme - Get the actual theme (resolves "system" to light/dark):

import { useResolvedTheme } from '@jeremyfuksa/campfire';

function MyComponent() {
  const resolvedTheme = useResolvedTheme(); // "light" | "dark"
  return <div>Current theme: {resolvedTheme}</div>;
}

useThemeToggle - Simple toggle between light and dark:

import { useThemeToggle } from '@jeremyfuksa/campfire';

function QuickToggle() {
  const toggle = useThemeToggle();
  return <button onClick={toggle}>🌓</button>;
}

Testing

Campfire uses Vitest and React Testing Library for comprehensive testing.

Running Tests

npm test              # Run tests in watch mode
npm run test:ui       # Run tests with Vitest UI
npm run test:coverage # Generate coverage report

Writing Tests

All components are tested for:

Rendering with various props
User interactions
Accessibility (via jest-axe)
Keyboard navigation
ARIA attributes

Example test:

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Button } from '@jeremyfuksa/campfire';

it('handles click events', async () => {
  const handleClick = vi.fn();
  render(<Button onClick={handleClick}>Click me</Button>);

  await userEvent.click(screen.getByRole('button'));
  expect(handleClick).toHaveBeenCalled();
});

Contributing Tests

When adding components, include tests in src/components/ui/__tests__/. See button.test.tsx for reference.