@unicitylabs/sphere-ui

Shared UI library for the Sphere ecosystem. Provides a unified design system, components, and hooks used across all Sphere applications.

Packages that use sphere-ui

App	Description
sphere	Wallet & marketplace
sphere-dev-portal	Developer Portal
sphere-backoffice	Admin panel
sphere-quest	Quest frontend (iframe)

Installation

npm install @unicitylabs/sphere-ui

For local development, link from the monorepo:

npm install file:../sphere-ui

Usage

Styles

Import the design system in your app's entry point:

import '@unicitylabs/sphere-ui/styles';

This provides:

• Tailwind 4 theme tokens (colors, fonts, shadows, radii)
• Light/dark mode CSS variables
• Component classes (sphere-card, btn-primary, badge-*, sphere-input, etc.)

Components

import {
  Field,
  Section,
  FormModal,
  ConfirmDialog,
  DataTable,
  StatusBadge,
  SearchInput,
  EmptyState,
  CustomSelect,
  PageShell,
  AlertBanner,
  AddressDisplay,
  JsonPanel,
  JsonToggleButton,
  ChainInput,
  MemoConditionsEditor,
} from '@unicitylabs/sphere-ui';

Hooks

import {
  useCanvasState,
  useAchievementCanvasState,
  useTestMode,
  useChainMode,
  useAchievementTestMode,
  useAchievementChainMode,
} from '@unicitylabs/sphere-ui/hooks';

Icons

import {
  IconBack, IconUndo, IconEdit, IconTrash, IconPlus,
  IconSearch, IconCheck, IconX, IconChain, IconPlay,
  IconStar, IconDiamond, IconCircle,
  // ... and more
} from '@unicitylabs/sphere-ui';

Types

import type {
  QuestData,
  TrackData,
  AchievementData,
  QuestFormApi,
  TrackFormApi,
  AchievementFormApi,
  QueryKeys,
} from '@unicitylabs/sphere-ui';

Design System

Tailwind Theme Tokens

Defined in src/styles/tokens.css via @theme {} block:

Token	Light	Dark
--color-bg-primary	#f5f5f5	#060606
--color-bg-card	#ffffff	#111111
--color-text-primary	#171717	#fefefe
--color-text-muted	#a3a3a3	rgba(255,255,255,0.28)
--color-brand-orange	#FF6F00	#FF6F00
--font-display	Anton	Anton
--font-sans	Geist	Geist
--font-mono	Geist Mono	Geist Mono

Component Classes

Class	Description
sphere-card	Card with border, radius, hover effect
sphere-card-glow	Card with orange glow shadow
sphere-input	Text input with focus ring
sphere-textarea	Multi-line text input
sphere-select	Select dropdown
sphere-table	Table with header/row styles
btn-primary	Orange primary button
btn-secondary	Outlined secondary button
btn-danger	Red danger button
badge-green	Green status badge
badge-orange	Orange status badge
badge-gray	Gray status badge
badge-red	Red status badge
badge-blue	Blue status badge
badge-purple	Purple status badge
badge-yellow	Yellow status badge

Backward-compatible aliases admin-card, admin-input, etc. are also available.

Development

npm install      # Install dependencies
npm run build    # Build with tsup (ESM + DTS)
npm run dev      # Watch mode
npm run typecheck # TypeScript check

Build Output

dist/
  index.js        # Base components + types
  index.d.ts
  forms/index.js  # Quest/Track/Achievement form exports
  canvas/index.js # Canvas component exports
  panels/index.js # Panel component exports
  hooks/index.js  # Hook exports

Architecture

src/
  styles/
    tokens.css       # Tailwind 4 @theme tokens + light/dark CSS vars
    components.css   # Reusable utility classes
    index.css        # Barrel CSS import
  components/        # 15 base UI components
  hooks/             # 6 canvas/chain/test mode hooks
  forms/             # Quest/Track/Achievement form barrel
  canvas/            # Canvas component barrel
  panels/            # Panel component barrel
  types.ts           # Shared TypeScript interfaces
  index.ts           # Main barrel export

Peer Dependencies

• react ^19.0.0
• react-dom ^19.0.0
• @tanstack/react-query ^5.0.0
• @tanstack/react-table ^8.0.0
• @dnd-kit/core ^6.0.0
• @dnd-kit/sortable ^8.0.0
• lucide-react ^0.400.0

License

MIT