Petal Design Skill (petal-design)
A design doctrine skill that makes AI-written HEEx UI in Phoenix/LiveView indistinguishable from official petal_components output.
The skill is pure documentation/design doctrine with no destructive execution; it explicitly mandates 'propose and confirm - never auto-run', a least-privilege posture. Deducted because it recommends installing a third-party MCP server (mcp.petal.build) reachable only over the network, and publisher identity is unverified, leaving attribution and rollback partly external; full marks not awarded.
Highly self-consistent: three-rung schema-resolution ladder, staleness check, explicit failure messaging (Tailwind v3 hard gate, one-time MCP-not-connected notice). Static cap of 10 applies: key paths cannot be reproduced without execution, only a partial schemas. excerpt is visible, and no committed test suite covers the skill's own paths, so higher scores are unreachable.
Trigger conditions are precise (HEEx, LiveView, Tailwind keywords) with an explicit non-fit exclusion for backend-only work. Deducted for English-only support and reliance on an overseas MCP service (mcp.petal.build) for fresh schemas; the bundled snapshot mitigates but carries version-lag risk, so not full marks.
Excellent layering (SKILL.md plus on-demand references plus a generated inventory), version in frontmatter with a built-in staleness check, MIT license stated. Deducted because maintenance responsibility and update path rest with an unverified publisher, the skill has no changelog, and the license file is not present in the skill directory itself.
Doctrine is exhaustive (tokens, patterns, review playbook, grep table) with targeted countermeasures for known AI mistakes, implying strong marginal value. Static cap of 7: no executed artifacts verify the output is directly usable; cost/benefit is inferred from documentation only.
Internal evidence chain is coherent: schemas. matches components.md (modulo the truncated excerpt), and mix.lock/deps source enable independent checks. Capped at 5: no third-party execution evidence, no visible CI test coverage over the skill's key paths; most claims rest on static consistency alone.
- Snapshot version may lag the project's actual petal_components version; always check mix.lock before first use.
- Fresh schemas depend on the overseas MCP server (mcp.petal.build), which may be unreachable from mainland China; fall back to the bundled snapshot and manually verify against deps source when currency matters.
- English-only documentation; no Chinese-language support.
- Publisher is not verified by the FollowSkills registry; treat identity as unknown.
- The embedded 'claude mcp add ...' install command is an unverified external instruction; review it yourself before running.
What does this skill do, and when should you use it?
petal-design is the companion design doctrine for petal_components (v4.16.1), covering all UI building, editing, review, and theming in Phoenix/LiveView projects. It ships a semantic @theme ramp, a single radius knob (--pc-radius), a dark-mode material, and an inventory of 213 components. The skill file plus its references ARE the doctrine — there is no init step and no DESIGN.md to write. Its core discipline is preferring <.component> tags over raw HTML and resolving component schemas through a three-rung ladder (MCP → bundled snapshot → source) instead of trusting memory.
Routes each request into three modes: Build (writing/editing HEEx, loading tokens.md or patterns.md first), Review (running the review.md playbook: written design judgment, grep-tell table, P0-P3 findings), and Theme (applying brand primary ramp, gray remap, --pc-radius, type knobs, dark ghost material). Before emitting any non-default attr, it resolves the schema via MCP get_component, the bundled data/schemas. snapshot, or deps source. It also enforces a craft floor: Tailwind v4 gating, gray-dial rules, paired dark: classes, house focus ring, ramp-walking solid fills — and compares frontmatter version against mix.lock to flag staleness.
- A Phoenix/LiveView developer composing pages from petal_components — forms, tables, modals — who wants every tag called with correct attrs.
- A team auditing hand-written HEEx/Tailwind for design drift, receiving a P0-P3 ranked findings list.
- Applying a brand theme: swapping the primary ramp, radius, fonts, and wiring dark mode.
- Styling custom markup that has no <.component> equivalent, keeping it visually indistinguishable from shipped components.
- After a dependency upgrade, verifying whether the skill snapshot version matches mix.lock.
What are this skill's strengths and limitations?
- Bundles a complete design system — semantic ramps, one radius knob, dark material — with no setup files
- The three-rung schema ladder directly addresses fast-moving releases and stale training data
- Craft floor rules are concrete at the class-name level, not vague advice
- Works degraded: bundled inventory and snapshot schema back up a disconnected MCP
- Hard-bound to petal_components and Tailwind v4; v3 projects are blocked outright
- Snapshot may drift from the installed version when MCP is offline — the skill itself requires checking mix.lock
- Frontend UI only; explicitly not for backend work
- Coverage beyond the 213-component inventory and its testing are not documented
How do you install this skill?
Copy the skill folder into the project at skills/petal-design/ (SKILL.md plus references/ and data/schemas.). SKILL.md itself advises re-copying from deps/petal_components/skills/petal-design to stay version-aligned. Optionally connect the MCP server: claude mcp add petal --transport http https://mcp.petal.build/mcp.
How do you use this skill?
Open your Phoenix project in an Agent Skills-capable client and make a UI request — e.g. "build a modal with a form using petal components" or "review this HEEx diff for design drift". Branding prompts like "make it ours / enable dark mode" route to Theme mode. Each run loads the main file plus at most two reference files.
How does this skill compare with similar options?
The project positions petal_components as the Phoenix take on shadcn: same philosophy (composable primitives, you own the patterns, MCP exposes schemas to AI tools), but HEEx instead of JSX, Tailwind v4 instead of Tailwind 3 + CSS variables, and a Hex package instead of a copy-files CLI.