CopyKit

A foundational collection of scripts, styles, and components designed to be copied into your projects. CopyKit provides essential building blocks that you can customize and modify completely according to your project's specific requirements.

Overview

CopyKit is a copy-and-customize component library that provides a starting point for web projects. Unlike traditional frameworks or libraries, CopyKit components are meant to be copied directly into your project where you have full control to modify, extend, or adapt them to your specific needs. Once copied, the code becomes entirely yours to customize.

🌐 Live Demo & Documentation

• 📱 Example Pages - See all components in action with interactive examples
• 📚 Complete UI Documentation - Comprehensive component documentation and usage guides

Features

• Copy-and-Customize - Take what you need, modify everything to fit your project
• Modular CSS Components - Reusable styles with CSS custom properties for easy theming
• JavaScript Utilities - Common functions and helpers for DOM manipulation and data handling
• HTML Templates - Semantic, accessible markup patterns
• Build Tools Integration - Compatible with modern bundlers and build systems
• Responsive Design - Mobile-first approach with flexible grid systems
• Accessibility First - WCAG compliant components and practices
• Performance Optimized - Minimal footprint with optional features
• Full Ownership - Once copied, the code is entirely yours to modify

Project Structure

The repository contains multiple copy points, each with a consistent structure for easy integration:

├── pages/                  # Example pages demonstrating components
│   ├── index.html          # Component showcase and navigation
│   ├── app.ts              # Example application setup
│   ├── style.css           # Example global styles
│   └── [page-name]/        # Additional example pages
├── stubs/                  # 📁 COPY THESE - Multiple copy points
│   ├── _base/              # ✨ Core foundation copy point
│   ├── [copy-point]/       # ✨ Additional copy points (future)
│   └── [copy-point]/       # ✨ Each with consistent structure
├── assets/                 # Static assets for examples
└── dist/                   # Build output for development

Copy Point Structure

Each copy point in stubs/ follows the same consistent structure:

[copy-point-name]/          # Note: only _base has underscore prefix
├── scripts/                # JavaScript functionality
│   ├── services/           # Feature services (interactive components)
│   └── utilities/          # Helper functions and utilities
└── styles/                 # CSS organized in layers
    ├── 01_defaults/        # Foundation: resets, variables, typography
    ├── 02_components/      # UI components: buttons, forms, etc.
    ├── 03_utilities/       # Utility classes: spacing, layout, etc.
    ├── 04_layouts/         # Page-level structural styles
    └── index.css           # Main entry point (only in _base copy point)

Important: Start with _base as it provides the foundation. The index.css file is only included in _base and imports all the CSS layers.

This consistent structure means you can:

• Copy entire copy points and they'll integrate the same way
• Mix and match between copy points easily
• Know exactly where to find specific types of code
• Paste into your project with predictable organization

Getting Started

CopyKit CLI (Recommended)

The easiest way to use CopyKit is through the CLI tool, which automatically copies copy-points into your project with proper structure and integration.

Installation

Option A: Install globally

npm install -g copykit
# or
pnpm add -g copykit
# or
yarn global add copykit

Option B: Use npx (no installation needed)

npx copykit <command>

Quick Start

# 1. Initialize your project with the base copy-point
copykit init

# 2. Add additional copy-points as needed
copykit add accordion
copykit add elevate

# 3. List available copy-points
copykit list

# 4. Get detailed information about a copy-point
copykit info accordion

CLI Commands

copykit init - Initialize project with _base copy-point

copykit init                   # Initialize in current directory
copykit init --overwrite       # Overwrite existing files
copykit init --skip-tests      # Skip copying test files
copykit init --help            # Show help for init command

copykit add <copy-point> - Add specific copy-point

copykit add accordion              # Add accordion copy-point
copykit add elevate                # Add elevate copy-point
copykit add accordion --overwrite  # Overwrite existing files
copykit add accordion --skip-tests # Skip copying test files
copykit add --help                 # Show help for add command

copykit list - List available copy-points

copykit list                   # Show all available copy-points with basic info

copykit info <copy-point> - Show detailed copy-point information

copykit info accordion        # Show detailed info about accordion copy-point
copykit info _base           # Show detailed info about base copy-point
copykit info elevate         # Show detailed info about elevate copy-point

copykit help - Show general help

copykit --help                 # Show main help
copykit <command> --help       # Show command-specific help

Integration After CLI Usage

After using the CLI, integrate the copied files into your project:

CSS Integration:

/* Import base styles in your main CSS file */
@import "./stubs/_base/styles/index.css";

/* Or import specific copy-point styles */
@import "./stubs/accordion/styles/02_components/accordion.css";
@import "./stubs/elevate/styles/03_utilities/elevate.css";

JavaScript Integration:

// Import services and utilities
import { expand } from "./stubs/_base/scripts/services/expand.js"
import { selectParent } from "./stubs/_base/scripts/utilities/select.js"
import { Accordion } from "./stubs/accordion/scripts/services/accordion.js"

// Initialize functionality
expand.init()
const accordion = new Accordion()

HTML Usage:

<!-- Use copied components with their classes -->
<div class="accordion" data-animate>
  <div class="item">
    <button class="control" aria-expanded="false">Toggle</button>
    <div class="content">Content here</div>
  </div>
</div>

Manual Copy (Alternative Method)

If you prefer manual control, you can copy files directly:

Using CopyKit Copy Points

CopyKit is designed as a copy-and-customize library organized in copy points. Here's how to use it:

1. Browse Copy Points

• 🌐 Live Example Pages - See components in action with interactive demos
• 📚 Complete UI Documentation - Explore detailed component documentation and usage guides
• Clone or download this repository to explore available copy points locally
• Browse the stubs/ directory to explore different copy points
• Each copy point has the same structure, making integration predictable

2. Copy What You Need

⚠️ Important: Always start by copying _base first, as it contains the foundational styles and utilities that other copy points depend on.

Option A: Copy an entire copy point

# STEP 1: Always copy _base first (required foundation)
cp -r stubs/_base/ your-project/src/

# STEP 2: Copy additional copy points as needed
cp -r stubs/[copy-point]/ your-project/src/components/

Option B: Copy specific parts

# Copy specific components from any copy point
cp -r stubs/_base/styles/02_components/ your-project/styles/components/
cp -r stubs/_base/scripts/services/ your-project/scripts/services/

# Copy specific files
cp stubs/_base/styles/02_components/button.css your-project/styles/
cp stubs/_base/scripts/utilities/dom.ts your-project/scripts/

Option C: Mix and match between copy points

# Take utilities from _base and components from another copy point
cp -r stubs/_base/scripts/utilities/ your-project/scripts/
cp -r stubs/advanced/styles/02_components/ your-project/styles/components/

3. Integrate with Consistent Structure

Thanks to the consistent structure, integration is predictable:

• CSS layers will organize properly (01_defaults → 02_components → 03_utilities → 04_layouts)
• JavaScript modules will have expected folder organization
• You can import the main CSS with @import "path/to/index.css"

4. Customize and Adapt

Once copied, the code is entirely yours:

• Modify CSS variables to match your design system
• Adapt JavaScript functions to your project's needs
• Rename classes, functions, or variables as needed
• Remove features you don't need
• Add new functionality

For CopyKit Development

If you want to contribute to CopyKit or run the development environment:

# Prerequisites: Node.js (v18+) and pnpm
git clone [repository-url]
cd copykit
pnpm install
pnpm run dev  # Start development server

Available Commands

# Development
pnpm run dev         # Start development server
pnpm run build       # Build for production
pnpm run preview     # Preview production build

# Code Quality
pnpm run lint        # Run all linters
pnpm run lint:fix    # Auto-fix linting issues
pnpm run format      # Format code with Prettier
pnpm run security    # Run security audit

Colorset System

CopyKit uses a colorset approach for systematic color management. A colorset is a comprehensive collection of coordinated colors that establishes a complete visual identity for UI components or sections.

What is a Colorset?

A colorset provides all essential color variables needed for consistent theming:

• Primary text and background colors
• Borders and shadows
• Accent colors and interactive states
• Hover and selection colors

Why Use Colorsets?

Component theming - Apply consistent colors across buttons, cards, forms, and other UI elements Section-based styling - Define distinct visual zones like headers, sidebars, or content areas
Theme variations - Create light/dark modes or brand-specific color schemes Contextual styling - Differentiate between states like default, success, warning, or error Systematic design - Maintain visual consistency across your entire application with predefined color relationships

By using colorsets, you ensure that all related colors work harmoniously together while maintaining flexibility to swap entire color schemes without touching individual component styles.

Available Copy Points

Use copykit list to see all available copy-points with basic information, or copykit info <copy-point> for detailed information. You can also explore the 📚 Complete UI Documentation for interactive component examples and detailed usage guides.

Available copy-points:

Currently Available

_base/ - Core Foundation Copy Point ⭐ REQUIRED STARTING POINT

The essential foundation that must be copied first. All other copy points build upon this base.

• CSS Layers: Browser resets, variables, components, utilities, and layouts
• JavaScript: Expand/collapse services and DOM utilities
• Foundation: Complete base styles and interactive functionality

📖 View complete _base documentation

accordion/ - Accessible Accordion Component

Advanced accordion/collapsible component with full ARIA support and keyboard navigation.

• WCAG 2.1 AA compliant with keyboard navigation support
• Customizable styling with CSS custom properties
• Animation support with configurable timing
• Multiple instances support

🌐 Live Demo | 📖 View complete accordion documentation

elevate/ - Visual Enhancement Utilities

Utility classes for adding visual depth and elevation to components using advanced CSS color-mixing.

• Material Design inspired elevation levels (0-24)
• Advanced color mixing with CSS color-mix() function
• Customizable elevation color and boost values
• Performance optimized utility classes

📖 View complete elevate documentation

border/ - Comprehensive Border Utilities

Flexible border utility system with directional controls and CSS custom properties.

• Directional Border Control - Apply borders to specific sides (top, right, bottom, left)
• Axis-Based Utilities - Control horizontal (x-axis) and vertical (y-axis) borders together
• CSS Custom Properties - Flexible customization through CSS variables
• Predefined Styles - Quick style application with solid, dashed, dotted, and none classes

🌐 Live Demo | 📖 View complete border documentation

rounded-simple/ - Border Radius Utilities

Simple and flexible border radius utilities for creating rounded corners on any element.

• Configurable border radius sizes (sm, base, md, lg, xl)
• CSS custom properties for per-corner customization
• Utility classes for common rounding patterns
• Full circle and pill shapes support

🌐 Live Demo | 📖 View complete rounded-simple documentation

shadow/ - Material Design Shadow System

Material Design-inspired shadow utilities with 24 elevation levels and scientifically-accurate calculations.

• 24-Level Shadow System - Precise elevation control from 0-24
• Scientific Shadow Calculation - Uses umbra, penumbra, and ambient shadow layers
• Customizable Shadow Colors - Full control over shadow color and opacity
• Material Design Compliance - Shadow calculations match Material Design guidelines

🌐 Live Demo | 📖 View complete shadow documentation

Future Copy Points

Additional copy points will follow the same structure:

• advanced/ - Extended components and advanced features
• animations/ - Enhanced animation utilities
• forms/ - Advanced form components

Copy Point Structure

Every copy point follows the same organized structure:

[name]/                     # Note: only _base has underscore prefix
├── copy-point.json         # Metadata for CLI discovery and tooling
├── README.md               # Complete documentation for this copy point
├── scripts/
│   ├── services/           # Interactive functionality
│   └── utilities/          # Helper functions
└── styles/
    ├── 01_defaults/        # Foundation layer
    ├── 02_components/      # Component layer  
    ├── 03_utilities/       # Utility layer
    ├── 04_layouts/         # Layout layer
    └── index.css           # Main entry point (only in _base copy point)

Note: Each copy point includes complete documentation in its README.md file with usage examples, customization options, and integration guides.

Integration Benefits

• Predictable Structure: Every copy point organizes code the same way
• Complete Documentation: Each copy point has comprehensive documentation
• Easy Mixing: Combine components from different copy points seamlessly
• Layer Organization: CSS layers ensure proper cascade order
• Modular Imports: Take only what you need from any copy point

Development

Code Quality Tools

The project includes comprehensive code quality tools:

• ESLint: TypeScript-focused linting with Prettier integration
• Stylelint: CSS linting with automatic property ordering
• Prettier: Consistent code formatting
• Husky + lint-staged: Pre-commit hooks for automatic code quality
• Commitlint: Conventional commit message validation

Build System

• Vite: Modern build tool with TypeScript support
• Multi-page Application: Automatic discovery of HTML pages
• UI-Doc: Component documentation generation from JSDoc comments
• CSS Layers: Organized styling with @layer declarations

Development Workflow

1. Components are developed in stubs/ for copying into other projects
2. Pages demonstrate component usage with the @/ alias
3. CSS follows the layer hierarchy: defaults → components → utilities → layouts
4. JavaScript services provide ARIA-compliant interactive functionality
5. Everything is designed to be copied and customized in target projects

Contributing

We welcome contributions! Please see our Contributing Guidelines for detailed information on:

• Conventional commit message format and scopes
• Development process and workflow
• Code quality standards
• Pull request guidelines

Philosophy

This project follows these principles:

• Flexibility over Convention - Provide tools, not rigid structures
• Performance First - Minimal overhead, maximum impact
• Accessibility Always - Inclusive design from the ground up
• Developer Experience - Easy to use, easy to customize
• Future Friendly - Built with modern standards and best practices

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes and version history.

CopyKit - Building the web, one component at a time.