Extend the library

Your components can live in your application or your own shared library. You do not need to contribute them upstream or reproduce this documentation site. Install the skills when you want an agent to follow the same process.

Choose what to build

Write the caller’s task in one sentence. Inspect the closest installed Ghost components and their public types. Compose existing owners first; extend an owner when the new capability shares its behavior. Add a component when it earns a distinct reusable job. Keep product-specific data, network requests and persistence in the application.

For example, a saved-filter action can compose Button and Dropdown menu. Its filter query and save request belong to the caller. A different label does not need a new Button variant. See Component hierarchy.

Pin the contract before styling

List inputs, callbacks, defaults, caller-owned state and meaningful states. Explain who updates a value after a callback, what happens while saving, and how failure is shown. Keep native attributes, accessible names, refs and composition available where the underlying owner supports them. Avoid a prop for every possible CSS change.

Use the current source and types as evidence. Research upstream behavior when building a new interaction; copying another library’s prop names does not supply its accessibility or behavior. Prototype the appearance after the contract makes sense. A Paper file is useful for a visual decision, not a prerequisite for writing a correct contract or setup guide.

Worked example: a save action

Start from a project with Button installed. This composition adds a reusable save action and error feedback without creating another Button implementation.

SaveFilterAction has three props: onSave requests work from the caller, pending defaults to false, and an optional error string supplies the message. The view uses Button’s existing loading state. The caller handles the asynchronous request, catches failures and passes the resulting state back.

Try saving. This local demonstration deliberately fails once; a second attempt succeeds. Replace the example’s save function with your own persistence. It does not contact a server or save a real filter.

Copy the TSX and CSS into the same folder in your project. Keep SaveFilterAction as the reusable view and replace SaveFilterExample with your application’s caller. When another screen needs the view, move it into your shared component folder and export only its supported props. The example’s attempt counter and request simulation stay with the caller.

The stylesheet arranges the composition and its error text. Button still owns its padding, corners, disabled state, spinner and focus behavior. No documentation stylesheet is required by the copied example.

Implement at the right owner

Keep a component’s implementation and styles together, using the folder conventions of your project. Import the real Ghost owners for controls, disclosures, loading and progress. Do not imitate an owner by copying its CSS classes or rebuilding its keyboard handling.

Use semantic theme tokens for shared meaning and owned CSS for structure and states. Arrange a composition with caller-owned wrappers. Preserve focus, contrast, reduced motion and disabled behavior. The styling guide explains these boundaries.

Keep a new component local until another caller needs it. If you distribute it, expose the intended public API and include its styles and transitive dependencies. Test the installed result in a separate consumer. A registry item and an npm package are different delivery choices; see Registry.

Document what actually works

Use Technical writing for the page structure and editing method. A component page starts with one working task, then useful choice guidance, installation, basic usage, public structures, meaningful examples and exact API reference. A setup guide starts with prerequisites and steps; an API reference starts with the contract.

Code must reproduce the example, including necessary data, state, helpers and CSS. Verify imports, types and defaults against the implementation. Show a visual comparison only when it teaches a decision; prose and executable code carry the technical explanation.

Verify the result

For the save action, check that a pending request prevents another activation, a failure is announced, retry clears the old error, and success appears only after completion. Activate it with a keyboard as well as a pointer. Your real request should retain these states when it fails or takes longer than expected.

For other components, choose the relevant empty/long content, controlled updates and focus states. For a styling change, inspect the affected interaction and viewport. For a distribution change, install the actual output and exercise its public imports and styles.

Review technical accuracy before editing for clarity. Keep unknown results explicit. A build, generated file or screenshot alone does not prove the user can complete the task. Stop when the component and its documentation demonstrate their intended job.