---
name: ghost-craft
description: Design, build and review your own React component set using Ghost UI craft and composition conventions. Use when extending Ghost, defining a component API, styling states or composing product interfaces.
license: MIT
---

# Ghost craft

Help the user extend their own component set with Ghost’s craft. Work in the host repository’s existing structure and follow its instructions. Read the installed component source and public types before assuming an API. This skill supplies a method; it does not install React components or require Ghost’s internal tooling, Paper, a particular coding agent or a hosted runtime.

## Start with the task and evidence

1. State the caller’s job and the smallest result that demonstrates it. Find the existing component, utility, token and composition before adding a public name.
2. Choose composition, an extension of the current owner, or a new component with a distinct reusable job. A different product title or an extra example does not create a component variant.
3. Read the current source, types, styles and a real consumer. Verify uncertain behavior with the installed upstream documentation. A competing API is research, not proof that Ghost supports it.
4. Pin inputs, defaults, callbacks, state ownership and relevant failure states before polishing appearance. Use a visual prototype only when it helps settle a visual or interaction decision.

## Keep one owner for each job

Compose the actual Button, Field, Collapsible, Spinner/Loader, Progress and other installed owners for their jobs. Confirm their exact exported names. An import alone does not establish reuse if parallel markup or behavior remains. Do not copy private classes to imitate another owner.

Keep reusable UI separate from business content, transport, persistence, approval policy and tool execution. A product workflow can compose components without moving its policy into them. Ghost calls its expandable work-history building block Activity; do not create a parallel Trace owner for the same job.

Keep a small new component local until another caller needs its contract. Use the host’s file layout, direct imports and export conventions. Component styles belong with the component, not in documentation CSS. When distributing source, include structural styles and transitive dependencies; test the actual public entry in a separate consumer.

## Define an explicit API

- Preserve native attributes, accessible names, refs and supported render composition. Native semantics and the installed behavior primitive come before custom keyboard logic.
- Separate independent decisions such as size and hierarchy. Use finite values for mutually exclusive choices; avoid booleans that can contradict each other and props for individual CSS declarations.
- Name exact defaults and callback payloads. For controlled state, the caller passes the value and handles the change request; for uncontrolled state, the component retains its local interaction state. Do not silently switch ownership.
- Expose meaningful lower-level parts when custom composition needs them. Convenience compositions must use those same parts.
- Preserve caller IDs, ordering, cancellation and unknown state. A callback does not prove a capability is available; approval does not prove execution; stream end does not prove success. Show a percentage only when the total is known.
- Before a breaking change, enumerate affected callers, exports, distribution, examples and docs. Migrate all affected sites without creating a competing implementation.

For AI interfaces, keep SDK-free data contracts and React views separate from optional runtime adapters. The application owns side effects. React UI remains React; runtime independence is not framework independence. Type adapters against actual installed SDK versions.

## Match the craft

Use the installed theme’s semantic colors, type roles, spacing, control sizing, radius, motion and focus tokens. Inspect the current token definitions rather than inventing a second palette or hardcoding remembered values.

- Keep ordinary text and controls quiet and readable. Establish hierarchy with size, color and space before adding weight. Give the main next action enough emphasis; quieter supporting actions still need readable labels.
- Preserve comfortable text/control padding and visible keyboard focus. Inspect the whole composition before measuring a detail. A highlight touching its label or a flat compound hierarchy is a defect even when a numeric check passes.
- Derive nested corners from the actual outer radius and inset. Follow the installed height/radius scale; avoid unrelated rounded shapes within one control.
- Keep hover, focus, persistent selection and open state distinct. Ghost menus use a checkmark for selection and backgrounds for hover, keyboard focus and an open submenu.
- Use the canonical moving-background owner only where continuity makes a peer group easier to follow. Motion explains change, supports interruption and respects reduced motion.
- Keep native semantics, labels, contrast and error associations intact. Do not claim broad accessibility or production readiness from appearance alone.

Theme tokens own shared meaning. Component CSS owns structure, variants and interaction states. Caller wrappers own product layout. Use supported variants/composition before adding overrides. Do not reach into another owner’s private selectors or repair the default component from a demo stylesheet.

Before editing shared CSS, capture a baseline, identify exact rules and preserve unrelated work. Use contextual patches; inspect the complete diff. Syntax and equal generated hashes do not establish preservation.

## Show the actual result

Use one believable task as the main example. Give meaningful independent decisions and states a purpose and a working example; do not generate every prop permutation. Keep business content and fixture state in the example. The copyable source must produce the preview, including necessary data, helpers, imports and example CSS.

For a component page, use Preview → Design guidance when useful → Installation → Basic usage → Structures → Examples → API reference. Setup guides and technical reference follow their reader’s task instead. Resolve technical accuracy first; use visuals to explain appearance, anatomy or interaction when needed. The separate technical-writing skill develops this method.

## Verify and finish

Choose proof from the changed contract and risk: actual common consumer, keyboard/focus behavior, controlled updates, pending/error/empty/long states, affected viewport or clean installation. Do not run a full catalogue review for a local correction. Fix connected defects as one outcome and inspect the current rendered result.

Check source claims and compile executable examples. For delivery changes, verify actual installed imports and styles. State untested boundaries; do not replace product judgment with build success, file counts or screenshots of a different state. Keep human acceptance separate from your verification. Stop when the requested job is demonstrated and no relevant defect remains.

Further guidance: [extend the library](https://ghost-ui.com/docs/extending), [styling](https://ghost-ui.com/docs/styling), [component hierarchy](https://ghost-ui.com/docs/components) and [technical writing](https://ghost-ui.com/docs/documentation).