...
+...
+```
+
+Names must be unique — defining the same name twice throws an error.
+
+### Anonymous components
+
+Omit the name and Forge generates one from the base tag: `Div`, `Button2`, `Anchor3`, etc.
+
+```tsx
+const Box = define({ display: 'flex', gap: 16 })
+// class="Div"
+
+const Link = define({ base: 'a', color: 'blue' })
+// class="Anchor"
+```
+
+---
+
+## HTML Tags
+
+By default, components render as ``. Use `base` to change the tag:
+
+```tsx
+const Button = define('Button', {
+ base: 'button',
+ padding: 20,
+ cursor: 'pointer',
+})
+//
...
+
+const Heading = define('Heading', {
+ base: 'h1',
+ fontSize: 28,
+})
+//
...
+```
+
+### Attribute shorthand
+
+Set default attributes right in the base string:
+
+```tsx
+const Radio = define('Radio', {
+ base: 'input[type=radio]',
+})
+//
+
+const Checkbox = define('Checkbox', {
+ base: 'input[type=checkbox]',
+})
+//
+```
+
+Props passed at usage time override base attributes.
+
+---
+
+## CSS Properties
+
+Write CSS properties in camelCase. They compile to real CSS at definition time.
+
+```tsx
+const Card = define('Card', {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 16,
+ padding: 20,
+ backgroundColor: '#111',
+ borderRadius: 8,
+ boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
+})
+```
+
+Generated CSS:
+
+```css
+.Card {
+ background-color: #111;
+ border-radius: 8px;
+ box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+ display: flex;
+ flex-direction: column;
+ gap: 16px;
+ padding: 20px;
+}
+```
+
+### Numeric values
+
+Numbers are auto-converted to `px`:
+
+```tsx
+{ padding: 20 } // padding: 20px
+{ margin: 0 } // margin: 0px
+{ fontSize: 14 } // font-size: 14px
+{ borderRadius: 8 } // border-radius: 8px
+```
+
+Except for unitless properties, which stay as plain numbers:
+
+```tsx
+{ opacity: 0.5 } // opacity: 0.5
+{ zIndex: 10 } // z-index: 10
+{ flex: 1 } // flex: 1
+{ flexGrow: 2 } // flex-grow: 2
+{ flexShrink: 0 } // flex-shrink: 0
+{ fontWeight: 400 } // font-weight: 400
+{ lineHeight: 1.6 } // line-height: 1.6
+{ order: 3 } // order: 3
+```
+
+Strings are passed through as-is:
+
+```tsx
+{ padding: '12px 24px' } // padding: 12px 24px
+{ border: '1px solid #222' } // border: 1px solid #222
+{ margin: '0 auto' } // margin: 0 auto
+```
+
+### All supported properties
+
+Every standard CSS property is supported in camelCase form: layout (`display`, `position`, `flexDirection`, `gridTemplateColumns`, etc.), box model (`margin`, `padding`, `width`, `height`, etc.), typography (`fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, etc.), visual (`background`, `border`, `boxShadow`, `opacity`, etc.), animation (`transition`, `animation`, `transform`, etc.), and SVG (`fill`, `stroke`, `strokeWidth`, etc.).
+
+---
+
+## States
+
+Pseudo-selectors like `:hover`, `:focus`, `:active`, and `:disabled`.
+
+```tsx
+const Button = define('Button', {
+ base: 'button',
+ padding: 20,
+ background: 'blue',
+ cursor: 'pointer',
+
+ states: {
+ ':hover': { background: 'darkblue' },
+ ':active': { transform: 'translateY(1px)' },
+ ':focus': { outline: '2px solid white' },
+ ':disabled': { opacity: 0.3, cursor: 'not-allowed' },
+ },
+})
+```
+
+The colon is optional — `hover` and `:hover` are equivalent:
+
+```tsx
+states: {
+ hover: { background: 'darkblue' }, // same as ':hover'
+}
+```
+
+### Complex pseudo-selectors
+
+Use the full string for compound selectors:
+
+```tsx
+states: {
+ ':not(:disabled):hover': { background: 'darkblue' },
+ ':not(:disabled):active': { transform: 'translateY(1px)' },
+}
+```
+
+Generated CSS:
+
+```css
+.Button:not(:disabled):hover { background: darkblue; }
+.Button:not(:disabled):active { transform: translateY(1px); }
+```
+
+---
+
+## Variants
+
+Variants are typed props that apply conditional CSS classes. They replace inline styles with a clean, declarative API.
+
+### Boolean variants
+
+A variant whose value is a style object. Activated by passing `true`.
+
+```tsx
+const Button = define('Button', {
+ base: 'button',
+ padding: 20,
+ background: 'blue',
+
+ variants: {
+ disabled: {
+ opacity: 0.3,
+ cursor: 'not-allowed',
+ },
+ rounded: {
+ borderRadius: 999,
+ },
+ },
+})
+```
+
+```tsx
+
Normal
+
Disabled
+
Pill
+
Both
+```
+
+Generated CSS:
+
+```css
+.Button { padding: 20px; background: blue; }
+.Button.disabled { cursor: not-allowed; opacity: 0.3; }
+.Button.rounded { border-radius: 999px; }
+```
+
+HTML output for `
`:
+
+```html
+Both
+```
+
+Variant props are consumed by Forge and **not** passed to the HTML element.
+
+### Keyed variants
+
+A variant whose value is an object of named options. Activated by passing a string.
+
+```tsx
+const Button = define('Button', {
+ base: 'button',
+ padding: 16,
+
+ variants: {
+ intent: {
+ primary: { background: 'blue', color: 'white' },
+ secondary: { background: '#333', color: '#ccc' },
+ danger: { background: 'red', color: 'white' },
+ ghost: { background: 'transparent', color: 'gray' },
+ },
+ size: {
+ small: { padding: '8px 16px', fontSize: 12 },
+ large: { padding: '16px 32px', fontSize: 16 },
+ },
+ },
+})
+```
+
+```tsx
+Save
+Delete Account
+Cancel
+```
+
+Generated CSS:
+
+```css
+.Button.intent-primary { background: blue; color: white; }
+.Button.intent-danger { background: red; color: white; }
+.Button.size-small { font-size: 12px; padding: 8px 16px; }
+.Button.size-large { font-size: 16px; padding: 16px 32px; }
+```
+
+### Variants with states
+
+Variants can include their own pseudo-selectors:
+
+```tsx
+variants: {
+ intent: {
+ danger: {
+ background: 'red',
+ states: {
+ ':not(:disabled):hover': { background: '#cc0000' },
+ },
+ },
+ secondary: {
+ background: '#333',
+ states: {
+ ':not(:disabled):hover': { borderColor: 'green' },
+ },
+ },
+ },
+}
+```
+
+### Combining multiple variants
+
+Multiple keyed and boolean variants can be used together freely:
+
+```tsx
+Small Primary
+Large Danger Disabled
+```
+
+---
+
+## Parts
+
+Parts are named sub-components within a component. They get their own CSS classes and can have their own base tags, states, and selectors.
+
+```tsx
+const Card = define('Card', {
+ padding: 20,
+ background: '#111',
+
+ parts: {
+ Header: {
+ base: 'h2',
+ fontSize: 24,
+ marginBottom: 12,
+ },
+ Body: {
+ fontSize: 14,
+ lineHeight: 1.6,
+ color: '#888',
+ },
+ Footer: {
+ base: 'footer',
+ marginTop: 16,
+ paddingTop: 12,
+ borderTop: '1px solid #333',
+ fontSize: 12,
+ },
+ },
+
+ render({ props, parts: { Root, Header, Body, Footer } }) {
+ return (
+
+
+ {props.children}
+
+
+ )
+ },
+})
+```
+
+```tsx
+
+ This is the card body content.
+
+```
+
+Generated CSS classes:
+
+```css
+.Card { padding: 20px; background: #111; }
+.Card_Header { font-size: 24px; margin-bottom: 12px; }
+.Card_Body { color: #888; font-size: 14px; line-height: 1.6; }
+.Card_Footer { border-top: 1px solid #333; font-size: 12px; margin-top: 16px; padding-top: 12px; }
+```
+
+### Parts with states
+
+Parts can have their own pseudo-selectors:
+
+```tsx
+parts: {
+ Tab: {
+ base: 'button',
+ color: '#888',
+ borderBottom: '1px solid transparent',
+
+ states: {
+ ':hover': { color: '#fff' },
+ },
+ },
+}
+```
+
+### Variants that affect parts
+
+Variants can override styles on specific parts:
+
+```tsx
+const UserProfile = define('UserProfile', {
+ padding: 24,
+
+ parts: {
+ Avatar: { base: 'img', width: 64, height: 64, borderRadius: '50%' },
+ Name: { fontSize: 18 },
+ Bio: { fontSize: 14, color: '#888' },
+ },
+
+ variants: {
+ size: {
+ compact: {
+ padding: 16, // override root
+ parts: {
+ Avatar: { width: 48, height: 48 }, // override part
+ Name: { fontSize: 16 },
+ },
+ },
+ large: {
+ padding: 32,
+ parts: {
+ Avatar: { width: 96, height: 96 },
+ Name: { fontSize: 24 },
+ },
+ },
+ },
+ verified: {
+ parts: {
+ Avatar: { border: '2px solid gold' },
+ },
+ },
+ },
+
+ render({ props, parts: { Root, Avatar, Name, Bio } }) {
+ return (
+
+ {props.name}{props.verified && ' ✓'}
+ {props.bio}
+
+ )
+ },
+})
+```
+
+```tsx
+
+ {props.items?.map((item: any) => (
+ {item.label}
+ ))}
+
+ )
+ },
+})
+```
+
+The `active` prop on `` adds the variant class to that specific tab instance. It is not passed through to the HTML.
+
+---
+
+## Custom Render
+
+Override the default rendering with a `render` function. It receives `props` (everything passed to the component) and `parts` (component functions for Root and all named parts).
+
+```tsx
+const FormGroup = define('FormGroup', {
+ marginBottom: 24,
+
+ parts: {
+ Label: { base: 'label', display: 'block', fontSize: 14, marginBottom: 8 },
+ Helper: { fontSize: 12, color: '#888', marginTop: 6 },
+ Error: { fontSize: 12, color: 'red', marginTop: 6 },
+ },
+
+ render({ props, parts: { Root, Label, Helper, Error } }) {
+ return (
+
+ {props.label && {props.label} }
+ {props.children}
+ {props.helper && {props.helper} }
+ {props.error && {props.error} }
+
+ )
+ },
+})
+```
+
+```tsx
+
+
+
+
+
+```
+
+### Destructuring props
+
+Destructure to separate custom props from HTML passthrough props:
+
+```tsx
+render({ props: { title, subtitle, ...rest }, parts: { Root, H2, P } }) {
+ return (
+
+ {title}
+ {subtitle}
+
+ )
+}
+```
+
+### Without render
+
+If no `render` is provided, the component renders its children into the root tag:
+
+```tsx
+const Box = define('Box', { padding: 20 })
+
+// Equivalent to:
+// render({ props, parts: { Root } }) {
+// return {props.children}
+// }
+```
+
+---
+
+## Selectors
+
+The `selectors` key lets you write custom CSS selectors. Use `&` for the current element and `@PartName` to reference other parts.
+
+### Basic selectors
+
+```tsx
+const NavLink = define('NavLink', {
+ base: 'a',
+ color: '#888',
+ textDecoration: 'none',
+
+ selectors: {
+ '&:hover': { color: '#fff' },
+ '&[aria-current]': { color: '#fff', textDecoration: 'underline' },
+ },
+})
+```
+
+```tsx
+Home
+About
+```
+
+### Cross-part selectors
+
+Reference other parts with `@PartName`. This is the mechanism that enables CSS-only interactive components.
+
+```tsx
+const Checkbox = define('Checkbox', {
+ parts: {
+ Input: {
+ base: 'input[type=checkbox]',
+ display: 'none',
+ },
+ Label: {
+ base: 'label',
+ padding: 10,
+ cursor: 'pointer',
+ color: 'gray',
+
+ selectors: {
+ // When the Input is checked, style this Label
+ '@Input:checked + &': {
+ color: 'green',
+ fontWeight: 'bold',
+ },
+ // When the Input is disabled, style this Label
+ '@Input:disabled + &': {
+ opacity: 0.5,
+ cursor: 'not-allowed',
+ },
+ },
+ },
+ },
+
+ render({ props, parts: { Root, Input, Label } }) {
+ return (
+
+ {props.label}
+
+ )
+ },
+})
+```
+
+The `@Input` in `@Input:checked + &` is replaced with `.Checkbox_Input`, and `&` is replaced with `.Checkbox_Label`, producing:
+
+```css
+.Checkbox_Input:checked + .Checkbox_Label {
+ color: green;
+ font-weight: bold;
+}
+```
+
+### CSS-only tab switcher
+
+Hidden radio inputs + sibling selectors = tabs without JavaScript:
+
+```tsx
+const TabSwitcher = define('TabSwitcher', {
+ parts: {
+ Input: {
+ base: 'input[type=radio]',
+ display: 'none',
+ },
+ TabBar: {
+ display: 'flex',
+ borderBottom: '1px solid #333',
+ },
+ TabLabel: {
+ base: 'label',
+ padding: '12px 24px',
+ color: '#888',
+ cursor: 'pointer',
+
+ states: {
+ ':hover': { color: '#fff' },
+ },
+
+ selectors: {
+ '@Input:checked + &': {
+ color: 'green',
+ borderBottom: '1px solid green',
+ },
+ },
+ },
+ Content: {
+ display: 'none',
+ padding: 24,
+
+ selectors: {
+ // General sibling combinator: when a radio is checked,
+ // show the corresponding content panel
+ '@Input:checked ~ &': { display: 'block' },
+ },
+ },
+ },
+
+ render({ props, parts: { Root, Input, TabBar, TabLabel, Content } }) {
+ return (
+
+
+ {props.tabs?.map((tab: any, i: number) => (
+ <>
+ {tab.label}
+
+ ))}
+
+ {props.tabs?.map((tab: any) => (
+ {tab.content}
+ ))}
+
+ )
+ },
+})
+```
+
+```tsx
+First panel },
+ { id: 'two', label: 'Tab 2', content: Second panel
},
+ { id: 'three', label: 'Tab 3', content: Third panel
},
+ ]}
+/>
+```
+
+### Selector reference
+
+| Selector | Meaning |
+|---|---|
+| `&:hover` | This element on hover |
+| `&[aria-current]` | This element when attribute is present |
+| `@Input:checked + &` | This element when adjacent Input is checked |
+| `@Input:checked ~ &` | This element when any preceding Input sibling is checked |
+| `@Input:disabled + &` | This element when adjacent Input is disabled |
+| `@Input:checked + &:hover` | This element on hover, but only when Input is checked |
+
+---
+
+## Scopes
+
+When building a family of related components, `createScope` prefixes all names automatically:
+
+```tsx
+import { createScope } from 'forge'
+
+const { define } = createScope('Button')
+
+const Button = define('Root', { // CSS class: "Button" (Root is special)
+ base: 'button',
+ padding: 20,
+})
+
+const ButtonRow = define('Row', { // CSS class: "ButtonRow"
+ display: 'flex',
+ gap: 16,
+})
+
+const ButtonIcon = define('Icon', { // CSS class: "ButtonIcon"
+ width: 20,
+ height: 20,
+})
+```
+
+`Root` is the special case — `define('Root', ...)` with scope `'Button'` produces class `Button`, not `ButtonRoot`.
+
+---
+
+## Themes
+
+Built-in CSS custom properties with type safety.
+
+### Define themes
+
+Create a theme file with your tokens:
+
+```tsx
+// darkTheme.tsx
+export default {
+ 'colors-bg': '#0a0a0a',
+ 'colors-bgElevated': '#111',
+ 'colors-fg': '#00ff00',
+ 'colors-fgMuted': '#888',
+ 'colors-border': '#222',
+ 'colors-accent': '#00ff00',
+ 'colors-accentDim': '#008800',
+
+ 'fonts-mono': "'Monaco', 'Menlo', monospace",
+
+ 'spacing-sm': '12px',
+ 'spacing-md': '16px',
+ 'spacing-lg': '24px',
+ 'spacing-xl': '32px',
+
+ 'radius-sm': '4px',
+ 'radius-md': '8px',
+} as const
+```
+
+```tsx
+// lightTheme.tsx
+export default {
+ 'colors-bg': '#f5f5f0',
+ 'colors-bgElevated': '#fff',
+ 'colors-fg': '#0a0a0a',
+ 'colors-fgMuted': '#666',
+ 'colors-border': '#ddd',
+ 'colors-accent': '#0066cc',
+ 'colors-accentDim': '#004499',
+
+ 'fonts-mono': "'Monaco', 'Menlo', monospace",
+
+ 'spacing-sm': '12px',
+ 'spacing-md': '16px',
+ 'spacing-lg': '24px',
+ 'spacing-xl': '32px',
+
+ 'radius-sm': '4px',
+ 'radius-md': '8px',
+} as const
+```
+
+### Register themes
+
+```tsx
+// themes.tsx
+import { createThemes } from 'forge'
+import darkTheme from './darkTheme'
+import lightTheme from './lightTheme'
+
+export const theme = createThemes({
+ dark: darkTheme,
+ light: lightTheme,
+})
+```
+
+`createThemes` returns a typed function. It only accepts keys that exist in your theme objects.
+
+### Use theme values
+
+`theme('key')` returns `var(--theme-key)`:
+
+```tsx
+import { theme } from './themes'
+
+const Card = define('Card', {
+ padding: theme('spacing-lg'), // var(--theme-spacing-lg)
+ background: theme('colors-bgElevated'), // var(--theme-colors-bgElevated)
+ color: theme('colors-fg'), // var(--theme-colors-fg)
+ border: `1px solid ${theme('colors-border')}`,
+ borderRadius: theme('radius-md'),
+})
+```
+
+### Switch themes
+
+Themes are controlled by the `data-theme` attribute:
+
+```tsx
+// Set initial theme
+
+
+// Switch at runtime
+document.body.setAttribute('data-theme', 'light')
+```
+
+Generated CSS:
+
+```css
+[data-theme="dark"] {
+ --theme-colors-bg: #0a0a0a;
+ --theme-colors-fg: #00ff00;
+ /* ... */
+}
+[data-theme="light"] {
+ --theme-colors-bg: #f5f5f0;
+ --theme-colors-fg: #0a0a0a;
+ /* ... */
+}
+```
+
+### Other theme APIs
+
+```tsx
+// Register a single theme
+import { createTheme } from 'forge'
+createTheme('dark', { bgColor: '#000', fgColor: '#fff' })
+
+// Extend existing themes with new tokens
+import { extendThemes } from 'forge'
+extendThemes({ dark: { 'colors-success': '#0f0' } })
+
+// Untyped fallback for dynamic theme keys
+import { themeVar } from 'forge'
+themeVar('colors-bg') // 'var(--theme-colors-bg)'
+```
+
+---
+
+## SSR and SPA
+
+### Server-side rendering
+
+Include `