TCCE Design System

A React component library for the TCCE CRM applications. Provides reusable, consistent UI components built with React, TypeScript, Tailwind CSS, and styled-components.

Overview

This is a component library designed to ensure visual and functional consistency across all TCCE CRM frontend applications. It includes:

• 50+ reusable components (Button, Card, Dialog, Table, Forms, etc.)
• Design tokens (colors, typography, spacing, shadows)
• Storybook documentation for all components
• TypeScript support with full type definitions

Table of Contents

• Prerequisites
• Quick Start
• Project Structure
• Development
• Building Components
• Code Quality
• Testing Components
• Publishing
• Contributing
• Troubleshooting

Prerequisites

| Tool | Version | Notes | |------|---------|-------| | Node.js | v18+ | LTS recommended | | pnpm | v8+ | Package manager | | Docker | v20+ | Required for containerized development | | Git | Any | Version control |

Docker Network Prerequisite

If using Docker Compose, you must create the tcce-network network before starting the containers:

docker network create tcce-network

Important: Always use docker-compose.dev.yml when running with Docker Compose.

Installing pnpm

npm install -g pnpm

Quick Start

Local Development

# Clone the repository
git clone <repository-url>
cd tcce-design-system

# Install dependencies
pnpm install

# Start Storybook (recommended for development)
pnpm storybook

# OR start Vite dev server
pnpm dev

Access:

• Storybook: http://localhost:6006
• Vite Dev: http://localhost:5173

Using Docker (Recommended for Teams)

docker compose -f docker-compose.dev.yml up

Project Structure

tcce-design-system/
├── src/
│   ├── components/           # All UI components
│   │   ├── Badge/
│   │   ├── Button/
│   │   ├── Can/             # Authorization component
│   │   ├── Card/
│   │   ├── Divider/
│   │   ├── Icon/
│   │   ├── InfoLabel/
│   │   ├── Spinner/
│   │   ├── Stepper/
│   │   ├── Typography/
│   │   ├── Token/           # Design tokens showcase
│   │   ├── forms/           # Form components
│   │   │   ├── Checkbox/
│   │   │   ├── FormField/
│   │   │   ├── PinInput/
│   │   │   ├── RadioInput/
│   │   │   └── inputs/      # Input components
│   │   ├── layout/          # Layout components
│   │   ├── navigations/     # Navigation components
│   │   ├── notifications/    # Toast & notifications
│   │   ├── overlays/        # Dialog, Tooltip, etc.
│   │   └── Table/           # Data tables
│   ├── shared/
│   │   ├── hooks/           # Shared React hooks
│   │   ├── types/           # Global TypeScript types
│   │   └── utils/           # Utility functions
│   ├── globals.css          # Global styles
│   ├── tokens.css           # Design tokens CSS
│   └── main.ts              # Library entry point
├── .storybook/              # Storybook configuration
├── public/                  # Static assets (fonts, images)
├── dist/                    # Build output (generated)
├── package.json
├── vite.config.ts
├── tsconfig.json
└── eslint.config.js

Component Structure

Each component follows this pattern:

ComponentName/
├── ComponentName.tsx        # Main component
├── ComponentName.types.ts  # TypeScript interfaces
├── ComponentName.styles.ts # Styled-components styles
├── ComponentName.stories.tsx # Storybook stories
├── index.ts                # Barrel export
└── components/             # Sub-components (if needed)

Development

Available Scripts

| Command | Description | |---------|-------------| | pnpm dev | Start Vite development server | | pnpm storybook | Start Storybook (recommended) | | pnpm build | Build library for production | | pnpm build-storybook | Build static Storybook | | pnpm preview | Preview production build | | pnpm lint | Run ESLint | | pnpm lint:fix | Fix ESLint issues | | pnpm format | Format with Prettier |

Environment Variables

Create a .env file if needed (check .env.example):

# Not required for local development

Building Components

Creating a New Component

1. Create the component folder:

src/components/controls/MyComponent/

2. Create files following the pattern:

// MyComponent.types.ts
export interface MyComponentProps {
  variant?: 'primary' | 'secondary';
  // ... other props
}

// MyComponent.tsx
import type { MyComponentProps } from './MyComponent.types';
import { StyledMyComponent } from './MyComponent.styles';

export const MyComponent = ({ variant = 'primary', ...props }: MyComponentProps) => {
  return <StyledMyComponent $variant={variant} {...props} />;
};

// MyComponent.styles.ts
import styled from 'styled-components';

export const StyledMyComponent = styled.div<{ $variant: string }>`
  /* Styles using Tailwind and styled-components */
`;

// MyComponent.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { MyComponent } from './MyComponent';

const meta = {
  title: 'Controls/MyComponent',
  component: MyComponent,
  tags: ['autodocs'],
} satisfies Meta<typeof MyComponent>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    variant: 'primary',
  },
};

// index.ts
export * from './MyComponent';
export * from './MyComponent.types';

3. Export from main.ts:

// src/main.ts
export * from './components/controls/MyComponent';

4. Run Storybook to test:

pnpm storybook

Component Patterns

• Use styled-components for component-specific styles
• Use Tailwind CSS via @apply in styles
• Prefix styled-component props with $ (transient props)
• Always create TypeScript types in .types.ts files
• Create Storybook stories for documentation and testing

Code Quality

Linting & Formatting

This project uses:

• ESLint - Code linting
• Prettier - Code formatting
• TypeScript - Type safety

Running Checks

# Lint
pnpm lint

# Fix lint issues
pnpm lint:fix

# Format code
pnpm format

# Type check
pnpm build  # (includes tsc)

Pre-commit Hooks

Ensure you run these before committing:

pnpm lint:fix && pnpm format

ESLint Rules

Key rules enforced:

• React hooks dependencies must be correct
• No unused variables
• Prettier formatting required

Testing Components

Using Storybook

Storybook is the primary way to test components:

pnpm storybook

• Browse components at http://localhost:6006
• Use Controls panel to test props
• Use Actions panel to see event handlers
• Check Accessibility tab for a11y issues

Component Story Format

Write stories following CSF (Component Story Format):

// ComponentName.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { ComponentName } from './ComponentName';

const meta = {
  title: 'Category/ComponentName',
  component: ComponentName,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary'] },
  },
} satisfies Meta<typeof ComponentName>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    label: 'Click me',
  },
};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    label: 'Cancel',
  },
};

Publishing

Building for npm

# Build the library
pnpm build

# Check dist folder
ls dist/

Publish to npm

# Login to npm
npm login

# Publish
npm publish

The build outputs:

• dist/tcce-design-system-components.js (ESM)
• dist/tcce-design-system-components.umd.cjs (UMD)
• dist/tcce-design-system-components.css
• Type definitions via vite-plugin-dts

Consuming in Other Projects

# Install from npm (when published)
pnpm add tcce-design-system

# Or from local path
pnpm add ../tcce-design-system

// Usage
import { Button, Card } from 'tcce-design-system';
import 'tcce-design-system/dist/tcce-design-system-components.css';

Contributing

Workflow

1. Create a branch:

   git checkout -b feature/component-name

2. Make changes:

   • Follow component patterns
   • Add Storybook stories
   • Update types

3. Run quality checks:

   pnpm lint:fix
   pnpm format
   pnpm build

4. Commit and push:

   git add .
   git commit -m "feat: add new component"
   git push origin feature/component-name

5. Create Pull Request

Coding Standards

• Use TypeScript for everything
• Use styled-components for styling
• Use Tailwind CSS utilities via @apply
• Follow existing component patterns
• Write stories for all components
• Use transient props ($prop) in styled-components
• No comments unless absolutely necessary

Versioning

This project uses Semantic Versioning:

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

Update version in package.json before publishing.

Troubleshooting

Common Issues

Port already in use:

# Find and kill process on port 6006
lsof -i :6006
kill -9 <PID>

Dependencies issues:

rm -rf node_modules
pnpm install

Docker build fails:

docker build --no-cache -t tcce-design-system .

TypeScript errors:

# Check for type errors
npx tsc --noEmit

Getting Help

• Check Storybook docs: http://localhost:6006
• Review existing component patterns
• Contact: [email protected]

License

MIT License

Team

• Author: BizAppsTotal [email protected]
• Version: 0.3.24