| name | component-description |
| description | Write feature descriptions for CraftUI blocks and components purely from a design engineering perspective, as structured JSON for the block registry. Use when writing or reviewing the description/features of a UI component, block, or variation. Triggers on component description, block features, "understanding the component", write features for, describe this component, design engineering description, featureSections, config.json features. |
Component descriptions as design engineering
Describe the component as mechanism, not benefit. The reader is a design engineer deciding whether to install this block; they want to know what drives the motion, which properties animate, and what accessibility contract ships with it. Voice models: Emil Kowalski (Sonner/Vaul docs, animations.dev), Jakub Krehel, Rauno Freiberg (rauno.me), Paco Coursey (cmdk), Radix/shadcn a11y notes, vercel.com/design.
Where the output goes
The deliverable is JSON in the block's source config, never prose in chat:
- Write into the variation's entry in
components/craftui/blocks/<slug>/config.json (icons/loaders have the same layout under their own folders).
scripts/build-registry.ts copies it into public/r/blocks.json.components/block-gallery/BlockContentPanel.tsx renders it in the details panel.
After editing a config, remind the user to run the registry build. Do not start a dev server to verify; the user checks the UI themselves.
Output schema
Preferred format — featureSections, one object per design-engineering concern:
"featureSections": [
{
"title": "Checkbox Icon Animation",
"summary": "Smoothly animates SVG paths based on checked state using scale, opacity, and clipPath transitions.",
"points": [
"Fills and scales circle on check",
"Reveals checkmark path via clipPath",
"Fades outer stroke when toggled"
]
}
]
- 2–4 sections per variation. Each section:
title (noun phrase naming the concern, e.g. "List Rendering & Interaction", "Text Strike-through & Movement"), summary (one sentence, states what it does and the techniques used), points (max 4–5 bullets, each starting with a present-tense verb).
- No code snippets anywhere — name APIs and primitives in prose instead.
- If
featureSections is not yet supported by the pipeline (see Schema status below), fall back to the flat features: string[] field with 3–5 dense mechanism bullets, in the register of the existing travel-card entry: "A single icon travels along an SVG offset-path between the button and the detail chip so the two stages read as one continuous object, not a swap".
Schema status
featureSections requires three one-time edits (flag these if they haven't landed yet):
types/block.ts — add featureSections? to BlockVariation (next to features? around line 34).scripts/build-registry.ts — pass the field through at the two spread sites (lines ~357 and ~512, beside features).components/block-gallery/BlockContentPanel.tsx — render sections near the existing features list (~line 219).
Process
- Read the component source first. Every claim must be traceable to a line of the
.tsx. Never invent features.
- Consult sibling skills before writing (internally — never cite them in the shipped JSON):
better-writing for voice, tense, and consistency; web-animation-design and better-ui for naming motion correctly; better-accessibility for describing a11y behavior accurately. Mention in your chat response which skills you applied.
- Verify each bullet against code. Don't say "spring" if the transition is a tween; don't claim
prefers-reduced-motion support unless the code handles it; check the actual ARIA attributes before naming them.
- Write the JSON into
config.json, then remind the user to run the registry build.
Voice rules
- Mechanism, not benefit. "Reveals checkmark path via clipPath", never "delightful check animation" or "improves UX".
- Every animation claim names its driver and its properties. Driver: state change, gesture, hover, scroll, layout. Properties: transform, opacity, clip-path — call out when motion is compositor-only.
- Name the concrete primitives.
AnimatePresence, layoutId, shared layout transitions, useMotionValue, keyframes, stagger, offset-path, transform-origin, spring vs tween. Specificity is what makes it read as design engineering.
- Accessibility is a first-class section, not a footnote.
role/aria-* attributes, focus management, keyboard support, and prefers-reduced-motion handling each earn a bullet when present in the code.
- Feel vocabulary when relevant. Spring character ("snappy spring on press"), easing direction (ease-out entrances, ease-in exits), enter/exit asymmetry, duration tiers.
- Interaction states by their real names. hover, press, focus-visible, checked, disabled, exit — not "when you interact with it".
- Bullets start with a present-tense verb. Fills, Reveals, Shifts, Animates, Applies, Respects.
Vocabulary
clipPath reveal · layout projection · shared layout transition (layoutId) · stagger · spring (stiffness/damping intent) · tween · keyframes · exit animation · enter/exit asymmetry · offset-path / motion path · transform-origin · optical alignment · overshoot · compositor-only (transform + opacity) · state-driven vs gesture-driven · focus trap · roving tabindex · reduced-motion fallback
Common mistakes
| Mistake | Fix |
|---|
| "Beautiful, smooth animation" | Name the properties: "Scales and fades the icon with an ease-out tween" |
| Benefit-speak ("improves UX", "delightful") | Mechanism-speak: what drives what, which properties move |
| 8 bullets in a section | Max 4–5; merge or cut |
| Code snippets in the description | Prose only; name APIs, don't show them |
| A11y vague or omitted | Cite exact attributes: role="checkbox", aria-checked |
| Claiming behavior not in the code | Verify every bullet against the .tsx source |
| Prose delivered in chat as the final output | Write JSON into the block's config.json |
| Marketing-style section titles | Noun phrases naming the concern: "Text Strike-through & Movement" |
Full example
For a checklist item component:
"featureSections": [
{
"title": "List Rendering & Interaction",
"summary": "Renders interactive list items and handles state toggling with proper accessibility attributes.",
"points": [
"Uses onToggle callback to update checked state",
"Applies role=\"checkbox\" and aria-checked for screen readers"
]
},
{
"title": "Checkbox Icon Animation",
"summary": "Smoothly animates SVG paths based on checked state using scale, opacity, and clipPath transitions.",
"points": [
"Fills and scales circle on check",
"Reveals checkmark path via clipPath",
"Fades outer stroke when toggled"
]
},
{
"title": "Text Strike-through & Movement",
"summary": "Animates title text sliding and strikethrough overlay to visually indicate checked status."
