From ca1f6db41af9a566ac581b453d64b5a659c1c8ee Mon Sep 17 00:00:00 2001 From: anmolsinghbhatia Date: Tue, 25 Aug 2026 15:06:51 +0530 Subject: [PATCH 1/2] docs: remove Kumo attributions from prop vocabulary rules Rules 6b, 6c and the "Why these names" list cited kumo-ui.com as the source of propel's `variant`/`size` vocabulary. The rules stand on their own reasoning, so drop the attributions. Item 2 of "Why these names" had no justification beyond the Kumo precedent, so it gets one: a caller picks exactly one look, and a separate `color` prop would only make contradictory pairs representable -- the same failure item 1 already describes for the `prominence`/`tone` split. --- packages/propel/AGENTS.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) 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. `