Taaw Design System

A modern, reusable design system built with shadcn/ui and Tailwind CSS by Ahmed Tawfik

📦 Installation

npm install @ahmed.tawfik.galal/my-design-system

🚀 Quick Start

1. Install Tailwind CSS (if not already installed)

npm install -D tailwindcss
npx tailwindcss init

2. Configure Tailwind

Update your tailwind.config.js:

const taawConfig = require('@ahmed.tawfik.galal/my-design-system/tailwind.config');

module.exports = {
  presets: [taawConfig],
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@ahmed.tawfik.galal/my-design-system/**/*.{js,jsx}',
  ],
}

3. Import Components

import { Button, Card, Input } from '@ahmed.tawfik.galal/my-design-system';

function App() {
  return (
    <div className="p-8">
      <Button variant="primary">Get Started</Button>
      <Card title="Welcome">
        This is the Taaw Design System
      </Card>
    </div>
  );
}

🎨 Design Tokens

Colors

This design system uses a carefully crafted color palette optimized for modern web applications.

| Token | Hex Value | Usage | Tailwind Class | |-------|-----------|-------|----------------| | Primary | #3B82F6 | Main brand color, primary CTAs | bg-primary, text-primary, border-primary | | Primary Light | #60A5FA | Hover states, lighter accents | bg-primary-light | | Primary Dark | #2563EB | Active states, pressed buttons | bg-primary-dark | | Secondary | #8B5CF6 | Accent color, secondary actions | bg-secondary, text-secondary | | Secondary Light | #A78BFA | Hover states | bg-secondary-light | | Secondary Dark | #7C3AED | Active states | bg-secondary-dark | | Success | #10B981 | Success messages, positive actions | bg-success, text-success | | Error | #EF4444 | Error states, destructive actions | bg-error, text-error | | Warning | #F59E0B | Warning messages, caution states | bg-warning, text-warning |

Neutral Colors (Grays):

| Token | Hex Value | Usage | |-------|-----------|-------| | Neutral 50 | #F9FAFB | Light backgrounds | | Neutral 100 | #F3F4F6 | Subtle backgrounds | | Neutral 200 | #E5E7EB | Borders, dividers | | Neutral 300 | #D1D5DB | Disabled states | | Neutral 400 | #9CA3AF | Placeholder text | | Neutral 500 | #6B7280 | Secondary text | | Neutral 700 | #374151 | Primary text | | Neutral 900 | #111827 | Headings, emphasis |

Example usage:

<div className="bg-primary text-white p-6 rounded-lg">
  Primary colored box
</div>

<p className="text-neutral-700">
  Body text in neutral gray
</p>

Spacing Scale

A harmonious spacing scale based on 4px increments.

| Token | Value | Usage | Tailwind Class | |-------|-------|-------|----------------| | 0 | 0px | No spacing | p-0, m-0 | | 1 | 4px | Tiny gaps, tight spacing | p-1, gap-1 | | 2 | 8px | Small spacing, compact layouts | p-2, m-2 | | 3 | 12px | Small-medium spacing | p-3 | | 4 | 16px | Default spacing, comfortable layouts | p-4, m-4 | | 5 | 20px | Medium spacing | p-5 | | 6 | 24px | Large spacing, section padding | p-6 | | 8 | 32px | Extra large spacing | p-8 | | 10 | 40px | Very large spacing | p-10 | | 12 | 48px | Section separators | p-12 | | 16 | 64px | Major section spacing | p-16 |

Example usage:

<div className="p-6 m-4 gap-2">
  <!-- Padding: 24px, Margin: 16px, Gap: 8px -->
</div>

Typography

Font Family:

• Default: Inter (optimized for UI)
• Headings: Poppins (optional, for emphasis)

Font Sizes:

| Size | Value | Usage | Tailwind Class | |------|-------|-------|----------------| | XS | 12px | Small labels, captions | text-xs | | SM | 14px | Secondary text | text-sm | | Base | 16px | Body text (default) | text-base | | LG | 18px | Emphasized text | text-lg | | XL | 20px | Small headings | text-xl | | 2XL | 24px | Section headings | text-2xl | | 3XL | 30px | Page headings | text-3xl | | 4XL | 36px | Large headings | text-4xl | | 5XL | 48px | Hero text, main titles | text-5xl |

Example usage:

<h1 className="text-4xl font-bold text-neutral-900">
  Welcome to Taaw Design System
</h1>
<p className="text-base text-neutral-700">
  Build beautiful interfaces faster
</p>

Border Radius

| Size | Value | Usage | Tailwind Class | |------|-------|-------|----------------| | None | 0px | Sharp corners | rounded-none | | SM | 4px | Subtle roundness | rounded-sm | | Default/MD | 8px | Default for most components | rounded, rounded-md | | LG | 12px | Cards, larger containers | rounded-lg | | XL | 16px | Very rounded | rounded-xl | | Full | 9999px | Pills, circles, avatars | rounded-full |

🧩 Components

Button

A customizable button component with multiple variants and sizes.

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | variant | 'primary' \| 'secondary' \| 'outline' \| 'ghost' | 'primary' | Visual style variant | | size | 'sm' \| 'md' \| 'lg' | 'md' | Button size | | disabled | boolean | false | Disabled state | | onClick | function | undefined | Click handler | | className | string | '' | Additional CSS classes | | children | ReactNode | required | Button content |

Examples:

import { Button } from '@ahmed.tawfik.galal/my-design-system';

// Primary button (default)
<Button variant="primary">Get Started</Button>

// Secondary button
<Button variant="secondary">Learn More</Button>

// Outline button (transparent with border)
<Button variant="outline">View Details</Button>

// Ghost button (minimal style)
<Button variant="ghost">Cancel</Button>

// Different sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

// Disabled state
<Button disabled>Cannot Click</Button>

// With click handler
<Button onClick={() => alert('Clicked!')}>
  Click Me
</Button>

// Custom styling
<Button className="w-full">
  Full Width Button
</Button>

Visual Guide:

| Variant | Appearance | |---------|-----------| | Primary | Solid blue background, white text, shadow | | Secondary | Solid purple background, white text, shadow | | Outline | Transparent, blue border, blue text | | Ghost | Transparent, subtle hover effect |

Card

A container component for grouping related content with elegant styling.

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | title | string | undefined | Optional heading at the top | | variant | 'default' \| 'elevated' \| 'outlined' \| 'flat' | 'default' | Card style variant | | className | string | '' | Additional CSS classes | | children | ReactNode | required | Card content |

Examples:

import { Card } from '@ahmed.tawfik.galal/my-design-system';

// Simple card with content
<Card>
  <p>This is a basic card with some content inside.</p>
</Card>

// Card with title
<Card title="Feature Name">
  <p>Description of the feature goes here.</p>
  <ul>
    <li>Benefit 1</li>
    <li>Benefit 2</li>
  </ul>
</Card>

// Elevated card (more shadow)
<Card variant="elevated" title="Premium Feature">
  <p>This card stands out with extra elevation.</p>
</Card>

// Outlined card (minimal)
<Card variant="outlined" title="Clean Design">
  <p>Border-focused design without shadow.</p>
</Card>

// Flat card (no shadow or border)
<Card variant="flat">
  <p>Minimal styling for subtle backgrounds.</p>
</Card>

// Custom styling
<Card title="Custom Card" className="max-w-md mx-auto">
  <p>Centered card with max width.</p>
</Card>

Visual Guide:

| Variant | Style Description | |---------|------------------| | Default | White background, medium shadow, subtle border | | Elevated | White background, large shadow, no border | | Outlined | White background, prominent border, no shadow | | Flat | Light gray background, no shadow or border |

Input

A text input component with label, error states, and helper text support.

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | label | string | undefined | Label text above input | | type | string | 'text' | HTML input type | | placeholder | string | undefined | Placeholder text | | error | string | undefined | Error message to display | | helperText | string | undefined | Helper text below input | | required | boolean | false | Show required indicator (*) | | disabled | boolean | false | Disable the input | | className | string | '' | Additional CSS classes |

Examples:

import { Input } from '@ahmed.tawfik.galal/my-design-system';

// Basic input
<Input placeholder="Enter your name" />

// Input with label
<Input 
  label="Email Address" 
  type="email" 
  placeholder="[email protected]"
/>

// Required field (shows red asterisk)
<Input 
  label="Password" 
  type="password" 
  required 
  placeholder="Enter password"
/>

// Input with error message
<Input 
  label="Email" 
  type="email" 
  error="Please enter a valid email address"
  value="invalid-email"
/>

// Input with helper text
<Input 
  label="Username" 
  helperText="Choose a unique username (3-20 characters)"
  placeholder="johndoe"
/>

// Disabled input
<Input 
  label="Account ID" 
  value="12345" 
  disabled
/>

// Full example with all features
<Input
  label="Full Name"
  type="text"
  placeholder="John Doe"
  helperText="Enter your first and last name"
  required
/>

Visual States:

| State | Appearance | |-------|-----------| | Normal | Gray border, white background | | Focus | Blue border with subtle blue ring | | Error | Red border with red ring, error text below | | Disabled | Gray background, cannot interact | | With Helper | Small gray text below input |

📖 Usage with AI Tools (Lovable)

This design system is optimized for AI-powered development tools like Lovable.

Installation prompt for Lovable:

Install the Taaw Design System:

npm install @ahmed.tawfik.galal/my-design-system

Configure Tailwind to use the design system:

const taawConfig = require('@ahmed.tawfik.galal/my-design-system/tailwind.config');

module.exports = {
  presets: [taawConfig],
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@ahmed.tawfik.galal/my-design-system/**/*.{js,jsx}',
  ],
}

Import and use components:

import { Button, Card, Input } from '@ahmed.tawfik.galal/my-design-system';

🛠️ Development

Local Testing

To test this package locally before publishing:

# In the package directory
npm link

# In your test project
npm link @ahmed.tawfik.galal/my-design-system

Adding New Components

1. Create component file in components/ui/
2. Export from src/index.js
3. Document in README
4. Update version in package.json
5. Publish update

📝 Changelog

Version 1.0.0 (Initial Release)

• ✅ Button component with 4 variants
• ✅ Card component with 4 variants
• ✅ Input component with error states
• ✅ Complete Tailwind configuration
• ✅ Design tokens (colors, spacing, typography)

📄 License

MIT © Ahmed Tawfik Galal

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

• Issues: GitHub Issues
• Pull Requests: Fork the repo and submit PRs

📞 Support

• NPM Package: https://www.npmjs.com/package/@ahmed.tawfik.galal/my-design-system
• Author: Ahmed Tawfik Galal
• Email: [email protected]
• GitHub: https://github.com/ahmedtaaw

🙏 Acknowledgments

Built with:

• Tailwind CSS
• shadcn/ui
• React

Made with ❤️ by Ahmed Tawfik

#### What this README provides

✅ **Complete installation instructions**
✅ **All your design tokens documented**
✅ **Every component with usage examples**
✅ **Tailwind class reference**
✅ **AI tool integration guide**
✅ **Professional formatting**
✅ **Your contact information**
✅ **License information**

#### Save the file

---

### Step 4: Create .npmignore File

**Purpose:** Tell NPM what files NOT to publish.

#### Create the file

In `my-design-system` folder, create `.npmignore`

**Important:** The filename starts with a dot (`.`)

#### Copy this template

Development files

node_modules/ .log npm-debug.log .DS_Store Thumbs.db

Test files

test/ tests/ tests/ *.test.js *.test.jsx *.spec.js *.spec.jsx coverage/

Development configs

.eslintrc .eslintrc.js .prettierrc .prettierrc.js .editorconfig

Editor files

.vscode/ .idea/ *.swp *.swo *~

Git files

.git/ .gitignore .gitattributes

Documentation source (keep README.md)

docs/ examples/ .github/

Build artifacts

dist/ build/ *.tgz

Personal notes

notes.md TODO.md NOTES.md scratch/

CI/CD

.travis.yml .circleci/ .github/workflows/

Misc

*.bak *.tmp

#### Understanding what this does

When you run `npm publish`, NPM will:
- ✅ **Publish:** Everything NOT in `.npmignore`
- ❌ **Skip:** Everything IN `.npmignore`

**What will be published:**
- ✅ `src/index.js`
- ✅ `components/ui/` folder
- ✅ `tailwind.config.js`
- ✅ `README.md`
- ✅ `package.json`
- ✅ `LICENSE`

**What will be skipped:**
- ❌ `node_modules/`
- ❌ Test files
- ❌ Your personal notes
- ❌ Editor settings

#### Save the file

---

### Step 5: Create LICENSE File

**Purpose:** Tell people how they can legally use your package.

#### Create the file

Create `LICENSE` (no file extension) in `my-design-system` folder.

#### Copy this MIT License

MIT License

Copyright (c) 2024 Ahmed Tawfik Galal

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

#### What MIT License means

**Simple explanation:**
- ✅ Anyone can use your package for free
- ✅ They can modify it
- ✅ They can use it commercially
- ✅ They can distribute it
- ⚠️ You're not responsible if something breaks
- ✅ They must include your copyright notice

**Mental model:** Like Creative Commons for code - free to use with attribution.

#### Save the file

---

### Step 6: Final Folder Structure Verification

Your complete package should now look **exactly** like this:

my-design-system/ ├── .npmignore ✓ ├── package.json ✓ (CORRECTED version) ├── LICENSE ✓ ├── README.md ✓ ├── src/ │ └── index.js ✓ ├── tailwind.config.js ✓ └── components/ └── ui/ ├── button.jsx ✓ ├── card.jsx ✓ └── input.jsx ✓