@fagerkod/korrektify-component-library

v2.0.0

Published

a month ago

Accessible-first web component library built with vanilla Web Components, WCAG 2.2 AA & EN 301 549 compliant

0High
0Medium
0Low

fagerkod

web-components custom-elements accessibility wcag a11y design-system component-library vanilla-js typescript

Korrektify Component Library

Accessible-first web component library built with vanilla Web Components, WCAG 2.2 AA & EN 301 549 compliant.

Features

✅ 100% Vanilla Web Components - No framework dependencies
✅ WCAG 2.2 AA Compliant - Full accessibility support
✅ EN 301 549 Compliant - European accessibility standards
✅ TypeScript - Full type safety
✅ Design Tokens - Consistent design system with Amber primary color
✅ Dark Mode - Complete dark mode support
✅ Tree-shakeable - Import only what you need
✅ Shadow DOM - Encapsulated styles
✅ Separated Styles Pattern - Clean architecture with SMACSS organization
✅ Production Optimized - Lit production mode enabled for optimal performance

Installation

npm install @korrektify/component-library

Quick Start

HTML

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Korrektify Components</title>
  <script type="module" src="node_modules/@korrektify/component-library/dist/korrektify.js"></script>
</head>
<body>
  <korr-button variant="primary" size="md">Click Me</korr-button>
</body>
</html>

JavaScript/TypeScript

import '@korrektify/component-library';

// Or import specific components
import '@korrektify/component-library/dist/components/button';

// Use design tokens
import { tokens } from '@korrektify/component-library/tokens';
console.log(tokens.colors.amber[500]); // #F59E0B

Development

Prerequisites

Node.js 18+
npm 9+

Setup

# Clone the repository
git clone https://github.com/korrektify/component-library.git
cd component-library

# Install dependencies
npm install

# Start development
npm run dev

# Start Storybook
npm run storybook

# Run tests
npm run test

# Build library
npm run build

Project Structure

korrektify-component-library/
├── src/
│   ├── components/         # Web Components
│   │   ├── button/
│   │   │   ├── button.component.ts    # Component logic & HTML
│   │   │   ├── button.styles.ts       # Separated CSS (SMACSS)
│   │   │   ├── button.test.ts         # Unit tests
│   │   │   └── button.stories.ts      # Storybook docs
│   │   └── _template/      # Component template
│   ├── design-tokens/      # Design system tokens
│   └── utils/             # Utility functions
│       ├── accessibility.ts
│       ├── events.ts
│       ├── styles.ts
│       └── types.ts
├── docs/                  # Documentation
│   ├── ARCHITECTURE.md
│   ├── ACCESSIBILITY.md
│   ├── COLOR-SYSTEM.md
│   ├── COMPONENT_SPEC.md
│   └── TESTING.md
└── .storybook/           # Storybook configuration

Architecture: Separated Styles Pattern (v2.0.0)

Each component uses the Separated Styles Pattern for cleaner, more maintainable code:

.component.ts - Component logic, HTML template, and behavior
.styles.ts - CSS styles organized using SMACSS methodology
.test.ts - Comprehensive unit tests
.stories.ts - Storybook documentation and examples

Benefits:

30-37% code reduction per component
Better separation of concerns
Easier to maintain and update styles
Consistent CSS organization across all components
Better TypeScript support for dynamic styles

See ARCHITECTURE.md for complete details.

Design Tokens

Colors

Primary brand color: Amber (#F59E0B)

import { colors } from '@korrektify/component-library/tokens';

// Primary palette
colors.amber[500]    // #F59E0B

// Neutral palette
colors.neutral[900]  // #171717

// Semantic colors
colors.semantic.success  // #16A34A
colors.semantic.error    // #DC2626
colors.semantic.warning  // #EA580C
colors.semantic.info     // #2563EB

All colors are WCAG 2.2 AA compliant with proper contrast ratios.

Typography, Spacing, Shadows

import { tokens } from '@korrektify/component-library/tokens';

// Typography
tokens.typography.fontSize.base    // 16px
tokens.typography.fontWeight.bold  // 700

// Spacing (4px grid)
tokens.spacing[4]  // 16px

// Shadows
tokens.shadows.md

Accessibility

All components are built with accessibility at their core:

WCAG 2.2 Level AA compliant
EN 301 549 compliant
Full keyboard navigation support
Screen reader tested
High contrast mode support
Reduced motion support
Proper ARIA attributes

See ACCESSIBILITY.md for complete details.

Browser Support

Chrome/Edge 67+
Firefox 63+
Safari 13.1+
Opera 54+

Contributing

We welcome contributions! Please see our contributing guidelines for details.

License

MIT License - see LICENSE file for details.

Documentation

Architecture - System design and structure
Accessibility - WCAG 2.2 AA & EN 301 549 compliance
Color System - Complete color palette with contrast testing
Component Spec - Component requirements
Testing - Testing guidelines

Components

34 production-ready components built with accessibility at their core:

Core Components

Button - Primary interaction element with multiple variants
Icon - Icon rendering with Lucide icons
Badge - Status indicators and labels
Avatar - User profile images with fallbacks
Spinner - Loading state indicators
Divider - Visual section separators
Link - Accessible hyperlinks
Heading - Semantic heading elements
Container - Layout container with responsive sizing
Image - Responsive image component

Form Components

Input - Text input fields
Checkbox - Single and multi-select checkboxes
Radio - Radio button groups
Select - Dropdown selection
Textarea - Multi-line text input
Search - Search input with icons

Display Components

Card - Content containers
Alert - Contextual messages
Toast - Temporary notifications
Tooltip - Contextual help text
Price - Price display with currency
Rating - Star rating display
Skeleton - Loading placeholders
Progress - Progress indicators
Table - Data tables
List - Ordered and unordered lists with icons

Navigation Components

Navigation - Top-level navigation
Breadcrumb - Hierarchical navigation
Tabs - Tabbed interfaces
Pagination - Page navigation
Dropdown - Dropdown menus

Interactive Components

Modal - Dialog overlays with focus management
Accordion - Collapsible content sections
Tag - Removable tags and chips

See ARCHITECTURE.md for detailed component specifications and wave-based development plan

Support

For issues and questions:

GitHub Issues: https://github.com/korrektify/component-library/issues
Documentation: https://github.com/korrektify/component-library

Built with accessibility in mind. Made with ❤️ by Korrektify.