Forge

A React component library with built-in motion, themeable tokens, and AI skill packs for Claude Code and Cursor.

Documentation · Components · Templates · Motion · Discord

Install

npm install wss3-forge
npx wss3-forge init

@fluentui/react-icons is a runtime dependency and installs automatically. The init command copies the Forge skill into .claude/skills/forge/ so Claude Code can invoke it via /forge. Safe on existing projects, it asks before overwriting.

Quick start

import { ForgeProvider, Card, Heading, Text, Button, VStack } from 'wss3-forge'
import 'wss3-forge/styles/animations.css'
import 'wss3-forge/styles/motion.css'

export default function App() {
  return (
    <ForgeProvider mode="dark">
      <Card padding="lg">
        <VStack gap="md">
          <Heading level={2}>Welcome</Heading>
          <Text color="secondary">
            Forge ships components, motion, and a token system out of the box.
          </Text>
          <Button variant="primary">Get started</Button>
        </VStack>
      </Card>
    </ForgeProvider>
  )
}

ForgeProvider is required. Without it, CSS variables are missing and components render unstyled.

Works with Vite, Next.js (app or pages router), Remix, and any React 18+ setup.

Features

• 100+ components across layout, forms, navigation, data display, feedback, overlays, charts, media, and utilities. One import path: 'wss3-forge'.
• First-class motion. Motion, AnimatePresence, Stagger, Marquee, RevealOnScroll, Parallax, Magnetic, Tilt, Starfield, plus 17 hooks (useMotionValue, useScrollMotion, useReducedMotion, and more). Respects prefers-reduced-motion everywhere.
• Token-based theming. Every color, radius, spacing, shadow, duration, and easing is a CSS variable. Override the whole theme by passing flat tokens to ForgeProvider. Built-in dark and light modes.
• TypeScript-first. 134 exports with full type definitions. Generic props, narrow unions, no any.
• Accessibility. ARIA roles, keyboard handlers, focus traps, and aria-* plumbing on Modal, Tabs, Tooltip, Popover, Combobox, Slider, NumberInput, Sheet, Avatar, ProgressBar.
• Forge-only icons. Fluent UI 2 ({Name}{Size}{Style}). One icon library, one stroke weight, one convention.
• AI skill packs. The /forge skill teaches Claude Code and Cursor the full component API, design rules, and layout patterns. See skills/forge.
• Built for production. Zero runtime dependencies beyond peer (react, react-dom) and @fluentui/react-icons. ESM and CJS bundles.

What is inside

The full reference lives in skills/forge/components.md.

Theming

Forge exposes its design as CSS variables, all overridable through ForgeProvider.

<ForgeProvider
  mode="light"
  theme={{
    brandPrimary: '#0066FF',
    radiusMd: 12,
    fontFamily: 'Inter, system-ui, sans-serif'
  }}
>
  <App />
</ForgeProvider>

Tokens you can override:

• Colors brandPrimary, brandSecondary, bgPrimary, bgSecondary, bgTertiary, bgElevated, bgHover, bgActive, textPrimary, textSecondary, textMuted, borderColor, borderSubtle, success, warning, error, info
• Radius radiusXs, radiusSm, radiusMd, radiusLg, radiusXl, radius2xl, radiusFull
• Spacing spacingNone, spacingXs, spacingSm, spacingMd, spacingLg, spacingXl, spacing2xl, spacing3xl, spacing4xl
• Shadows shadowSm, shadowMd, shadowLg, shadowXl
• Motion durationFast, durationBase, durationSlow, easingGentle, easingDecelerate, easingAccelerate

Full token list: skills/forge/tokens.md.

Motion

Forge ships a complete motion system as primitives, hooks, and tokens. Every motion component reads prefers-reduced-motion and collapses to instant transitions when the user requests it.

import { Motion, RevealOnScroll, Stagger } from 'wss3-forge'

<RevealOnScroll>
  <Motion
    initial={{ opacity: 0, y: 24 }}
    animate={{ opacity: 1, y: 0 }}
    transition={{ duration: 'slow', easing: 'gentle' }}
  >
    <Heading>Hello</Heading>
  </Motion>
</RevealOnScroll>

<Stagger delay={80}>
  {items.map(item => <Card key={item.id}>{item.title}</Card>)}
</Stagger>

Motion guides and live demos: forge.webba-creative.com/motion.

AI skills

Forge ships skill packs that teach Claude Code and Cursor how to use the library correctly. After running npx wss3-forge init, the /forge skill loads automatically when AI edits a .tsx file.

The skill includes:

• SKILL.md rules, anti-patterns, mobile gotchas, component quick reference
• components.md every component, every prop, every default
• tokens.md the full token list with values
• theming.md ForgeProvider, dark and light modes, custom themes
• motion.md primitives, hooks, tokens, common compositions
• patterns.md ready-to-use layouts (dashboard, form, auth, modal, settings)
• a11y.md accessibility checklist per component
• anti-patterns.md what not to do, with the correct alternative

For project-level rules, the package also ships AGENTS.md (18 rules) and DESIGN.md (the reasoning behind the rules).

CLI

npx wss3-forge init       # install the /forge skill into .claude/skills/forge/
npx wss3-forge upgrade    # re-sync the skill after upgrading wss3-forge
npx wss3-forge doctor     # validate Forge setup in the current project

Browser support

Last two versions of Chrome, Firefox, Safari, and Edge. Forge uses color-mix, CSS variables, aspect-ratio, @container, and backdrop-filter. No IE11.

Documentation

• Live site: forge.webba-creative.com
• Component reference: forge.webba-creative.com/docs/components
• Templates: forge.webba-creative.com/templates
• Motion: forge.webba-creative.com/motion
• Theming: forge.webba-creative.com/docs/theming
• AI Integration: forge.webba-creative.com/docs/ai-integration
• Changelog: CHANGELOG.md

Community

• Discord: discord.gg/DwzReVGzdp
• Reddit: r/webbaforge
• GitHub: github.com/Webba-Creative-Technologies/forge

License

MIT (c) Webba Creative