@formant/aesthetics 0.0.0 → 0.0.3

package/README.md

@@ -1,21 +1,241 @@
-# Next.js template
+# @formant/aesthetics
 
-This is a Next.js template with shadcn/ui.
+Formant design system — themed React components built on shadcn/ui, Radix, and Tailwind CSS v4.
 
-## Adding components
+[![npm version](https://badge.fury.io/js/@formant%2Faesthetics.svg)](https://www.npmjs.com/package/@formant/aesthetics)
 
-To add components to your app, run the following command:
+## Installation
 
 ```bash
-npx shadcn@latest add button
+npm install @formant/aesthetics
 ```
 
-This will place the ui components in the `components` directory.
+Peer dependencies required:
+```bash
+npm install react react-dom tailwindcss@^4.0.0
+```
+
+## Minimal Example (Vite + React + Tailwind v4)
+
+Here's the complete setup based on what we discovered building `formant-metaphysics`:
+
+### 1. `index.css`
+
+```css
+@import "tailwindcss";
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=Space+Grotesk:wght@300;400;500;600;700&family=JetBrains+Mono:wght@300;400;500&display=swap');
+
+/* CRITICAL: This tells Tailwind to scan the compiled library for classes.
+   Path is relative to this CSS file. */
+@source "../../node_modules/@formant/aesthetics/dist/**/*.js";
+
+@theme inline {
+  --font-heading: 'Space Grotesk', sans-serif;
+  --font-sans: 'Inter', sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  /* ... (see full theme in styles/globals.css) */
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+}
+
+:root {
+  /* Formant Dark Theme (Slate Mist) */
+  --background: #202428;
+  --foreground: #F2F3F4;
+  --card: #0A0F11;
+  --primary: #ACC3B3;
+  --primary-foreground: #0A0F11;
+  --muted: #202428;
+  --muted-foreground: #A3ABA9;
+  --border: rgba(163, 171, 169, 0.1);
+  --input: rgba(163, 171, 169, 0.2);
+  --ring: #ACC3B3;
+  --radius: 0.25rem;
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-family: 'Inter', sans-serif;
+  }
+  h1, h2, h3, h4, h5, h6 {
+    font-family: 'Space Grotesk', sans-serif;
+    letter-spacing: -0.02em;
+  }
+}
+```
+
+### 2. `App.tsx`
+
+```tsx
+import { Button, Card, CardHeader, CardTitle, Badge } from "@formant/aesthetics";
+
+function App() {
+  return (
+    <div className="min-h-screen bg-background text-foreground p-8">
+      <Card>
+        <CardHeader>
+          <CardTitle>Hello @formant/aesthetics</CardTitle>
+          <Badge>v0.0.0</Badge>
+        </CardHeader>
+        <div className="p-6 space-y-4">
+          <Button>Default</Button>
+          <Button variant="secondary">Secondary</Button>
+          <Button variant="destructive">Destructive</Button>
+        </div>
+      </Card>
+    </div>
+  );
+}
 
-## Using components
+export default App;
+```
 
-To use the components in your app, import them as follows:
+### 3. `main.tsx`
 
 ```tsx
-import { Button } from "@/components/ui/button";
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)
+```
+
+### Key Insights
+
+1. **`@source` path must be relative to the CSS file** — from `src/index.css`, go up 2 levels to `node_modules/`
+2. **Theme variables live in `:root`** — Tailwind needs them at build time to generate classes like `bg-background`
+3. **No runtime CSS injection needed** — the theme is baked into your CSS, components just use the variables
+
+## Alternative: Using the Canonical Theme
+
+If you want the complete Formant theme without copying the CSS:
+
+```css
+@import "tailwindcss";
+@import "@formant/aesthetics/styles";
+
+/* Customize specific variables */
+@theme inline {
+  --color-primary: #your-color;
+}
+```
+
+## Full Setup Reference
+
+### 1. Import components
+
+```tsx
+import { Button, Card, CardHeader, CardTitle } from "@formant/aesthetics";
+
+function App() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Hello Formant</CardTitle>
+      </CardHeader>
+      <Button>Click me</Button>
+    </Card>
+  );
+}
 ```
+
+### 2. Configure Tailwind to scan the library
+
+In your `index.css` (or `globals.css`):
+
+```css
+@import "tailwindcss";
+
+/* Tell Tailwind to scan the compiled library for classes */
+@source "../../node_modules/@formant/aesthetics/dist/**/*.js";
+
+/* Formant theme variables */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-primary: var(--primary);
+  /* ... other theme vars ... */
+}
+
+:root {
+  /* Formant Dark Theme (Slate Mist) */
+  --background: #202428;
+  --foreground: #F2F3F4;
+  --card: #0A0F11;
+  --primary: #ACC3B3;
+  /* ... etc ... */
+}
+```
+
+### 3. Import the canonical theme (optional)
+
+For the complete Formant theme including fonts and all CSS variables:
+
+```css
+@import "@formant/aesthetics/styles";
+```
+
+Then customize as needed:
+
+```css
+@import "@formant/aesthetics/styles";
+
+@theme inline {
+  /* Override specific variables */
+  --color-primary: #your-color;
+}
+```
+
+## What's included
+
+- **40+ shadcn/ui components** — Accordion, Alert, Badge, Button, Card, Dialog, Dropdown, Form, Input, Select, Table, Tabs, Toast, etc.
+- **Formant brand components** — `FormantLogo`, `FormantLogoWithText`
+- **Theme provider** — `ThemeProvider` from next-themes (dark/light mode with keyboard shortcut)
+- **Charts** — Recharts components (BarChart, LineChart, PieChart, etc.)
+- **Utilities** — `cn()` for class merging
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library
+npm run build
+
+# Watch mode for development
+npm run dev
+
+# Type check
+npm run typecheck
+```
+
+## Architecture
+
+- **Source**: TypeScript React components in `components/`
+- **Build**: tsup compiles to `dist/index.js` + `dist/index.d.ts`
+- **Styling**: Tailwind CSS v4 with CSS variables for theming
+- **Distribution**: Published to npm as `@formant/aesthetics`
+
+The compiled JavaScript preserves all Tailwind class names as strings, allowing consuming projects to scan them and generate only the CSS they need.
+
+## License
+
+MIT