Syncrofy Design System

A comprehensive design system based on Material UI (MUI) with React and TypeScript, following atomic design principles.

Features

• 🎨 Custom Theming: Extended MUI theme with custom colors, typography, and component overrides
• ⚛️ Atomic Design: Components organized into Atoms, Molecules, and Organisms
• 📦 TypeScript: Full type safety with exported prop types
• 🎯 Tree-shakeable: Barrel exports for optimal bundle size
• 🔧 Extensible: Easy to customize and extend

Installation

npm install

Development

npm run dev

Build

npm run build

This builds the library package for npm publishing, generating:

• dist/index.js - Main entry point
• dist/components.js - Components-only export
• dist/theme.js - Theme-only export
• TypeScript declaration files (.d.ts)

Publishing to npm

This package is published as @syncrofy/design-system on npm.

Prerequisites

1. Ensure you have an npm account with access to publish @syncrofy/design-system
2. Set up an npm token as a GitHub secret named NPM_TOKEN in the repository settings

Publishing a New Version

1. Make your changes to components, theme, or other design system code
2. Test locally:

   npm run build        # Verify build works
   npm run storybook    # Test in Storybook

3. Commit your changes:

   git add .
   git commit -m "Description of changes"
   git push origin main

4. Bump version and create tag:

   npm version patch    # for bug fixes (1.0.0 -> 1.0.1)
   npm version minor    # for new features (1.0.0 -> 1.1.0)
   npm version major    # for breaking changes (1.0.0 -> 2.0.0)

   This automatically:
   • Updates version in package.json
   • Creates a git commit with version change
   • Creates a git tag (e.g., v1.0.1)
5. Push version tag:

   git push origin main
   git push origin --tags

6. GitHub Actions automatically publishes:
   • Detects the version tag
   • Builds the package
   • Runs type checks
   • Publishes to npm
   • Usually takes 2-5 minutes

The package will be available on npm within a few minutes. Check publication status:

npm view @syncrofy/design-system version

Local Development with npm link

To test the package locally in another project before publishing:

# In syncrofy-ds
npm run build
npm link

# In your other project
npm link @syncrofy/design-system

See the workflow documentation below for more details.

Testing

Unit Tests

npm test

UI Tests

npm run test:ui

Testing Options

1. Browser-Based Visual Testing (Recommended)

Run visual tests directly in your browser with interactive feedback:

npm run test:browser

Or use the browser UI for a visual test runner:

npm run test:browser:ui

2. Terminal-Based Visual Regression Tests

The design system includes visual regression testing using Playwright to ensure components maintain their visual appearance across changes.

Setup:

1. Start Storybook (required for visual tests):

npm run storybook

2. In another terminal, run visual regression tests:

npm run test:visual

Updating Baselines: When you intentionally change component appearance, update the visual baselines:

npm run test:visual:update

3. Chromatic Visual Testing

For cloud-based visual testing with team collaboration:

npx chromatic --project-token=YOUR_PROJECT_TOKEN

Current Baselines

• Button component variants (Primary, Secondary, Outlined, Text, Small, Medium, Large, Disabled, Full Width)
• Baselines are stored in tests/visual-regression/__screenshots__/
• Your original Button.png screenshot serves as the primary baseline

Adding Screenshots for New Components

1. Add your desired screenshot to the screenshots/ folder
2. Create visual regression tests in tests/visual-regression/
3. Copy screenshots to the __screenshots__ directory as baselines

Component Structure

Atoms (20 components)

Base building blocks of the design system:

• Avatar
• Badge
• Breadcrumbs
• Button
• Checkbox
• Chips
• Date Picker
• Divider
• Icon
• Icon Button
• Input
• Link
• Logo
• Password Input
• Radio
• Search
• Slot
• Spinner
• Toggle
• Tooltip

Molecules (8 components)

Composite components built from atoms:

• Button Group
• Dropdown
• List Item
• Segmented Control
• Snack Bar
• Stepper
• Tabs
• Typeahead

Organisms (6 components)

Complex components built from molecules and atoms:

• Accordion
• Modal
• Navigation (Side Nav)
• Navigation (Top Nav / App Bar)
• Pagination
• Table

Usage

Basic Setup

import { ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';
import { theme } from '@/components';

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

Using Components

import { Button, Input, Modal, Table } from '@/components';

function MyComponent() {
  return (
    <>
      <Button variant="contained" color="primary">
        Click me
      </Button>
      <Input label="Email" />
      <Modal open={true} title="Example Modal">
        Content here
      </Modal>
    </>
  );
}

Importing from Specific Categories

// Import from atoms only
import { Button, Input } from '@/components/atoms';

// Import from molecules only
import { Dropdown, Tabs } from '@/components/molecules';

// Import from organisms only
import { Modal, Table } from '@/components/organisms';

Theme Customization

The theme extends MUI's default theme and includes:

• Custom Palette: Based on design system color (#89C3E1)
• Typography Scale: Custom font sizes and weights
• Component Overrides: Pre-styled components with consistent spacing and borders
• Spacing: 8px base unit

Customizing the Theme

import { theme } from '@/components';
import { createTheme } from '@mui/material/styles';

const customTheme = createTheme({
  ...theme,
  palette: {
    ...theme.palette,
    primary: {
      main: '#YOUR_COLOR',
    },
  },
});

TypeScript Support

All components export their prop types for full TypeScript support:

import { Button, ButtonProps } from '@/components';

const buttonProps: ButtonProps = {
  variant: 'contained',
  color: 'primary',
  children: 'Click me',
};

<Button {...buttonProps} />;

Path Aliases

The project uses path aliases for cleaner imports:

• @/ - Points to src/
• @/components - All components
• @/theme - Theme configuration
• @/types - Type definitions

Dependencies

• React 18+
• Material UI v7
• TypeScript 5+
• Emotion (for CSS-in-JS)

<<<<<<< HEAD

MCP Server

The design system includes an MCP (Model Context Protocol) server that provides AI tools with access to component information, code generation, and migration assistance.

Setup

1. Install MCP server dependencies:

cd mcp-server
npm install
npm run build

2. Configure your AI tool (e.g., Cursor) to use the MCP server. Add to your MCP configuration:

{
  "mcpServers": {
    "syncrofy-design-system": {
      "command": "node",
      "args": ["/path/to/syncrofy-ds/mcp-server/dist/index.js"]
    }
  }
}

MCP Resources

The server exposes the following resources:

• Component Information: component://ComponentName - Get detailed info about any component
• Category Lists: components://atoms, components://molecules, components://organisms
• Migration Guides: migration://MUIComponentName - Get migration guide from MUI to design system

MCP Tools

• get_component_info: Get detailed information about a design system component
• search_components: Search for components by name, category, or use case
• generate_component_code: Generate code snippets using design system components
• migrate_mui_code: Convert Material UI code to use design system components

Usage Example

// Get component information
const buttonInfo = await mcp.getResource('component://Button');

// Generate code
const code = await mcp.callTool('generate_component_code', {
  componentName: 'Button',
  props: { variant: 'contained', color: 'primary' },
  useCase: 'Submit button in a form'
});

// Migrate MUI code
const migrated = await mcp.callTool('migrate_mui_code', {
  code: `import { Button } from '@mui/material';`
});

Publishing Workflow

Daily Development Workflow

Viewing Changes Locally

Viewing Design System Changes in Storybook:

npm run storybook  # Runs on http://localhost:6006

Using npm link for Local Testing

To test design system changes in another project (like prototypes) without publishing:

In syncrofy-ds:

npm run build  # Build the design system
npm link       # Create a global symlink

In your consuming project (e.g., syncrofy-prototypes):

npm link @syncrofy/design-system  # Link to local build
npm run dev  # Start dev server to see changes

To unlink when done:

npm unlink @syncrofy/design-system
npm install  # Restore npm package

Syncing Changes Locally

1. Make changes in syncrofy-ds
2. Build: npm run build
3. If using npm link, changes are automatically reflected when you rebuild
4. Test in consuming project

Publishing Changes

1. Test locally (Storybook + build)
2. Commit changes: git commit -m "Description"
3. Push: git push origin main
4. Bump version: npm version patch|minor|major
5. Push tag: git push origin main && git push origin --tags
6. GitHub Actions publishes automatically

For more detailed workflow documentation, see docs/PUBLISHING_WORKFLOW.md.

Migration Guide

See docs/MIGRATION_GUIDE.md for a comprehensive guide on migrating from Material UI to the Syncrofy Design System.

License

ISC