diff --git a/README.md b/README.md index 1301f7a..79cc19d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,35 @@ -# forge +# Forge + +## Why Forge? + +CSS is powerful, but hostile to humans at scale. + +### Problems with CSS + +- Styles are **global and open** — anything can override anything. +- There’s **no link** between a class in markup and its definition. +- Inline styles exist because there’s **no structured way to vary styles per instance**. +- Overrides are silent — conflicts happen without feedback. +- Complex components require selector gymnastics and reach-in styling. + +### What Forge Does Instead + +- Styles are **local to components** and attached by generated handles, not strings. +- **Parts** give components named sub-targets without selectors. +- **Variants** replace inline styles with typed, declarative parameters. +- Style composition is **deterministic** (known merge order, last-wins). +- Overlapping changes are **warned about in dev**, not silently ignored. + +### What Forge Is + +- A typed, local, variant-driven way to author CSS. +- A system that optimizes for **people typing at a keyboard**, not selectors in a cascade. + +### What Forge Is Not + +- Not a new component model. +- Not a new language. +- Not a CSS replacement — it compiles _to_ CSS, but removes the chaos. Example: