@bitcoin-os/ui-kit

@bitcoin-os/ui-kit

Unified design system and component library for the Bitcoin OS ecosystem. Provides consistent theming, authentication, and UI components across all Bitcoin applications.

Features

• 🎨 Unified Theme System - User-controlled look & feel across all bApps
• 🔐 Cross-App Authentication - Login once, access all subscribed apps
• 📱 Responsive Components - Works on desktop and mobile
• 🎯 TypeScript Support - Full type safety
• 🚀 BSV Integration - Built for Bitcoin SV ecosystem
• 📦 Tree Shakeable - Import only what you need

Installation

npm install @bitcoin-os/ui-kit

Quick Start

1. Wrap your app with providers

import { ThemeProvider, AuthProvider } from '@bitcoin-os/ui-kit'

function App() {
  return (
    <ThemeProvider>
      <AuthProvider>
        <YourApp />
      </AuthProvider>
    </ThemeProvider>
  )
}

2. Use components and hooks

import { CleanTaskbar, useTheme, useAuth } from '@bitcoin-os/ui-kit'

function YourApp() {
  const { theme, setTheme, isDarkMode, toggleDarkMode } = useTheme()
  const { user, isAuthenticated, login, logout } = useAuth()

  return (
    <div>
      <CleanTaskbar 
        onSettingsClick={() => console.log('Settings')}
        onProfileClick={() => console.log('Profile')}
      />
      {/* Your app content */}
    </div>
  )
}

Components

CleanTaskbar

A minimal, macOS-style taskbar for Bitcoin OS applications.

<CleanTaskbar 
  showThemeToggle={true}
  showUserMenu={true}
  onSettingsClick={() => openSettings()}
  onProfileClick={() => openProfile()}
/>

Theming

Using Predefined Themes

import { useTheme } from '@bitcoin-os/ui-kit'

function ThemeSelector() {
  const { applyPreset, themePresets } = useTheme()

  return (
    <div>
      <button onClick={() => applyPreset('dark')}>Dark Theme</button>
      <button onClick={() => applyPreset('light')}>Light Theme</button>
      <button onClick={() => applyPreset('orange')}>Orange Theme</button>
      <button onClick={() => applyPreset('green')}>Green Theme</button>
      <button onClick={() => applyPreset('purple')}>Purple Theme</button>
    </div>
  )
}

Custom Theme

import { useTheme } from '@bitcoin-os/ui-kit'

function CustomTheme() {
  const { setTheme } = useTheme()

  const applyCustomTheme = () => {
    setTheme({
      colors: {
        primary: '#ff6500',
        accent: '#ffd700',
        background: '#1a1a1a'
      }
    })
  }

  return <button onClick={applyCustomTheme}>Apply Custom Theme</button>
}

Authentication

Basic Authentication

import { useAuth } from '@bitcoin-os/ui-kit'

function LoginForm() {
  const { login, logout, isAuthenticated, user } = useAuth()

  const handleLogin = async () => {
    try {
      await login('[e-mail]', 'password')
    } catch (error) {
      console.error('Login failed:', error)
    }
  }

  if (isAuthenticated) {
    return (
      <div>
        Welcome, {user?.username}!
        <button onClick={logout}>Logout</button>
      </div>
    )
  }

  return <button onClick={handleLogin}>Login</button>
}

Subscription Management

import { useAuth } from '@bitcoin-os/ui-kit'

function SubscriptionCheck({ appId }: { appId: string }) {
  const { hasSubscription, hasPermission } = useAuth()

  if (!hasSubscription(appId)) {
    return <div>Please subscribe to access this app</div>
  }

  if (!hasPermission(appId, 'read')) {
    return <div>Insufficient permissions</div>
  }

  return <div>Access granted!</div>
}

TypeScript

Full TypeScript support with comprehensive type definitions:

import type { 
  BitcoinOSTheme, 
  BitcoinOSUser, 
  BitcoinOSAuth,
  UserSubscription 
} from '@bitcoin-os/ui-kit'

const customTheme: Partial<BitcoinOSTheme> = {
  colors: {
    primary: '#f7931a',
    secondary: '#2d2d2d'
  }
}

Configuration

Theme Provider Options

<ThemeProvider
  initialTheme={customTheme}
  storageKey="my-app-theme"
>
  <App />
</ThemeProvider>

Auth Provider Options

<AuthProvider
  apiBaseUrl="/api/v1"
  storageKey="my-app-auth"
>
  <App />
</AuthProvider>

Development

# Install dependencies
npm install

# Start development
npm run dev

# Build package
npm run build

# Run tests
npm test

# Start Storybook
npm run storybook

Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

License

This project is licensed under the Open BSV License v5 - see the LICENSE file for details.

Support

• Documentation: Bitcoin OS Docs
• Issues: GitHub Issues
• Email: [e-mail]

Built with ❤️ by The Bitcoin Corporation LTD