Contributing to Vera UI

We welcome contributions to Vera UI! This guide will help you get started with contributing to the project.

Development Setup

Fork and Clone

Fork the repository on GitHub and clone it locally:

git clone https://github.com/helgadigitals-limited-company/vera-ui.git
cd vera-ui

Install Dependencies

pnpm install
We use pnpm for package management:

```bash
pnpm install

Development Workflow

The project is organized as a monorepo with two main packages:

packages/ui: The component library
packages/docs: This documentation site

Run both in development:

# Start both UI development and docs
pnpm dev

# Or run individually
pnpm dev:ui    # Component library development
pnpm dev:docs  # Documentation site

Build and Test

# Build the component library
pnpm build:ui

# Build the documentation
pnpm build:docs

# Run tests
pnpm test

# Lint code
pnpm lint

Project Structure

vera-ui/
├── packages/
│   ├── ui/                    # Component library
│   │   ├── src/
│   │   │   ├── components/    # React components
│   │   │   │   ├── ui/       # Base UI components
│   │   │   │   └── ...       # Complex components
│   │   │   ├── hooks/        # Custom hooks
│   │   │   ├── lib/          # Utilities
│   │   │   └── index.ts      # Main export
│   │   └── package.json
│   └── docs/                  # Documentation site
│       ├── content/           # MDX documentation
│       ├── app/              # Next.js app
│       └── package.json
├── pnpm-workspace.yaml
└── package.json

Component Development Guidelines

Component Architecture

All components should follow these principles:

Accessibility First: Every component must be accessible by default with proper ARIA attributes, keyboard navigation, and screen reader support.

Built with Radix UI: Use Radix UI primitives when available
Customizable: Support className overrides and style customization
TypeScript: Full TypeScript support with proper type definitions
Composable: Components should be composable and follow compound component patterns
Responsive: Work well across different screen sizes

Component Template

Here's a template for creating new components:

packages/ui/src/components/ui/my-component.tsx

"use client"

import * as React from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

const myComponentVariants = cva(
  "base-classes-here",
  {
    variants: {
      variant: {
        default: "default-variant-classes",
        secondary: "secondary-variant-classes",
      },
      size: {
        default: "default-size-classes", 
        sm: "small-size-classes",
        lg: "large-size-classes",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

export interface MyComponentProps
  extends React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof myComponentVariants> {
  // Additional props here
}

const MyComponent = React.forwardRef<HTMLDivElement, MyComponentProps>(
  ({ className, variant, size, ...props }, ref) => {
    return (
      <div
        className={cn(myComponentVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)
MyComponent.displayName = "MyComponent"

export { MyComponent, myComponentVariants }

Component Categories

Organize components into these categories:

Forms

Input, Textarea, Select, Checkbox, Radio, etc.
Form validation and handling components

Breadcrumb, Navigation Menu, Tabs, Sidebar, etc.
Components for site navigation

Data Display

Table, Badge, Avatar, Card, etc.
Components for displaying information

Layout

Container, Grid, Stack, Separator, etc.
Components for page layout

Feedback

Alert, Toast, Progress, Loading, etc.
Components for user feedback

Overlays

Dialog, Sheet, Popover, Tooltip, etc.
Components that appear above other content

Documentation Guidelines

Component Documentation

Every component should have comprehensive documentation including:

Overview: What the component does and when to use it
Installation: Import statement and dependencies
Basic Usage: Simple example
Props: All available props with types and descriptions
Variants: Different visual styles available
Examples: Multiple real-world use cases
Accessibility: ARIA patterns and keyboard interactions
API Reference: Detailed prop documentation

Documentation Template

packages/docs/content/docs/components/category/component-name.mdx

---
title: Component Name
description: Brief description of what the component does
---

import { ComponentPreview } from "@/components/component-preview"
import { Button } from "@helgadigitals/vera-ui"

# Component Name

Brief overview of the component and its purpose.

## Installation

```bash npm2yarn
npm install @helgadigitals/vera-ui


## Usage

<ComponentPreview>
  <Button>Example usage</Button>
</ComponentPreview>

```tsx
import { Button } from "@helgadigitals/vera-ui"

export default function Example() {
  return (
    <Button>
      Example usage
    </Button>
  )
}
```

Examples

Basic Example

[Description and code example]

Advanced Example