wss3-forge

Forge

AI-Ready React Component Library

A modern, production-ready React component library built for speed, developer experience, and AI integration.

Installation

npm install wss3-forge

yarn add wss3-forge

pnpm add wss3-forge

Quick Start

import { ForgeProvider, Button, Card, Text } from 'wss3-forge'
import 'wss3-forge/styles'

function App() {
  return (
    <ForgeProvider mode="dark">
      <Card padding="lg">
        <Text>Welcome to Forge</Text>
        <Button variant="primary">Get Started</Button>
      </Card>
    </ForgeProvider>
  )
}

Features

• 100+ Components - Production-ready UI components
• Dark & Light Themes - Built-in theme switching with CSS variables
• Global Shadows - Consistent elevation system with toggle support
• TypeScript - Full type safety and autocomplete
• Fluent UI 2 Icons - Seamless icon integration
• AI-Ready - Dedicated guide for AI assistants to generate correct code
• Accessible - WCAG compliant with ARIA attributes and keyboard navigation
• Zero Config - Works out of the box

Components

Layout & Structure

Card ImageCard StatCard Section PageHeader Grid VStack HStack Divider Spacer

Forms & Inputs

Input Select Checkbox Switch Radio Slider DatePicker ColorPicker SearchInput OTPInput

Navigation

Navbar AppSidebar Tabs Breadcrumbs Pagination Stepper CommandBar Affix

Feedback & Overlays

Toast Modal Drawer Sheet Popover Tooltip Banner Spinner Skeleton ProgressBar Tour

Data Display

Table Badge Avatar AvatarGroup Timeline Accordion List CodeBlock

Charts

BarChart LineChart AreaChart PieChart DonutChart ProgressRing

Utilities

Button IconButton Pill CopyButton Animate

Hooks

useToast useNotification useForge useDraggableScroll useStepper useResponsive

Constants

SHADOWS Z_INDEX COLORS AVATAR_COLORS STATUS_COLORS CHART_COLORS

Theming

ForgeProvider

Wrap your app with ForgeProvider to enable theming:

import { ForgeProvider } from 'wss3-forge'

function App() {
  return (
    <ForgeProvider
      mode="dark"
      shadows={true}
      theme={{
        brandPrimary: '#A35BFF',
        radiusLg: '12px'
      }}
    >
      {/* Your app */}
    </ForgeProvider>
  )
}

Shadows

Control shadows globally with the shadows prop:

// Enable shadows (default)
<ForgeProvider shadows={true}>

// Disable shadows for flat design
<ForgeProvider shadows={false}>

Custom Theme

Override CSS variables or use the theme prop:

<ForgeProvider
  theme={{
    light: {
      bgPrimary: '#ffffff',
      textPrimary: '#1a1625'
    },
    dark: {
      bgPrimary: '#0a0a0a',
      textPrimary: '#fafafa'
    }
  }}
>

Theme Creator

Use our visual Theme Creator to design your theme and export the configuration.

Constants

Import design tokens for consistent styling:

import { SHADOWS, Z_INDEX, COLORS } from 'wss3-forge'

// Shadows with elevation presets
SHADOWS.elevation.card    // Card shadow
SHADOWS.elevation.modal   // Modal shadow
SHADOWS.soft.sm           // Soft small shadow

// Z-index layering
Z_INDEX.modal             // 1000
Z_INDEX.tooltip           // 1100

// Semantic colors
COLORS.success            // Success green
COLORS.error              // Error red

AI Integration

Forge is designed for AI assistants. Include FORGE_AI_GUIDE.md in your project context to enable AI code generation with correct component usage.

# In your AI context/prompt:
Read FORGE_AI_GUIDE.md before writing any Forge code.

The guide includes:

• Complete component reference with all props
• Icon usage patterns (Fluent UI 2)
• Common patterns and best practices
• Component aliases (e.g., Alert → Banner, Snackbar → Toast)

Examples

Form with Validation

import { VStack, Input, Button, Text } from 'wss3-forge'

function LoginForm() {
  return (
    <VStack gap="md">
      <Input
        label="Email"
        type="email"
        placeholder="[e-mail]"
      />
      <Input
        label="Password"
        type="password"
      />
      <Button variant="primary" fullWidth>
        Sign In
      </Button>
    </VStack>
  )
}

Dashboard Card

import { StatCard } from 'wss3-forge'
import { ArrowUp16Regular } from '@fluentui/react-icons'

function RevenueCard() {
  return (
    <StatCard
      title="Revenue"
      value="$12,450"
      trend={{ value: 12, direction: 'up' }}
      icon={<ArrowUp16Regular />}
    />
  )
}

Toast Notifications

import { useToast, Button } from 'wss3-forge'

function SaveButton() {
  const { showToast } = useToast()

  return (
    <Button
      onClick={() => showToast({
        title: 'Saved',
        description: 'Your changes have been saved.',
        variant: 'success'
      })}
    >
      Save
    </Button>
  )
}

Documentation

Full documentation: forge.webba-creative.com

Community

Join our Discord for support and discussions.

License

MIT