@tuwaio/nova-core

@tuwaio/nova-core is the UI Core (L6) package of the TUWA Ecosystem design system. It acts as the shared foundation for styling primitives, CSS variable definitions, base React elements, and helper utilities. Fully independent of Web3 logic, it provides the common design boundaries consumed by visual modules like @tuwaio/nova-connect and @tuwaio/nova-transactions to maintain visual consistency across all TUWA interfaces.

🏛️ Core Capabilities

• 🎨 Design Token System: Declares variables for colors, typography, borders, animations, and spacing, with built-in switching for light and dark modes.
• 🛠️ Style Merger (cn): An optimized composition utility blending clsx and tailwind-merge to resolve style overrides dynamically without class conflicts.
• ⚡ Tailwind CSS v4 Native: Configured to map variables into Tailwind's modern engine, allowing arbitrary class declarations.
• ♿ Base Components & Primitives: Shared layout modules, dialog nodes, overlays, and common utility indicators.
• 📱 Shared React Hooks: Reusable, performance-optimized hooks for clipboards (useCopyToClipboard) and responsive layouts (useMediaQuery).

💾 Installation

pnpm add @tuwaio/nova-core

CSS Setup

Import the core CSS styles into the entrypoint of your application (e.g., main.css or globals.css):

@import '@tuwaio/nova-core/dist/index.css';

🚀 Usage Guide

1. Tailwind Arbitrary Tokens

Use Nova custom variables directly in components for consistent styling:

export function AccentCard() {
  return (
    <div className="p-6 bg-[var(--tuwa-bg-secondary)] border border-[var(--tuwa-border-primary)] rounded-[var(--tuwa-rounded-corners)]">
      <h3 className="text-[var(--tuwa-text-primary)] font-medium">Core Primitive Card</h3>
      <p className="mt-2 text-[var(--tuwa-text-secondary)] text-sm">Styled using central ecosystem design tokens.</p>
      <button className="mt-4 px-4 py-2 bg-[var(--tuwa-text-accent)] text-[var(--tuwa-text-on-accent)]">Action</button>
    </div>
  );
}

2. Styling Composition (cn)

Blend default styles with external prop overrides cleanly:

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

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary';
}

export function Button({ variant = 'primary', className, ...props }: ButtonProps) {
  return (
    <button
      className={cn(
        'px-4 py-2 font-medium rounded transition-colors',
        variant === 'primary'
          ? 'bg-[var(--tuwa-text-accent)] text-[var(--tuwa-text-on-accent)]'
          : 'bg-[var(--tuwa-standart-button-bg)] text-[var(--tuwa-text-primary)] hover:bg-[var(--tuwa-standart-button-hover)]',
        className,
      )}
      {...props}
    />
  );
}

3. Clipboard copy with useCopyToClipboard

Easily build wallet address display nodes with copying feedback:

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

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

  return (
    <button
      onClick={() => copy(address)}
      className="font-mono text-xs text-[var(--tuwa-text-secondary)] hover:text-[var(--tuwa-text-accent)]"
    >
      {address.slice(0, 6)}...{address.slice(-4)}
      {copied ? ' (Copied ✓)' : ' (Copy)'}
    </button>
  );
}

🎨 Theme Customization

Override default tokens in your global CSS stylesheet to match your brand:

:root {
  /* Customize Brand Accent Colors */
  --tuwa-text-accent: #10b981; /* Emerald-500 */
  --tuwa-text-on-accent: #ffffff;
  --tuwa-rounded-corners: 8px;
}

/* Customize Dark Mode styling */
.dark {
  --tuwa-bg-primary: #050505;
  --tuwa-bg-secondary: #121212;
  --tuwa-border-primary: #222222;
}

🔧 API & Module Architecture

@tuwaio/nova-core exports the following modules and functions:

• Style Composition: cn.
• React Hooks: useCopyToClipboard, useMediaQuery.
• UI Dialog Primitives: Dialog, DialogOverlay, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter.
• Utility Indicators: StarsBackground, FallbackIcon, GithubFallbackIcon, ChevronArrowWithAnim, ToastCloseButton, ToastValidationError, NetworkIcon, WalletIcon.
• Formatters: deepMerge, svgToBase64, isTouchDevice, textCenterEllipsis, resolveCssVariable.

📄 License

Licensed under the Apache-2.0 License. See the LICENSE file for details.