npm package: @gumgum/resonance
Description: GumGum's React design system — accessible components, design tokens, and patterns built on Radix primitives
Latest version: 0.14.0

# @gumgum/resonance

GumGum's design system. 78 React components built on Radix UI Primitives with BEM CSS, CSS custom properties, and a physics-inspired motion system.

## Installation

### Prerequisites

- React 19+
- Node.js 18+

### 1. Install the package

**From npm (private registry):**

```bash
npm install @gumgum/resonance
```

**From a tarball (direct distribution):**

```bash
npm install ./gumgum-resonance-0.1.0.tgz
```

### 2. Import styles

Add the CSS import to your app's entry point (e.g., `main.tsx` or `App.tsx`):

```tsx
import '@gumgum/resonance/styles.css';
```

This loads all component styles, the token system (`--gg-*` custom properties), and the tonal color palette.

### 3. Wrap your app with ResonanceProvider

```tsx
import { ResonanceProvider } from '@gumgum/resonance';

function App() {
  return (
    <ResonanceProvider>
      {/* Your app here */}
    </ResonanceProvider>
  );
}
```

The provider sets up the theme context, applies the `gg-root` class, and manages light/dark mode.

### 4. Start using components

```tsx
import { Button, Heading, Text, Flex, Card } from '@gumgum/resonance';

function Dashboard() {
  return (
    <Flex direction="column" gap="4" p="4">
      <Heading size="2">Dashboard</Heading>
      <Card>
        <Text>Welcome to your app.</Text>
        <Button variant="solid" intent="primary">Get Started</Button>
      </Card>
    </Flex>
  );
}
```

---

## Claude Code Integration

If your team uses [Claude Code](https://claude.com/claude-code), the package includes a built-in setup command that configures your project to enforce design system conventions automatically.

### What this does

When Claude Code works on your project, it will:

- **Load the DS skill system** — 85+ skill files containing component usage guidance, theme rules, composition patterns, and the build methodology
- **Use DS components first** — Claude will use `<Button>`, `<Card>`, `<Flex>` etc. instead of building ad-hoc HTML with inline styles
- **Follow the token system** — all colors, spacing, typography, and shadows use `var(--gg-*)` custom properties
- **Get warned about violations** — hooks detect when ad-hoc patterns are written and flag them for correction

### Setup

Run once after installing the package:

```bash
npx @gumgum/resonance setup
```

That's it. This command configures three things:

| What | Where | Purpose |
|------|-------|---------|
| Project instructions | `CLAUDE.md` | Tells Claude Code to load the DS skills and follow component-first rules |
| Skill loading hook | `.claude/hooks/enforce-skill-loading.sh` | Blocks AI subagents that don't load the DS skill system |
| Usage enforcement hook | `.claude/hooks/enforce-ds-usage.sh` | Warns when ad-hoc HTML is written instead of DS components |

#### Options

```bash
npx @gumgum/resonance setup --dry-run   # Preview changes without writing files
npx @gumgum/resonance setup --force      # Overwrite existing files
```

#### Safe to re-run

The setup command is idempotent:

- **CLAUDE.md** — If you already have one, the DS section is appended (or updated in place if it was previously added). Your existing instructions are never modified.
- **.claude/settings.json** — Hook entries are merged into your existing configuration. Other hooks from other tools are preserved.
- **Hook scripts** — Created if they don't exist, skipped if they do (unless `--force`).

#### What gets added to CLAUDE.md

The command appends a section wrapped in HTML comment markers:

```markdown
<!-- @gumgum/resonance:start -->
## @gumgum/resonance — Design System Integration
...instructions...
<!-- @gumgum/resonance:end -->
```

Running setup again replaces the content between these markers. Everything outside the markers is untouched.

### How it works under the hood

The skill system lives inside `node_modules/@gumgum/resonance/skills/`:

```
node_modules/@gumgum/resonance/
├── skills/
│   ├── resonance.md              # Master orchestrator — loaded first
│   ├── process/
│   │   └── build.md              # Component-first build rules (78-component inventory)
│   ├── design/
│   │   ├── foundations.md        # Design DNA, 80/20 rule, quality baseline
│   │   └── composition.md       # Page layout patterns
│   ├── theme/
│   │   ├── color.md              # CSS custom property color system
│   │   ├── typography.md         # Type scale
│   │   ├── spacing.md            # Spatial rhythm
│   │   ├── motion.md             # Animation system
│   │   ├── dark-mode.md          # Light/dark theming
│   │   └── ...                   # elevation, interaction, responsive, accessibility
│   ├── components/               # Per-component usage skills (74 files)
│   │   ├── form-controls/        # Button, Input, Select, Toggle, ...
│   │   ├── layout/               # Box, Flex, Grid, Container, ...
│   │   ├── overlays/             # Dialog, Popover, Accordion, ...
│   │   └── ...                   # typography, data-display, feedback, navigation, etc.
│   └── references/               # Deep-dive lookup tables
├── brand/                        # Brand tokens (colors, typography, motion)
├── claude/                       # Template files used by setup command
│   ├── CLAUDE.snippet.md
│   └── hooks/
└── bin/setup.js                  # The setup CLI
```

When Claude Code starts a task:

1. **CLAUDE.md** tells it to load `skills/resonance.md` (the orchestrator)
2. The orchestrator determines which skills to load based on the task (e.g., building a form → load `skills/components/form-controls/index.md` + `skills/process/build.md`)
3. The **build skill** enforces using DS components over ad-hoc HTML
4. The **hooks** provide a mechanical safety net — if the model drifts, the hook flags it

### What the build skill enforces

The build skill (`skills/process/build.md`) defines a decision tree:

1. Does a DS component exist for this? **Use it.**
2. Can I compose existing DS components? **Compose them.**
3. Can I use a layout primitive (`Box`, `Flex`, `Grid`) with tokens? **Use it.**
4. Is this purely structural with no visual treatment? **Plain `<div>`, no styles.**
5. Only now: custom HTML + CSS (with `gg-*` BEM classes and `var(--gg-*)` tokens).

The skill contains a complete inventory of all 78 components mapped to common UI needs, so there's no guessing about what's available.

### Updating

When you update `@gumgum/resonance` to a new version:

```bash
npm update @gumgum/resonance
npx @gumgum/resonance setup   # Re-run to pick up any new hooks or instruction changes
```

The skills update automatically (they live in `node_modules/`). Re-running setup ensures your CLAUDE.md section and hooks match the installed version.

---

## Pure HTML/CSS Usage (No React)

For projects that can't use React, the package includes a standalone CSS file and HTML documentation:

```bash
# CSS file with all component styles and tokens
node_modules/@gumgum/resonance/html/resonance.css

# HTML usage guide with copy-paste snippets
node_modules/@gumgum/resonance/html/docs.md
```

Link the CSS in your HTML:

```html
<link rel="stylesheet" href="path/to/resonance.css">

<button class="gg-button" data-variant="solid" data-size="md">
  Get Started
</button>
```

This covers ~30 components that work with CSS-only (typography, buttons, badges, cards, tables, form controls, layout utilities). Interactive components that require JavaScript (Dialog, Popover, Accordion, etc.) need the React package.

---

## What's in the package

| Directory | Contents |
|-----------|----------|
| `dist/` | Compiled ESM React components + TypeScript declarations |
| `html/` | `resonance.css` (standalone CSS) + `docs.md` (HTML usage guide) |
| `skills/` | 85+ design system skill files (component usage, theme rules, build methodology) |
| `brand/` | Brand tokens (colors, typography, motion, gradients) as JSON |
| `bin/` | `setup.js` CLI for Claude Code integration |
| `claude/` | Template CLAUDE.md snippet and hook scripts |

## Exports

```js
// React components (ESM)
import { Button, Card, Flex, ... } from '@gumgum/resonance';

// Component styles + token system
import '@gumgum/resonance/styles.css';

// Standalone CSS (no React required)
// <link rel="stylesheet" href="node_modules/@gumgum/resonance/html/resonance.css">
```

## Requirements

| Dependency | Version |
|------------|---------|
| `react` | ^19.0.0 |
| `react-dom` | ^19.0.0 |

Radix UI Primitives and Phosphor Icons are bundled as direct dependencies — no additional installs needed.

## Links

- **Showcase App** — Component documentation, interactive previews, motion demos
- **Brand Tokens** — `node_modules/@gumgum/resonance/brand/tokens/`
- **Component Skills** — `node_modules/@gumgum/resonance/skills/components/`