Baruk Design System (@baruk/design-system)

Design System oficial do ecossistema Baruk — design tokens, temas multi-tenant e componentes React.

Contrato oficial de tokens: --bk-* · Arquitetura de 4 camadas (Brand → Semantic → Component → React). Documentação canônica: DESIGN_SYSTEM.md. Decisão: ADR-ECO-0010. Ex-wellington-ui-kit.

Overview

O Baruk Design System fornece a linguagem visual única do ecossistema (Baruk Connect, Manga Verde BI, Office OS e futuros produtos/tenants): tokens de marca, temas por tenant sem duplicação de componentes, e uma biblioteca de componentes React acessível. Um tenant substitui apenas a camada Brand (--bk-*); Semantic, Component e componentes permanecem intactos.

Purpose

This repository is not a final product but a foundational template that provides:

• Design Consistency: Unified tokens for colors, typography, spacing, and more
• Component Library: Battle-tested, accessible, and composable React components
• Layout System: Pre-built layouts and templates for common patterns
• AI-Safe Architecture: Structured to prevent regressions when working with AI tools
• Developer Experience: Clear patterns, minimal dependencies, TypeScript-first

When to Use

Use Wellington UI Kit as the starting point for:

• New web applications
• Internal tools and dashboards
• Customer-facing products
• Design system documentation sites

Do NOT use for:

• Non-React projects
• Projects that don't use Tailwind CSS
• Highly specialized UIs that require completely custom design systems

Quick Start

📖 New to this template? Read TEMPLATE_GUIDE.md for a complete quick start guide.

Using the Setup Script (Recommended)

./scripts/setup.sh

The setup script will:

• Check Node.js and npm versions
• Install dependencies
• Create .env from .env.example
• Initialize git (optional)
• Run type check

Manual Setup

# Install dependencies
npm install

# Start development
npm run dev

# Build for production
npm run build

# Type check
npm run type-check

Project Structure

Wellington-UI-Kit/
├── src/
│   ├── components/
│   │   ├── atoms/          # Base components (Button, Input, etc.)
│   │   ├── molecules/      # Composite components (Card, SearchBar, etc.)
│   │   ├── organisms/      # Complex components (DataTable, Sidebar, etc.)
│   │   └── templates/      # Page templates
│   ├── layouts/            # Layout components
│   ├── styles/             # Global styles and tokens
│   ├── types/              # TypeScript types
│   ├── mocks/              # Mock data for examples
│   └── lib/                # Utilities
├── docs/                       # Project documentation
│   ├── PROJECT_CONTEXT.md      # Project overview (1 page)
│   ├── PRD.md                  # Product Requirements template
│   ├── ARCHITECTURE.md         # Architecture documentation template
│   ├── CHECKLIST_EXECUTION.md  # Task execution workflow
│   ├── DECISIONS.md            # Architectural decision records (ADR)
│   ├── AGENTS.md               # AI agents contracts
│   └── BI_RULES.md             # Business Intelligence rules
├── prompts/                    # Reusable AI prompts
│   ├── SUPER_PROMPTS.md        # Development task prompts
│   ├── DEBUG_PROMPTS.md        # Debugging prompts
│   └── TEST_PROMPTS.md         # Testing prompts
├── scripts/                    # Automation scripts
│   ├── setup.sh                # Project setup
│   ├── deploy.sh               # Deployment (customize)
│   └── reset-db.sh             # Database reset (customize)
├── TEMPLATE_GUIDE.md           # Quick start guide for template
├── DESIGN_SYSTEM.md            # Design system philosophy
├── AI_GUIDELINES.md            # Rules for AI-assisted development
└── CONTRIBUTING.md             # Contribution guidelines

Key Features

Design Tokens

All design decisions are tokenized and centralized:

• Colors (primary, secondary, success, warning, destructive, etc.)
• Typography (sizes, weights, line heights)
• Spacing (xs, sm, md, lg, xl)
• Border radius (sm, md, lg)
• Shadows (sm, md, lg)

Component Hierarchy

Components follow Atomic Design principles:

• Atoms: Basic building blocks
• Molecules: Simple combinations of atoms
• Organisms: Complex, feature-rich components
• Templates: Layout structures

Type Safety

Full TypeScript support with strict typing for all components and utilities.

Accessibility

All components are built with accessibility in mind, following WCAG 2.1 AA standards.

Using This as a Template

Starting a New Project

Wellington UI Kit is designed to be cloned and customized as the foundation for new projects. Follow these steps:

1. Clone the Template

# Using degit (recommended - copies without git history)
npx degit wellingtonbarros/wellington-ui-kit my-new-project

# Or clone and remove git history
git clone https://github.com/wellingtonbarros/wellington-ui-kit my-new-project
cd my-new-project
rm -rf .git

2. Initialize Your Project

# Initialize new git repository
git init

# Update package.json
# Edit: name, version, description, repository, author

# Install dependencies
npm install

3. Customize for Your Project

# Start development server
npm run dev

# Review and customize design tokens
# Edit: tailwind.config.ts (colors, spacing, typography)

# Update documentation
# Edit: docs/PROJECT_CONTEXT.md with your project specifics
# Edit: docs/DECISIONS.md to track your architectural decisions

4. Build Your Application

• Keep existing components as-is (they're your foundation)
• Add new components following Atomic Design principles
• Use design tokens for all styling
• Follow patterns in AI_GUIDELINES.md when using AI assistance
• Track tasks using docs/CHECKLIST_EXECUTION.md
• Document decisions in docs/DECISIONS.md

Standard Project Workflow

For Developers

1. Before Starting: Read docs/PROJECT_CONTEXT.md
2. During Development: Follow docs/CHECKLIST_EXECUTION.md
3. For Decisions: Document in docs/DECISIONS.md
4. For Design: Reference DESIGN_SYSTEM.md
5. For Contributing: See CONTRIBUTING.md

For AI-Assisted Development

1. Context: Provide docs/PROJECT_CONTEXT.md to your AI assistant
2. Tasks: Use prompts from prompts/SUPER_PROMPTS.md
3. Debugging: Use prompts from prompts/DEBUG_PROMPTS.md
4. Guidelines: Reference AI_GUIDELINES.md
5. Workflow: Follow docs/CHECKLIST_EXECUTION.md

What to Customize

Always Customize

• package.json - Project name, description, repository
• docs/PROJECT_CONTEXT.md - Your project's specific context
• Design tokens in tailwind.config.ts (if brand colors differ)
• Add your application-specific components
• Add your business logic and features

Keep As-Is (Unless Absolutely Needed)

• Base component library (src/components/)
• Layout components (src/layouts/)
• Utility functions (src/lib/utils.ts)
• TypeScript configuration
• Build configuration (Vite, PostCSS)

Project Structure Standards

All projects using this template should maintain:

• Atomic Design component organization
• Design tokens for all styling values
• TypeScript strict mode for type safety
• Accessibility standards (WCAG 2.1 AA)
• Documentation in docs/ directory
• Decision records in docs/DECISIONS.md

Template Updates

This template may receive updates. To incorporate updates:

1. Review changes in the template repository
2. Manually merge relevant updates to your project
3. Test thoroughly after merging
4. Document merge decisions in docs/DECISIONS.md

Note: This template does not support automatic updates to avoid breaking project-specific customizations.

Documentation

Getting Started

• Template Guide: Complete quick start guide for using this template

Core Documentation

• Design System Guide: Comprehensive design system documentation
• AI Development Guidelines: Rules for AI-assisted development
• Contributing Guide: How to extend and maintain the system

Project Documentation (/docs)

• Project Context: Essential project information (1 page max)
• PRD Template: Product Requirements Document template
• Architecture Template: Architecture documentation template
• Execution Checklist: Standardized workflow for executing tasks
• Architectural Decisions: Record of significant decisions (ADR)
• AI Agents: Contracts and guidelines for AI agents
• BI Rules: Business Intelligence rules and metrics

AI Assistance (/prompts)

• Super Prompts: Comprehensive prompts for common development tasks
• Debug Prompts: Specialized prompts for debugging and troubleshooting
• Test Prompts: Prompts for generating tests and test scenarios

Quick Reference

| I want to... | Read this | |--------------|-----------| | Start using this template | TEMPLATE_GUIDE.md ⭐ | | Understand the project | docs/PROJECT_CONTEXT.md | | Create a PRD | docs/PRD.md | | Document architecture | docs/ARCHITECTURE.md | | Start a new task | docs/CHECKLIST_EXECUTION.md | | Use AI assistance | prompts/SUPER_PROMPTS.md | | Debug an issue | prompts/DEBUG_PROMPTS.md | | Write tests | prompts/TEST_PROMPTS.md | | Configure AI agents | docs/AGENTS.md | | Define BI rules | docs/BI_RULES.md | | Understand design decisions | docs/DECISIONS.md | | Learn the design system | DESIGN_SYSTEM.md | | Work with AI tools | AI_GUIDELINES.md | | Contribute or extend | CONTRIBUTING.md |

Philosophy

1. Consistency over customization: Use tokens, don't override
2. Composition over configuration: Combine small pieces, don't build monoliths
3. Simplicity over complexity: Avoid premature abstraction
4. Type safety over runtime errors: Leverage TypeScript fully
5. Accessibility by default: Build for everyone

Tech Stack

• React 18: UI library
• TypeScript: Type safety
• Tailwind CSS: Utility-first styling
• Vite: Build tool
• Lucide React: Icon library

Available Scripts

Development

npm run dev          # Start development server
npm run build        # Build for production
npm run preview      # Preview production build
npm run type-check   # Run TypeScript type checking

Project Scripts

./scripts/setup.sh      # Initial project setup (recommended for new projects)
./scripts/deploy.sh     # Deploy to staging/production (customize first)
./scripts/reset-db.sh   # Reset database to clean state (customize first)

Note: Customize deployment and database scripts in /scripts directory based on your infrastructure.

License

MIT

Support

For questions, issues, or contributions, please refer to CONTRIBUTING.md.

Built by Wellington Barros