Forge Design System

Forge is a React component library that ships as wss3-forge. Every UI concern (layout, forms, overlays, data display, charts, motion) is covered by a component. All colors, spacing, radius, shadows, and motion live in CSS variables injected by ForgeProvider.

Decision rule: if the task changes what the user sees, touches, or waits for, load this skill.

Find by task

Lookup table for the most common requests. Jump straight to the relevant anchor.

Review priority (check in this order)

1. Accessibility. Focus visible, correct roles, aria-label on icon-only buttons, aria-invalid/aria-describedby on errored inputs, keyboard navigation works, reduced motion respected. See a11y.md.
2. Semantics. Using the right Forge primitive: Heading not styled <h1>, Button not styled <button>, VStack/HStack not flex <div>, Card not styled container. See anti-patterns.md.
3. Motion. Durations 150 to 300ms for interactions, reduced-motion respected by ForgeProvider, no animations over 500ms for UI feedback. See motion.md.
4. Theme parity. Code works in both darkTheme and lightTheme. No hardcoded rgba(255, 255, 255, ...) or #xxx. Use CSS vars or color-mix(in srgb, currentColor N%, transparent).
5. Performance. VirtualList when rendering more than 100 rows, lazy routes, <Motion whileInView> over animate for offscreen content.

Hard rules

1. Import only from 'wss3-forge'. No deep imports.
2. Wrap the app in <ForgeProvider>. Without it every component renders unstyled.
3. Icons only from @fluentui/react-icons. Convention: {Name}{Size}{Style} (e.g. ArrowRight20Regular).
4. Colors via var(--...). No hardcoded hex, RGB, or color names.
5. Spacing via gap/padding props on Forge primitives. No raw px/rem when a semantic key exists.
6. Layout via VStack, HStack, Stack, Grid, Flex, Box, Center, Spacer, AspectRatio. No flex divs.
7. Responsive via useIsMobile, useBreakpoint, or responsive object props. No @media queries in app code.
8. Typography via Heading, Text, Label. Never style <h1>, <span>, or <p> manually.
9. No em-dashes anywhere. Period, comma, colon, or line break.
10. No emojis in UI. Use Fluent icons.
11. No decorative colored backgrounds behind icons. Color the glyph itself via style={{ color: '...' }}. Only StatusBadge, Avatar status, and colored Badge variants keep a tinted surface.
12. No custom components when Forge provides one. Check components.md first.
13. No custom CSS classes for design-system concerns (spacing, color, radius, shadow, typography). Use props or CSS vars.

For the reasoning behind each rule, see design.md. For concrete wrong/right pairs, see anti-patterns.md.

What Forge is NOT

Forge is a restrained design system. These are baseline anti-aesthetics:

• No aurora-gradient backgrounds. The page reads as flat surfaces with brand-tinted accents, not as a colored sky.
• No glass-on-everything. Backdrop-filter is a tool for the navbar and the modal scrim, not for every card.
• No icon glow / icon-tint backgrounds. Color the glyph itself; let surfaces stay calm.
• No cyan-magenta-violet gradients. They read as AI-template defaults; we build for Linear / Stripe / Vercel restraint.
• No streaming-text fakery, no ASCII art in production UI, no AI-marketing clichés.

When in doubt, restrain. Forge ships polished defaults; consumers reach for them, not around them.

Pre-delivery checklist

Before claiming done, verify:

• [ ] tsc --noEmit clean.
• [ ] Works in both dark and light mode (no hardcoded dark-only colors).
• [ ] Focus ring visible on every interactive element.
• [ ] Icon-only buttons have aria-label or tooltip.
• [ ] Touch targets at least size="sm" (32px) on mobile flows.
• [ ] Motion durations within 150 to 300ms for interactions, reduced-motion respected.
• [ ] No em-dash, no emoji in UI strings.
• [ ] No hardcoded hex/rgba in styles. All colors via CSS var.
• [ ] No fallback or try/catch for scenarios that cannot happen.
• [ ] No trivial comments that restate the code.

Files in this skill

Load the file that matches your task. Do not load them all at once.

• getting-started.md five-minute install and first screen. Read this first if Forge is not already wired up.
• components.md every export grouped by category, with props table. Read this when picking a component or looking up props.
• tokens.md CSS variables, spacing scale, radius, shadows, z-index, motion tokens, breakpoints, color constants. Read this when styling edges Forge does not cover with a prop.
• theming.md ForgeProvider props, ForgeTheme fields, default darkTheme and lightTheme, createTheme, useForge. Read this when configuring the provider or building a custom theme.
• motion.md the Motion library (Motion, AnimatePresence, Stagger, gesture, scroll, text/visual effects, canvas backgrounds, motion hooks). Read this when adding animations.
• patterns.md full compositions for dashboards, forms, responsive sidebars, list-with-actions, plus quality gates per pattern and block creation rules. Read this when building a page, not a single component.
• a11y.md accessibility playbook: what Forge adds automatically per component and what the dev must still add. Read this when working on any interactive surface.
• anti-patterns.md wrong/right pairs for the most common mistakes. Skim this when you are about to write a styled native element, a flex div, a @media query, or a hardcoded color.
• design.md design rules and the reasoning behind them. Read this when choosing between multiple valid approaches or when the user asks "why".
• migration.md upgrade notes from previous versions. Read this when bumping wss3-forge.
• faq.md common gotchas and their fixes (unstyled components, 404s, wrong sizes). Read this when something does not behave as expected.

Typical flow

1. Read the user's request.
2. Open components.md and find the primitive that matches. If the request is a composition, open patterns.md first.
3. If the primitive needs a color, radius, or spacing you cannot express with a prop, open tokens.md.
4. If the request involves animation, open motion.md.
5. If the request touches theming or provider configuration, open theming.md.
6. If the request is interactive (form, menu, dialog, table), skim a11y.md.
7. Write the code. Run through the Review priority and Pre-delivery checklist. Run tsc --noEmit before claiming done.

Blocks

Block templates live under src/pages/blocks/blocks/{category}/{slug}/. Categories: marketing | dashboard | auth | commerce | settings | content | utility. Block creation rules are documented in patterns.md.