🚀 Bliz CC UI Engine (@blizcc/ui)

The Bliz CC UI Engine is a high-performance, specialized React component library designed to power the next generation of interactive marketing experiences. It serves as the design system and logic-layer for the Bliz Marketplace, ensuring that every widget—from spinning wheels to AI agents—maintains visual consistency, legal compliance, and sub-second performance.

💎 Project Philosophy

Unlike generic UI kits, Bliz UI is built with a specific "Blue Ocean" marketing strategy in mind:

• Sub-Second Performance: Every component is optimized for <1s load times (500-900ms) to reduce bounce rates in high-traffic ad campaigns.
• Deterministic Integrity: Visual states are designed to map strictly to the Bliz Deterministic Prize Kernel—eliminating the "gambling" feel and ensuring outcomes are auditable.
• Portable Design: Every component is "link-native," meaning it works perfectly inside iframes, GTM scripts, or standalone marketing pages.

🛠 Technical Stack

• Runtime: React 19 + TypeScript
• Bundler: Vite 8 (Library Mode)
• Styling: Tailwind CSS 3.4.3 + PostCSS (Mantine Preset)
• Animation: Framer Motion 10.18.0
• Types: Auto-generated .d.ts via vite-plugin-dts

📦 What’s Included?

1. Atomic Components (src/components/)

Standardized parts used across all marketplace widgets:

• WidgetHeadings: Features high-performance typography with a specialized color-mix "Shine" animation. Automatically handles responsive vertical stacking.
• WidgetFooter: (In Migration) The standard Bliz CTA button with integrated loading states, "Sold Out" logic, and branded pulse animations.
• WidgetBaseContainer: The master wrapper that handles full-screen toggles, z-indexing, and device-safe padding.

2. The Workbench (src/App.tsx)

A local development environment ("Sandbox") used to build and review components in isolation before publishing. It mocks the Bliz Kernel hooks to simulate "Win/Loss" states.

3. Build & Distribution Engine

A specialized Vite configuration that outputs:

• ES Modules (.js): For modern React apps and the Bliz Marketplace.
• UMD (.umd.cjs): For legacy environments and direct browser injection.
• Single CSS Bundle (style.css): A minified, JIT-compiled Tailwind bundle.

🏗 Project Structure

bliz-ui/
├── dist/                # Production-ready NPM bundle
├── src/
│ ├── components/        # Atomic widget parts (Headings, Footers, etc.)
│ ├── index.ts           # Library Entry Point (exports)
│ ├── index.css          # Global Tailwind directives
│ ├── App.tsx            # Workbench / Development Gallery
│ └── main.tsx           # Workbench Entry
├── tailwind.config.js   # Optimized for JIT and specific Bliz theme
├── postcss.config.js    # Includes Mantine presets for specialized layout
└── vite.config.ts       # Library Mode & DTS configuration

🚀 Getting Started (Developers)

Installation

pnpm install

Local Development

Launch the Workbench to build new components:

pnpm run dev

Building for Production

pnpm run build

🌍 Distribution (NPM)

This library is published under the @blizcc scope.

• Package Name: @blizcc/ui
• Access: Public
• Registry: https://www.npmjs.com/package/@blizcc/ui

Publishing Workflow

1. Increase version in package.json.
2. Run pnpm run build.
3. Publish using npm publish --access public.

🔗 Consumer Usage

For developers building games for the Bliz Marketplace:

1. Install:

   pnpm add @blizcc/ui

2. Import Styles in your entry file:

   import '@blizcc/ui/style.css'

3. Import Components: Use exact paths for component imports. We explicitly avoid barrel files to ensure maximum performance and minimal bundle size.

   import WidgetHeadings from '@blizcc/ui/components/widget-headings';

4. Configure Component Properties: Components enforce snake_case themes (e.g., theme_primary, theme_secondary, theme_border_radius) mapped identically to Bliz Database definitions:

   <WidgetHeadings 
      title="Spin & Win"
      sub_title="Claim your prize today!"
      theme_primary="#FF0000"
      theme_secondary="#333333"
      theme_accent="#EEEEEE"
      theme_border_radius={12}
      theme_line_height={1.2}
      classname="my-custom-class"
   />

5. Configure Tailwind: Add the library to your content array in tailwind.config.js:

   export default {
     content: [
       // ... other paths
       "./node_modules/@blizcc/ui/dist/**/*.js",
     ],
     // ...
   }

Bliz CC UI Engine — Interactive marketing automation that turns every click into a conversion.