From f88eb4dc832641d9e86f6811aaa66bc415aa52eb Mon Sep 17 00:00:00 2001 From: Chris Wanstrath Date: Fri, 26 Dec 2025 22:22:08 -0800 Subject: [PATCH] claude --- CLAUDE.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..645017e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,105 @@ +# Forge - Structured CSS Authoring + +A typed, local, variant-driven way to author CSS. Compiles to real CSS but removes the chaos: no global conflicts, no selector gymnastics, no inline styles. Built for Hono JSX with SSR support. + +## The Problem + +CSS is hostile to humans at scale: global namespace, no markup-to-definition link, requires inline styles for per-instance variance, silent conflicts, selector complexity. + +## The Solution + +- **Local styles** - Attached via generated class names, not strings +- **Parts** - Named sub-components replace selectors (no `.Button > .Icon` nonsense) +- **Variants** - Typed parameters replace inline styles (no `style={{ color: x }}`) +- **Deterministic** - Known merge order, dev warnings for conflicts +- **Compiles to CSS** - Not a new language, not runtime CSS-in-JS, just organized CSS generation + +## Core Concepts + +**`define(name?, def)`** - Creates a styled component. Returns a component function. +- Accepts CSS properties in camelCase (auto-converts to kebab-case) +- Numbers auto-converted to `px` (except unitless props like `opacity`, `zIndex`) +- Generates CSS classes and registers styles globally + +**Parts** - Sub-components within a component (e.g., Header, Body, Footer) +- Defined via `parts: { PartName: { ...styles } }` +- Accessible in render as `parts.PartName` +- Generate classes like `ComponentName_PartName` + +**Variants** - Conditional styling based on props +- Boolean: `variants: { active: { color: 'blue' } }` → `` +- Keyed: `variants: { size: { small: {...}, large: {...} } }` → `` +- Work on both root and parts +- Generate classes like `ComponentName.variant-key` + +**States** - Pseudo-selectors like hover, focus +- `states: { hover: { background: 'blue' } }` → `.Class:hover { ... }` + +**Custom Render** - Override default rendering +- `render({ props, parts }) { return ... }` +- Compose parts manually, pass props through + +## File Structure + +- `src/index.tsx` - Main implementation (`define`, `Styles`, CSS generation) +- `src/types.ts` - `TagDef` type with all CSS properties, helper sets +- **`examples/`** - **REFERENCE THESE** for real-world usage patterns: + - `helpers.tsx` - Layout wrapper, reusable components (Body, Header, ThemeToggle) + - `index.tsx` - Landing page with grid, cards, parts, and custom render + - `button.tsx` - Button variants (intent, size, disabled) + - `profile.tsx` - Complex component with multiple parts and variants + - `navigation.tsx` - Tabs, pills, breadcrumbs, vertical nav patterns +- `src/tests/` - Comprehensive test suite with test helpers + +## Implementation Details + +- **Static CSS generation** - CSS created at component definition time, not runtime +- **Global styles registry** - `styles` object stores all CSS as plain objects +- **`Styles` component** - Renders `