Component hierarchy
Choose the reusable owner by its job, then compose upward without copying its behavior.
The layers
| Layer | Contract | Example |
|---|---|---|
| Theme token | Shared visual meaning | Foreground, control radius, focus ring |
| Primitive | Focused reusable building block | SharedBackground or a native behavior adapter |
| Part | A region belonging to an owner | Dialog.Trigger, Dialog.Popup |
| Component | A reusable UI job | Choose a value, display progress, edit a date |
| Library | Related contracts and utilities with a useful independent domain | Calendar core and scheduling views; emoji/icon search and providers |
| Block | Components plus a complete product task and caller policy | Notification preferences with persistence and retry |
| Template | Connected pages or flows for a product | An account settings area |
These are ownership boundaries, not a quality ranking. A primitive may have a public component page; a part is not a second independent component. A complex view can still be a component if its job and contract are reusable.
One job, one owner
Search the existing component and library before adding a public name. Extend the owner when the new need shares its behavior. Compose owners when the task combines several jobs. Keep local helpers private until another caller needs their contract.
For example, Activity owns expandable work history; a business-specific activity feed can compose it. A reference library calling a similar pattern Trace is not a reason to introduce a parallel Ghost owner.
Where a use case belongs
A different title or product domain does not create a variant. A real caller choice can: single versus multiple selection, compact versus ordinary density, or a different supported placement. Pending, invalid and disabled are states. A workflow that adds persistence or product policy belongs in a block or host application.
Component documentation shows meaningful decisions through small examples. Blocks can show the complete task. Templates can connect those tasks into an application. See Blocks and the documentation standard.
Domain libraries
The sidebar gives each real library its own section. Calendar and scheduling covers the neutral calendar core and the related date, time and booking views. Emoji and icons covers the catalog, providers, adapters and picker view. These are current source/package export boundaries, not promises of separately published npm packages.
API structure
Use native semantics and familiar prop names. Keep independent choices independent, use finite values for exclusive choices and expose useful parts for custom composition. A convenience wrapper should use the same parts. Keep application data, transport, persistence and side effects explicit and caller-owned.
For AI views, keep SDK-free contracts separate from optional adapters. React UI remains React even when the data contracts work with multiple runtimes. See the Ghost craft skill for the full API and code structure guide.