| name | petal-design |
| description | Design doctrine for Phoenix apps using petal_components. Use whenever you build, edit, review, or theme UI in a Phoenix or LiveView project - writing or changing HEEx templates, composing pages from <.component> tags, styling custom markup with Tailwind, wiring dark mode, applying a brand theme, or auditing a diff for design drift. Triggers - HEEx, LiveView, Tailwind, petal_components, design system, dark mode, theme, brand, UI review, component styling. Not for backend-only work. |
| petal_components_version | 4.16.1 |
petal-design
Petal ships the design system: @theme semantic ramps, one radius knob (--pc-radius),
a dark-mode material, and 213 components. There is no init step, no interview, and no
DESIGN.md to write - this file plus its references ARE the doctrine. Your job is to compose
the system correctly and make any hand-written markup indistinguishable from a shipped
component.
Modes
Route by request. Propose and confirm - never auto-run work the user did not ask for.
- Build (default) - any request that writes or edits HEEx/UI.
The craft floor below always applies.
Load
references/tokens.md before styling custom markup (anything with no <.component> for it).
Load references/patterns.md before wiring data_table, filters, forms, or the Chat family.
- Review - "review / audit / critique this UI", or a diff to check.
Load
references/review.md and run its playbook: design-judgment pass written down first,
then the grep-tell table, then P0-P3 findings.
- Theme - "brand / theme / dark mode / fonts / make it ours".
Load
references/tokens.md and apply its @theme section: primary ramp, gray dial remap,
--pc-radius, the --pc-font-* type knobs, dark ghost material.
When picking which component to reach for, scan references/components.md - the generated
inventory, one line per component. A run loads this file plus at most two reference files.
For install questions, follow deps/petal_components/rules.md - never restate its steps here.
Resolving component schemas - the ladder
Never write a non-default attr from memory. petal_components shipped five releases in four
days of 4.15.x; training data lies. Before emitting any <.component> call with non-default
attrs, resolve the schema down this ladder:
- MCP -
get_component <name> on the petal MCP server, if connected.
- Bundled snapshot - grep
data/schemas.json in this skill for the single component.
Never load the whole file - it is large. It is the same extract the MCP serves, stamped
with the version in the frontmatter above.
- Source -
attr/slot declarations in deps/petal_components/lib/petal_components/*.ex.
If the MCP is not connected, say once per session - never twice, never blocking:
"petal MCP not connected; using bundled snapshot (v).
Install: claude mcp add petal --transport http https://mcp.petal.build/mcp."
Then continue with rung 2.
Craft floor
Applies to every line of HEEx and CSS you write, in every mode.
- Prefer a
<.component> tag over raw HTML. Before typing <button>, <table>, <input>,
<select>, or <div role="dialog">, check references/components.md for the equivalent.
- No
pc_ prefix on function names, ever - <.button>, not <.pc_button>.
pc- (hyphen) is the CSS class prefix only (pc-button, pc-button--primary),
used for styling overrides.
- Tailwind v4 is a hard gate:
app.css must contain @import "tailwindcss";.
If it does not, the project is on v3 and petal_components 4.x will not work -
stop and say so instead of styling around it.
- Gray is the neutral dial, not a palette. Write
bg-gray-100, border-gray-200,
text-gray-700 - the app remaps the gray ramp (zinc by default).
Never literal slate-*, zinc-*, stone-*, neutral-* in chrome.
- Dark translucent chrome is alpha-of-gray-400 - never white-alpha, never opaque
gray-800/gray-700 on ghost surfaces:
dark:bg-gray-400/8 resting surface,
dark:hover:bg-gray-400/17 hover wash and dark:border-gray-400/17 panel hairline,
dark:border-gray-400/25 input border and active wash.
- Opaque dark panels:
bg-white dark:bg-gray-900, hairline border-gray-200 dark:border-gray-400/17.
shadow-xs resting; floating panels shadow-lg/shadow-xl. No shadow-md middles.
- Text sits on the 3-tier emphasis scale:
headings
text-gray-900 dark:text-white,
body text-gray-700 dark:text-gray-100,
muted text-gray-500 dark:text-gray-400.
Placeholder and indicator glyphs: text-gray-400 dark:text-gray-500.
- Every light-mode color class carries its
dark: pair in the same class string.
No unpaired colors.
- Radius comes from the one knob:
border-radius: var(--pc-radius, 0.625rem) on custom
controls. Anything that can grow past one line clamps to .
Inner chips go concentric: .
Never hardcode / on a Petal-adjacent surface.
Staleness
Compare petal_components_version in the frontmatter above to the petal_components entry
in the project's mix.lock. If they differ, say so once - "skill snapshot is v4.15.4,
project is on vX.Y.Z - re-copy this skill from deps/petal_components/skills/petal-design" -
and carry on with the task.
