Dashboard Design System

A design component library for Yuno's dashboard, built with React, TypeScript, and based on the shadcn/ui design system.

Project Description

This library provides a complete set of reusable components that follow Atomic Design principles and are aligned with Yuno's design system. All components are built on a solid foundation of shadcn/ui components and extended with specific functionalities for dashboard needs.

Motivation and Objective

The primary motivation of this design system is to be perfectly aligned with our Figma design system to facilitate AI-powered interface generation and optimize our development workflow. By maintaining strict consistency between our component library and Figma designs, we enable:

• 🤖 AI-assisted development: Seamless code generation from Figma designs
• ⚡ Accelerated development: Faster prototyping and implementation
• 🎯 Design-to-code consistency: Perfect alignment between design and implementation
• 🔄 Streamlined workflow: Reduced friction between design and development teams

Figma Design System

All components in this library must correspond exactly in name and design with the components defined in our Figma design system:

🎨 Figma Design System - shadcn UI Kit for Yuno

This Figma system is based on shadcndesign.com, ensuring industry-standard design patterns and AI compatibility.

⚠️ IMPORTANT: It is mandatory that any new component or modification follows exactly the design specifications, nomenclature, and behavior defined in Figma.

Technology Foundation

Shadcn/ui Base

This design system is primarily based on shadcn/ui, a collection of beautifully designed components built using Radix UI and Tailwind CSS. Shadcn/ui provides:

• ✅ Accessibility-first: Full ARIA support and keyboard navigation
• ✅ Customizable: Built with CSS variables and utility classes
• ✅ Copy & paste: Simple integration without package dependencies
• ✅ TypeScript: Full type safety and IntelliSense support

📚 Shadcn/ui Documentation

Tailwind CSS Integration

All components use Tailwind CSS utility classes for styling. Developers must be familiar with Tailwind's utility-first approach:

• 🎨 Utility-first: Use utility classes for rapid UI development
• 📱 Responsive design: Built-in responsive design utilities
• 🌙 Dark mode: Native dark mode support
• ⚡ Performance: Optimized CSS output with purging

📚 Tailwind CSS Documentation

CSS Stylesheets — Integration Guide

The design system exports three CSS files for use by consumer MFEs. Each one serves a different integration pattern.

Exported files

| Import path | Description | |-------------|-------------| | @yuno-payments/dashboard-design-system/tokens.css | Self-contained stylesheet. Includes Tailwind CSS, the full color/font/radius/animation token set, light/dark semantic tokens, and the Tailwind utility bridge. This is what most MFEs should use. | | @yuno-payments/dashboard-design-system/theme.css | Theme tokens only. A raw @theme block for consumers that run their own Tailwind build and want to merge DS tokens into their pipeline. No Tailwind import, no base styles. | | @yuno-payments/dashboard-design-system/styles.css | Component overrides & global utilities. Compiled from src/global.css. Includes everything in tokens.css plus base body styles, z-index layers, toast/notification styling, RTL support, and DataTable padding. |

Usage patterns

Pattern A — Most MFEs (no own Tailwind build):

/* src/index.css */
@import '@yuno-payments/dashboard-design-system/tokens.css';

/* Your local styles below */

One import. Done. Tailwind utilities like bg-background, text-foreground, border-border work out of the box.

Pattern B — Container MFE (own Tailwind build):

/* src/index.css */
@import 'tailwindcss/theme';
@import '@yuno-payments/dashboard-design-system/theme.css';
@import '@yuno-payments/dashboard-design-system/styles.css';
@import 'tailwindcss/utilities';

theme.css merges DS tokens into the consumer's Tailwind config. styles.css provides the component-level overrides (toasts, z-index, RTL, DataTable, etc.).

What each file contains

• @import "tailwindcss"
• @custom-variant dark (class-based dark mode)
• Static @theme block: font-sans, border-radius, 8 color families × 10 shades (RGB), opacity variants for Badge, animation keyframes
• Dynamic semantic tokens (:root / .dark): background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, surface, ring, success, warning, info
• Base override: border-color: var(--border) on all elements
• @theme inline bridge: maps CSS vars to --color-* so Tailwind generates utilities

• A single @theme block with the same static tokens as tokens.css (fonts, radii, colors, animations)
• No Tailwind import, no :root/.dark, no bridge — purely for native @theme merging

• Everything in tokens.css plus:
• @import "tw-animate-css" (animation plugin)
• Base body styles: bg-background text-foreground, cursor pointer on buttons
• Z-index utilities: z-sheet (1000), z-dialog (1000), z-popover (10000), z-tooltip (100000)
• .bg-input light/dark override
• Time picker icon positioning fix
• Notification toast colored borders (success, error, warning, info)
• Sonner toast icon colors by data-type
• RTL directional icon mirroring (.rtl-mirror)
• DataTable first/last column padding (.yuno-data-table)

Keeping files in sync

The @theme block in tokens.css and global.css must mirror the one in theme.css. When adding or changing tokens, update all three source files.

Vendors Folder

The src/vendor/ folder contains the base components that we use to create our custom components:

src/vendor/shadcn/
├── alert.tsx           # Base alert component
├── avatar.tsx          # Base avatar component
├── badge.tsx           # Base badge component
├── breadcrumb.tsx      # Base breadcrumb component
├── button.tsx          # Base button component
├── checkbox.tsx        # Base checkbox component
├── dropdown-menu.tsx   # Base dropdown component
├── input.tsx           # Base input component
├── label.tsx           # Base label component
├── radio-group.tsx     # Base radio group component
├── separator.tsx       # Base separator component
├── skeleton.tsx        # Base skeleton component
├── switch.tsx          # Base switch component
├── tabs.tsx            # Base tabs component
└── tooltip.tsx         # Base tooltip component

These shadcn/ui base components provide:

• ✅ Complete accessibility (ARIA, keyboard navigation)
• ✅ Base styles with Tailwind CSS
• ✅ Predefined variants and states
• ✅ Radix UI primitives compatibility

Atomic Design Structure

The library strictly follows the Atomic Design methodology with the following structure:

src/components/
├── atoms/              # Basic and indivisible components
│   ├── alert/
│   ├── avatar/
│   ├── badge/
│   ├── button/
│   ├── checkbox/
│   ├── icon/
│   ├── input/
│   ├── label/
│   ├── radio-group/
│   ├── separator/
│   ├── skeleton/
│   ├── switch/
│   ├── tabs/
│   ├── tooltip/
│   └── typography/
├── molecules/          # Combinations of atoms
│   └── breadcrumb/
└── organisms/          # Complex components
    └── dialog/

Atomic Design Rules

1. Atoms: Basic components that cannot be divided further (Button, Input, Icon)
2. Molecules: Simple combinations of atoms that work together (Breadcrumb, SearchBox)
3. Organisms: Complex components that combine molecules and atoms (Dialog, DataTable, Navigation)

⚠️ IMPORTANT: All new components MUST follow this structure and be classified correctly according to their complexity.

Project Rules

📋 Mandatory Requirements for Components

Every component added to the library MUST include:

1. 📄 Main file (component.tsx)
2. 📖 Storybook story (component.stories.tsx)
3. 🧪 Unit test (component.test.tsx)
4. 📤 Export file (index.tsx)

📁 Component Folder Structure

src/components/[atomic-level]/[component-name]/
├── index.tsx                    # Component exports
├── [component-name].tsx         # Main implementation
├── [component-name].stories.tsx # Storybook documentation
└── [component-name].test.tsx    # Unit tests

📖 Story Requirements

Each story must include:

• ✅ Complete documentation with description, when to use, best practices
• ✅ Examples of all variants and states
• ✅ Common use cases
• ✅ Accessibility examples
• ✅ Reference to Figma component
• ✅ Interactive controls for all props

🧪 Test Requirements

Each test must cover:

• ✅ Basic component rendering
• ✅ All variants and states
• ✅ User interactions
• ✅ Accessibility (ARIA roles, keyboard navigation)
• ✅ Props and callbacks
• ✅ Edge cases and error handling

Best Practices

🎯 Component Development

1. Extend base components: Always start from components in src/vendor/shadcn/
2. Follow naming conventions: PascalCase for components, camelCase for props
3. Use strict TypeScript: Define clear interfaces for all props
4. Implement forwardRef: For components that need DOM access
5. Use class-variance-authority: To handle style variants
6. Apply cn() utility: To combine Tailwind CSS classes

🎨 Styling and Design

1. Use design tokens: CSS variables defined in the theme
2. Maintain consistency: Follow spacing and typography system
3. Responsive design: Consider all breakpoints
4. Dark mode: Support light and dark themes
5. Accessibility: Comply with WCAG 2.1 AA

📚 Documentation

1. Complete JSDoc: Document all props and methods
2. Clear examples: Show real use cases
3. Best practices: Explain when and how to use each component
4. Accessibility: Document accessibility features

Important Scripts

# 🔨 Build and development
npm run build              # Build library for production
npm run storybook          # Run Storybook in development mode (port 6006)
npm run build-storybook    # Build static Storybook

# 🧪 Testing and quality
npm run test               # Run unit tests with Vitest
npm run lint               # Run ESLint to verify code quality

# 📦 Publishing
npm run publish            # Publish library to npm (public access)

🔧 Development Scripts

• storybook: Starts Storybook development server to document and test components
• build: Uses Vite to build the library optimized for production
• test: Runs the test suite with Vitest in single-run mode
• lint: Verifies code with ESLint according to configured rules

Component Dependencies

🔗 Dependency Hierarchy

Organisms
    ↓
Molecules  
    ↓
Atoms
    ↓
Vendor (shadcn)

📊 Specific Dependency Mapping

Atoms → Vendor + External Libraries

• Button → @/vendor/shadcn/button + Icon (atom) + react
  • Uses specific icons: CircleNotch (loading), startIcon, endIcon
• Typography → class-variance-authority + @/lib/utils (cn)
• Icon → @phosphor-icons/react (100+ icons available)
• Tooltip → @/vendor/shadcn/tooltip
• Badge → @/vendor/shadcn/badge
• Avatar → @/vendor/shadcn/avatar
• Checkbox → @/vendor/shadcn/checkbox
• Input → @/vendor/shadcn/input
• Switch → @/vendor/shadcn/switch
• Alert → @/vendor/shadcn/alert
• Separator → @/vendor/shadcn/separator

Molecules → Atoms + Vendor

• Breadcrumb → Multiple dependencies:
  • Icon (atom) - uses CaretDown for dropdowns
  • @/vendor/shadcn/breadcrumb (6 base components)
  • @/vendor/shadcn/dropdown-menu (4 components)
  • react (Fragment, ReactNode, forwardRef)

Organisms → Atoms + Libraries

• Dialog → Complex dependencies:
  • Button + ButtonProps (atom)
  • @/lib/utils (cn utility)
  • class-variance-authority (style variants)
  • lucide-react (X, ArrowLeft icons)
  • react (forwardRef, useState, useEffect)

🛠️ Shared Utilities

// src/lib/utils.ts
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

This utility is fundamental and used in all components for:

• ✅ Combining Tailwind CSS classes
• ✅ Resolving style conflicts
• ✅ Applying conditional styles

Project Structure

dashboard-design-system/
├── .storybook/              # Storybook configuration
├── src/
│   ├── components/          # Components organized by Atomic Design
│   │   ├── atoms/          # Basic components
│   │   ├── molecules/      # Combinations of atoms
│   │   └── organisms/      # Complex components
│   ├── lib/                # Utilities and helpers
│   ├── types/              # TypeScript type definitions
│   ├── vendor/             # Base components (shadcn)
│   ├── global.css          # Global styles and CSS variables
│   └── index.ts            # Main entry point
├── package.json            # Dependencies and scripts
├── vite.config.ts          # Vite configuration
├── vitest.config.ts        # Test configuration
└── tsconfig.json           # TypeScript configuration

Contributing

To contribute to this library:

1. 🔍 Review Figma: Verify that the component exists in the design system
2. 🏗️ Follow Atomic Design: Classify the component correctly
3. 📝 Create documentation: Complete story with examples and best practices
4. 🧪 Write tests: Complete coverage of functionality and accessibility
5. ✅ Verify quality: Run lint and tests before commit
6. 📦 Export correctly: Update corresponding index.ts files

Current version: 0.0.8-beta.6
Maintained by: Dashboard Frontend Team - Yuno Payments