Contribution Guidelines

​

Code Quality Standards

​

Code Style and Formatting

bunx ultracite lint

​

TypeScript Usage

• Use explicit types for props and component parameters
• Leverage TypeScript’s type inference where appropriate
• Avoid using any type unless absolutely necessary
• Define proper interfaces for complex prop structures

// Good
interface ButtonProps {
  variant: "primary" | "secondary";
  size?: "sm" | "md" | "lg";
  onClick?: () => void;
}

export default function CustomButton({ variant, size = "md", onClick }: ButtonProps) {
  // ...
}

// Avoid
export default function CustomButton(props: any) {
  // ...
}

​

Import Organization

1. External packages (React, third-party libraries)
2. Internal UI components from @/components/ui
3. Other internal imports
4. Types and interfaces

import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import type { FormProps } from "@/types";

​

Component Naming Conventions

​

File Naming

• login-01.tsx
• file-upload-03.tsx
• command-menu-02.tsx

​

Component Naming

• Login01
• FileUpload03
• CommandMenu02

​

Block IDs

{category}-{number}

• login-01
• stats-15
• file-upload-06

​

Accessibility Requirements

​

Semantic HTML

// Good
<nav>
  <ul>
    <li><a href="/home">Home</a></li>
  </ul>
</nav>

// Avoid
<div>
  <div>
    <div><a href="/home">Home</a></div>
  </div>
</div>

​

ARIA Attributes

• Add aria-label for icon-only buttons
• Use aria-describedby for form field descriptions
• Include aria-hidden for decorative elements
• Implement proper focus management for interactive components

// Icon button with accessible label
<Button aria-label="Close dialog">
  <X className="h-4 w-4" />
</Button>

// Decorative icon
<GoogleIcon className="size-5" aria-hidden={true} />

​

Keyboard Navigation

• All interactive elements should be focusable
• Focus states should be clearly visible
• Implement logical tab order
• Support standard keyboard shortcuts (Enter, Space, Escape)

​

Color Contrast

• Use CSS variables from the theme system
• Test with different themes (light/dark)
• Ensure text meets WCAG AA standards (4.5:1 for normal text)

// Use theme variables
<h2 className="text-foreground">
  Sign in to your account
</h2>

<p className="text-muted-foreground">
  Enter your credentials below
</p>

​

Component Structure

​

Layout and Styling

• Prefer utility classes over custom CSS
• Use responsive classes (sm:, md:, lg:) for responsive design
• Leverage the cn() utility for conditional classes
• Follow mobile-first approach

<div className="flex flex-col gap-4 sm:flex-row sm:gap-6">
  {/* Content */}
</div>

​

Component Composition

• Button
• Input
• Label
• Card
• Dialog
• Separator
• And other shadcn/ui components

import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

export default function MyBlock() {
  return (
    <form>
      <Label htmlFor="email">Email</Label>
      <Input type="email" id="email" />
      <Button type="submit">Submit</Button>
    </form>
  );
}

​

State Management

• Use React hooks (useState, useEffect) appropriately
• Keep state as local as possible
• Consider uncontrolled components for form inputs
• Document any required external state management

​

Documentation Standards

​

Component Documentation

/**
 * Login form with email verification
 * Sends a magic link to the user's email address
 */
export default function Login10() {
  // ...
}

​

Metadata Quality

{
  id: "login-10",
  category: categoryIds.Login,
  name: "Login with Email Link", // Clear, descriptive name
  iframeHeight: "500px", // Appropriate preview height
  type: "file",
}

​

Performance Considerations

​

Optimize Imports

// Good
import { Button } from "@/components/ui/button";

// Avoid importing entire modules when not needed
import * as AllComponents from "@/components/ui";

​

Image Optimization

• Use Next.js Image component
• Provide appropriate alt text
• Specify width and height
• Use appropriate formats (WebP, AVIF)

import Image from "next/image";

<Image
  src="/path/to/image.png"
  alt="Descriptive alt text"
  width={200}
  height={200}
/>

​

Avoid Heavy Dependencies

• Use built-in browser APIs when possible
• Leverage existing project dependencies
• Avoid adding new packages unless necessary

​

Testing Your Contribution

bun run dev

bun run build

bunx ultracite lint

​

Commit Message Format

<type>: <description>

[optional body]

[optional footer]

​

Commit Types

• feat: - New feature or block
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

​

Examples

# Adding a new block
git commit -m "feat: add login-10 block with email link authentication"

# Fixing a bug
git commit -m "fix: correct button alignment in login-01 block"

# Documentation
git commit -m "docs: update contributing guidelines for accessibility"

​

Code Review Checklist

• Code follows TypeScript best practices
• Component uses proper naming conventions
• All accessibility requirements are met
• Component works in both light and dark themes
• Responsive design works on all screen sizes
• Registry has been regenerated
• Linter passes without errors
• Build completes successfully
• Commit messages follow conventional format
• Metadata is clear and descriptive

​

Questions?

• Review existing blocks for examples
• Check the project’s GitHub discussions
• Open an issue for clarification