@facter/ds-core 1.1.0 → 1.1.2

package/README.md

@@ -1,28 +1,205 @@
 # @facter/ds-core
 
-Core components for Facter Design System.
+Core UI components for Facter Design System built with React, TypeScript, and Tailwind CSS.
 
 ## Installation
 
 ```bash
+npm install @facter/ds-core
+# or
 pnpm add @facter/ds-core
 ```
 
-## Usage
+### Peer Dependencies
+
+```bash
+npm install react react-dom framer-motion
+```
+
+### Optional (for icons)
+
+```bash
+npm install lucide-react
+# or
+npm install react-icons
+```
+
+## Setup
+
+### 1. Configure Tailwind CSS
+
+Add the design system to your `tailwind.config.js`:
+
+```js
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@facter/ds-core/dist/**/*.{js,mjs}',
+  ],
+  theme: {
+    extend: {
+      colors: {
+        border: 'hsl(var(--border))',
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        // ... add more as needed
+      },
+    },
+  },
+}
+```
+
+### 2. Configure CSS Variables
+
+Create or update your `globals.css`:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 0 0% 3.9%;
+    --border: 0 0% 89.8%;
+    --primary: 24 100% 50%;
+    --primary-foreground: 0 0% 98%;
+    --muted: 0 0% 96.1%;
+    --muted-foreground: 0 0% 45.1%;
+  }
+
+  /* Optional: Custom font */
+  * {
+    font-family: 'Your Custom Font', sans-serif;
+  }
+}
+```
+
+**See `theme.example.css` for complete theme configuration.**
+
+### 3. Import Global Styles
+
+In your app entry point:
+
+```tsx
+import './globals.css'
+```
+
+## Components
+
+### Button
+
+5 variants, 4 sizes, icon support.
 
 ```tsx
 import { Button } from '@facter/ds-core'
 
+<Button variant="default" size="md">Click me</Button>
+<Button variant="destructive" size="lg">Delete</Button>
+```
+
+### Input
+
+Floating label, icon support, password toggle.
+
+```tsx
+import { Input } from '@facter/ds-core'
+import { Mail, Lock } from 'lucide-react'
+
+<Input label="Email" icon={Mail} type="email" />
+<Input label="Password" icon={Lock} type="password" required />
+```
+
+**Icon Support:** Works with any icon library (lucide-react, react-icons, heroicons, custom SVG).
+
+### Badge
+
+7 color variants.
+
+```tsx
+import { Badge } from '@facter/ds-core'
+
+<Badge variant="success">Active</Badge>
+<Badge variant="error">Failed</Badge>
+```
+
+### Loader
+
+5 animated variants with Provider, Hook, and helper function.
+
+```tsx
+import { LoaderProvider, useLoader, Loader } from '@facter/ds-core'
+
+// Option 1: With Provider + Hook
 function App() {
-  return <Button variant="default">Click me</Button>
+  return (
+    <LoaderProvider>
+      <MyComponent />
+    </LoaderProvider>
+  )
+}
+
+function MyComponent() {
+  const loader = useLoader()
+
+  const handleClick = async () => {
+    loader.show({ variant: 'pulse', message: 'Processing...' })
+    await fetchData()
+    loader.hide()
+  }
+
+  return <button onClick={handleClick}>Load</button>
 }
+
+// Option 2: Direct component
+<Loader variant="spinner" show={true} message="Loading..." />
 ```
 
-## Components
+## Customization
+
+### Theme Colors
+
+Each project can define its own brand colors in CSS variables:
+
+```css
+:root {
+  --primary: 24 100% 50%; /* Orange for Facter */
+  /* or */
+  --primary: 220 91% 50%; /* Blue for another project */
+}
+```
+
+### Custom Fonts
+
+```css
+@layer base {
+  * {
+    font-family: 'Neue Haas Grotesk Display Pro', sans-serif;
+  }
+}
+```
+
+Or in `tailwind.config.js`:
+
+```js
+theme: {
+  extend: {
+    fontFamily: {
+      sans: ['Neue Haas Grotesk Display Pro', 'sans-serif'],
+    },
+  },
+}
+```
+
+## Documentation
 
-- Button
-- (More to come...)
+Full documentation and interactive examples available in Storybook.
 
-## Utils
+## License
 
-- `cn()` - Merge Tailwind classes
+MIT