AI Integration

For AI Assistants

Guide for using Forge with AI assistants like Claude, GPT, and others. This page explains best practices for generating Forge code with AI.

Overview

Forge is designed to be AI-friendly. The design system provides a comprehensive guide document that AI assistants should read before generating code. This ensures consistent, correct, and maintainable output.

AI Integration Guide

Complete markdown documentation (2500+ lines) with all components, examples, and rules.

Quick Setup

The basic structure every Forge app needs:

tsx

1import { ForgeProvider, ToastProvider, NotificationProvider } from 'wss3-forge'
2 
3function App() {
4  return (
5    <ForgeProvider mode="dark">
6      <ToastProvider position="bottom-right">
7        <NotificationProvider>
8          <YourApp />
9        </NotificationProvider>
10      </ToastProvider>
11    </ForgeProvider>
12  )
13}

Rules for AI

Always use Fluent UI 2 icons (@fluentui/react-icons)

Use CSS variables for all colors (var(--text-primary), etc.)

Import all components from a single source

Wrap your app with ForgeProvider

Use ToastProvider and NotificationProvider for feedback

Follow the component API exactly as documented

Use responsive hooks (useIsMobile, useBreakpoint)

Test in both light and dark modes

DON'T

Never use other icon libraries (Lucide, react-icons, etc.)

Never hardcode colors (#ffffff, rgb(), etc.)

Never deep import from component paths

Never mix Forge with other UI libraries

Never create custom components when Forge has one

Never skip the ForgeProvider wrapper

Never use inline colors for theming

Never ignore TypeScript errors on props

Icons

Critical

Only use Fluent UI 2 icons. Other icon libraries will break visual consistency.

tsx

1// Correct - Fluent UI 2 icons
2import {
3  Add20Regular,      // Outline style
4  Add20Filled,       // Solid style
5  Settings24Regular, // Different size
6  Home16Regular      // Small size
7} from '@fluentui/react-icons'
8 
9// Icon naming: {Name}{Size}{Style}
10// Sizes: 12, 16, 20, 24, 28, 32, 48
11// Styles: Regular (outline), Filled (solid)
12 
13<Button icon={<Add20Regular />}>Add Item</Button>
14<IconButton icon={<Settings24Regular />} />

Colors

Always use CSS variables for colors. This ensures themes work correctly.

tsx

1// Correct - CSS Variables
2<div style={{
3  backgroundColor: 'var(--bg-secondary)',
4  color: 'var(--text-primary)',
5  borderColor: 'var(--border-color)'
6}}>
7 
8// Available color variables:
9// --bg-primary, --bg-secondary, --bg-tertiary, --bg-active
10// --text-primary, --text-secondary, --text-muted
11// --brand-primary, --brand-secondary
12// --border-color, --border-subtle
13// --success, --warning, --error, --info

Using Components

Import all components from a single source. Check the documentation for correct props.

tsx

1import {
2  Button, Card, Input, Modal,
3  VStack, HStack, Grid,
4  Text, Heading, Badge,
5  useToast, useNotification
6} from 'wss3-forge'
7 
8function MyComponent() {
9  const { toast } = useToast()
10 
11  return (
12    <Card padding="lg">
13      <VStack gap="md">
14        <Heading level={3}>Form Title</Heading>
15        <Input
16          label="Email"
17          placeholder="Enter email"
18          type="email"
19        />
20        <Button
21          variant="primary"
22          onClick={() => toast.success('Saved!')}
23        >
24          Submit
25        </Button>
26      </VStack>
27    </Card>
28  )
29}

Prompt Template

Add this to your AI instructions or system prompt when working with Forge:

text

1When using Forge design system:
2 
31. Read the AI guide first: packages/wss3-forge/FORGE_AI_GUIDE.md
42. Only use Fluent UI 2 icons from @fluentui/react-icons
53. Use CSS variables for colors, never hardcode
64. Import components from 'wss3-forge' (single source)
75. Always wrap with ForgeProvider
86. Check component props in documentation before using

Best Practices

Read the Guide First

Before generating any code, AI should read FORGE_AI_GUIDE.md for the complete component reference. This prevents errors and ensures correct API usage.

Check Props Before Using

Each component has specific props. Don't assume - check the documentation. For example, Button has variant, size, icon props but not color or type.

Use Theme Creator for Custom Themes

Need custom colors? Use the Theme Creator to generate ForgeProvider configuration instead of manually defining CSS variables.

Leverage Existing Components

Forge has 100+ components. Before creating custom UI, check if a component already exists. StatCard, ImageCard, Timeline, etc. cover many use cases.

Explore Components

See all available components in the documentation.

Watermark

Changelog

Last updated: December 2025