MCR Design Systems

A React component library built with TypeScript, Vite, and Tailwind CSS V4.

Goal

Build design system for mcbr web app for the support tool and web app

Prerequisites

Before running this project, make sure you have the following installed:

• Node.js (version 16 or higher)
• npm or yarn package manager
• Git (for cloning the repository)

Installation

1. Clone the repository:

git clone <repository-url>
cd mcbr-design-system

2. Install dependencies:

npm install
# or
yarn install

Running the Project

Development Mode

To start the development server with hot reload:

Test UI at localhost:

# or
yarn dev

Building the Project

To build the project for production at the library:

# or
yarn build

To implement the link library to use at local source Open another terminal run your fe source

cd "source/name-source-fe"
yarn link "project-name"

Thess command will:

• Build source code
• Go to your local front-end source code
• Stay at your local source and link to the library "mcr-design-systems" you have built

Building Library Only

To build only the library components:

yarn build

Preview Production Build

To preview the production build locally:

yarn preview

Code Quality

Linting

To check for code quality issues:

yarn lint

Publishing to NPM

This project includes an automated publishing script that handles version management, building, and publishing to npm.

Prerequisites for Publishing

Before using the publishing script, ensure you have:

1. NPM Authentication: You must be logged into npm with publishing rights

   npm login

2. Clean Working Directory: All changes must be committed to git

3. Correct Branch: Should be on main or master branch (script will warn if not)

4. Node.js and npm: Must be installed and working

5. Git Repository: Must be initialized and connected to a remote

Using the Publishing Script

The publish.sh script automates the entire publishing process:

# Increment patch version (1.0.0 → 1.0.1) - Default
./publish.sh

# Increment minor version (1.0.0 → 1.1.0)
./publish.sh minor

# Increment major version (1.0.0 → 2.0.0)
./publish.sh major

# Set specific version
./publish.sh 1.5.0

What the Script Does

The publishing script performs these steps automatically:

1. Safety Checks:

   • Verifies npm authentication
   • Checks for clean working directory
   • Confirms you're on the correct branch
   • Validates all dependencies are installed

2. Quality Assurance:

   • Runs linting (if available)
   • Builds the library (yarn build-lib)
   • Ensures build completes successfully

3. Version Management:

   • Increments version in package.json
   • Shows current → new version for confirmation

4. Git Operations:

   • Commits version changes with standard message
   • Creates git tag with new version
   • Pushes changes and tags to remote repository

5. NPM Publishing:

   • Publishes package to npm registry
   • Shows success confirmation with package URL

Manual Publishing (Alternative)

If you prefer to publish manually:

# 1. Build the library
yarn build-lib

# 2. Increment version
npm version patch  # or minor/major

# 3. Commit and tag (if not done by npm version)
git push origin main --tags

# 4. Publish to npm
npm publish

Publishing Best Practices

• Test thoroughly before publishing
• Use semantic versioning:
  • patch: Bug fixes (1.0.0 → 1.0.1)
  • minor: New features, backward compatible (1.0.0 → 1.1.0)
  • major: Breaking changes (1.0.0 → 2.0.0)
• Write clear commit messages
• Update documentation when adding new features
• Announce releases to your team

Troubleshooting Publishing

"Not logged into npm":

npm login
npm whoami  # Verify login

"Working directory not clean":

git status          # Check what files are modified
git add .           # Stage changes
git commit -m "..."  # Commit changes

"Publishing failed":

• Check if version already exists on npm
• Verify package name is available
• Ensure you have publishing rights
• Check npm registry status

Script permission denied:

chmod +x publish.sh

Library Usage

Installation

Install the library in your project:

npm install mcr-design-system
# or
yarn add mcr-design-system

Setup with Tailwind CSS v4

For projects using Tailwind CSS v4 (recommended):

1. Install Tailwind CSS v4:

npm install tailwindcss@next @tailwindcss/vite
# or
yarn add tailwindcss@next @tailwindcss/vite

2. Configure Vite to use the Tailwind plugin (vite.config.ts):

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),
    },
  },
});

3. Create your tailwind.config.js using the design system generator:

import { generateTailwindConfig } from 'mcr-design-system';

/** @type {import('tailwindcss').Config} */
export default generateTailwindConfig();

4. Import Tailwind and configure in your main CSS file:

@import 'tailwindcss';
@config '../tailwind.config.js';

/* Optional: Add any custom styles */

5. Wrap your app with the ThemeProvider:

import { ThemeProvider } from 'mcr-design-system';

function App() {
  return <ThemeProvider>{/* Your app content */}</ThemeProvider>;
}

Setup with Tailwind CSS v3

For projects using Tailwind CSS v3:

1. Install Tailwind CSS v3:

npm install -D tailwindcss postcss autoprefixer
# or
yarn add -D tailwindcss postcss autoprefixer

2. Create/update your tailwind.config.js:

import { generateTailwindConfig } from 'mcr-design-system';

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/mcr-design-system/dist/**/*.{js,ts,jsx,tsx}',
  ],
  ...generateTailwindConfig(), // Spreads design system tokens and configuration
};

3. Configure PostCSS (postcss.config.js):

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

4. Import Tailwind in your main CSS file:

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

5. Wrap your app with the ThemeProvider:

import { ThemeProvider } from 'mcr-design-system';

function App() {
  return <ThemeProvider>{/* Your app content */}</ThemeProvider>;
}

Using Components

Import and use components in your React application:

import { Button, Alert, Typography, Badge } from 'mcr-design-system';

function MyComponent() {
  return (
    <div>
      <Typography variant="h1">Welcome</Typography>
      <Button variant="primary" size="lg">
        Click me
      </Button>
      <Alert variant="success">Operation completed successfully!</Alert>
      <Badge variant="info">New</Badge>
    </div>
  );
}

TypeScript Support

The library includes full TypeScript support. Import types as needed:

import type { ButtonProps, AlertVariant } from 'mcr-design-system';

interface MyComponentProps {
  buttonProps: ButtonProps;
  alertType: AlertVariant;
}

Design Token Access

Access design tokens programmatically:

import { useTheme } from 'mcr-design-system';

function MyComponent() {
  const theme = useTheme();

  return (
    <div
      style={{
        backgroundColor: theme.colors.bg.surface.level1,
        color: theme.colors.fg.neutral.main,
      }}
    >
      Custom styled content
    </div>
  );
}

Project Structure

src/
├── App.tsx                        # Main application component
├── main.tsx                       # Application entry point
├── index.css                      # Global styles
├── lib/                           # Library components
│   ├── components/                # React components
│   │   └── [ComponentName]/
│   │       ├── index.tsx          # Component implementation
│   │       └── helper/            # Component-specific utilities
│   └── shared/                    # Shared utilities
│       ├── icons/                 # Icon components
│       └── utils/                 # Utility functions
├────── tokens/                    # Design system tokens
        ├── index.ts               # Token system exports
        ├── context.ts             # React context for tokens
        ├── hooks.ts               # Custom hooks for token access
        ├── semantic.ts            # Semantic token definitions
        ├── tailwind-config.ts     # Tailwind configuration
        ├── theme.tsx              # Theme provider component
        ├── utils.ts               # Token utility functions
        └── primitives/            # Core design tokens
            ├── index.ts           # Primitive token exports
            ├── colors.ts          # Color palette definitions
            ├── typography.ts      # Font, size, weight definitions
            └── layout.ts          # Spacing, sizing definitions

Design Token Usage

Token Workflow

1. Export tokens from Figma as JSON → tools/tokenVariant.json
2. Run: node tools/convert-token.js to update semantic tokens
3. Use semantic tokens in components via Tailwind classes

Token Usage Patterns

• Colors: bg-bg-surface-level-1, text-neutral-main
• Borders: Use border-neutral (not border-neutral-100 or border-border-neutral)
• Spacing: Use semantic tokens like p-sm-2, m-md (not p-3, m-4)

Component Styling Conventions

• Use tv() from tailwind-variants for component variants (not conditional classNames)
• Use cn() utility for className concatenation
• Use dataTestId() for consistent test selectors
• Use @app/ alias for internal imports

Development Guidelines

1. Components: All reusable components should be placed in src/lib/components/
2. Styling: Use Tailwind CSS with semantic design tokens for styling components
3. TypeScript: Maintain type safety across all components
4. Design Tokens: Always use semantic tokens instead of hardcoded values
5. Testing: Run linting before committing changes

Publishing

To publish the library: (TO BE DETERMINE)

npm run publish-lib
# or
yarn publish-lib

Note: This will automatically run the build process before publishing.

Dependencies

Main Dependencies

• React 19.x
• React DOM 19.x
• Tailwind CSS 4.x (for development)
• TypeScript 5.x
• Vite 7.x

Peer Dependencies (Required in consuming projects)

• React: ^18.0.0 || ^19.0.0
• React DOM: ^18.0.0 || ^19.0.0
• Tailwind CSS: ^3.0.0 || ^4.0.0-next

Development Tools

• ESLint for code linting
• Husky for git hooks
• Vite Plugin DTS for TypeScript declarations
• Tailwind Variants for component styling
• Class Variance Authority for type-safe variants

Tailwind CSS Compatibility

| Tailwind Version | Support Status | Setup Method | | ---------------- | ---------------- | ------------------------- | | v4.x (Next) | ✅ Recommended | Vite plugin + CSS imports | | v3.x | ✅ Supported | PostCSS + config merge | | v2.x | ❌ Not supported | - |

Browser Support

This project supports modern browsers that are compatible with React 18+ and ES2020+ features.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run yarn lint to ensure code quality
5. Submit a pull request

Troubleshooting

Common Issues

1. Port already in use: If port 5173 is busy, Vite will automatically use the next available port
2. Node version: Ensure you're using Node.js version 16 or higher
3. Dependencies: Delete node_modules and package-lock.json, then run yarn install if you encounter dependency issues

Tailwind CSS Issues

Styles not applying in consuming project

For Tailwind v4:

• Ensure your tailwind.config.js uses generateTailwindConfig() from the design system
• Verify Vite configuration includes @tailwindcss/vite plugin
• Check that your CSS imports @import 'tailwindcss'; and @config '../tailwind.config.js';
• Verify ThemeProvider wraps your app

For Tailwind v3:

• Verify tailwind.config.js includes the design system path in content array
• Ensure generateTailwindConfig() is spread in your config: ...generateTailwindConfig()
• Check PostCSS configuration is correct
• Verify standard Tailwind imports: @tailwind base;, @tailwind components;, @tailwind utilities;

Design tokens not working

1. Verify ThemeProvider is wrapping your application
2. Check console for token loading errors
3. Ensure proper CSS imports are in place

Version conflicts

If you encounter version conflicts between Tailwind v3 and v4:

# Clear node_modules and lock files
rm -rf node_modules package-lock.json yarn.lock
# Reinstall with specific Tailwind version
npm install tailwindcss@^3.4.0  # for v3
# or
npm install tailwindcss@next    # for v4

Getting Help

If you encounter issues:

1. Check the console for error messages
2. Ensure all dependencies are properly installed
3. Verify Node.js version compatibility
4. Check the Vite documentation for additional configuration options
5. Review Tailwind CSS documentation for version-specific setup