forge

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.

| If you're trying to | Read | Skip ahead | |---|---|---| | Build a login screen | patterns.md | [#auth](patterns.md#auth) | | Build signup or forgot-password | patterns.md | [#auth-forgot](patterns.md#auth-forgot) | | Show a toast on user action | components.md | [#feedback-toast](components.md#feedback-toast) | | Inline alert (success, error, info) | components.md | [#feedback-decision](components.md#feedback-decision) | | Errored input with screen-reader feedback | a11y.md | [#inputs](a11y.md#inputs) | | Icon-only button | a11y.md | [#buttons](a11y.md#buttons) | | Pricing strip with monthly/yearly toggle | patterns.md | [#pricing](patterns.md#pricing) | | Pick Modal vs Sheet vs Drawer vs Popover | components.md | [#overlay-decision](components.md#overlay-decision) | | Pick Card vs StatCard vs KpiCard | components.md | [#cards-decision](components.md#cards-decision) | | Pick VStack vs HStack vs Grid vs Box | components.md | [#layout-decision](components.md#layout-decision) | | Pick Input vs Select vs Combobox | components.md | [#forms-decision](components.md#forms-decision) | | Pick Checkbox vs Switch vs Radio vs Tabs | components.md | [#selection-decision](components.md#selection-decision) | | Animate items into view, one by one | motion.md | [#stagger](motion.md#stagger) | | Sticky scroll-jacked phase | motion.md | [#sticky-section](motion.md#sticky-section) | | Brand color customization | theming.md | [#brand-customization-in-30-seconds](theming.md#brand-customization-in-30-seconds) | | Theme color won't apply | faq.md | [faq.md](faq.md) | | Empty state | patterns.md | [#empty-state](patterns.md#empty-state) | | Loading or error or empty triad | patterns.md | [#triad](patterns.md#triad) | | Settings page (profile, billing, team) | patterns.md | [#settings](patterns.md#settings) | | Marketing page (hero, pricing, testimonials) | patterns.md | [#marketing](patterns.md#marketing) | | Data screen (table, master-detail, kanban) | patterns.md | [#data](patterns.md#data) | | Dashboard with sidebar | patterns.md | [#dashboard-sidebar--content](patterns.md#dashboard-sidebar--content) | | Build a docs site | patterns.md | [#docs](patterns.md#docs) | | Pick Navbar vs AppSidebar (horizontal vs vertical menu) | components.md | [#navigation](components.md#navigation) |

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](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](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](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](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](design.md). For concrete wrong/right pairs, see [anti-patterns.md](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](getting-started.md) five-minute install and first screen. Read this first if Forge is not already wired up.
• [components.md](components.md) every export grouped by category, with props table. Read this when picking a component or looking up props.
• [tokens.md](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](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](motion.md) the Motion library (Motion, AnimatePresence, Stagger, gesture, scroll, text/visual effects, canvas backgrounds, motion hooks). Read this when adding animations.
• [patterns.md](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](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](anti-patterns.md) wrong/right pairs for the most common mistakes. Skim this when you are about to write a s