@jakeseanp/socrates-ui

Socrates component library for React applications.

Requirements

• React 18 or newer.
• React DOM 18 or newer.
• Tailwind CSS v4 for the primary CSS-first setup.

Tailwind v3 is supported through the compatibility stylesheet and preset, but new consuming apps should use the Tailwind v4 setup below.

Installation

pnpm add @jakeseanp/socrates-ui

Tailwind v4 Setup

Import Socrates from your app's global CSS file. In a Next.js App Router project, this is usually app/globals.css or src/app/globals.css.

@import "tailwindcss";

@import "@jakeseanp/socrates-ui/theme.css";
@import "@jakeseanp/socrates-ui/base.css";

@source "../node_modules/@jakeseanp/socrates-ui/dist";

If your global CSS file lives in src/app/globals.css, adjust the source path:

@source "../../node_modules/@jakeseanp/socrates-ui/dist";

Do not import @jakeseanp/socrates-ui/styles.css in Tailwind v4 apps. That file is the precompiled compatibility stylesheet for Tailwind v3-style consumption.

Theme Overrides

Socrates components use semantic Tailwind classes such as bg-primary, text-primary-foreground, border-border, and ring-ring.

In Tailwind v4, those classes are created by theme.css and resolve through runtime CSS variables from base.css. Override variables after the Socrates imports:

@import "tailwindcss";

@import "@jakeseanp/socrates-ui/theme.css";
@import "@jakeseanp/socrates-ui/base.css";

@source "../node_modules/@jakeseanp/socrates-ui/dist";

:root {
  --primary: oklch(0.78 0.18 145);
  --primary-foreground: oklch(0.98 0.02 145);
}

Theme values should be valid oklch(...) color values. For interactive components, set both the surface token and its foreground token so contrast remains intentional.

Common tokens:

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.78 0.18 145);
  --primary-foreground: oklch(0.98 0.02 145);
  --secondary: oklch(0.967 0.001 286.375);
  --secondary-foreground: oklch(0.21 0.006 285.885);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.985 0 0);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --radius: 0.625rem;
}

Dark mode is class-based. Override dark tokens under .dark:

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.68 0.16 145);
  --primary-foreground: oklch(0.145 0 0);
}

Importing Components

import { Button } from "@jakeseanp/socrates-ui";

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

Tailwind v3 Compatibility

Tailwind v3 apps can import the precompiled stylesheet and use the published preset:

import "@jakeseanp/socrates-ui/styles.css";

// tailwind.config.cjs
module.exports = {
  presets: [require("@jakeseanp/socrates-ui/tailwind-preset")],
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@jakeseanp/socrates-ui/dist/**/*.{js,cjs}",
  ],
};