About The Project

This is a library of components I have found useful to build web sites quickly.

Built With

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• ![PayPal][PayPal.com]
• 
• 
• 

♿ Accessibility

Pixelated Components is committed to creating inclusive web experiences. All components are built with accessibility in mind and include:

• WCAG 2.1 AA compliance - Components meet web accessibility guidelines
• Keyboard navigation - Full keyboard support for all interactive elements
• Screen reader support - Proper ARIA labels, roles, and semantic HTML
• Focus management - Clear focus indicators and logical tab order
• Color contrast - High contrast ratios for text and interactive elements
• Semantic HTML - Proper use of headings, landmarks, and structural elements

Accessibility Features

• Automatic ARIA label generation
• Focus trap management for modals and overlays
• Skip links for keyboard users
• Reduced motion support for users with vestibular disorders
• High contrast mode compatibility

📦 Installation & Setup

Requirements

• React: 19.0 or higher
• Next.js: 16.0 or higher
• Node.js: 18.0 or higher
• TypeScript: 4.9 or higher (optional, but recommended)

Basic Installation

# npm
npm install @pixelated-tech/components

# yarn
yarn add @pixelated-tech/components

# pnpm
pnpm add @pixelated-tech/components

Peer Dependencies

This library requires the following peer dependencies (install if not already present). Versions in examples match the package's peerDependency policy:

npm install react@^19 react-dom@^19 next@^16 prop-types

TypeScript Support

This library is written in TypeScript and provides full type definitions. No additional setup required.

Release Process

This project uses an automated release script to ensure consistent versioning and branch synchronization:

# Run the release script (must be on dev branch)
npm run release
# Or run directly:
./scripts/release.sh

The release script will:

• Update dependencies and run security audits
• Run linting and build the project
• Prompt for version bump type (patch/minor/major/custom/none)
• Commit changes with proper versioning
• Push dev branch to remote
• Force-sync main branch to match dev
• Create and push git tags
• Optionally publish to npm (with OTP authentication)

Important: Always run releases from the dev branch. The script ensures both dev and main branches stay synchronized.

Config policy: To avoid shipping secrets, keep pixelated.config.json encrypted on disk as pixelated.config.json.enc and never commit the plaintext pixelated.config.json. The release script will remove any plaintext pixelated.config.json from dist post-build and will fail if the .enc file is not present.

Universal Usage: This script is designed to work with any Pixelated project and automatically detects project settings.

Reference Implementation

For a complete working example of Pixelated Components in action, check out the pixelated-admin project. This admin interface demonstrates:

• Component Integration: Real-world usage of all major components
• Configuration Management: Dynamic site configuration with ConfigBuilder
• Page Building: Visual page construction with PageBuilderUI
• Authentication: NextAuth.js integration for secure admin access
• Deployment Ready: Production-ready setup with HTTPS and optimized builds

# Clone the reference implementation
git clone https://github.com/brianwhaley/pixelated-admin.git
cd pixelated-admin
npm install
npm run dev

Visit http://localhost:3006 to explore the admin interface and see components in action.

Component index

The full component index and API reference live in docs/components.md (single source-of-truth). For interactive exploration, run Storybook: npm run storybook.

• Quick link: Component API reference

If you want to browse individual components interactively, run Storybook: npm run storybook.

Utilities

Shared technical utilities and helpers:

• CacheManager - Unified caching layer with Memory, Session, and LocalStorage support with TTL and SSR fallbacks.
• Cloudinary - Image processing and URL generation helpers.
• Date/Time - Formatting and manipulation utilities.

Site Health & Monitoring

Comprehensive site health monitoring and analytics:

• SiteHealthOverview - Dashboard overview of site health metrics
• SiteHealthPerformance - Performance monitoring and optimization insights
• SiteHealthAccessibility - Accessibility compliance testing with axe-core
• SiteHealthSecurity - Security vulnerability scanning and recommendations
• SiteHealthSEO - On-page SEO analysis and scoring
• SiteHealthOnSiteSEO - Advanced on-page SEO metrics (browser caching, gzip compression, mobile-first indexing, etc.)
• SiteHealthGoogleAnalytics - Google Analytics data integration
• SiteHealthGoogleSearchConsole - Google Search Console integration
• SiteHealthCloudwatch - AWS CloudWatch uptime monitoring
• SiteHealthGit - Git repository health and status
• SiteHealthUptime - Uptime monitoring and alerts
• SiteHealthAxeCore - Automated accessibility testing
• SiteHealthDependencyVulnerabilities - Dependency security scanning

� Quick Start

Get up and running in minutes:

# Install the package
npm install @pixelated-tech/components

# Import and use components
import { Accordion, Callout } from '@pixelated-tech/components';

For detailed usage examples and API documentation, see the Component Reference Guide.

For administrative components and site management features, see the Admin Components Guide.

Storybook Interactive Demos

Explore all components with live, interactive examples:

# Start Storybook development server
npm run storybook

Access locally at: http://localhost:6006

See the open issues for a full list of proposed features (and known issues).

🚀 Roadmap

See our detailed Roadmap for planned improvements and refactoring initiatives.

🧪 Testing

See our comprehensive Testing Documentation for test coverage, setup, and strategies.

Quick conventions:

• Unit & integration tests → src/tests (filename: *.test.{ts,tsx})
• Shared harnesses / fixtures → src/test
• Storybook stories & play() tests → src/stories (run with npm run storybook)

Following these locations keeps CI discovery and story-driven QA consistent across the monorepo.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors:

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Brian Whaley - @brianwhaley - [email protected]

Project Link: https://github.com/brianwhaley/pixelated-components