Guide for Developers

Installation, setup, and your first component with Fidus Design System

Installation

Install the Fidus UI component library using your preferred package manager:

Using npm

npm install @fidus/ui

Using pnpm

pnpm add @fidus/ui

Using yarn

yarn add @fidus/ui

Prerequisites

Fidus Design System requires the following dependencies in your project:

React 18.0 or higher
TypeScript 5.0 or higher (recommended)
Tailwind CSS 3.0 or higher

Note on Styling

Fidus components use Tailwind CSS for styling. If you do not have Tailwind CSS installed in your project, follow the Tailwind CSS installation guide for your framework.

Basic Setup with Next.js

Here is how to set up Fidus Design System in a Next.js project:

1. Create a Next.js Project

npx create-next-app@latest my-fidus-app
cd my-fidus-app

2. Install Fidus UI

npm install @fidus/ui

3. Configure Tailwind CSS

Update your tailwind.config.js to include Fidus components:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    // Include Fidus UI components
    './node_modules/@fidus/ui/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      // Fidus design tokens
      spacing: {
        'xs': '0.25rem',   // 4px
        'sm': '0.5rem',    // 8px
        'md': '1rem',      // 16px
        'lg': '1.5rem',    // 24px
        'xl': '2rem',      // 32px
        '2xl': '3rem',     // 48px
      },
    },
  },
  plugins: [],
}

4. Add Global Styles

Create or update app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  /* Fidus Design Tokens */
  --color-primary: #2563eb;
  --color-secondary: #64748b;
  --color-success: #16a34a;
  --color-warning: #f59e0b;
  --color-danger: #dc2626;

  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
}

Your First Component

Let's create a simple page with a Button component:

Import and Use Button

import { Button } from '@fidus/ui/button';;

export default function HomePage() {
  const handleClick = () => {
    alert('Button clicked!');
  };

  return (
    <div className="p-8">
      <h1 className="text-3xl font-bold mb-6">
        Welcome to Fidus
      </h1>

      <div className="space-x-4">
        <Button variant="primary" onClick={handleClick}>
          Primary Button
        </Button>

        <Button variant="secondary" onClick={handleClick}>
          Secondary Button
        </Button>

        <Button variant="outline" onClick={handleClick}>
          Outline Button
        </Button>
      </div>
    </div>
  );
}

Result

You should now see three styled buttons on your page. All buttons are fully accessible, support keyboard navigation, and follow Fidus design principles.

Importing Components

Fidus UI exports all components from the main package. You can import them individually or as a group:

Named Imports (Recommended)

import { Button } from '@fidus/ui/button';
import { Card } from '@fidus/ui/card';
import { Alert } from '@fidus/ui/alert';;

Available Components

Core components available in the library:

Layout: Container, Stack, Grid
Forms: Button, Input, Textarea, Checkbox, Radio, Select, DatePicker, TimePicker
Data Display: Card, Table, Badge, Avatar
Feedback: Alert, Toast, Progress, Spinner
Navigation: Tabs, Breadcrumbs
Overlay: Modal, Dialog, Tooltip

Browse all components →

TypeScript Support

Fidus Design System is built with TypeScript and provides complete type definitions:

import { Button } from '@fidus/ui/button';;

// Component with typed props
interface MyComponentProps {
  onSubmit: () => void;
  disabled?: boolean;
}

export function MyComponent({ onSubmit, disabled }: MyComponentProps) {
  return (
    <Button
      variant="primary"
      size="large"
      onClick={onSubmit}
      disabled={disabled}
    >
      Submit
    </Button>
  );
}

// Using ButtonProps for custom wrappers
export function CustomButton(props: ButtonProps) {
  return <Button {...props} className="my-custom-class" />;
}

Type Safety

All component props are fully typed, providing autocomplete and compile-time error checking. This helps catch issues early and improves developer experience.

Styling Components

Fidus components use Tailwind CSS and CSS variables for styling:

Using CSS Variables

<div
  style={{
    padding: 'var(--spacing-md)',
    margin: 'var(--spacing-lg)',
    color: 'var(--color-primary)',
  }}
>
  Content with design tokens
</div>

Extending Component Styles

import { Button } from '@fidus/ui/button';;

// Add additional classes to components
<Button
  variant="primary"
  className="shadow-lg hover:shadow-xl transition-shadow"
>
  Custom Styled Button
</Button>

Important: Never Hardcode Spacing

Always use CSS variables or Tailwind classes for spacing:

// ❌ BAD: Hardcoded values
<div style={{ padding: '16px', margin: '8px' }}>

// ✅ GOOD: CSS variables
<div style={{
  padding: 'var(--spacing-md)',
  margin: 'var(--spacing-sm)'
}}>

// ✅ GOOD: Tailwind classes
<div className="p-md m-sm">

Theme Configuration

Fidus supports light and dark themes out of the box:

Setting Up Dark Mode

// tailwind.config.js
module.exports = {
  darkMode: 'class', // Enable class-based dark mode
  // ... rest of config
}

// In your root layout or theme provider
<html className={theme === 'dark' ? 'dark' : ''}>
  <body>{children}</body>
</html>

Dark Mode CSS Variables

/* globals.css */
:root {
  --color-background: #ffffff;
  --color-foreground: #000000;
}

.dark {
  --color-background: #0f172a;
  --color-foreground: #f1f5f9;
}

Form Example

Here is a complete example of a form using Fidus components:

import { useState } from 'react';
import { Button } from '@fidus/ui/button';
import { Alert } from '@fidus/ui/alert';;

export function ContactForm() {
  const [formData, setFormData] = useState({
    name: '',
    email: '',
    message: '',
  });
  const [submitted, setSubmitted] = useState(false);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    // Handle form submission
    setSubmitted(true);
  };

  return (
    <form onSubmit={handleSubmit} className="space-y-6">
      {submitted && (
        <Alert variant="success">
          Thank you! Your message has been sent.
        </Alert>
      )}

      <Input
        label="Name"
        value={formData.name}
        onChange={(e) =>
          setFormData({ ...formData, name: e.target.value })
        }
        required
      />

      <Input
        label="Email"
        type="email"
        value={formData.email}
        onChange={(e) =>
          setFormData({ ...formData, email: e.target.value })
        }
        required
      />

      <Textarea
        label="Message"
        value={formData.message}
        onChange={(e) =>
          setFormData({ ...formData, message: e.target.value })
        }
        rows={5}
        required
      />

      <Button type="submit" variant="primary">
        Send Message
      </Button>
    </form>
  );
}

Testing Components

Fidus components are designed to be easily testable with common testing libraries:

Using Vitest and React Testing Library

import { render, screen, fireEvent } from '@testing-library/react';
import { Button } from '@fidus/ui/button';;
import { describe, it, expect, vi } from 'vitest';

describe('Button', () => {
  it('should render with text', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });

  it('should call onClick when clicked', () => {
    const handleClick = vi.fn();
    render(<Button onClick={handleClick}>Click me</Button>);

    fireEvent.click(screen.getByText('Click me'));
    expect(handleClick).toHaveBeenCalledOnce();
  });

  it('should be disabled when disabled prop is true', () => {
    render(<Button disabled>Click me</Button>);
    expect(screen.getByText('Click me')).toBeDisabled();
  });
});

Test IDs

All Fidus components include data-test-id attributes for easy selection in tests. Use single values without spaces:

// ✅ GOOD: Single value
<Button data-test-id="submit-button">Submit</Button>

// ❌ BAD: Multiple values
<Button data-test-id="submit button">Submit</Button>

Need Help?

If you encounter issues or have questions about using Fidus Design System:

Check the component documentation for API details
Review the patterns section for common use cases
Visit the contributing guide to report bugs or request features

View contributing guide →