@jakeseanp/socrates-ui 0.3.1 → 0.3.2

package/README.md

@@ -0,0 +1,121 @@
+# @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
+
+```sh
+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`.
+
+```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:
+
+```css
+@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:
+
+```css
+@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:
+
+```css
+: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`:
+
+```css
+.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
+
+```tsx
+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:
+
+```ts
+import "@jakeseanp/socrates-ui/styles.css";
+```
+
+```js
+// tailwind.config.cjs
+module.exports = {
+  presets: [require("@jakeseanp/socrates-ui/tailwind-preset")],
+  content: [
+    "./src/**/*.{ts,tsx}",
+    "./node_modules/@jakeseanp/socrates-ui/dist/**/*.{js,cjs}",
+  ],
+};
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jakeseanp/socrates-ui",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Socrates component library.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,6 +21,7 @@
     "dist",
     "theme.css",
     "base.css",
+    "README.md",
     "tailwind-preset.cjs"
   ],
   "sideEffects": [