@zaidalshibi/design-system

A React + TypeScript design system built with Atomic Design principles.

Features

• Reusable UI components across atoms, molecules, organisms, and templates
• Theme support via ThemeProvider and useTheme
• Dashboard widgets and chart components
• Typed exports for all public components
• Bundled styles via @zaidalshibi/design-system/styles.css

Installation

npm install @zaidalshibi/design-system

Peer dependencies (install if not already in your app):

npm install react react-dom recharts react-hook-form

Quick Start

1) Import global styles

import '@zaidalshibi/design-system/styles.css';

2) Wrap your app with ThemeProvider

import React from 'react';
import { ThemeProvider } from '@zaidalshibi/design-system';
import '@zaidalshibi/design-system/styles.css';

export function AppRoot() {
  return (
    <ThemeProvider>
      <App />
    </ThemeProvider>
  );
}

function App() {
  return <div>Hello Design System</div>;
}

3) Use components

import React, { useState } from 'react';
import {
  Button,
  Input,
  Select,
  type SelectOption,
  Card,
  CardHeader,
  CardContent,
} from '@zaidalshibi/design-system';

const roleOptions: SelectOption[] = [
  { label: 'Admin', value: 'admin' },
  { label: 'Editor', value: 'editor' },
  { label: 'Viewer', value: 'viewer' },
];

export function ProfileForm() {
  const [name, setName] = useState('');
  const [role, setRole] = useState('viewer');

  return (
    <Card>
      <CardHeader>Profile</CardHeader>
      <CardContent className="space-y-4">
        <Input
          value={name}
          onChange={(event) => setName(event.target.value)}
          placeholder="Enter your name"
        />

        <Select
          value={role}
          options={roleOptions}
          onChange={(event) => setRole(event.target.value)}
        />

        <Button onClick={() => console.log({ name, role })}>Save</Button>
      </CardContent>
    </Card>
  );
}

Theme Usage

import React from 'react';
import {
  ThemeProvider,
  useTheme,
  defaultLightTokens,
  defaultDarkTokens,
} from '@zaidalshibi/design-system';

function ThemeToggleButton() {
  const { mode, toggleMode } = useTheme();

  return (
    <button onClick={toggleMode}>
      Switch to {mode === 'light' ? 'dark' : 'light'} mode
    </button>
  );
}

export function ThemedApp() {
  return (
    <ThemeProvider
      theme={{
        mode: 'light',
        tokens: {
          ...defaultLightTokens,
        },
        darkTokens: {
          ...defaultDarkTokens,
        },
      }}
    >
      <ThemeToggleButton />
    </ThemeProvider>
  );
}

Charts Example

import React from 'react';
import { LineChart, type ChartDataPoint } from '@zaidalshibi/design-system';

const data: ChartDataPoint[] = [
  { name: 'Jan', value: 120 },
  { name: 'Feb', value: 180 },
  { name: 'Mar', value: 150 },
  { name: 'Apr', value: 220 },
];

export function RevenueChart() {
  return (
    <LineChart
      data={data}
      xAxisKey="name"
      lines={[{ dataKey: 'value', label: 'Revenue' }]}
    />
  );
}

Common Imports

import {
  // Atoms
  Button,
  Input,
  Badge,
  Avatar,

  // Molecules
  Alert,
  Tabs,
  Pagination,

  // Organisms
  Modal,
  DataTable,
  Sidebar,

  // Dashboard
  KPICard,
  DataGrid,

  // Templates
  DashboardLayout,
} from '@zaidalshibi/design-system';

TypeScript Support

This package ships with type definitions at:

• dist/types/index.d.ts
• dist/types/tailwind-preset.d.ts

No additional setup is required for TypeScript consumers.

Development

pnpm install
pnpm run dev

Build and test:

pnpm run build
pnpm run test

Publish

This package is configured to publish to npmjs (https://registry.npmjs.org) with public access.

1) Bump version

npm version patch

Use minor or major when needed:

npm version minor
# or
npm version major

2) Authenticate with npm

npm login

3) Verify package contents (recommended)

npm publish --dry-run

4) Publish

npm publish

If you use pnpm for release flow, this also works:

pnpm publish --no-git-checks

License

MIT