ClarityKit - Svelte Component Library

A comprehensive Svelte component library focused on accessibility, ADHD-optimized design, and exceptional developer experience. Built with Svelte 5 and TypeScript, ClarityKit provides a complete toolkit for building modern, inclusive web applications with 187+ components across 12 categories.

LATEST v1.8.2: Dual-Export System Restored, ValidatedInput Fixed, TipTap 3 Integration, Enhanced SSR Compatibility

✨ Features

• 🎯 ADHD-Optimized Design: Components designed with cognitive load reduction in mind
• ♿ Accessibility First: WCAG 2.1 AA compliant with comprehensive screen reader support
• 🏗️ SSR Ready: Full server-side rendering compatibility with SvelteKit
• 🎨 Themeable: Built-in light/dark mode with customizable design tokens
• 📱 Responsive: Mobile-first design with flexible layouts
• 🔧 TypeScript: Fully typed API with excellent IntelliSense support
• 🌳 Tree Shakeable: Import only what you need for optimal bundle size
• 📖 Well Documented: Comprehensive Storybook documentation with examples

📦 Installation

npm install claritykit-svelte

pnpm add claritykit-svelte

yarn add claritykit-svelte

🚀 Quick Start

Basic Usage

<script>
  import { Button, Card, Alert } from 'claritykit-svelte';
  import 'claritykit-svelte/styles/tokens.css';
  import 'claritykit-svelte/styles/components.css';
</script>

<Card>
  <h2>Welcome to ClarityKit</h2>
  <p>A beautiful, accessible component library for Svelte.</p>
  <Button variant="primary" onclick={() => alert('Hello!')}>
    Get Started
  </Button>
</Card>

With SvelteKit

// app.html or +layout.svelte
import 'claritykit-svelte/styles/tokens.css';
import 'claritykit-svelte/styles/components.css';

Individual Component Imports

<script>
  // Tree-shakeable imports
  import { Button } from 'claritykit-svelte';
  import { Card } from 'claritykit-svelte';
  import type { ButtonVariant } from 'claritykit-svelte';
</script>

Specialized Bundle Imports

<script>
  // Import specific bundles for optimal performance
  import { Button, Input, Card } from 'claritykit-svelte/essentials';
  import { ChatThread, AgentCard } from 'claritykit-svelte/agent';
  import { LineChart, BarChart } from 'claritykit-svelte/data-viz';
  import { BlockEditor } from 'claritykit-svelte/knowledge';
</script>

🎨 Styling

ClarityKit uses CSS custom properties for theming. Import the base styles and customize as needed:

/* Import base styles */
@import 'claritykit-svelte/styles/tokens.css';
@import 'claritykit-svelte/styles/components.css';

/* Customize theme */
:root {
  --ck-color-primary: #3b82f6;
  --ck-color-secondary: #6366f1;
  --ck-border-radius: 8px;
}

🔧 Troubleshooting

Common Issues

SvelteKit Import Errors

If you see "Unexpected token" errors when importing in SvelteKit, ensure you're using the correct import paths:

// ✅ Correct - Use specialized bundles
import { Button } from 'claritykit-svelte/essentials';
import { ChatThread } from 'claritykit-svelte/agent';

// ❌ Avoid - May cause import issues
import { Button, ChatThread } from 'claritykit-svelte';

TypeScript Errors

For better TypeScript support, import types explicitly:

import type { ButtonVariant, InputSize } from 'claritykit-svelte';
import { Button, Input } from 'claritykit-svelte/essentials';

ValidatedInput Issues

If you encounter validation errors, ensure rules are properly formatted:

<script>
  import { ValidatedInput } from 'claritykit-svelte/form';
  
  // ✅ Correct - Array of validation functions
  const rules = [
    (value) => value.length > 0 || 'Required',
    (value) => value.includes('@') || 'Must be valid email'
  ];
</script>

<ValidatedInput validationRules={rules} />

SSR Compatibility

For server-side rendering, some components require client-side guards:

<script>
  import { browser } from '$app/environment';
  import { KnowledgeGraph } from 'claritykit-svelte/knowledge';
</script>

{#if browser}
  <KnowledgeGraph {nodes} {edges} />
{/if}

Browser Compatibility

• Chrome: 90+ ✅
• Firefox: 88+ ✅
• Safari: 14+ ✅
• Edge: 90+ ✅

Component Categories

187+ Components Across 12 Categories

• Primitives: Button, Input, Checkbox, Radio, Switch, Avatar, Loader, StatusDot, etc.
• Layout: Container, Grid, Card, Modal, Sidebar, Popover, GalleryView, ListView, etc.
• Feedback: Alert, Toast, StatusIndicator, LoadingSpinner, Progress indicators, etc.
• Data Visualization: Charts (Line, Bar, Area, Pie, Scatter, Network), KPI cards, Metrics, Dashboard widgets, etc.
• Form: Enhanced Select with search/multi-select/async loading, FormField, Textarea, DatePicker, validation, etc.
• Navigation: Tabs, Badge, CommandPalette, WorkspaceSelector, Breadcrumbs, etc.
• Agent & AI: AgentCard, PlanCard, ChatThread, AgentLogView, AISettings, CollaborativeWorkspace, etc.
• Knowledge Management: BlockEditor, CollaborativeBlockEditor, KnowledgeGraph, SemanticTagger, etc.
• Research: NEW CitationFormatter, PaperMetadataCard, ResearchDiscoveryPanel, PaperIngestionProgress, etc.
• BMS: Business Management System components for workflow automation and integration
• Therapeutic: ADHD-specific components like CrisisModeToggle, MoodTracker, EnergyLevelIndicator, etc.
• Interactive: Gantt charts, Task management, Kanban boards, etc.

🧠 Personal Knowledge Management (PKM)

ClarityKit provides a complete suite of PKM components designed for building modern knowledge management applications, note-taking tools, and collaborative platforms.

Core PKM Components

BlockEditor

A rich TipTap-based block editor with AI assistance capabilities:

<script>
  import { BlockEditor } from 'claritykit-svelte';
  
  let content = '<p>Start typing...</p>';
</script>

<BlockEditor 
  bind:content
  placeholder="What's on your mind?"
  enableAI={true}
  onSave={(html) => console.log('Saved:', html)}
/>

CollaborativeBlockEditor

Real-time collaborative editing powered by Hocuspocus and Yjs:

<script>
  import { CollaborativeBlockEditor, HocuspocusCollaborationProvider } from 'claritykit-svelte';
  
  const provider = new HocuspocusCollaborationProvider({
    url: 'wss://your-collab-server.com',
    name: 'document-123'
  });
</script>

<CollaborativeBlockEditor 
  {provider}
  userName="John Doe"
  userColor="#3b82f6"
  enablePresenceIndicators={true}
/>

KnowledgeGraph

Interactive knowledge graphs using Cytoscape.js:

<script>
  import { KnowledgeGraph } from 'claritykit-svelte';
  
  const nodes = [
    { id: 'concept1', label: 'Machine Learning', category: 'technology' },
    { id: 'concept2', label: 'Neural Networks', category: 'technology' },
    { id: 'concept3', label: 'Deep Learning', category: 'technology' }
  ];
  
  const edges = [
    { source: 'concept1', target: 'concept2', relationship: 'includes' },
    { source: 'concept2', target: 'concept3', relationship: 'enables' }
  ];
</script>

<KnowledgeGraph 
  {nodes}
  {edges}
  layout="cose"
  enablePhysics={true}
  onNodeClick={(node) => console.log('Clicked:', node)}
/>

SemanticTagger

AI-powered semantic tagging and concept extraction:

<script>
  import { SemanticTagger } from 'claritykit-svelte';
  
  let selectedTags = [];
  
  const concepts = [
    { id: 1, term: 'machine learning', definition: 'AI technique for pattern recognition' },
    { id: 2, term: 'neural network', definition: 'Computing system inspired by biological neural networks' }
  ];
</script>

<SemanticTagger
  {concepts}
  bind:selectedTags
  enableAIExtraction={true}
  onTagCreate={(tag) => console.log('New tag:', tag)}
/>

MaterialViewTable

Advanced table component with filtering, sorting, and views:

<script>
  import { MaterialViewTable } from 'claritykit-svelte';
  
  const data = [
    { id: 1, title: 'Research Paper', type: 'document', tags: ['AI', 'ML'] },
    { id: 2, title: 'Meeting Notes', type: 'note', tags: ['meeting', 'planning'] }
  ];
  
  const columns = [
    { key: 'title', label: 'Title', sortable: true },
    { key: 'type', label: 'Type', filterable: true },
    { key: 'tags', label: 'Tags', render: 'tags' }
  ];
</script>

<MaterialViewTable 
  {data}
  {columns}
  searchable={true}
  exportable={true}
  viewModes={['table', 'card', 'list']}
/>

DatabaseView

Notion-style database views with multiple display modes:

<script>
  import { DatabaseView } from 'claritykit-svelte';
  
  const data = [
    { id: 1, name: 'Project Alpha', status: 'active', priority: 'high' },
    { id: 2, name: 'Project Beta', status: 'planning', priority: 'medium' }
  ];
</script>

<DatabaseView
  {data}
  view="kanban"
  groupBy="status"
  enableInlineEditing={true}
  onUpdate={(item) => console.log('Updated:', item)}
/>

RichTextToolbar

Customizable toolbar for rich text editing:

<script>
  import { RichTextToolbar } from 'claritykit-svelte';
  
  let editor; // TipTap editor instance
</script>

<RichTextToolbar
  {editor}
  tools={['bold', 'italic', 'link', 'image', 'code', 'list']}
  variant="floating"
/>

PKM Features

• 🔄 Real-time Collaboration: Multi-user editing with presence indicators
• 🤖 AI Integration: Smart suggestions, auto-tagging, and content enhancement
• 🔗 Bidirectional Linking: Create and navigate knowledge connections
• 📊 Multiple Views: Table, kanban, graph, timeline, and calendar views
• 🏷️ Semantic Tagging: AI-powered concept extraction and organization
• 📱 Responsive Design: Optimized for desktop and mobile PKM workflows
• 🔍 Advanced Search: Full-text search with semantic understanding
• 📤 Export Capabilities: Multiple format support (Markdown, JSON, CSV)

Getting Started with PKM

npm install claritykit-svelte

<script>
  import { 
    BlockEditor,
    KnowledgeGraph,
    SemanticTagger,
    MaterialViewTable 
  } from 'claritykit-svelte';
  import 'claritykit-svelte/styles/tokens.css';
  import 'claritykit-svelte/styles/components.css';
  
  let notes = [];
  let tags = [];
</script>

<!-- Your PKM Application -->
<main class="pkm-app">
  <BlockEditor placeholder="Capture your thoughts..." />
  <KnowledgeGraph nodes={notes} />
  <MaterialViewTable data={notes} />
</main>

🔬 Research Components (NEW in v1.6.0)

ClarityKit now includes specialized components for academic research and paper management workflows.

CitationFormatter

Format citations in multiple academic styles:

<script>
  import { CitationFormatter } from 'claritykit-svelte';
  
  const paper = {
    title: "Machine Learning Applications in Healthcare",
    authors: ["Smith, J.", "Doe, A."],
    year: 2024,
    journal: "Journal of AI Research",
    volume: 15,
    pages: "123-145"
  };
</script>

<CitationFormatter 
  {paper}
  style="apa"
  editable={true}
  onEdit={(updatedPaper) => console.log('Updated:', updatedPaper)}
/>

PaperMetadataCard

Display and edit research paper metadata:

<script>
  import { PaperMetadataCard } from 'claritykit-svelte';
  
  const metadata = {
    title: "Research Paper Title",
    authors: ["Author One", "Author Two"],
    abstract: "Paper abstract here...",
    keywords: ["AI", "machine learning", "research"],
    doi: "10.1000/182"
  };
</script>

<PaperMetadataCard 
  {metadata}
  editable={true}
  showValidation={true}
  onSave={(updated) => console.log('Saved:', updated)}
/>

ResearchDiscoveryPanel

Discover and explore research papers:

<script>
  import { ResearchDiscoveryPanel } from 'claritykit-svelte';
  
  let searchQuery = "";
  let filters = { year: "2024", field: "computer-science" };
</script>

<ResearchDiscoveryPanel
  bind:searchQuery
  bind:filters
  enableAIRecommendations={true}
  onPaperSelect={(paper) => console.log('Selected:', paper)}
/>

Research Features

• 📄 Citation Management: Support for APA, MLA, Chicago, and IEEE citation styles
• 🔍 Paper Discovery: AI-powered research paper recommendations
• 📊 Metadata Validation: Ensure citation completeness and accuracy
• 🏷️ Keyword Extraction: Automatic keyword and topic identification
• 📈 Progress Tracking: Monitor research paper processing and analysis
• 🔗 DOI Integration: Automatic metadata fetching from DOI lookups

🛡️ Quality Assurance

ClarityKit maintains the highest standards of quality through comprehensive automated testing and quality gates:

Continuous Integration

• Multi-Node Testing: Automated testing across Node.js 18, 20, and 22
• Accessibility Testing: Automated WCAG 2.1 AA compliance verification
• Cross-Browser Testing: Chromium, Firefox, Safari, and Edge support
• Visual Regression Testing: Chromatic integration for visual consistency
• Security Auditing: Automated vulnerability scanning and dependency updates

Quality Gates

• Test Coverage: Minimum 85% code coverage requirement
• Type Safety: Full TypeScript coverage with strict mode
• Accessibility Compliance: Automated axe-core testing
• Component Testing: Individual component and utility testing
• Build Verification: Package integrity and SSR compatibility checks

Development Workflow

• Automated Releases: Semantic versioning with Changesets
• Dependency Updates: Automated security updates via Dependabot
• Code Quality: ESLint, Prettier, and Stylelint enforcement
• Performance Monitoring: Bundle size analysis and optimization

📖 Documentation

Primary Resources

• Storybook Documentation - Interactive component examples and API documentation
• Contributing Guide - Comprehensive guide for contributors
• Accessibility Guidelines - WCAG compliance and accessibility patterns
• ADHD Design Principles - Cognitive load optimization strategies

Additional Documentation

• Component API Reference - Complete API documentation
• SSR Integration Guide - Server-side rendering setup
• Migration Guides - Version upgrade instructions
• Design System - Design tokens and styling guidelines

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

• Development setup and workflow
• Component development guidelines
• Testing requirements
• Accessibility standards
• ADHD optimization principles
• Pull request process

Quick Contribution Setup

# Fork and clone the repository
git clone https://github.com/your-username/ClarityKit_svelte.git
cd ClarityKit_svelte

# Install dependencies
npm ci

# Start development environment
npm run storybook

# Run tests
npm test

Development

Setup

# Clone the repository
git clone https://github.com/warkrismagic/ClarityKit_svelte.git
cd ClarityKit_svelte

# Install dependencies
npm install

# Start Storybook
npm run storybook

Scripts

• npm run dev: Start development server
• npm run build: Build the library
• npm run storybook: Start Storybook
• npm run build-storybook: Build Storybook
• npm run test: Run tests
• npm run lint: Run linting

License

Apache License 2.0