@tagaddod-design/react

v0.1.30

Published

4 months ago

Modern, accessible React component library for building consistent UI at scale.

Downloads

0High
0Medium
0Low

ahmedamrdev

react ui component-library design-system storybook accessible LLM AI documentation

@tagaddod/react

📚 Complete Documentation & Interactive Examples

A modern, accessible React component library for building consistent user interfaces following the Tagaddod Design System. Built with performance, accessibility, and developer experience in mind.

🤖 LLM Agent Integration

This package includes comprehensive AI agent documentation designed specifically for Large Language Models (GPT, Claude, etc.). The llms.txt file contains structured information about component usage, props, examples, and best practices to help AI agents understand and use the component library effectively.

For AI Agents: Access the documentation at:

Live URL: https://tagaddod-design-system.vercel.app/llms.txt
Package export: @tagaddod/react/llms.txt
Local path: node_modules/@tagaddod/react/llms.txt

This enables more accurate AI-assisted development with proper component usage, accessibility practices, and theme integration.

🚀 What's New in v0.1.0

This release includes major optimizations and improvements:

🏗️ Monorepo Architecture: Full design system with tokens, themes, and components
📦 Token Management: Live token editing with Storybook addon and admin UI
⚡ Performance: Optimized build process with Style Dictionary and W3C tokens
🎨 Multi-Brand Theming: Tagaddod and GreenPan themes with runtime switching
🌍 RTL/LTR Support: Complete bi-directional language support (English/Arabic)
🧹 Developer Experience: TypeScript, comprehensive docs, and LLM integration

View full documentation

📦 Installation

npm install @tagaddod/react

yarn add @tagaddod/react

pnpm add @tagaddod/react

🔧 Prerequisites

React >=17.0.0
React DOM >=17.0.0

🚀 Quick Start (Plug & Play)

1. Install

npm install @tagaddod/react
# or
yarn add @tagaddod/react

2. Load Google Fonts (Required)

Add these font links to your HTML <head> section:

<!-- Google Fonts for the design system -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&family=Tajawal:wght@400;500;600;700&display=swap" rel="stylesheet">

3. Import Styles (Required)

// In your app's entry point (App.js, main.js, or index.js)
import '@tagaddod/react/styles';

4. Import & Use Components

import { Button, TextInput, ThemeProvider } from '@tagaddod/react';

function App() {
  return (
    <ThemeProvider defaultTheme="tagaddod" defaultLocale="en">
      <Button variant="primary">Click me</Button>
      <TextInput label="Name" placeholder="Enter your name" />
    </ThemeProvider>
  );
}

That's it! 🎉 Your components are ready to use with full theming and accessibility support.

📦 What's Included

18+ React Components - Buttons, Forms, Tables, Modals, and more
Complete Design System - Tokens, themes, and utilities
Full TypeScript Support - Type-safe development experience
Accessibility First - WCAG 2.1 AA compliant components
RTL/LTR Support - Built-in internationalization
Multi-Brand Theming - Tagaddod and GreenPan themes
Tree Shakeable - Import only what you need
Token Management - Live editing via Storybook and admin UI

🎨 Theming

Automatic Theme Detection

// Themes are applied via data attributes
<div data-theme="tagaddod">Tagaddod theme</div>
<div data-theme="greenpan">GreenPan theme</div>

React Theme Provider

import { ThemeProvider, useTheme } from '@tagaddod/react';

function App() {
  return (
    <ThemeProvider defaultTheme="greenpan" defaultLocale="ar">
      <MyComponents />
    </ThemeProvider>
  );
}

function ThemeSwitcher() {
  const { setTheme, setLocale } = useTheme();
  
  return (
    <div>
      <button onClick={() => setTheme('tagaddod')}>Tagaddod</button>
      <button onClick={() => setTheme('greenpan')}>GreenPan</button>
      <button onClick={() => setLocale('ar')}>العربية</button>
    </div>
  );
}

🌍 Internationalization

Automatic Direction Support

// Set locale and direction is automatically applied
const { setLocale } = useTheme();

setLocale('ar'); // Automatically sets dir="rtl"
setLocale('en'); // Automatically sets dir="ltr"

Manual Direction Control

<html dir="rtl">
  <!-- All components automatically adapt to RTL -->
</html>

🧩 Component Examples

Forms

import { 
  TextInput, 
  Checkbox, 
  Switch, 
  RadioGroup, 
  RadioButtonItem,
  Button 
} from '@tagaddod/react';

function ContactForm() {
  return (
    <form>
      <TextInput 
        label="Email" 
        type="email" 
        required 
        helpText="We'll never share your email"
      />
      
      <Checkbox>Subscribe to newsletter</Checkbox>
      
      <RadioGroup>
        <RadioButtonItem value="individual">Individual</RadioButtonItem>
        <RadioButtonItem value="business">Business</RadioButtonItem>
      </RadioGroup>
      
      <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
        <span>Enable notifications</span>
        <Switch />
      </div>
      
      <Button type="submit" variant="primary">Submit</Button>
    </form>
  );
}

Data Display

import { Table, Badge, Avatar, Tabs, TabsList, TabsTrigger, TabsContent } from '@tagaddod/react';

function Dashboard() {
  const data = [
    { id: 1, name: 'John Doe', status: 'active', role: 'Admin' },
    { id: 2, name: 'Jane Smith', status: 'inactive', role: 'User' }
  ];
  
  const columns = [
    { accessorKey: 'name', header: 'Name' },
    { 
      accessorKey: 'status', 
      header: 'Status',
      cell: ({ getValue }) => (
        <Badge tone={getValue() === 'active' ? 'success' : 'neutral'}>
          {getValue()}
        </Badge>
      )
    },
    { accessorKey: 'role', header: 'Role' }
  ];

  return (
    <Tabs defaultValue="users">
      <TabsList>
        <TabsTrigger value="users">Users</TabsTrigger>
        <TabsTrigger value="settings">Settings</TabsTrigger>
      </TabsList>
      
      <TabsContent value="users">
        <Table 
          data={data} 
          columns={columns}
          title="User Management"
          showSearch
          showFilters
        />
      </TabsContent>
      
      <TabsContent value="settings">
        <div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>
          <Avatar src="https://i.pravatar.cc/150" alt="User" />
          <div>
            <h3>Profile Settings</h3>
            <p>Manage your account preferences</p>
          </div>
        </div>
      </TabsContent>
    </Tabs>
  );
}

🎯 Advanced Usage

Custom Styling with CSS Variables

.my-custom-component {
  background-color: var(--t-color-surface-primary);
  padding: var(--t-space-400);
  border-radius: var(--t-border-radius-200);
  color: var(--t-color-text-primary);
}

Utility Classes

function MyComponent() {
  return (
    <div className="t-p-400 t-bg-primary t-rounded-200 t-shadow-1">
      <h2 className="t-heading-lg t-text-primary">Title</h2>
      <p className="t-body-md-default t-text-secondary">Description</p>
    </div>
  );
}

Tree Shaking (Import Only What You Need)

// ✅ Good - Only imports Button component
import { Button } from '@tagaddod/react';

// ✅ Also good - Explicit imports
import { Button } from '@tagaddod/react/components/Button';

// ❌ Avoid - Imports entire library
import * as TagaddodReact from '@tagaddod/react';

📱 Framework Integration

Next.js

// pages/_app.js or app/layout.js
import '@tagaddod/react/styles';
import { ThemeProvider } from '@tagaddod/react';

export default function App({ Component, pageProps }) {
  return (
    <ThemeProvider defaultTheme="tagaddod">
      <Component {...pageProps} />
    </ThemeProvider>
  );
}

Vite/React

// main.jsx
import '@tagaddod/react/styles';
import { ThemeProvider } from '@tagaddod/react';

ReactDOM.createRoot(document.getElementById('root')).render(
  <ThemeProvider defaultTheme="tagaddod">
    <App />
  </ThemeProvider>
);

Create React App

// src/index.js
import '@tagaddod/react/styles';
import { ThemeProvider } from '@tagaddod/react';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <ThemeProvider defaultTheme="tagaddod">
    <App />
  </ThemeProvider>
);

🔧 TypeScript Support

Full TypeScript support is included out of the box:

import { ButtonProps, TextInputProps } from '@tagaddod/react';

interface MyComponentProps {
  primaryButton: ButtonProps;
  emailInput: TextInputProps;
}

function MyComponent({ primaryButton, emailInput }: MyComponentProps) {
  return (
    <div>
      <TextInput {...emailInput} />
      <Button {...primaryButton} />
    </div>
  );
}

🌐 Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

🛠️ Design Token Management

This package is part of a comprehensive design system with advanced token management:

Live Token Editing: Use the Storybook token sandbox for real-time experimentation
Admin UI: Manage tokens through the dedicated admin interface with validation
GitHub Integration: Automatic sync with Figma via Tokens Studio
W3C Compliance: All tokens follow W3C Design Token Community Group standards
Multi-Brand Support: Easy theme switching for different brands

Token Usage in Components

// Tokens are automatically available as CSS variables with --t- prefix
const customStyles = {
  backgroundColor: 'var(--t-color-surface-primary)',
  padding: 'var(--t-space-400)',
  borderRadius: 'var(--t-border-radius-200)'
};

📚 Documentation

Storybook Documentation - Interactive component examples
LLM Agent Documentation - AI-friendly API reference
GitHub Repository - Source code and issues
Design Tokens - Token definitions and build process

🤝 Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

📄 License

MIT License - see LICENSE for details.

Made with ❤️ by the Tagaddod Design System Team

This package includes specialized documentation for AI coding agents. The llms.txt file provides structured information to help LLMs understand and use the component library effectively.