forge: Instructions file for Codex

AGENTS.md

Hard rules for AI code generation with Forge. Read this before writing any code.

Rule 1: Forge first, always

Before writing UI, check if Forge already has the component. The full list is in skills/forge/components.md. If Forge has it, import it. Do not reimplement.

Do not build: modals, drawers, tooltips, popovers, dropdowns, date pickers, time pickers, toasts, notifications, tables, tabs, accordions, steppers, breadcrumbs, avatars, badges, banners, toolbars, sidebars, navbars, footers, skeletons, spinners, carousels, image galleries, video players, audio players, command palettes, color pickers, sliders, tag inputs, OTP inputs, phone inputs, password inputs, mention inputs, tree views, sortable lists, calendars, timelines, charts, or cookie banners. Forge provides all of these.

Rule 2: Single import source

Always import from 'wss3-forge'. No deep imports.

// Correct
import { Button, Card, useToast } from 'wss3-forge'

// Wrong
import { Button } from 'wss3-forge/components/Button'

Rule 3: ForgeProvider is required

The app must be wrapped in ForgeProvider at the root. Without it, CSS variables are missing and every component renders unstyled. Never nest multiple providers.

import { ForgeProvider } from 'wss3-forge'

<ForgeProvider mode="dark">
  <App />
</ForgeProvider>

Rule 4: Icons from Fluent UI 2 only

Icons come from @fluentui/react-icons. No react-icons, no lucide-react, no heroicons, no inline SVG when a Fluent equivalent exists.

Naming convention: {Name}{Size}{Style} where size is 12 | 16 | 20 | 24 | 28 | 32 | 48 and style is Regular | Filled.

import { ArrowRight20Regular, Heart24Filled } from '@fluentui/react-icons'

No text arrows (->, =>, →). Use ArrowRight{Size}Regular.

Rule 5: Colors via CSS variables

Use var(--...) for every color. Never hardcode hex values, RGB, HSL, or any color name.

// Correct
<div style={{ color: 'var(--text-primary)', background: 'var(--bg-secondary)' }} />

// Wrong
<div style={{ color: '#fff', background: '#181818' }} />