thoth-blocks

A React component library built with Vite and documented with Storybook. Ships ESM, CJS, TypeScript declarations, and a combined CSS file.

Installation

npm install thoth-blocks

Usage

import { Button } from "thoth-blocks";
import "thoth-blocks/styles.css";

function App() {
  return <Button variant="default">Click me</Button>;
}

Theming

thoth-blocks supports two built-in themes: punctum and thoth. Apply a theme by setting the data-theme attribute:

<div data-theme="punctum">
  <button>Punctum themed</button>
</div>

Each theme defines its own color palette and border radius. Themes use shadcn/ui CSS variable conventions (--primary, --secondary, --background, etc.) so shadcn-based components work out of the box.

| Theme | Primary Color | | --------- | ------------- | | punctum | #000000 | | thoth | #6e4f7f |

Development

Prerequisites

• Node.js (see .nvmrc for version)

Setup

npm install

Scripts

| Command | Description | | ------------------------- | --------------------------------------- | | npm run storybook | Start Storybook dev server on port 6006 | | npm run build | Build the library to dist/ | | npm run build-storybook | Build static Storybook site | | npm test | Run all tests (Vitest + Playwright) | | npm run lint | Lint with oxlint | | npm run lint:fix | Auto-fix lint issues | | npm run fmt | Format with oxfmt | | npm run fmt:check | Check formatting |

Project Structure

src/
  components/         # Component source + co-located stories
    Button/
      Button.tsx          # shadcn/ui Button (Tailwind + CVA)
      Button.stories.ts
    Header/
    Page/
  lib/
    utils.ts          # cn() utility (clsx + tailwind-merge)
  themes/
    themes.css        # Theme definitions (punctum, thoth) using shadcn variable conventions
  globals.css         # Tailwind imports + @theme inline token mapping
  docs/
    Configure.mdx     # Storybook documentation pages
  index.ts            # Barrel export
.storybook/
  main.ts             # Storybook config
  preview.ts          # Theme decorator, controls
  Page.stories.ts     # Page-level demos (not packaged)

Stories follow Atomic Design hierarchy:

| Level | Description | Examples | Story title | Location | | ------------- | ------------------------------------------------ | ------------------------------------------- | ------------------ | ----------------- | | Atoms | Smallest indivisible UI elements | Button, Input, Label, Icon, Badge, Checkbox | Atoms/<Name> | src/components/ | | Molecules | Small groups of atoms with a single purpose | Search bar, Form field, Menu item | Molecules/<Name> | src/components/ | | Organisms | Complex sections composed of molecules and atoms | Header, Card, Sidebar, Footer | Organisms/<Name> | src/components/ | | Templates | Page layouts with placeholder content | Dashboard layout, Settings layout | Templates/<Name> | .storybook/ | | Pages | Templates filled with real content | Home, Login, Dashboard | Pages/<Name> | .storybook/ |

Atoms, Molecules, and Organisms are co-located with their components in src/components/ and shipped with the library. Templates and Pages live in .storybook/ so they stay out of the published package.

Adding a Component

1. Create src/components/<Name>/<Name>.tsx — use Tailwind classes with the cn() utility from src/lib/utils.ts
2. Use shadcn CSS variables (--primary, --background, --border, etc.) via Tailwind's theme mapping for theming
3. Export the component and its props type from src/index.ts
4. Add <Name>.stories.ts in the same directory (or .storybook/ for pages)

Compatibility

• React 18 and 19

License

Apache-2.0