| name | primitive-docs |
| description | Write and update Essence UI Primitives documentation pages (Markdown + MDEx HEEx demos, primitive_css, Demo* CSS, anatomy, props, examples, accessibility) with Radix primitives docs parity. Use when authoring or improving docs/content/primitives/**, primitive_css, Demo* class demos, or when the user mentions Radix primitives docs, .radix-ui/website, or primitive component docs. |
Primitive docs
Radix-first authoring for Essence Primitives docs. Read Radix from the local
mirror, map to Essence LiveView APIs, write MD + Demo* CSS.
Hard gates
Stop before writing if any gate fails.
-
Mirror required. Path must exist:
.radix-ui/website/data/primitives/docs/components/
If missing, tell the user to clone the Radix website repo into
.radix-ui/website (gitignored as .radix-ui/). Do not invent Radix copy
from memory.
-
Read sources in order for kebab name {name} (e.g. alert-dialog):
| # | Source |
|---|
| 1 | .radix-ui/website/data/primitives/docs/components/{name}.mdx |
| 2 | .radix-ui/website/components/demos/{name}/css/ (prefer css/ over other styling folders) |
| 3 | lib/essence_ui/primitives/{snake}.ex (alert-dialog → alert_dialog.ex) |
| 4 | docs/content/primitives/components/{name}.md if it exists |
| 5 | assets/css/primitives/{name}.css |
| 6 | docs/ENGINE.md authoring section |
-
Props truth. Only document attrs that exist on EssenceUI.Primitives.*
(module source or <.props_table>). Translate Radix ideas; never paste
React callbacks as LiveView attrs without checking the module. See mapping.md.
-
No speculative all: unset. Do not add UA resets to component Demo* CSS
unless the user asks. Utility resets stay in assets/css/primitives/demo-canvas.css.
Workflow
Copy and track:
Primitive docs:
- [ ] Mirror present; Radix MDX + demo CSS read
- [ ] Essence module attrs verified
- [ ] Page sections complete (order below)
- [ ] Hero demo: Demo* + primitive_css
- [ ] Examples are Essence HEEx (Radix-translated)
- [ ] Events documented as LiveView on_* / controlled assigns
- [ ] Nav updated if new page
- [ ] No component-level all: unset unless requested
- Resolve
{name} (kebab) and {snake} (underscores).
- Read all sources in the table above.
- Diff Radix sections vs Essence module; drop or rewrite React-only features.
- Write/update the page using fixed section order (below).
- Port demo styles →
assets/css/primitives/{name}.css with Demo* renames.
- If new page: add to
docs/nav/primitives.exs.
- Run the done checklist.
Fixed page section order
Gold refs: docs/content/primitives/components/dialog.md, accordion.md.
- Frontmatter —
title, description, optional aria: (from Radix MDX)
- Lead — Radix Description as a short paragraph
- Hero demo
<.demo theme="light" variant="primitive" component="{name}" css={primitive_css("{name}")}>
<:heex>
… Demo* classes …
</:heex>
</.demo>
<.highlights> — port Radix Highlights; rewrite/drop React-only bullets## Anatomy — HEEx fence + <.anatomy> for public parts## API Reference — per part: short prose, <.props_table>, then
<.data_attributes_table> / CSS variables when Radix documents them and
Essence exposes them## Examples — real translated examples from Radix.
Prefer extra <.demo> when interactive; else fenced heex / css## Accessibility — ARIA link + <.keyboard_table> from Radix keyboard section
Full skeleton: reference.md.
Demo & CSS conventions
- CSS tab = component file only (
primitive_css/1); canvas is preview-only.
- Class names:
Demo{Component}{Part} (e.g. DemoAccordionTrigger).
- Portaled overlays: dual selectors when needed, e.g.
.DemoAlertDialogContent, [data-radix-alert-dialog-content].DemoAlertDialogContent.
- Port Radix demo CSS from
components/demos/{name}/css/ →
assets/css/primitives/{name}.css; primitive_css strips @import.
- Import nothing in Markdown —
PageLive already aliases all primitives + docs helpers.
- MDEx: no
""" in attrs; use ~s[...] / ~S|...|; keep complex attrs single-line.
Done checklist
