@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):

npm install @gumgum/resonance

From a tarball (direct distribution):

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):

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

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

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, 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:

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

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:

<!-- @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:

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:

# 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:

<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

// 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/