Skip to content

Commit 20e9408

Browse files
committed
docs(propel): ui parts never author render={<X/>}; ui stories never import components
Clarify rule 1 — forwarding the consumer's render (useRender) is render-capability and fine, but baking a render={<Specific/>} target is composition (components' job). Add rule 2b — ui/base stories import only from ui/base + Base UI/external, never components; build a composition inline from atoms.
1 parent 73cae03 commit 20e9408

1 file changed

Lines changed: 9 additions & 2 deletions

File tree

packages/propel/AGENTS.md

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,10 @@ from tiers below it, never above. `internal/` is shared implementation usable by
4040
`base` primitive, or an intrinsic element via Base UI's `useRender`
4141
(`useRender({ defaultTagName, render, props: mergeProps(defaults, props) })`, defaults first).
4242
No `Context.Provider` wrap, no second element/frame, no baked default child (a slot renders
43-
`{children}`, never `children ?? <Default/>`). If you need more structure, add a NEW named
44-
`ui` part and compose the parts in `components`.
43+
`{children}`, never `children ?? <Default/>`), and no authored `render={<X/>}` that injects
44+
another component/behavior — forwarding the consumer's own `render` (the `useRender` mechanism)
45+
IS the render-capability and is fine; baking a specific render target is composition. If you
46+
need more structure, add a NEW named `ui` part and compose the parts in `components`.
4547

4648
2. **All composition lives in `components`** (and `patterns`). Providers, multi-element frames,
4749
defaults, and wiring belong here — never in `ui`.
@@ -53,6 +55,11 @@ imports `lucide-react`, rendering an icon as `{children}` (a slot) and sizing it
5355
carries no `className`, so its size comes from the `ui` cva). `lucide-react` may be imported
5456
**only** in `components` source and in stories — never in `ui`, `base`, or `internal` source.
5557

58+
2b. **`ui`/`base` stories stay in-tier.** A `ui` (or `base`) story imports only from `ui`/`base`
59+
(+ Base UI and external libs like `lucide-react`) — NEVER from `components`. To show what a
60+
`components` ready-made composes (e.g. a toolbar toggle = `ToolbarButton` + Base UI `Toggle`), build
61+
it from the `ui` atoms inline in the story.
62+
5663
3. **`cva`/`cx` live only in `ui`; `className`/`style` exposure stops at `base`.** `base` follows
5764
Base UI exactly and **exposes `className`/`style`** (it is unstyled — `ui` is what styles it).
5865
`ui` and `components` do **not** expose `className`/`style`: `ui` bakes its styling into a cva

0 commit comments

Comments
 (0)