@facter/ds-core

Core UI components for Facter Design System built with React, TypeScript, and Tailwind CSS.

Installation

npm install @facter/ds-core
# or
pnpm add @facter/ds-core

Peer Dependencies

npm install react react-dom framer-motion

Optional (for icons)

npm install lucide-react
# or
npm install react-icons

Setup

1. Configure Tailwind CSS

Add the design system to your tailwind.config.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:

@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:

import './globals.css'

Components

Button

5 variants, 4 sizes, icon support.

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.

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.

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.

import { LoaderProvider, useLoader, Loader } from '@facter/ds-core'

// Option 1: With Provider + Hook
function App() {
  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..." />

Customization

Theme Colors

Each project can define its own brand colors in CSS variables:

:root {
  --primary: 24 100% 50%; /* Orange for Facter */
  /* or */
  --primary: 220 91% 50%; /* Blue for another project */
}

Custom Fonts

@layer base {
  * {
    font-family: 'Neue Haas Grotesk Display Pro', sans-serif;
  }
}

Or in tailwind.config.js:

theme: {
  extend: {
    fontFamily: {
      sans: ['Neue Haas Grotesk Display Pro', 'sans-serif'],
    },
  },
}

Documentation

Full documentation and interactive examples available in Storybook.

License

MIT