@tuwaio/nova-core

TUWA Nova Core

The foundational package for the TUWA ecosystem, Nova Core serves as the shared foundation that powers all other Nova packages (@tuwaio/nova-connect, @tuwaio/nova-transactions).

Why Nova Core??

Building design systems requires consistent foundations: colors, spacing, typography, and utility functions. Without a shared core, different packages end up with conflicting styles, duplicated code, and inconsistent user experiences.

Nova Core solves this by:

• Offering Smart Utilities: Battle-tested helper functions like the cn utility that combines clsx and tailwind-merge for conflict-free styling.
• Supplying Common Hooks: A collection of reusable React hooks for common UI patterns.
• Ensuring Tailwind CSS v4 Integration: Seamless compatibility with modern Tailwind CSS workflows.

✨ Key Features

• 🎨 Complete Design Token System: Comprehensive CSS variables for colors, spacing, typography, shadows, and animations
• 🛠️ Smart Utility Functions: Advanced cn utility that merges Tailwind classes intelligently, preventing style conflicts
• ⚡ Tailwind CSS v4 Ready: Full compatibility with modern Tailwind CSS workflows and arbitrary value usage
• 🌓 Dark Mode Support: Built-in dark mode theming with CSS variable-based switching
• ♿ Accessibility First: ARIA-compliant design tokens and utilities for building accessible interfaces
• 📱 Responsive Design: Mobile-first breakpoints and responsive utility functions

💾 Installation

Requirements

• React: 19+
• Node.js: 20-24
• TypeScript: 5.9+ (recommended)

Package Installation

Install the package using your preferred package manager:

# Using pnpm (recommended), but you can use npm, yarn or bun as well
pnpm add @tuwaio/nova-core

CSS Setup

⚠️ Critical Step: Import the core styles into your application's main CSS file. This step is essential for accessing base styles.

/* src/styles/globals.css or src/styles/app.css */
@import '@tuwaio/nova-core/dist/index.css';

🚀 Usage

Design Tokens with Tailwind CSS v4

Nova Core is designed to work seamlessly with Tailwind CSS v4. You can use the CSS variables directly in your className as arbitrary values:

// Using Nova design tokens in Tailwind classes
<button className="bg-[var(--tuwa-text-accent)] text-[var(--tuwa-text-on-accent)]">
  Connect Wallet
</button>

// With hover states and transitions
<div className="
  p-4
  bg-[var(--tuwa-bg-secondary)]
  hover:bg-[var(--tuwa-bg-muted)]
  transition-colors
">
  Card Content
</div>

The cn Utility Function

The cn utility combines clsx and tailwind-merge to provide intelligent class merging:

import { cn } from '@tuwaio/nova-core';

// Basic usage
const buttonClass = cn(
  'px-4 py-2 font-medium rounded-lg', // base styles
  'bg-blue-500 text-white', // default variant
  { 'opacity-50 cursor-not-allowed': isLoading }, // conditional styles
  className, // additional classes from props
);

// Tailwind class conflict resolution
const mergedClasses = cn(
  'p-4 text-sm', // base classes
  'p-6 text-lg', // these override the base classes intelligently
);
// Result: 'p-6 text-lg' (conflicts resolved)

Common React Hooks

Nova Core provides several utility hooks for common UI patterns:

import { cn, useCopyToClipboard } from '@tuwaio/nova-core';

function WalletAddress({ address }: { address: string }) {
  const [copied, copy] = useCopyToClipboard();

  return (
    <div className={cn('transition-all', { 'w-12': isCollapsed })}>
      <button onClick={() => copy(address)} className="font-mono text-sm hover:bg-[var(--tuwa-bg-hover)]">
        {address.slice(0, 6)}
        {copied && ' ✓'}
      </button>
    </div>
  );
}

🛠️ Theme Customization

Basic Customization

Override design tokens in your CSS to match your brand:

/* src/styles/globals.css */
@import '@tuwaio/nova-core/dist/index.css';

/* Your custom theme overrides */
:root {
  /* Text Colors */
  --tuwa-text-primary: #0f172a;
  --tuwa-text-secondary: #64748b;
  --tuwa-text-tertiary: #94a3b8;
  --tuwa-text-accent: #3b82f6;
  --tuwa-text-on-accent: #ffffff;

  /* Background System */
  --tuwa-bg-primary: #ffffff;
  --tuwa-bg-secondary: #f8fafc;
  --tuwa-bg-muted: #f1f5f9;

  /* Border System */
  --tuwa-border-primary: #e2e8f0;
  --tuwa-border-secondary: #cbd5e1;
}

Dark Mode Support

Nova Core includes built-in dark mode support:

/* Dark mode overrides */
.dark {
  --tuwa-text-primary: #f1f5f9;
  --tuwa-text-secondary: #9ca3af;
  --tuwa-text-accent: #60a5fa;
  --tuwa-bg-primary: #0f172a;
  --tuwa-bg-secondary: #1e293b;
  --tuwa-bg-muted: #334155;
  --tuwa-border-primary: #374151;
}

Advanced Usage

Component Integration

Nova Core works seamlessly with other Nova packages:

import { cn } from '@tuwaio/nova-core';
import { ConnectButton } from '@tuwaio/nova-connect/components';
import { NovaTransactionsProvider } from '@tuwaio/nova-transactions';

function App() {
  return (
    <div className={cn('min-h-screen', 'bg-[var(--tuwa-bg-primary)]', 'text-[var(--tuwa-text-primary)]')}>
      <NovaTransactionsProvider {...params} />
      <header className="border-b border-[var(--tuwa-border-primary)]">
        <ConnectButton />
      </header>
      <main>{/* Your app content */}</main>
    </div>
  );
}

API Reference

Utilities

Function	Description	Usage
cn(...classes)	Merges class names intelligently, resolving Tailwind conflicts	cn('p-4 text-sm', 'p-6', {'hidden': conditional})

Hooks

Hook	Description	Return Type
useCopyToClipboard()	Copy text to clipboard with feedback	[boolean, (text: string) => void]
useMediaQuery(query)	Responsive media query hook	boolean

🤝 Contributing & Support

Contributions are welcome! Please read our main Contribution Guidelines.

If you find this library useful, please consider supporting its development. Every contribution helps!

➡️ View Support Options

📄 License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.