Design System 3

🚧 Note: DS3 is currently under active development. While we're working hard to make it production-ready, please be aware that APIs and features may change. We welcome your feedback and contributions as we continue to improve!

DS3 is a comprehensive design system that enables truly universal application development:

• 🌐 Cross-Platform - Build once and run everywhere with a unified codebase
• 🔄 Universal Compatibility - Works fully on web, fully on native, and in hybrid environments
• 🖼️ SVG Icon Support - Use any SVG icon library seamlessly across platforms
• 🎨 Advanced Theming - Powerful, customizable theming with dark/light mode and color schemes
• ♿ Fully Accessible - Built with accessibility in mind, including ARIA roles and proper semantics
• ⛓️ Web3 Integration - First-class support for blockchain and Web3 applications
• 🛠️ Customizable - Easily adaptable to your brand with configurable styles and components
• 🧩 Multi-Framework - Works with React and React Native, with consistent APIs across platforms

Project Structure

This monorepo contains shared packages and applications built with those packages.

Packages

@consensys/ds3-theme - Theming system

• Built on Radix UI Colors for accessible, consistent color usage
• Complete design token system (colors, spacing, typography, shadows, animations)
• Tailwind integration with pre-configured design tokens
• Light/dark mode and theme switching support
• Nested theme support with dynamic inheritance
• Dynamic CSS variable system for runtime customization

@consensys/ds3-config - Build configuration layer

• Unified configuration layer for the DS3 ecosystem
• Vite plugin and configuration presets
• Next.js configuration with React Native Web support
• Expo and React Native setup (Babel, Metro)
• TailwindCSS and NativeWind integration
• Runtime theme injection system
• Workspace optimization for monorepos

@consensys/ds3 - Component library

• Built on top of @consensys/ds3-theme
• React Native Primitives integration
• Cross-platform components (web + native)
• TailwindCSS/NativeWind styling
• Compound components pattern for flexible composition
• Dual API system for web and native development
• Slot pattern for component customization
• Includes Avatar, Dialog, Checkbox, Select, and more UI components

@consensys/ds3-web3 - Blockchain integration

• Built on top of @consensys/ds3
• Wallet integration (MetaMask, WalletConnect)
• Cross-chain support for multiple networks
• ENS resolution for human-readable addresses
• Ethereum-specific utilities
• Web3 UI components

Package Architecture

The packages follow a layered architecture:

1. theme → Theming system and design tokens
2. config → Build configuration layer (depends on theme)
3. ui → UI components (depends on theme)
4. web3 → Blockchain components (depends on ui)

Usage

Installation

pnpm install

Package Development

Build all packages:

pnpm build-deps

Watch all packages for development:

pnpm watch-deps

Build individual packages:

pnpm theme:build
pnpm config:build

Documentation

The interactive documentation and component examples are available in the docs app.

🌐 Live Demo - Explore DS3 components and examples online

Start the markdown server (serves markdown files with live reload):

pnpm markdown-server

Start the documentation site:

pnpm docs:start

Template Projects

We provide official templates to help you get started:

• Vite Template - Production-ready Vite.js setup
• Next.js Template - Production-ready Next.js setup
• Expo Template - React Native/Expo setup

To use these template projects within the monorepo, first clone with the --recursive flag to include the template submodules:

git clone --recursive https://github.com/Consensys-Network-State/ds3.git ds3             

Then you can run the templates:

# Install dependencies
pnpm i

# Start Vite template
pnpm --filter vite-template dev

# Start Next.js template
pnpm --filter nextjs-template dev

# Start Expo template
pnpm --filter expo-template start

Maintenance

Clean up node_modules and dist folders:

pnpm clean

Versioning and Publishing

We use Changesets for versioning and publishing our packages. This ensures consistent versioning across our monorepo and maintains a detailed changelog.

To create a new changeset:

pnpm changeset

To update versions based on changesets:

pnpm changeset version

To build and publish packages:

pnpm build-deps
pnpm changeset publish

The typical workflow is:

1. Make your changes
2. Create a changeset (pnpm changeset)
3. Update versions (pnpm changeset version)
4. Commit the changes (version bumps and changelog updates)
5. Build dependencies (pnpm build-deps)
6. Publish (pnpm changeset publish)

Contributors

We'd like to thank the following contributors for their work on DS3:

• Damian Sarzynski - Co-Creator & Design Lead (UI/UX Design, Design System Architecture)
• Leif DeJong - Co-Creator & Technical Lead (Core Development, Architecture & Implementation)
• Jerry Tan - Contributor (Web3 Development, Cross-Platform Architecture)

License

MIT License - Copyright (c) 2024 ConsenSys Mesh