diff --git a/apps/docs/CLAUDE.md b/apps/docs/CLAUDE.md index a43550b..5f49172 100644 --- a/apps/docs/CLAUDE.md +++ b/apps/docs/CLAUDE.md @@ -13,7 +13,7 @@ do's & don'ts). Read both before any UI/design work here. In short: - **Register:** product · **Platform:** web. A developer **reference tool**, not a marketing surface: design serves the task of looking up, copying, and correctly - using components. Closest kin: Radix / Base UI, Stripe, and Tailwind / shadcn docs. + using components. Closest kin: a dense, copy-first API reference, not a product tour. - **Audience:** internal-first — Plane's own engineers and designers adopting propel, then external `@makeplane/propel` consumers. - **Success:** a developer can use any component correctly **without reading the diff --git a/apps/docs/PRODUCT.md b/apps/docs/PRODUCT.md index 2910c16..a17199e 100644 --- a/apps/docs/PRODUCT.md +++ b/apps/docs/PRODUCT.md @@ -67,8 +67,8 @@ Show the real thing, twice. Every component appears as a live, interactive insta _and_ as its exact source, together — never a screenshot, never a paraphrase. What the reader sees working is what they can copy. -Earned familiarity. Navigation, layout, and interaction follow the conventions a -developer fluent in Radix, Stripe, and Tailwind docs already knows. No invented +Earned familiarity. Navigation, layout, and interaction follow the conventions any +developer who reads component-library docs already knows. No invented affordances for standard tasks; the interface disappears into the lookup. Practice what it documents. The site is built from propel's own tokens and honors diff --git a/packages/propel/AGENTS.md b/packages/propel/AGENTS.md index 5959979..9b3dabb 100644 --- a/packages/propel/AGENTS.md +++ b/packages/propel/AGENTS.md @@ -167,12 +167,11 @@ An identical styled element shared across families is a single `internal/` primi does not re-export it (rule 4a). 6b. **A style/layout prop only reuses a native attribute name when it IS that concept.** `variant` -and `size` are the two standard axes (propel follows [Kumo](https://kumo-ui.com)'s vocabulary) and -are used as such; `width`, `height` and `color` stay off-limits (an `elements` part is -render-capable, so those would collide with the element's own attribute for no gain). Genuine native -attributes (`type`, `disabled`, `href`, `aria-*`) pass through untouched, and a part that declares -its own `type`/`value`/`placeholder` on top of the native one is fine — that is a real, documentable -prop. +and `size` are the two standard axes and are used as such; `width`, `height` and `color` stay +off-limits (an `elements` part is render-capable, so those would collide with the element's own +attribute for no gain). Genuine native attributes (`type`, `disabled`, `href`, `aria-*`) pass +through untouched, and a part that declares its own `type`/`value`/`placeholder` on top of the +native one is fine — that is a real, documentable prop. Where the axis and a real native attribute genuinely collide, the **styling axis wins** and the native attribute is omitted from the props type: @@ -192,11 +191,11 @@ stays `stretch: "auto" | "full"` (mirroring CSS `width`'s own vocabulary), never elements.** One `variant` prop carries the component's look — including its color weight, which is NOT a second axis (a destructive button is `variant="danger"`, not `prominence="secondary"` × `tone="danger"`). A single `variant` union may mix semantic values with decorative ones: `Badge` -takes `variant="danger"` and `variant="crimson"` from the same axis, exactly as Kumo's Badge does. -Do not split such a union into `variant` + `color`; `color` is reserved for the rare case where the -value set is _only_ a surface choice. Reach for a different axis name only when a component carries -a **second, orthogonal** visual dimension that `variant` already occupies (`density`, `stretch`, -`sizing`, `surface`, `elevation`, `placement`, `layout`, `visibility`, `orientation`, `side`). +takes `variant="danger"` and `variant="crimson"` from the same axis. Do not split such a union into +`variant` + `color`; `color` is reserved for the rare case where the value set is _only_ a surface +choice. Reach for a different axis name only when a component carries a **second, orthogonal** +visual dimension that `variant` already occupies (`density`, `stretch`, `sizing`, `surface`, +`elevation`, `placement`, `layout`, `visibility`, `orientation`, `side`). If the values would render a **different element or semantics** (e.g. `