@eco-ds/eco-design-system

A comprehensive React component library built with shadcn/ui, featuring 40+ UI components with TypeScript support and modern design patterns.

🚀 Quick Start

Installation

npm install @eco-ds/eco-design-system
# or
yarn add @eco-ds/eco-design-system
# or
pnpm add @eco-ds/eco-design-system

Usage

import { Button, Card, Input, Badge } from '@eco-ds/eco-design-system';

function App() {
  return (
    <div>
      <Card>
        <CardHeader>
          <CardTitle>Welcome</CardTitle>
        </CardHeader>
        <CardContent>
          <Input placeholder="Enter your name" />
          <Button>Submit</Button>
        </CardContent>
      </Card>
    </div>
  );
}

📦 What's Included

UI Components (40+ components)

• Layout: Card, Separator, AspectRatio, Resizable
• Forms: Input, Textarea, Select, Checkbox, RadioGroup, Switch, Slider
• Navigation: Button, Tabs, Pagination, Breadcrumb, NavigationMenu
• Feedback: Alert, Dialog, Popover, Tooltip, Toast
• Data Display: Table, Badge, Avatar, Progress, Skeleton
• Overlay: Modal, Drawer, Sheet, HoverCard
• Interactive: Accordion, Collapsible, Command, ContextMenu, DropdownMenu

Features

• ✅ TypeScript Support - Full type definitions included
• ✅ Modern React - Built with React 18+ and modern patterns
• ✅ Accessible - Following ARIA guidelines and best practices
• ✅ Customizable - Easy theming with CSS variables
• ✅ Tree-shakeable - Only import what you need
• ✅ No CSS-in-JS - Uses CSS variables for theming

🎨 Theming

The package includes a comprehensive theme system with CSS variables:

:root {
  --background: #ffffff;
  --foreground: #1A1A1F;
  --primary: #007BD9;
  --primary-foreground: #ffffff;
  /* ... and many more */
}

🔧 Requirements

• React 18.0.0 or higher
• React DOM 18.0.0 or higher
• Next.js 13.0.0 or higher (if using Next.js)

📚 Documentation

For detailed component documentation and examples, visit our Storybook.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE for details.

🏗️ Development

This package is built from the eco-design-system-2 repository.

Local Development

git clone https://github.com/eco-ds/eco-design-system-2.git
cd eco-design-system-2
pnpm install
pnpm dev

Building the Package

pnpm run build:lib

Deploy Your Own

You can deploy your own version of the Next.js Registry Starter to Vercel with one click:

Open in v0

This registry application also exposes Open in v0 buttons for each component. Once this application is deployed, the Open in v0 button redirects to v0.dev with a prepopulated prompt and a URL pointing back to this registry's /r/${component_name}.json endpoint. This endpoint will provide v0 the necessary file information, content, and metadata to start your v0 chat with your component, theme, and other related code.

These /r/${component_name}.json files are generated using shadcn/ui during the build and dev based on the repository's registry.json. For more information, refer to the documentation.

Theming

To use a custom theme for all the components, all you need to do is modify the CSS tokens in globals.css. More information on these practices can be found on ui.shadcn.com/docs.

🎯 Important: Keeping Your Design System Updated

When you make UI changes (colors, fonts, design tokens), you need to update both files to ensure consistency:

1. src/app/globals.css - for your local development
2. registry.json - for the registry system and external tools

Always run this command after any UI changes:

npm run registry:build

This ensures that v0, Cursor, and other tools see your latest design system updates.

Complete Workflow for UI Changes

Step 1: Make Your Changes

# Edit design tokens
code src/app/globals.css

# Edit registry configuration
code registry.json

Step 2: Update Both Files

• ✅ Update globals.css with new colors/fonts
• ✅ Update registry.json cssVars section to match
• ✅ Keep both files in sync

Step 3: Rebuild & Deploy

npm run registry:build  # Regenerates all registry files
npm run build          # Builds your application

What to Update When

| Change Type | Files to Update | Command to Run | |-------------|----------------|----------------| | Colors & Design Tokens | globals.css + registry.json | npm run registry:build | | Fonts | layout.tsx + globals.css | npm run registry:build | | Components | Component files | npm run registry:build | | Layouts & Pages | Layout/page files | npm run registry:build |

Common Pitfalls to Avoid

❌ Don't:

• Only update globals.css without rebuilding registry
• Only update registry.json without updating globals.css
• Forget to run npm run registry:build after changes
• Deploy without rebuilding registry

✅ Do:

• Keep both files in sync
• Always rebuild after changes
• Test locally before deploying
• Use consistent naming conventions

Testing Your Changes

# Local testing
npm run dev
# Check your app locally, toggle themes, verify colors

# Registry testing
npm run registry:build
# Visit registry page, check theme toggle, verify component previews

# v0 integration testing
# Use "Open in v0" buttons, verify new colors are applied

MCP Integration

To use this registry with MCP, you must also edit registry.json's first registry-item named theme. This registry:theme item not only contains the tailwind configuration, but it also contains your design tokens / CSS variables.

The shadcn/ui CLI's MCP command will use the entire registry.json file, so it must be put in the /public folder with all of your registry:items. This will enable you to use your registry in tools like Cursor & Windsurf.

Fonts

To use custom fonts, you can either use next/font/google or the @font-face CSS rule in your globals.css.

@font-face {
    font-family: 'Montserrat';
    font-style: normal;
    font-weight: 400;
    src: url('https://fonts.gstatic.com/s/montserrat/v15/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.woff2') format('woff2'),
    url('https://fonts.gstatic.com/s/montserrat/v15/JTUSjIg1_i6t8kCHKm45xW5rygbj49c.woff') format('woff');
}

If you use @font-face, ensure you modify globals.css tailwind configuration to map your custom font variables to Tailwind fonts. Refer to this Tailwind documentation

For Team Development

• Communication: Document design system changes, share registry links for reviews
• Version Control: Commit both files together, use descriptive commit messages
• Consistency: Use CSS variables for all colors, maintain clear naming conventions
• Accessibility: Ensure sufficient contrast ratios, test both themes

Running locally

pnpm install
pnpm dev

Your app should now be running on localhost:3000.

File Structure

app/(registry) routes contains the registry pages.

app/demo routes contains various UI primitives, Components, or Blocks (based on registry.json)

@/components contains all components used in the registry

@/components/ui contains all shadcn/ui UI Primitives used in the registry

@/components/registry contains all components for this Registry Starter application

@/hooks contains all React hooks

@/lib contains all business logic & utils

@/layouts contains all v0 layouts used in registry.json