@breakergames/design-system 0.1.0

package/guidelines/components/game-grid.md

@@ -0,0 +1,34 @@
+# Game Grid Components
+
+## GameGrid
+Responsive card grid layout. 2 columns on mobile, 3 on tablet, optionally 4 on desktop.
+
+```tsx
+<GameGrid columns={3}>
+  <ScenarioCard ... />
+  <ScenarioCard ... />
+  <ScenarioCard ... />
+</GameGrid>
+```
+
+## HotGrid
+Section with emoji icon + title header, followed by a content grid.
+Use for "Trending", "New", "Popular" sections.
+
+```tsx
+<HotGrid title="Trending" icon="🔥">
+  <ScenarioCard ... />
+  <ScenarioCard ... />
+</HotGrid>
+```
+
+## WaterfallGrid
+Two-column masonry layout where the right column is offset 24px down.
+Use for infinite scroll feeds.
+
+```tsx
+<WaterfallGrid
+  leftColumn={<><ScenarioCard /><ScenarioCard /></>}
+  rightColumn={<><ScenarioCard /><ScenarioCard /></>}
+/>
+```

package/guidelines/components/header.md

@@ -0,0 +1,38 @@
+# Header
+
+Fixed top navigation bar with frosted glass background.
+
+## Layout
+- **Logo** (left): Icon + gradient text (text hidden on mobile)
+- **Tabs** (center): Pill-shaped navigation tabs
+- **Actions** (right): Language toggle, user name/avatar, sign in button
+
+## Props
+- `logoText`: string — brand name (default: "Makabaka")
+- `logoIcon`: ReactNode — logo icon (default: 🦙)
+- `tabs`: HeaderTab[] — `{ id: string, label: string }`
+- `activeTab`: string — currently active tab ID
+- `onTabChange`: (id) => void
+- `userName`: string — logged-in user name
+- `avatar`: ReactNode — avatar component
+- `onSignIn`: () => void — show sign in button
+- `onLogout`: () => void
+- `languageLabel`: string — e.g. "EN" or "中文"
+- `onLanguageToggle`: () => void
+
+## Usage
+```tsx
+<Header
+  tabs={[
+    { id: 'recommend', label: 'For You' },
+    { id: 'community', label: 'Community' },
+    { id: 'messages', label: 'Messages' },
+  ]}
+  activeTab="recommend"
+  onTabChange={setTab}
+  userName="Alice"
+  avatar={<Avatar name="Alice" size="sm" />}
+  languageLabel="EN"
+  onLanguageToggle={toggleLang}
+/>
+```

package/guidelines/components/input.md

@@ -0,0 +1,22 @@
+# Input
+
+Text input field with optional label, error state, and helper text.
+
+## States
+- **Default**: Dark background, subtle border
+- **Focus**: Purple border with ring
+- **Error**: Red border, error message below
+- **Disabled**: Reduced opacity
+
+## Props
+- `label`: string — label text above input
+- `error`: string — error message (activates red border)
+- `helperText`: string — hint text below input
+- All standard `<input>` attributes (type, placeholder, etc.)
+
+## Usage
+```tsx
+<Input label="Email" type="email" placeholder="you@example.com" />
+<Input label="Password" type="password" error="Password is too short" />
+<Input label="Code" helperText="Check your email for the code" />
+```

package/guidelines/components/modal.md

@@ -0,0 +1,42 @@
+# Modal & BottomSheet
+
+## Modal
+Centered overlay dialog with frosted backdrop.
+
+### Sizes
+- `sm` — 400px max width (alerts, confirmations)
+- `md` — 560px max width (forms, game details)
+- `lg` — 896px max width (full game detail view)
+
+### Props
+- `isOpen`: boolean
+- `onClose`: () => void
+- `size`: 'sm' | 'md' | 'lg'
+
+### Usage
+```tsx
+<Modal isOpen={showDetail} onClose={close} size="lg">
+  <GameDetailContent />
+</Modal>
+```
+
+## BottomSheet
+Bottom-sliding panel on mobile, centered modal on desktop.
+
+### Props
+- `isOpen`: boolean
+- `onClose`: () => void
+- `title`: string
+- `subtitle`: string
+
+### Features
+- Mobile drag handle (hidden on desktop)
+- Header with title, subtitle, close button
+- Scrollable body content
+
+### Usage
+```tsx
+<BottomSheet isOpen={showSimilar} onClose={close} title="Similar Games" subtitle="8 games found">
+  <GameList />
+</BottomSheet>
+```

package/guidelines/design-tokens/colors.md

@@ -0,0 +1,47 @@
+# Color Tokens
+
+## Brand Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--maka-primary` | `#7c5cfa` | Primary actions, active states, logo gradient start |
+| `--maka-primary-hover` | `#6b4ee0` | Primary button hover state |
+| `--maka-secondary` | `#5c9cfa` | Secondary accents, logo gradient end |
+| `--maka-accent` | `#06d6a0` | Success indicators, highlights |
+
+## Surface Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--maka-bg-dark` | `#1b2838` | Page background |
+| `--maka-bg-card` | `#1e2a3a` | Card/panel surfaces |
+| `--maka-bg-hover` | `#2a3a4a` | Hover state surfaces |
+| `--maka-bg-overlay` | `rgba(0,0,0,0.8)` | Modal backdrops |
+| `--maka-bg-frosted` | `rgba(0,0,0,0.7)` | Frosted glass panels |
+
+## Text Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--maka-text-primary` | `#e8e8ec` | Main content text |
+| `--maka-text-secondary` | `rgba(255,255,255,0.7)` | Labels, descriptions |
+| `--maka-text-muted` | `rgba(255,255,255,0.4)` | Placeholders, hints |
+| `--maka-text-disabled` | `rgba(255,255,255,0.3)` | Disabled elements |
+
+## Semantic Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--maka-danger` | `#ef4444` | Errors, destructive actions |
+| `--maka-success` | `#22c55e` | Success messages |
+| `--maka-warning` | `#f59e0b` | Warnings, cautions |
+| `--maka-like` | `#f43f5e` | Like/heart active state |
+
+## Gradients
+- **Primary gradient**: `linear-gradient(to right, var(--maka-primary), var(--maka-secondary))`
+- **Card overlay**: `linear-gradient(to top, rgba(0,0,0,0.85) 0%, transparent 100%)`
+
+## Badge Colors
+Each badge type has a `from` and `to` gradient:
+- Staff Pick: amber `#f59e0b` → `#eab308`
+- Hot: orange `#f97316` → red `#ef4444`
+- Liked: pink `#ec4899` → rose `#f43f5e`
+- Rising: green `#22c55e` → emerald `#10b981`
+- New: purple `#a855f7` → indigo `#6366f1`
+- Trending: cyan `#06b6d4` → blue `#3b82f6`

package/guidelines/design-tokens/spacing.md

@@ -0,0 +1,47 @@
+# Spacing & Layout
+
+## Spacing Scale
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--maka-space-1` | 4px | Tight gaps (badge icon-text) |
+| `--maka-space-2` | 8px | Small gaps (tab spacing, icon gaps) |
+| `--maka-space-3` | 12px | Grid gaps, card padding compact |
+| `--maka-space-4` | 16px | Standard padding, input padding |
+| `--maka-space-5` | 20px | Card content padding |
+| `--maka-space-6` | 24px | Card padding, section gaps |
+| `--maka-space-8` | 32px | Desktop header padding, large gaps |
+| `--maka-space-10` | 40px | Section margins |
+| `--maka-space-12` | 48px | Page top padding (below header) |
+| `--maka-space-16` | 64px | Hero section padding |
+
+## Border Radius
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--maka-radius-sm` | 4px | Chat bubble sharp corners |
+| `--maka-radius-md` | 8px | Buttons, inputs |
+| `--maka-radius-lg` | 12px | Cards, stat cards |
+| `--maka-radius-xl` | 16px | Featured cards, chat bubbles |
+| `--maka-radius-2xl` | 24px | Modals, bottom sheets |
+| `--maka-radius-full` | 9999px | Pills, badges, avatars, tabs |
+
+## Borders
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--maka-border-subtle` | `rgba(255,255,255,0.1)` | Default card/divider borders |
+| `--maka-border-medium` | `rgba(255,255,255,0.2)` | Input borders, language toggle |
+| `--maka-border-emphasis` | `rgba(255,255,255,0.4)` | Hover emphasis borders |
+| `--maka-border-primary` | `rgba(124,92,250,0.4)` | Primary accent borders |
+
+## Shadows
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--maka-shadow-card` | `0 8px 24px rgba(0,0,0,0.3)` | Card hover shadows |
+| `--maka-shadow-button` | `0 4px 16px rgba(124,92,250,0.35)` | Primary button glow |
+
+## Layout Patterns
+- **Max container width**: 896px (`max-width: 56rem`)
+- **Page padding**: 16px mobile, 32px desktop
+- **Header height**: ~56px
+- **Bottom bar height**: ~64px (+ safe-area-inset)
+- **Grid columns**: 2 (mobile) → 3 (tablet) → 4 (desktop)
+- **Grid gap**: 12px (mobile) → 16px (desktop)

package/guidelines/design-tokens/typography.md

@@ -0,0 +1,30 @@
+# Typography
+
+## Font Families
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--maka-font-display` | "Plus Jakarta Sans", "Inter", sans-serif | Headings, logos, card titles, stats |
+| `--maka-font-body` | "Inter", sans-serif | Body text, labels, buttons, inputs |
+
+## Font Weights
+| Weight | Value | Usage |
+|--------|-------|-------|
+| Regular | 400 | Body text, descriptions |
+| Medium | 500 | Labels, buttons, tabs |
+| Semibold | 600 | Card titles, section headers |
+| Bold | 700 | Page titles, logo text, stats |
+| Extrabold | 800 | Hero headings |
+
+## Type Scale (recommended)
+| Size | Usage |
+|------|-------|
+| 11px | Badges |
+| 12px | Stat labels, helper text |
+| 13px | Secondary text, card stats, error/helper messages |
+| 14px | Body text, inputs, buttons (md), tabs |
+| 15px | Card titles, tabs (desktop) |
+| 16px | Buttons (lg) |
+| 18px | Section headers, bottom sheet titles |
+| 20px | Featured card titles |
+| 24px | Page titles, logo text |
+| 28px | Stat values |

package/guidelines/overview-components.md

@@ -0,0 +1,43 @@
+# Component Overview
+
+## Primitives
+| Component | Description | When to use |
+|-----------|-------------|-------------|
+| `Button` | Action button with 4 variants | Any clickable action |
+| `Input` | Text input with label/error | Forms, search fields |
+| `Badge` | Colored pill label | Game status tags (Hot, New, etc.) |
+| `Avatar` | Circular user image/initial | User profiles, comments |
+| `StatCard` | Metric display card | Dashboard statistics |
+
+## Cards
+| Component | Description | When to use |
+|-----------|-------------|-------------|
+| `Card` | Base container card | Generic card wrapper |
+| `FeaturedCard` | Hero-size game card with overlay | Featured/promoted games |
+| `ScenarioCard` | Standard game listing card | Game grids and lists |
+| `GeneratingCard` | Loading placeholder card | During AI game generation |
+
+## Chat
+| Component | Description | When to use |
+|-----------|-------------|-------------|
+| `ChatBubble` | Message bubble (user/assistant) | MakaAI chat conversations |
+| `LikeButton` | Heart toggle with count | Like/favorite actions |
+| `BottomInputBar` | Fixed bottom input trigger | Discovery page chat launcher |
+
+## Layout
+| Component | Description | When to use |
+|-----------|-------------|-------------|
+| `Header` | Fixed top navigation bar | Every page (required) |
+| `Modal` | Centered overlay dialog | Game details, confirmations |
+| `BottomSheet` | Bottom-sliding panel | Similar games, filters |
+| `GameGrid` | Responsive card grid | Game listings (2-4 cols) |
+| `HotGrid` | Section with title + grid | Trending/featured sections |
+| `WaterfallGrid` | Masonry 2-column layout | Infinite scroll feed |
+
+## Icons
+| Icon | Description |
+|------|-------------|
+| `PlayIcon` | Filled play triangle |
+| `CloseIcon` | X close mark |
+| `HeartIcon` | Heart (outline or filled) |
+| `ArrowUpIcon` | Upward arrow |

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@breakergames/design-system",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./theme.css": "./dist/style.css"
+  },
+  "files": [
+    "dist",
+    "guidelines"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.7.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch"
+  }
+}