Shade

Ghost Design System that can be used by micro-frontends.

Usage in embedded Ghost Admin apps

Ghost Admin provides Shade's CSS and application wrapper centrally. Embedded Admin surfaces, including apps/admin and apps/activitypub, must not import @tryghost/shade/styles.css or add another ShadeApp wrapper. Import components from their layer-specific subpaths:

Example:

tsx

import {Button} from '@tryghost/shade/components';

export function Example() {
    return <Button>Continue</Button>;
}

Usage in standalone surfaces

The setup below applies only to a standalone surface that owns its complete application and CSS entry points. Shade is currently a private package; when published, consumption will follow standard npm usage.

CSS-first styling contract:

css

/* app entry CSS */
@import "@tryghost/shade/styles.css";

No Tailwind preset/config import is required for Shade runtime styling.

Scoping and dark mode:

All styles are scoped under a .shade container.
Dark mode is toggled by adding .dark within that scope.

Wrap your surface with ShadeApp (includes provider and scoping):

tsx

import {ShadeApp} from '@tryghost/shade/app';

<ShadeApp darkMode={false}>
</ShadeApp>

Develop

This is a monorepo package.

For a fresh clone or worktree, follow the setup instructions from the repository root:

bash

corepack enable pnpm
pnpm setup

After setup, run the package commands below from apps/shade or with pnpm --filter @tryghost/shade <command>.

Local docs with Storybook:

pnpm storybook — run Storybook and view docs under src/docs/
pnpm build-storybook — build a static export
pnpm build — build the package and its type declarations

Test

pnpm test — type-checks and runs Vitest with coverage
pnpm test:unit — type-checks and runs Vitest
pnpm test:types — TypeScript only
pnpm lint — ESLint for src/ and test/

Notes

Utilities live at @/lib/utils (not @/utils). Use cn(...) to merge class names and prefer CVA for variants.
Docs live alongside the code and are rendered via Storybook (src/docs/*).