import { Meta } from '@storybook/addon-docs/blocks';

Shade Design System

<p className="excerpt">Shade is Ghost's design system for product design. Built on ShadCN/UI and TailwindCSS, it provides a complete set of components and patterns for building consistent user experiences.</p>

Overview

Shade is built on three powerful foundations:

ShadCN/UI - Reusable components built with Radix UI
TailwindCSS - Utility-first CSS framework
Radix UI - Accessible component primitives

Scope & Reuse

Shade contains reusable, system-wide components and patterns. Keep one-off, app-specific components in the consuming application rather than adding them to Shade.

Target Audience

Designers: Understand our design language and component capabilities
Engineers: Find implementation details and integration examples
AI Agents: Access machine-readable metadata for automation

Core Surfaces

Shade components are used across:

Admin interfaces
Settings panels
Portal experiences
Email templates
Documentation sites

Getting Started

Installation

bash

# Install Shade
yarn add @tryghost/shade

# Install peer dependencies
yarn add react react-dom tailwindcss

Note: The package is currently private and primarily consumed internally in the monorepo. The snippet above reflects usage once published.

Basic Usage

tsx

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

function MyComponent() {
    return (
        <Button variant="solid">
            Continue
        </Button>
    );
}

Configure Styles (CSS-first)

Import Shade's styles in your app entry CSS:

css

@import "@tryghost/shade/styles.css";

For Tailwind v4 utility generation, scan both your app files and Shade component usage paths with @source.

Scope Styles & Dark Mode

Shade scopes all styles to a .shade container and toggles dark mode with a .dark class inside that scope.

Use ShadeApp to handle scoping and provide context:

tsx

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

export default function App() {
    // Toggle dark mode by switching the `darkMode` prop
    return (
        <ShadeApp darkMode={false}>
            <div>
                <Button>Continue</Button>
            </div>
        </ShadeApp>
    );
}

Alternatively, wrap your UI in a div with className="shade" and toggle a nested .dark class when needed.

Documentation Structure

Our documentation is organized into:

Components - Individual UI elements with variants and usage
Patterns - Common UI patterns and compositions
Tokens - Design tokens via TailwindCSS
Guidelines - Best practices and standards

Resources

</div>