Design system (Ghost theme)

This folder holds the source CSS for the Ghost theme (screen.css → ghost-theme/assets/css/screen.css) and a small React component layer used in Storybook and embeddable web projects.

Principles (Ghost parity for overlapping patterns): see ../docs/design-system-principles.md.

Node version

From the repository root, always load nvm and run nvm use so your shell matches .nvmrc (required before any npm commands). In scripts or CI shells that do not load your profile, source nvm first:

export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" && nvm use

Commands (repo root)

Requires Node.js per .nvmrc and package.json engines (>=22.12 — Storybook, Vite, and PostCSS).

| Script | Purpose | | ----------------- | -------------------------------------------- | | npm run storybook | Interactive component preview | | npm run build-storybook | Static Storybook output (storybook-static/) | | npm run typecheck | tsc --noEmit for components + Storybook | | npm run build | Compile design-system CSS into the theme | | npm run example-site:dev | Run canonical example website | | npm run example-site:typecheck | Typecheck canonical website | | npm run lint:design-system-parity | Enforce Storybook + example-site parity checks | | npm run example-site:check-components | Run parity checks directly in example-site workspace | | npm run example-site:build | Build canonical example website |

Canonical website reference

design-system/example-site is the baseline, full-page implementation that demonstrates how to compose a site entirely from library components.

Recommended React setup

Import the shared stylesheet and wrap app content with ThemeProvider so the design-system document hooks are initialized for you.

import "@tharbakim/proving-theme/screen.css";
import { ThemeProvider } from "@tharbakim/proving-theme";

export function AppShell() {
  return (
    <ThemeProvider accentPreset="emerald" colorScheme="system">
      {/* app UI */}
    </ThemeProvider>
  );
}

ThemeProvider applies the library bootstrap hooks that the CSS expects:

• body.ds-body
• a .ds-root wrapper around your React app
• html[data-color-scheme]
• html.accent-*

If an app already sets those hooks manually, remove the duplicate html / body bootstrap once it adopts ThemeProvider.

Contributor rules for this app:

• Import visible UI from @tharbakim/proving-theme.
• Do not add ad-hoc app-local class styling for page composition.
• Do not render raw semantic UI primitives directly (h1, p, img, button, form controls, table tags); use the design-system components.
• Run npm run example-site:check-components before merging canonical-site updates.

Adding a component

1. Add or reuse semantic tokens in styles/03-semantics.css when introducing new global primitives.
2. Add styles to styles/10-react-components.css (or extend existing 06-components.css patterns) using var(--ds-*) — avoid hard-coded palette values.
3. Implement the React API under components/ with accessibility defaults (aria-*, labels, keyboard).
4. Add a Storybook story under stories/ covering default, error/disabled, and keyboard behavior where relevant.
5. Represent the component in example-site/src by importing and composing at least one export from that module.
6. Run npm run lint:design-system-parity before opening/merging a PR.

Autocomplete

components/Autocomplete.tsx is a headless, MUI-inspired combobox (single value). It does not bundle Material UI; behavior follows ARIA combobox + listbox patterns and theme tokens for visuals.