Styling

One theme, component-owned styles, and examples that own only their task layout.

Neutral

Blue

123456:root {
  --primary: #2355D6;
  --primary-foreground: #FAFAFA;
  --primary-hover: #1D47B0;
  --primary-active: #193D99;
}

Fix the narrowest owner. Theme tokens share meaning; component styles own structure; your application owns the task.

Choose the owner

Layer	Owns	Example
Theme	Shared semantic colors, typography, spacing, radius and motion scales	Change the brand or light/dark mapping once
Component	Its layout, dimensions, variants, focus and interaction states	Button padding and disabled appearance
Example	Task arrangement, content and local demo state	Place two actions beside a model selector
Block or template	Product layout, workflow, persistence and policy	Save and retry account preferences

Use a theme token when the meaning repeats across components. Use component CSS for the component's own structure and states. Use an example class for the surrounding task. If a demo needs to fix a component's padding or focus, fix the component owner instead.

Theme values

The authored shared values live in design-system/tokens.css. Components consume semantic roles such as --foreground, --border and --ring, plus shared spacing and radius tokens. Hosts can override these roles without editing each component. See Theme tokens for the actual theme contract.

Raw palette steps are inputs for the theme and deliberate data scales. They should not replace semantic roles in ordinary controls. Preserve readable contrast and visible focus when changing a palette.

Component styles

Keep an owner's TSX and CSS together. The CSS owns geometry, supported variants, state selectors and functional transitions. Shared control typography, focus and composition rules live in foundation.css; these are component styling. Button's base, variants and interaction rules live in button.css.

Registry items install source and styles with their dependencies. Import the React component: its source imports load the shared baseline and its structural CSS automatically, including theme defaults. Add host token overrides after the library defaults. Pure data and adapter entries do not load CSS.

Package JavaScript keeps CSS separate for server rendering. Import @ghost-ui/core/styles.css before @ghost-ui/core/components.css, or use @ghost-ui/core/full.css for the aggregate. See Installation for working imports.

The package artifact is @ghost-ui/core, with component and CSS subpaths defined in its manifest. This is one package with exports, not a separate published package for every component. See Installation for the source and local package paths.

Customize deliberately

Choose the narrowest useful mechanism:

Shared token: change the same visual meaning across owners.
Component variant: choose a recurring supported presentation with coherent states.
Component custom property: adjust a documented local value.
className, style or composition: arrange a particular host use where the owner supports it.

Avoid reaching into another component's private selectors, global element resets or !important fixes. Keep native attributes, refs and the supported render composition intact. Do not create a prop for every CSS declaration.

Examples and copyable CSS

An example can own a grid, a width constraint, content styling or fixture state. It must include the CSS needed to reproduce that arrangement. Component styling belongs to the installed owner, not a hidden docs stylesheet. The source shown below a preview should produce that preview with the documented dependencies.

A small style correction needs a focused live check. A shared token or shared CSS change also needs preservation and identified-consumer checks. Syntax and matching distribution hashes cannot prove unrelated styles survived.