Shared Packages & Design System (@debelu/ui & @debelu/core)

This document is the authoritative engineering specification for the shared monorepo packages [@debelu/ui](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/packages/ui) and [@debelu/core](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/packages/core). Grounded directly in packages/ui/src/, packages/core/src/, the 44 KB domain type catalog in [types.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/packages/core/src/types.ts), and the design system in [DESIGN.md](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/DESIGN.md), this specification establishes our cross-application standards for visual consistency, type safety, and shared business logic.

---

1. System Overview & The Shared Foundation

Debelu segregates shared code into two distinct foundational libraries located in packages/:

graph TD
    subgraph SharedFoundations [Shared Foundation Layer]
        Core["@debelu/core<br/>Universal Business Logic, Types & Services"]
        UI["@debelu/ui<br/>Visual Components, Theme Tokens & Design System"]
    end

    subgraph ConsumingSurfaces [Consuming Monorepo Surfaces]
        Storefront["apps/storefront (Buyer & Vendor SPA)"]
        Marketing["debelu-marketing (Next.js Public Portal)"]
        Admin["debelu-admin (Isolated Operations Console)"]
        Backend["debelu-backend (API Gateway & Daemons)"]
    end

    Core --> UI
    Core --> Storefront
    Core --> Marketing
    Core --> Admin
    Core --> Backend
    
    UI --> Storefront
    UI --> Marketing
    UI --> Admin

1.1 Architectural Purpose & Boundaries

Package	Workspace Path	Primary Responsibilities	Architectural Constraints
@debelu/core	packages/core	Domain entity types, stateless client API services, Zod validation schemas, internationalization (i18n), and feature flag orchestration.	Zero DOM / Styling dependencies. Must remain strictly headless and framework-agnostic.
@debelu/ui	packages/ui	Unified design tokens (theme.css), Radix UI component primitives, Debelu branded compound components, haptics, and maintenance overlays.	Zero Business Logic. Components receive data and callbacks via typed props.

---

2. @debelu/ui — Design System & Component Library

The @debelu/ui package acts as the single source of truth for all visual presentation across Debelu web and mobile applications.

graph TD
    subgraph UI_Architecture [packages/ui Architecture]
        Tokens["theme.css: CSS Custom Properties<br/>Colors, Radii, Typography, Shadows"]
        Primitives["components/ui/: Radix Primitives<br/>Button, Input, Dialog, Dropdown, Checkbox"]
        Compound["components/debelu/: Branded Components<br/>ProductCard, CampusBadge, VerificationBadge, DeliveryPinInput"]
        Custom["components/custom/: System Overlays<br/>MaintenanceScreen, GlobalLoading, ErrorBoundary"]
        Hooks["hooks/: UI Behavior<br/>useHaptic, useMaintenanceMode, useOnlineStatus"]
    end

    Tokens --> Primitives
    Primitives --> Compound
    Compound --> Applications[Consuming Applications]
    Custom --> Applications
    Hooks --> Applications

2.1 Theme & Design Tokens (packages/ui/src/theme.css)

Debelu enforces curated, harmonious tokens representing our emerald green campus brand identity:

• Brand Primary: Emerald #1B5E20 (--color-primary-600), accent mint #E8F5E9 (--color-primary-50).
• Surface & Backgrounds: Warm neutral #F5F5F7 (--color-background), pure card white #FFFFFF (--color-surface).
• Typography: Inter / Outfit sans-serif hierarchy with fluid scale steps (text-xs through text-4xl).
• Border Radii: Generous, modern corner radiuses (rounded-xl for cards, rounded-full for badges).

IMPORTANT

Strict Styling Invariant (from DESIGN.md): Applications must never define custom colors, ad-hoc utility classes, or local restyling overrides. All visual components and tokens must be imported directly from @debelu/ui.

2.2 Component Hierarchy

packages/ui/src/components/
├── ui/                                     # Unstyled, accessible UI primitives
│   ├── button.tsx                          # Radix slot-based button with loading spinners
│   ├── input.tsx                           # Floating label text input with error states
│   ├── dialog.tsx                          # Accessible modal dialog with focus traps
│   ├── sheet.tsx                           # Mobile bottom/side drawer sheets
│   └── checkbox.tsx                        # Accessible form checkbox
├── debelu/                                 # Debelu-branded compound components
│   ├── ProductCard.tsx                     # Product listing card with campus badges and price
│   ├── CampusBadge.tsx                     # Pill badge displaying active university campus
│   ├── VerificationBadge.tsx               # Student ID & BVN verified trust shield
│   ├── DeliveryPinInput.tsx                # 6-digit PIN input for escrow delivery confirmation
│   └── PriceDisplay.tsx                    # Kobo-to-Naira formatted currency with strikethrough
└── custom/                                 # Platform-level system overlays
    ├── MaintenanceScreen.tsx               # Full-page maintenance interceptor with status polling
    ├── GlobalLoading.tsx                   # Accessible spinner and skeleton placeholders
    └── AppErrorBoundary.tsx                # React error boundary with Sentry reporting

2.3 Shared UI Hooks

• useMaintenanceMode(): Real-time hook polling platform status (/api/status), triggering maintenance screens automatically during scheduled maintenance windows.
• useHaptic(): Triggers discrete physical vibration pulses (light, selection, success, error) on mobile devices via Capacitor bridges.
• useOnlineStatus(): Detects network disconnects, toggling offline banners.

---

3. @debelu/core — Universal Business Logic & Type System

The @debelu/core package provides shared business logic, client services, and the master domain type system across all monorepo surfaces.

graph TD
    subgraph Core_Architecture [packages/core Architecture]
        Types["types.ts: Master Domain Types (44 KB)<br/>User, Order, Vendor, Product, Escrow, Dispute"]
        Constants["constants.ts: System Enums & Values<br/>Campuses, OrderStatus, CategoryTrees"]
        Services["services/: Client API Clients<br/>userService, paymentService, disputeService, etc."]
        Schemas["schemas/: Shared Zod Validators<br/>checkoutSchema, applicationSchema, supportSchema"]
        Contexts["contexts/: React Context Providers<br/>I18nProvider, StoreProvider, ToastProvider"]
    end

    Types --> Services
    Constants --> Services
    Schemas --> Services
    Services --> Consumers[Consuming Applications]
    Contexts --> Consumers

3.1 Master Domain Type Catalog (packages/core/src/types.ts)

A comprehensive, 44 KB type catalog defining every entity across the platform:

• UserProfile & StaffRole: Member accounts, verification levels, campus affiliations, and staff permissions (canManageOrders, canManageFinances).
• VendorProfile: Merchant store configuration, NUBAN bank accounts, vacation toggles, and reputation metrics.
• Order & OrderFeeSnapshot: Complete 9-state order lifecycle, line items, delivery PINs, and immutable fee records.
• Transaction & LedgerEntry: Double-entry general ledger statements with positive credits and negative debits in Kobo.
• DisputeCase & ReturnCase: Escrow dispute escalation records, evidence attachments, and arbitration findings.

3.2 Client Service Modules (18+ Modules)

Service Client	Target Domain	Key Responsibilities
userService.ts	Identity & Profiles	Profile updates, campus delivery address management, and onBeforeSignOut hooks.
vendorService.ts	Merchant Operations	Vendor onboarding application submission, store policies, and sales analytics queries.
productService.ts	Catalog & Search	Product CRUD, image upload coordination, category filters, and campus search facets.
paymentService.ts	Checkout & Escrow	Paystack checkout initialization, payment verification, and virtual account generation.
disputeService.ts	Customer Arbitration	Dispute ticket creation, evidence upload handling, and settlement polling.
geminiService.ts	Nduzi AI Assistant	Server-Sent Events (SSE) streaming chat connections, tool invocations, and session management.
notificationService.ts	Real-Time Alerts	In-app notification polling, push registration, and read-receipt synchronization.
pushService.ts	Mobile Device Sync	FCM and APNs token registration with the backend device registry.
deepLinkResolver.ts	Routing & Deep Links	Universal link parsing, mapping inbound URLs to internal React Router navigation paths.
featureFlags.ts	Feature Governance	Unleash client integration, canary rollout evaluation, and kill switches.
i18n.ts	Internationalization	Locale detection and translation dictionary resolution.
telemetry.ts	Error & Performance	Sentry error boundaries and Web Vitals reporting.

---

4. Contributing & Adding to Shared Packages

To preserve monorepo integrity and avoid circular dependencies, engineers must adhere to the following decision matrix:

flowchart TD
    Req[New Code / Asset Required] --> Q1{Is it a visual component or design style?}
    Q1 -->|Yes| Q2{Is it used by more than one app?}
    Q2 -->|Yes| AddUI[Add to packages/ui/src/components/]
    Q2 -->|No, Storefront Only| AddStorefront[Add to apps/storefront/src/components/]
    
    Q1 -->|No, it is Logic/Types/API| Q3{Is it domain data, types, or API client?}
    Q3 -->|Yes| AddCore[Add to packages/core/src/services/ or types.ts]
    Q3 -->|No, Server-Only DB Logic| AddBackend[Add to debelu-backend/src/services/]

4.1 Verification Protocol

When updating either shared package:

# 1. Verify type correctness in packages/core
npm run type-check --workspace=@debelu/core

# 2. Verify type correctness in packages/ui
npm run type-check --workspace=@debelu/ui

# 3. Verify that consuming applications compile cleanly
npm run type-check --workspace=@debelu/storefront
npm run type-check --workspace=debelu-marketing

---

5. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal Frontend Architect	Initial enterprise specification detailing @debelu/ui design system, theme tokens, and @debelu/core domain types and services.	Active Living Standard