@nexcraft/forge

October 5, 2025 · View on GitHub

"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.

🤖 FOR AI ASSISTANTS & LLMs

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-react'
🌲 Selective: import { ForgeButton } from '@nexcraft/forge/button'
🎨 Tailwind: import forgePlugin from '@nexcraft/forge/plugin'
📝 Forms: import { RHFForgeInput } from '@nexcraft/forge-rhf'

📚 AI Documentation:

🤖 AI Metadata Reference - Complete AI metadata system guide (interfaces, methods, implementation)
🤖 AI Integration Guide - ChatGPT, Claude, Copilot integration examples & common patterns
🎨 Styling Guide - Complete styling reference (variants, CSS, Tailwind)
📦 Import Guide - All import methods & framework examples
🤖 AI Manifest - Structured component metadata

🤖 AI Manifest Files - Machine-Readable Component Metadata

Forge provides comprehensive, machine-readable metadata files that AI assistants and build tools can consume programmatically:

📋 Available Files

1. ai-index.json - Fast component discovery (465 lines)

Quick component lookup by tag/description
Framework usage examples (React, Vue, Angular, vanilla)
Component metrics (props count, events, slots, a11y)
Navigation to detailed resources

2. ai-manifest.json - Complete API reference (2000+ lines)

Full component metadata (props, events, slots with types)
Accessibility details (ARIA, keyboard nav, screen reader behavior)
AI method documentation (getPossibleActions, explainState, aiState)
SSR fallback HTML templates
Framework-specific examples

3. ai-manifest.schema.json - Schema validation

JSON Schema for validating manifest structure
Use in CI/CD pipelines to ensure quality

💻 Programmatic Access

// Import manifest files directly from the package
import aiIndex from '@nexcraft/forge/ai-index.json';
import aiManifest from '@nexcraft/forge/ai-manifest.json';

// Quick discovery: Find components by capability
const selectComponents = aiIndex.components.filter(c =>
  c.tag.includes('select')
);
// [{ tag: 'forge-select', props: 39, ... },
//  { tag: 'forge-multi-select', props: 32, ... }]

// Detailed API: Get full component metadata
const buttonMeta = aiManifest.components.find(c =>
  c.tag === 'forge-button'
);
console.log(buttonMeta.props);     // All props with types
console.log(buttonMeta.a11y);      // Accessibility requirements
console.log(buttonMeta.aiMethods); // AI integration methods

🤖 AI Agent Usage Examples

AI assistants use these files to provide accurate code generation:

Scenario 1: Component Discovery

User: "I need a component for notifications"
AI: [Reads ai-index.json] → Finds forge-toast and forge-alert
AI: "Use forge-toast for temporary notifications or forge-alert for persistent messages"

Scenario 2: Code Generation

User: "Create a primary button that's disabled"
AI: [Reads ai-manifest.json] → Gets forge-button props
AI: Generates: <forge-button variant="primary" disabled>Submit</forge-button>

Scenario 3: Accessibility Verification

User: "Is my table accessible?"
AI: [Reads ai-manifest.json] → Checks forge-data-table a11y requirements
AI: "Add aria-label: <forge-data-table aria-label='User accounts'>..."

🛠️ Build Tool Integration

// Use in build scripts, documentation generators, or testing tools
import { components } from '@nexcraft/forge/ai-index.json';

// Generate component documentation
components.forEach(comp => {
  generateDocs(comp.tag, comp.description, comp.examples);
});

// Validate component usage
function validateComponent(tagName, props) {
  const manifest = getComponentFromManifest(tagName);
  const validProps = manifest.props.map(p => p.name);
  const invalidProps = Object.keys(props).filter(p => !validProps.includes(p));
  if (invalidProps.length) {
    throw new Error(`Invalid props: ${invalidProps.join(', ')}`);
  }
}

📖 Learn More

Component Index - Browse all 31 components with quick metrics
Full API Reference - Complete component specifications
AI Integration Guide - How to use AI features in your app

🎯 Why Choose @nexcraft/forge?

✨ What Makes @nexcraft/forge Special:

// @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

💡 Real-World Benefits:

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

🚀 Quick Start (30 Seconds!)

Option 1: Zero-Config CDN (Instant!)

<!-- 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>

Option 2: NPM Installation

npm install @nexcraft/forge

Works with EVERY Framework (Same Code!)

// 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 (with dedicated package)
npm install @nexcraft/forge-vue
<template>
  <forge-button @click="handleClick" :ai-context="context">Click</forge-button>
</template>

// Angular Example (with dedicated package)
npm install @nexcraft/forge-angular
// In Angular templates
<forge-button forgeComponent (click)="handleClick()" [aiContext]="context">Click</forge-button>

// Vanilla JS - Full Power!
const btn = document.querySelector('forge-button');
console.log(btn.getPossibleActions()); // AI-ready!

Development Setup

# 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 tests

📦 Framework Packages

Core Package

@nexcraft/forge - Pure web components (truly framework-agnostic)

Optional Framework Extensions

@nexcraft/forge-react - React wrappers, hooks & SSR support
@nexcraft/forge-vue - Vue composables, directives & plugin
@nexcraft/forge-angular - Angular directives, services & reactive forms
@nexcraft/forge-rhf - React Hook Form adapters

# Install what you need
npm install @nexcraft/forge                    # Pure web components
npm install @nexcraft/forge-react             # + React integration
npm install @nexcraft/forge-vue               # + Vue composables & plugin
npm install @nexcraft/forge-angular           # + Angular integration  
npm install @nexcraft/forge-rhf               # + React Hook Form

📖 View Integration Guides → — React: docs/integrations/react.md • Angular: docs/integrations/angular.md • Vue: docs/integrations/vue.md

📋 Component Index

Quick reference to all 26 components with HTML tag names:

Organisms (6 components)

<forge-tabs> • <forge-pagination> • <forge-navigation-bar> • <forge-data-table> • <forge-accordion> • <forge-tree-view>

Molecules (8 components)

<forge-tooltip> • <forge-date-picker> • <forge-dropdown> • <forge-form-field> • <forge-modal> • <forge-multi-select> • <forge-card> • <forge-toast>

Atoms (12 components)

<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.

📚 Documentation

Getting Started

Quick Start Guide - Get your first component running in 4 hours
Component Architecture - Atomic design patterns & composition
Component API Design - API standards & conventions

Core Features

🤖 AI Metadata Reference - Complete AI metadata system guide (architecture, API, implementation)
🤖 AI Integration Guide - ChatGPT, Claude, Copilot examples & common patterns
🤖 AI-Native Development - Building with AI coding assistants
🎨 Theming Overview - Core theming concepts and strategies
🎨 Token Bridge Reference - Complete guide and API for design token conversion
🔄 Token Migration Guide - Migrate from existing token systems
⚡ Performance Dashboard Guide - Real-time performance monitoring
⚡ Performance Monitoring - Advanced performance monitoring system
Figma → Forge Tokens - Pull tokens from Figma via CLI/MCP (no plugin required)

Architecture & Planning

Implementation Roadmap - Complete development timeline with all differentiators
🚀 Phase 9: AI-Native Development - Strategic pivot to AI-first component library
Architecture Decision Records - 18 key technical decisions including AI-native components
Build Tooling Strategy - Vite, Lit, TypeScript stack decisions

✨ The "Shiny" Stuff - What Makes Us Special

🤖 AI-Native Components (Industry First!)

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 }

🎨 Design Token Bridge (Industry First!)

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; }

⚡ Performance Dashboard (Unique Feature!)

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!

🎯 Core Differentiators

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

🚀 Zero-Config Magic

<!-- 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>

🏗️ Architecture

Core Technologies

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

Key Principles

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

📦 Components Showcase

🏛️ Organism Components (Phase 3 - Production Ready!)

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

🌟 Molecule Components (Advanced & Feature-Rich)

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

⚙️ Atomic Components (Foundation + Essential)

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

📊 Component Stats

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!

Roadmap

See our Implementation Roadmap for the complete component timeline.

🧪 Testing

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Visual regression
npm run test:visual

# All tests
npm run test:all

Our comprehensive testing strategy includes:

✅ Unit tests (90%+ coverage)
✅ Visual regression (Chromatic)
✅ Cross-framework E2E tests
✅ Accessibility audits
✅ Performance benchmarks

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Commands

# 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

📊 Performance & Quality Metrics

🏆 Phase 8 Started - Enterprise Data Grid Delivered!

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

🏆 Phase 7 Complete - Essential Components Foundation!

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

🚀 Why This Matters

🏗️ 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

📄 License

🔗 Links

NPM Package - Published package
GitHub - Source code
Storybook - Live component playground (Coming Soon)
Documentation - Complete planning documentation

💡 Philosophy & Vision

"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.

// 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 debt

🚀 Join the Revolution

Stop rewriting. Start building components that outlive frameworks.