@memelabui/ui 0.6.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -10,6 +10,8 @@ Shared UI component library for MemeLab projects. Dark-first glassmorphism desig
10
10
  pnpm add @memelabui/ui
11
11
  ```
12
12
 
13
+ Peer dependencies: `react >= 18`, `react-dom >= 18`, `tailwindcss >= 3.4`.
14
+
13
15
  ## Setup
14
16
 
15
17
  ### 1. Tailwind preset
@@ -27,13 +29,17 @@ export default {
27
29
  };
28
30
  ```
29
31
 
32
+ The preset adds MemeLab colors (`primary`, `accent`, `surface`, `glow`), animations, border radius, and box shadow tokens to your Tailwind config. No component CSS is duplicated — component styles come from the CSS import below.
33
+
30
34
  ### 2. Import styles
31
35
 
32
36
  ```ts
33
- // main.tsx
37
+ // main.tsx (before your app code)
34
38
  import '@memelabui/ui/styles';
35
39
  ```
36
40
 
41
+ This imports base styles, CSS variables (`--ml-*` tokens), glassmorphism utility classes, and component animations. Must be imported once at the root of your app.
42
+
37
43
  ### 3. Use components
38
44
 
39
45
  ```tsx
@@ -42,153 +48,361 @@ import { Button, Card, Input, ToastProvider } from '@memelabui/ui';
42
48
  function App() {
43
49
  return (
44
50
  <ToastProvider>
45
- <Card hoverable>
51
+ <Card variant="glass" hoverable>
52
+ <h2 className="section-title">Login</h2>
46
53
  <Input label="Email" placeholder="you@example.com" />
47
- <Button variant="primary">Submit</Button>
54
+ <Button variant="primary" className="mt-4">Submit</Button>
48
55
  </Card>
49
56
  </ToastProvider>
50
57
  );
51
58
  }
52
59
  ```
53
60
 
54
- ## Components (60+ exports)
61
+ ---
55
62
 
56
- ### Form
63
+ ## CSS Utility Classes
57
64
 
58
- | Component | Description |
59
- |-----------|-------------|
60
- | `Input` | Text input with label, error, helperText |
61
- | `SearchInput` | Search input with icon and clear button |
62
- | `Select` | Select dropdown with label/error wrapper |
63
- | `Combobox` | Searchable select with keyboard navigation and filtering |
64
- | `Textarea` | Multiline text input with label/error |
65
- | `Checkbox` | Custom checkbox with indeterminate support |
66
- | `RadioGroup` / `RadioItem` | Compound radio button group |
67
- | `Toggle` | Switch toggle (sm/md sizes) with `busy` spinner state |
68
- | `Slider` | Range input with custom track/thumb and value display |
69
- | `TagInput` | Tag input with Enter/comma/paste, dedup, maxTags |
70
- | `ColorInput` | Hex color picker with swatch + text input |
71
- | `FormField` | Generic label + error + helper wrapper for any input |
72
-
73
- ### Actions
74
-
75
- | Component | Description |
76
- |-----------|-------------|
77
- | `Button` | Primary, secondary, danger, success, warning, ghost variants + loading |
78
- | `IconButton` | Icon-only button with required `aria-label` |
79
- | `ProgressButton` | Button with shimmer loading animation |
65
+ These classes are available globally after importing `@memelabui/ui/styles`. They provide the MemeLab visual foundation.
80
66
 
81
- ### Data Display
67
+ | Class | Purpose | When to use |
68
+ |-------|---------|-------------|
69
+ | `.glass` | Glassmorphism panel — translucent `bg`, `backdrop-filter: blur(16px)`, inset border, rounded | Visual shell for containers. **Does not include padding** — use `Card` component for padded cards |
70
+ | `.surface` | Surface panel — slightly more opaque `bg`, `blur(12px)`, border shadow | Alternative to `.glass` with stronger background. Also **no padding** |
71
+ | `.surface-hover` | Hover elevation transition — adds `box-shadow` on hover | Pair with `.glass` or `.surface` for interactive cards |
72
+ | `.section-title` | Card section heading — `font-semibold`, `border-bottom`, `mb-4` | Use inside `Card` for titled sections (settings, forms) |
73
+ | `.text-gradient` | Gradient text (violet to pink) | Branding, hero headings |
74
+ | `.animated-gradient` | Animated gradient background | Decorative elements, loading placeholders |
75
+ | `.page-container` | Centered max-w-80rem container with responsive padding | Page-level wrapper |
76
+ | `.orb` / `.orb-purple` / `.orb-blue` / `.orb-pink` | Decorative blurred orbs | Background effects (see `PageShell`) |
77
+ | `.pb-safe` / `.pt-safe` | iOS safe area padding | Mobile bottom/top bars |
78
+ | `.no-scrollbar` | Hides scrollbar | Horizontal scroll areas, custom scrolling |
79
+ | `.link-soft` | Subtle underline link | Secondary navigation links |
82
80
 
83
- | Component | Description |
84
- |-----------|-------------|
85
- | `Card` | Surface or glass card container |
86
- | `SectionCard` | Settings section card with title, description, right slot, overlay slot |
87
- | `Badge` / `Pill` | Status badges (neutral, primary, success, danger, warning, accent) |
88
- | `StatCard` | Dashboard stat card with value, label, icon, trend indicator |
89
- | `Table` / `TableHeader` / `TableBody` / `TableRow` / `TableHead` / `TableCell` | Styled table primitives |
90
- | `Tabs` / `TabList` / `Tab` / `TabPanel` | Compound tabs with underline and pill variants |
91
- | `CollapsibleSection` | Animated expand/collapse with ARIA |
92
- | `EmptyState` | Placeholder with icon, title, description, action |
93
- | `Skeleton` | Pulse placeholder for loading states |
94
- | `Spinner` | Loading spinner (sm/md/lg) |
95
- | `DropZone` | Drag & drop file upload area with accept filter |
96
- | `Avatar` | Circular avatar with image + initials fallback |
97
- | `Divider` | Horizontal/vertical divider with optional label |
98
- | `ActiveFilterPills` | Dismissible filter pill row with "Clear all" action |
99
- | `DotIndicator` | Dot-based remaining count with urgency colors |
81
+ ### Important: `.glass` / `.surface` vs `Card`
100
82
 
101
- ### Progress & Status
83
+ The `.glass` and `.surface` CSS classes are **visual treatments only** — they add background, blur, border, and shadow. They intentionally do **not** include padding because they're used across diverse elements (headers, sidebars, modals, custom layouts).
102
84
 
103
- | Component | Description |
104
- |-----------|-------------|
105
- | `ProgressBar` | Horizontal progress bar with variants and sizes |
106
- | `CooldownRing` | SVG circular countdown timer with color changes and pulse |
107
- | `StageProgress` | Multi-stage process indicator with shimmer animation |
85
+ **For content cards, always use the `Card` component** instead of raw `.glass`/`.surface` classes. `Card` provides built-in padding (`p-5` by default) plus correct ARIA semantics.
86
+
87
+ ```tsx
88
+ // Correct Card handles padding automatically
89
+ <Card variant="glass" hoverable>
90
+ <h2 className="section-title">Settings</h2>
91
+ <Input label="Name" />
92
+ </Card>
93
+
94
+ // Avoid — raw classes require manual padding
95
+ <div className="glass surface-hover p-5">
96
+ <h2 className="section-title">Settings</h2>
97
+ <Input label="Name" />
98
+ </div>
99
+ ```
100
+
101
+ ---
102
+
103
+ ## Components
104
+
105
+ ### Cards & Containers
106
+
107
+ Use these to wrap content sections. Each has different levels of structure.
108
+
109
+ | Component | When to use | Key props |
110
+ |-----------|-------------|-----------|
111
+ | `Card` | Generic content container with glassmorphism | `variant` (`'surface'` / `'glass'`), `hoverable`, `padding` (`'none'` / `'sm'` / `'md'` / `'lg'`) |
112
+ | `SectionCard` | Settings/config section with title, description, and optional right slot | `title`, `description?`, `right?`, `overlay?` |
113
+ | `StatCard` | Dashboard metric tile with value, label, icon, and trend | `value`, `label`, `icon?`, `trend?` |
114
+ | `CollapsibleSection` | Expandable/collapsible content block | `title`, `defaultOpen?` |
115
+
116
+ **Choosing the right card:**
117
+
118
+ - Building a **settings form section** (title + form fields)? Use `SectionCard`
119
+ - Showing a **dashboard metric** (number + label + icon)? Use `StatCard`
120
+ - Need a **generic container** with glass/surface styling? Use `Card`
121
+ - Need an **expandable block**? Use `CollapsibleSection`
122
+
123
+ ```tsx
124
+ // Settings page section
125
+ <SectionCard title="AI Provider" description="Choose the AI model for your bot">
126
+ <Select label="Provider" />
127
+ <Input label="Model" placeholder="Default" />
128
+ </SectionCard>
129
+
130
+ // Dashboard metric
131
+ <StatCard value="1,234" label="Messages today" trend={{ value: 12, direction: 'up' }} />
132
+
133
+ // Generic glass card
134
+ <Card variant="glass" hoverable padding="lg">
135
+ <p>Any content here</p>
136
+ </Card>
137
+ ```
138
+
139
+ ### Form Inputs
140
+
141
+ All form components accept `label`, `error`, and `helperText` props with automatic ARIA linkage (`aria-invalid`, `aria-describedby`). They use `forwardRef` for ref forwarding and spread all native HTML attributes.
142
+
143
+ | Component | When to use | Key props |
144
+ |-----------|-------------|-----------|
145
+ | `Input` | Single-line text input | `label?`, `error?`, `helperText?`, `hasError?` + all `<input>` attrs |
146
+ | `SearchInput` | Search field with icon and clear button | `onClear?` + all `Input` props |
147
+ | `Textarea` | Multi-line text input | `label?`, `error?` + all `<textarea>` attrs |
148
+ | `Select` | Native dropdown select | `label?`, `error?` + all `<select>` attrs |
149
+ | `Combobox` | Searchable select with keyboard navigation | `options`, `value`, `onChange`, `placeholder?` |
150
+ | `Checkbox` | Checkbox with label and indeterminate support | `label?`, `indeterminate?`, `checked`, `onChange` |
151
+ | `RadioGroup` / `RadioItem` | Radio button group | `value`, `onChange` on Group; `value`, `label` on Item |
152
+ | `Toggle` | On/off switch | `checked`, `onChange(boolean)`, `label?`, `busy?`, `size?` |
153
+ | `Slider` | Range slider with value display | `min`, `max`, `value`, `onChange` |
154
+ | `TagInput` | Tag input with Enter/comma/paste support | `value: string[]`, `onChange`, `maxTags?` |
155
+ | `ColorInput` | Hex color picker with swatch | `value`, `onChange` |
156
+ | `FormField` | Generic wrapper for any input (label + error + helper) | `label`, `error?`, `helperText?`, `children` |
157
+
158
+ ```tsx
159
+ // Full form with Toggle + Input + Select
160
+ <Card variant="glass" hoverable>
161
+ <h2 className="section-title">Bot Personality</h2>
162
+ <Input label="Bot name" value="MemeBot" />
163
+ <Textarea label="Personality" placeholder="Friendly, humorous..." />
164
+ <Select label="Response style">
165
+ <option value="concise">Concise</option>
166
+ <option value="detailed">Detailed</option>
167
+ </Select>
168
+ <Toggle
169
+ label="Respond to @mentions"
170
+ checked={mentionEnabled}
171
+ onChange={setMentionEnabled}
172
+ />
173
+ </Card>
174
+ ```
175
+
176
+ ### Buttons
177
+
178
+ | Component | When to use | Key props |
179
+ |-----------|-------------|-----------|
180
+ | `Button` | Primary actions, form submits, navigation | `variant` (`'primary'` / `'secondary'` / `'danger'` / `'success'` / `'warning'` / `'ghost'`), `loading?`, `size?` |
181
+ | `IconButton` | Icon-only actions (close, menu, refresh) | `aria-label` (required), `variant?`, `size?` |
182
+ | `ProgressButton` | Button with shimmer loading state | `loading?`, `progress?` |
183
+
184
+ ### Data Display
185
+
186
+ | Component | When to use | Key props |
187
+ |-----------|-------------|-----------|
188
+ | `Badge` / `Pill` | Status labels, tags, categories | `variant` (`'neutral'` / `'primary'` / `'success'` / `'danger'` / `'warning'` / `'accent'` / `'successSolid'` / `'dangerSolid'`), `size?` |
189
+ | `Table` / `TableHeader` / `TableBody` / `TableRow` / `TableHead` / `TableCell` | Data tables | Compound — compose like native `<table>` |
190
+ | `Tabs` / `TabList` / `Tab` / `TabPanel` | Tabbed content switching | `variant` (`'underline'` / `'pill'`); compound pattern |
191
+ | `EmptyState` | Empty content placeholder | `icon?`, `title`, `description?`, `action?` |
192
+ | `Skeleton` | Loading placeholder | `width?`, `height?`, `rounded?` |
193
+ | `Spinner` | Loading indicator | `size` (`'sm'` / `'md'` / `'lg'`) |
194
+ | `Avatar` | User avatar with fallback | `src?`, `name?`, `size?` |
195
+ | `Divider` | Separator line | `orientation?`, `label?` |
196
+ | `ActiveFilterPills` | Filter pill bar with clear-all | `filters`, `onRemove`, `onClearAll` |
197
+ | `DotIndicator` | Remaining count dots | `count`, `max?` |
108
198
 
109
199
  ### Navigation
110
200
 
111
- | Component | Description |
112
- |-----------|-------------|
113
- | `Pagination` | Page navigation with prev/next, ellipsis, active state |
114
- | `Stepper` | Horizontal step indicator for wizards/onboarding |
115
- | `Breadcrumbs` | Breadcrumb navigation with links/buttons/separators |
201
+ | Component | When to use | Key props |
202
+ |-----------|-------------|-----------|
203
+ | `Pagination` | Page navigation | `page`, `totalPages`, `onChange` |
204
+ | `Stepper` | Multi-step wizard indicator | `steps`, `currentStep` |
205
+ | `Breadcrumbs` | Breadcrumb path | `items` (links/buttons) |
206
+
207
+ ### Overlay & Popups
208
+
209
+ | Component | When to use | Key props |
210
+ |-----------|-------------|-----------|
211
+ | `Modal` | Dialog / fullscreen overlay | `open`, `onClose`, children |
212
+ | `ConfirmDialog` | Confirmation prompts (delete, discard) | `open`, `onConfirm`, `onCancel`, `title`, `description` |
213
+ | `Tooltip` | Hover/focus info text | `content`, `children` (trigger) |
214
+ | `Dropdown` | Dropdown menu (context menu, actions) | Compound: `DropdownTrigger` + `DropdownMenu` + `DropdownItem` + `DropdownSeparator` |
215
+ | `Popover` | Click-triggered popup | `trigger`, `children` (content) |
216
+ | `Drawer` | Slide-in side panel | `open`, `onClose`, `position` (`'left'` / `'right'` / `'bottom'`) |
217
+ | `MutationOverlay` | Saving/saved/error status indicator | `status` (`'idle'` / `'saving'` / `'saved'` / `'error'`) |
218
+ | `NotificationBell` | Notification button with badge | `count`, `onClick` |
116
219
 
117
- ### Overlay
220
+ ### Progress & Status
118
221
 
119
- | Component | Description |
120
- |-----------|-------------|
121
- | `Modal` | Dialog with focus trap, scroll lock, backdrop blur |
122
- | `ConfirmDialog` | Confirmation modal with cancel/confirm actions |
123
- | `Tooltip` | Hover/focus tooltip with portal positioning |
124
- | `Dropdown` | Compound menu (Trigger, Menu, Item, Separator) |
125
- | `MutationOverlay` | Saving/saved/error status overlay for cards |
126
- | `NotificationBell` | Notification bell button with unread count badge and ping animation |
127
- | `Popover` | Click-triggered positioned popup with portal |
128
- | `Drawer` | Slide-in side panel (left/right/bottom) with focus trap |
222
+ | Component | When to use | Key props |
223
+ |-----------|-------------|-----------|
224
+ | `ProgressBar` | Linear progress indicator | `value`, `max?`, `variant?`, `size?` |
225
+ | `CooldownRing` | Circular countdown timer | `remaining`, `total` |
226
+ | `StageProgress` | Multi-stage process tracker | `stages`, `currentStage` |
129
227
 
130
228
  ### Typography
131
229
 
132
- | Component | Description |
133
- |-----------|-------------|
134
- | `Heading` | Heading h1-h6 with size/color presets and gradient variant |
135
- | `Text` | Text paragraph/span with size, color, weight, and truncate |
230
+ | Component | When to use | Key props |
231
+ |-----------|-------------|-----------|
232
+ | `Heading` | Section headings h1-h6 | `as` (`'h1'` - `'h6'`), `size?`, `gradient?` |
233
+ | `Text` | Body text, captions, labels | `as` (`'p'` / `'span'`), `size?`, `color?`, `weight?`, `truncate?` |
136
234
 
137
235
  ### Layout
138
236
 
139
- | Component | Description |
140
- |-----------|-------------|
141
- | `PageShell` | Page wrapper with animated background orbs |
142
- | `Navbar` | Fixed glass navigation bar |
143
- | `Sidebar` | Collapsible glass sidebar |
144
- | `DashboardLayout` | Navbar + sidebar + content composition |
145
- | `Stack` | Flex container with direction, gap, align, justify |
146
- | `ScrollArea` | Scroll container with custom dark scrollbar styling |
237
+ These components provide the overall page structure. Use them together for full-page layouts.
238
+
239
+ | Component | When to use | Key props |
240
+ |-----------|-------------|-----------|
241
+ | `PageShell` | Page wrapper with animated gradient orbs | `children` |
242
+ | `DashboardLayout` | Full dashboard (navbar + sidebar + content) | `navbar`, `sidebar`, `children` |
243
+ | `Navbar` | Fixed top navigation bar with glass effect | `logo?`, `children` (right-side content), `glass?` |
244
+ | `Sidebar` | Collapsible side navigation | `collapsed?`, `onToggle?`, `children` (nav items) |
245
+ | `Stack` | Flex container | `direction?`, `gap?`, `align?`, `justify?` |
246
+ | `ScrollArea` | Scrollable container with styled scrollbar | `children` |
247
+
248
+ **Full page layout example:**
249
+
250
+ ```tsx
251
+ import { PageShell, DashboardLayout, Navbar, Sidebar, Card } from '@memelabui/ui';
252
+
253
+ function App() {
254
+ return (
255
+ <PageShell>
256
+ <DashboardLayout
257
+ navbar={
258
+ <Navbar logo={<span className="text-gradient font-bold">MyApp</span>}>
259
+ <Button variant="ghost">Sign out</Button>
260
+ </Navbar>
261
+ }
262
+ sidebar={
263
+ <Sidebar>
264
+ <a href="/dashboard" className="px-4 py-2.5 rounded-lg text-sm text-white/60 hover:text-white">
265
+ Overview
266
+ </a>
267
+ <a href="/settings" className="px-4 py-2.5 rounded-lg text-sm bg-accent/20 text-accent">
268
+ Settings
269
+ </a>
270
+ </Sidebar>
271
+ }
272
+ >
273
+ <Card variant="glass" hoverable>
274
+ <h2 className="section-title">Settings</h2>
275
+ <Input label="Bot name" />
276
+ </Card>
277
+ </DashboardLayout>
278
+ </PageShell>
279
+ );
280
+ }
281
+ ```
147
282
 
148
283
  ### Feedback
149
284
 
150
- | Component | Description |
151
- |-----------|-------------|
152
- | `ToastProvider` / `useToast` | Toast notification system with variants |
153
- | `Alert` | Inline notification banner (info, success, warning, error) |
154
- | `CopyField` | Read-only field with copy button and optional masking |
155
- | `Transition` | Animated enter/exit wrapper (fade, scale, slide presets) |
285
+ | Component | When to use | Key props |
286
+ |-----------|-------------|-----------|
287
+ | `ToastProvider` / `useToast` | Toast notifications (wrap app root in Provider) | `useToast()` returns `{ toast }` function |
288
+ | `Alert` | Inline notification banner | `variant` (`'info'` / `'success'` / `'warning'` / `'error'`), `title?`, `children` |
289
+ | `CopyField` | Read-only field with copy button | `value`, `masked?` |
290
+ | `Transition` | Enter/exit animations | `show`, `preset` (`'fade'` / `'scale'` / `'slide'`) |
156
291
 
157
292
  ### Accessibility
158
293
 
159
- | Component | Description |
294
+ | Component | When to use |
160
295
  |-----------|-------------|
161
- | `VisuallyHidden` | Screen reader-only content (invisible but accessible) |
296
+ | `VisuallyHidden` | Screen reader-only text (hidden visually but accessible) |
162
297
 
163
298
  ### Hooks
164
299
 
165
- | Hook | Description |
166
- |------|-------------|
167
- | `useClipboard` | Copy text to clipboard with status |
168
- | `useDisclosure` | Open/close state management |
169
- | `useMediaQuery` | Responsive media query listener |
170
- | `useDebounce` | Debounced value |
171
- | `useHotkeys` | Global keyboard shortcuts with modifier support |
172
- | `useIntersectionObserver` | IntersectionObserver for infinite scroll and lazy loading |
173
- | `useSharedNow` | Reactive current-time for countdowns and "X ago" labels |
300
+ | Hook | When to use | Returns |
301
+ |------|-------------|---------|
302
+ | `useClipboard` | Copy text with status feedback | `{ copy, copied }` |
303
+ | `useDisclosure` | Toggle open/close state for modals, menus | `{ isOpen, onOpen, onClose, onToggle }` |
304
+ | `useMediaQuery` | Respond to viewport changes | `boolean` |
305
+ | `useDebounce` | Debounce fast-changing values (search, resize) | debounced value |
306
+ | `useHotkeys` | Global keyboard shortcuts | bind key combos to callbacks |
307
+ | `useIntersectionObserver` | Lazy loading, infinite scroll | `{ ref, isIntersecting }` |
308
+ | `useSharedNow` | Live clock for "X ago" labels, countdowns | `Date` that updates every N ms |
309
+
310
+ ---
311
+
312
+ ## Common Patterns
313
+
314
+ ### Settings page with sections
315
+
316
+ ```tsx
317
+ import { Card, Input, Textarea, Select, Toggle } from '@memelabui/ui';
318
+
319
+ function SettingsPage() {
320
+ return (
321
+ <div className="space-y-6">
322
+ <Card variant="glass" hoverable>
323
+ <h2 className="section-title">Bot Personality</h2>
324
+ <div className="space-y-4">
325
+ <Input label="Bot name" value={name} onChange={...} />
326
+ <Textarea label="Personality description" value={desc} onChange={...} />
327
+ <div className="grid grid-cols-3 gap-4">
328
+ <Select label="Style"><option>Concise</option></Select>
329
+ <Select label="Language"><option>Auto</option></Select>
330
+ <Input label="Max length" type="number" />
331
+ </div>
332
+ </div>
333
+ </Card>
334
+
335
+ <Card variant="glass" hoverable>
336
+ <h2 className="section-title">Triggers</h2>
337
+ <div className="space-y-3">
338
+ <Toggle label="Respond to @mentions" checked={...} onChange={...} />
339
+ <Toggle label="Respond to keywords" checked={...} onChange={...} />
340
+ <TagInput value={keywords} onChange={...} placeholder="Add keyword" />
341
+ </div>
342
+ </Card>
343
+ </div>
344
+ );
345
+ }
346
+ ```
347
+
348
+ ### Dashboard with stats
349
+
350
+ ```tsx
351
+ import { StatCard, SectionCard, Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@memelabui/ui';
352
+
353
+ function Dashboard() {
354
+ return (
355
+ <>
356
+ <div className="grid grid-cols-3 gap-4 mb-6">
357
+ <StatCard value="1,234" label="Messages" trend={{ value: 12, direction: 'up' }} />
358
+ <StatCard value="89%" label="Response rate" />
359
+ <StatCard value="2.3s" label="Avg. response" />
360
+ </div>
361
+
362
+ <SectionCard title="Recent Activity" description="Last 24 hours">
363
+ <Table>
364
+ <TableHeader>
365
+ <TableRow><TableHead>Time</TableHead><TableHead>Message</TableHead></TableRow>
366
+ </TableHeader>
367
+ <TableBody>
368
+ <TableRow><TableCell>12:30</TableCell><TableCell>Hello bot!</TableCell></TableRow>
369
+ </TableBody>
370
+ </Table>
371
+ </SectionCard>
372
+ </>
373
+ );
374
+ }
375
+ ```
376
+
377
+ ---
174
378
 
175
379
  ## Customization
176
380
 
177
- Override CSS variables to customize the theme:
381
+ Override CSS variables to customize the theme. Values must be **space-separated RGB channels** (not hex) for Tailwind opacity support:
178
382
 
179
383
  ```css
180
- /* Values must be space-separated RGB channels (not hex) for Tailwind opacity support */
181
384
  :root {
182
- --ml-bg: 10 10 15;
183
- --ml-primary: 139 92 246;
184
- --ml-accent: 102 126 234;
185
- --ml-glow-purple: 118 75 162;
186
- --ml-glow-pink: 240 147 251;
187
- --ml-surface-50: 20 20 32;
188
- --ml-surface-100: 30 30 48;
385
+ --ml-bg: 10 10 15; /* Page background */
386
+ --ml-primary: 139 92 246; /* Primary color (buttons, toggles, active states) */
387
+ --ml-accent: 102 126 234; /* Accent / gradient start */
388
+ --ml-glow-purple: 118 75 162; /* Gradient middle */
389
+ --ml-glow-pink: 240 147 251; /* Gradient end */
390
+ --ml-surface-50: 20 20 32; /* Surface tint */
391
+ --ml-surface-100: 30 30 48; /* Surface tint darker */
189
392
  }
190
393
  ```
191
394
 
395
+ Additional tokens:
396
+
397
+ | Token | Default | Purpose |
398
+ |-------|---------|---------|
399
+ | `--ml-glass-bg` | `rgba(255,255,255,0.05)` | Glass panel background |
400
+ | `--ml-glass-blur` | `16px` | Glass backdrop blur |
401
+ | `--ml-glass-border` | `rgba(255,255,255,0.1)` | Glass inset border |
402
+ | `--ml-radius-md` | `0.75rem` | Default border radius |
403
+ | `--ml-font-sans` | System font stack | Base font family |
404
+ | `--ml-transition-fast` | `150ms ease` | Hover/focus transition speed |
405
+
192
406
  ## Features
193
407
 
194
408
  - **Dark-first glassmorphism** design system
package/dist/index.cjs CHANGED
@@ -1236,13 +1236,24 @@ function TabPanel({ value, children, className }) {
1236
1236
  }
1237
1237
  );
1238
1238
  }
1239
- var Card = React.forwardRef(function Card2({ hoverable, variant = "surface", className, ...props }, ref) {
1239
+ var padClass = {
1240
+ none: "",
1241
+ sm: "p-3",
1242
+ md: "p-5",
1243
+ lg: "p-6"
1244
+ };
1245
+ var Card = React.forwardRef(function Card2({ hoverable, variant = "surface", padding = "md", className, ...props }, ref) {
1240
1246
  return /* @__PURE__ */ jsxRuntime.jsx(
1241
1247
  "div",
1242
1248
  {
1243
1249
  ref,
1244
1250
  ...props,
1245
- className: cn(variant === "glass" ? "glass" : "surface", hoverable && "surface-hover", className)
1251
+ className: cn(
1252
+ variant === "glass" ? "glass" : "surface",
1253
+ hoverable && "surface-hover",
1254
+ padClass[padding],
1255
+ className
1256
+ )
1246
1257
  }
1247
1258
  );
1248
1259
  });
package/dist/index.d.cts CHANGED
@@ -330,14 +330,19 @@ declare function Tab({ value, disabled, children, className }: TabProps): react_
330
330
  declare function TabPanel({ value, children, className }: TabPanelProps): react_jsx_runtime.JSX.Element | null;
331
331
 
332
332
  type CardVariant = 'surface' | 'glass';
333
+ type CardPadding = 'none' | 'sm' | 'md' | 'lg';
333
334
  type CardProps = HTMLAttributes<HTMLDivElement> & {
334
335
  hoverable?: boolean;
335
336
  variant?: CardVariant;
337
+ /** Card inner padding. Defaults to `'md'` (20 px). */
338
+ padding?: CardPadding;
336
339
  children: ReactNode;
337
340
  };
338
341
  declare const Card: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
339
342
  hoverable?: boolean;
340
343
  variant?: CardVariant;
344
+ /** Card inner padding. Defaults to `'md'` (20 px). */
345
+ padding?: CardPadding;
341
346
  children: ReactNode;
342
347
  } & react.RefAttributes<HTMLDivElement>>;
343
348
 
@@ -914,4 +919,4 @@ type VisuallyHiddenProps = HTMLAttributes<HTMLSpanElement> & {
914
919
  */
915
920
  declare function VisuallyHidden({ children, as: Tag, style, ...props }: VisuallyHiddenProps): react_jsx_runtime.JSX.Element;
916
921
 
917
- export { ActiveFilterPills, type ActiveFilterPillsProps, Alert, type AlertProps, type AlertVariant, Avatar, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeSize, type BadgeVariant, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, type CardProps, type CardVariant, Checkbox, type CheckboxProps, CollapsibleSection, type CollapsibleSectionProps, ColorInput, type ColorInputProps, Combobox, type ComboboxOption, type ComboboxProps, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogVariant, CooldownRing, type CooldownRingProps, type CooldownRingSize, CopyField, type CopyFieldProps, DashboardLayout, type DashboardLayoutProps, Divider, type DividerProps, DotIndicator, type DotIndicatorProps, Drawer, type DrawerProps, type DrawerSide, type DrawerSize, DropZone, type DropZoneProps, Dropdown, DropdownItem, type DropdownItemProps, DropdownMenu, type DropdownMenuProps, type DropdownProps, DropdownSeparator, type DropdownSeparatorProps, DropdownTrigger, type DropdownTriggerProps, EmptyState, type EmptyStateProps, type FilterPill, FormField, type FormFieldProps, Heading, type HeadingLevel, type HeadingProps, type HotkeyBinding, type HotkeyModifiers, IconButton, type IconButtonProps, Input, type InputProps, Modal, type ModalProps, MutationOverlay, type MutationOverlayProps, type MutationOverlayStatus, Navbar, type NavbarProps, NotificationBell, type NotificationBellProps, PageShell, type PageShellProps, type PageShellVariant, Pagination, type PaginationProps, Pill, Popover, type PopoverPlacement, type PopoverProps, ProgressBar, type ProgressBarProps, type ProgressBarVariant, ProgressButton, type ProgressButtonProps, RadioGroup, type RadioGroupProps, RadioItem, type RadioItemProps, ScrollArea, type ScrollAreaProps, SearchInput, type SearchInputProps, SectionCard, type SectionCardProps, Select, type SelectProps, Sidebar, type SidebarProps, type Size, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, type SpinnerSize, Stack, type StackProps, StageProgress, type StageProgressProps, StatCard, type StatCardProps, type StatCardTrend, type Step, Stepper, type StepperProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHead, type TableHeadProps, TableHeader, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, type TabsProps, type TabsVariant, TagInput, type TagInputProps, Text, type TextColor, type TextProps, type TextSize, Textarea, type TextareaProps, type ToastData, type ToastPosition, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, Tooltip, type TooltipPlacement, type TooltipProps, Transition, type TransitionPreset, type TransitionProps, type UseClipboardReturn, type UseDisclosureReturn, type UseHotkeysOptions, type UseIntersectionObserverOptions, type UseIntersectionObserverReturn, type UseSharedNowOptions, VisuallyHidden, type VisuallyHiddenProps, cn, focusSafely, getFocusableElements, useClipboard, useDebounce, useDisclosure, useHotkeys, useIntersectionObserver, useMediaQuery, useSharedNow, useToast };
922
+ export { ActiveFilterPills, type ActiveFilterPillsProps, Alert, type AlertProps, type AlertVariant, Avatar, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeSize, type BadgeVariant, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, type CardPadding, type CardProps, type CardVariant, Checkbox, type CheckboxProps, CollapsibleSection, type CollapsibleSectionProps, ColorInput, type ColorInputProps, Combobox, type ComboboxOption, type ComboboxProps, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogVariant, CooldownRing, type CooldownRingProps, type CooldownRingSize, CopyField, type CopyFieldProps, DashboardLayout, type DashboardLayoutProps, Divider, type DividerProps, DotIndicator, type DotIndicatorProps, Drawer, type DrawerProps, type DrawerSide, type DrawerSize, DropZone, type DropZoneProps, Dropdown, DropdownItem, type DropdownItemProps, DropdownMenu, type DropdownMenuProps, type DropdownProps, DropdownSeparator, type DropdownSeparatorProps, DropdownTrigger, type DropdownTriggerProps, EmptyState, type EmptyStateProps, type FilterPill, FormField, type FormFieldProps, Heading, type HeadingLevel, type HeadingProps, type HotkeyBinding, type HotkeyModifiers, IconButton, type IconButtonProps, Input, type InputProps, Modal, type ModalProps, MutationOverlay, type MutationOverlayProps, type MutationOverlayStatus, Navbar, type NavbarProps, NotificationBell, type NotificationBellProps, PageShell, type PageShellProps, type PageShellVariant, Pagination, type PaginationProps, Pill, Popover, type PopoverPlacement, type PopoverProps, ProgressBar, type ProgressBarProps, type ProgressBarVariant, ProgressButton, type ProgressButtonProps, RadioGroup, type RadioGroupProps, RadioItem, type RadioItemProps, ScrollArea, type ScrollAreaProps, SearchInput, type SearchInputProps, SectionCard, type SectionCardProps, Select, type SelectProps, Sidebar, type SidebarProps, type Size, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, type SpinnerSize, Stack, type StackProps, StageProgress, type StageProgressProps, StatCard, type StatCardProps, type StatCardTrend, type Step, Stepper, type StepperProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHead, type TableHeadProps, TableHeader, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, type TabsProps, type TabsVariant, TagInput, type TagInputProps, Text, type TextColor, type TextProps, type TextSize, Textarea, type TextareaProps, type ToastData, type ToastPosition, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, Tooltip, type TooltipPlacement, type TooltipProps, Transition, type TransitionPreset, type TransitionProps, type UseClipboardReturn, type UseDisclosureReturn, type UseHotkeysOptions, type UseIntersectionObserverOptions, type UseIntersectionObserverReturn, type UseSharedNowOptions, VisuallyHidden, type VisuallyHiddenProps, cn, focusSafely, getFocusableElements, useClipboard, useDebounce, useDisclosure, useHotkeys, useIntersectionObserver, useMediaQuery, useSharedNow, useToast };
package/dist/index.d.ts CHANGED
@@ -330,14 +330,19 @@ declare function Tab({ value, disabled, children, className }: TabProps): react_
330
330
  declare function TabPanel({ value, children, className }: TabPanelProps): react_jsx_runtime.JSX.Element | null;
331
331
 
332
332
  type CardVariant = 'surface' | 'glass';
333
+ type CardPadding = 'none' | 'sm' | 'md' | 'lg';
333
334
  type CardProps = HTMLAttributes<HTMLDivElement> & {
334
335
  hoverable?: boolean;
335
336
  variant?: CardVariant;
337
+ /** Card inner padding. Defaults to `'md'` (20 px). */
338
+ padding?: CardPadding;
336
339
  children: ReactNode;
337
340
  };
338
341
  declare const Card: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
339
342
  hoverable?: boolean;
340
343
  variant?: CardVariant;
344
+ /** Card inner padding. Defaults to `'md'` (20 px). */
345
+ padding?: CardPadding;
341
346
  children: ReactNode;
342
347
  } & react.RefAttributes<HTMLDivElement>>;
343
348
 
@@ -914,4 +919,4 @@ type VisuallyHiddenProps = HTMLAttributes<HTMLSpanElement> & {
914
919
  */
915
920
  declare function VisuallyHidden({ children, as: Tag, style, ...props }: VisuallyHiddenProps): react_jsx_runtime.JSX.Element;
916
921
 
917
- export { ActiveFilterPills, type ActiveFilterPillsProps, Alert, type AlertProps, type AlertVariant, Avatar, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeSize, type BadgeVariant, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, type CardProps, type CardVariant, Checkbox, type CheckboxProps, CollapsibleSection, type CollapsibleSectionProps, ColorInput, type ColorInputProps, Combobox, type ComboboxOption, type ComboboxProps, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogVariant, CooldownRing, type CooldownRingProps, type CooldownRingSize, CopyField, type CopyFieldProps, DashboardLayout, type DashboardLayoutProps, Divider, type DividerProps, DotIndicator, type DotIndicatorProps, Drawer, type DrawerProps, type DrawerSide, type DrawerSize, DropZone, type DropZoneProps, Dropdown, DropdownItem, type DropdownItemProps, DropdownMenu, type DropdownMenuProps, type DropdownProps, DropdownSeparator, type DropdownSeparatorProps, DropdownTrigger, type DropdownTriggerProps, EmptyState, type EmptyStateProps, type FilterPill, FormField, type FormFieldProps, Heading, type HeadingLevel, type HeadingProps, type HotkeyBinding, type HotkeyModifiers, IconButton, type IconButtonProps, Input, type InputProps, Modal, type ModalProps, MutationOverlay, type MutationOverlayProps, type MutationOverlayStatus, Navbar, type NavbarProps, NotificationBell, type NotificationBellProps, PageShell, type PageShellProps, type PageShellVariant, Pagination, type PaginationProps, Pill, Popover, type PopoverPlacement, type PopoverProps, ProgressBar, type ProgressBarProps, type ProgressBarVariant, ProgressButton, type ProgressButtonProps, RadioGroup, type RadioGroupProps, RadioItem, type RadioItemProps, ScrollArea, type ScrollAreaProps, SearchInput, type SearchInputProps, SectionCard, type SectionCardProps, Select, type SelectProps, Sidebar, type SidebarProps, type Size, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, type SpinnerSize, Stack, type StackProps, StageProgress, type StageProgressProps, StatCard, type StatCardProps, type StatCardTrend, type Step, Stepper, type StepperProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHead, type TableHeadProps, TableHeader, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, type TabsProps, type TabsVariant, TagInput, type TagInputProps, Text, type TextColor, type TextProps, type TextSize, Textarea, type TextareaProps, type ToastData, type ToastPosition, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, Tooltip, type TooltipPlacement, type TooltipProps, Transition, type TransitionPreset, type TransitionProps, type UseClipboardReturn, type UseDisclosureReturn, type UseHotkeysOptions, type UseIntersectionObserverOptions, type UseIntersectionObserverReturn, type UseSharedNowOptions, VisuallyHidden, type VisuallyHiddenProps, cn, focusSafely, getFocusableElements, useClipboard, useDebounce, useDisclosure, useHotkeys, useIntersectionObserver, useMediaQuery, useSharedNow, useToast };
922
+ export { ActiveFilterPills, type ActiveFilterPillsProps, Alert, type AlertProps, type AlertVariant, Avatar, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeSize, type BadgeVariant, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, type CardPadding, type CardProps, type CardVariant, Checkbox, type CheckboxProps, CollapsibleSection, type CollapsibleSectionProps, ColorInput, type ColorInputProps, Combobox, type ComboboxOption, type ComboboxProps, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogVariant, CooldownRing, type CooldownRingProps, type CooldownRingSize, CopyField, type CopyFieldProps, DashboardLayout, type DashboardLayoutProps, Divider, type DividerProps, DotIndicator, type DotIndicatorProps, Drawer, type DrawerProps, type DrawerSide, type DrawerSize, DropZone, type DropZoneProps, Dropdown, DropdownItem, type DropdownItemProps, DropdownMenu, type DropdownMenuProps, type DropdownProps, DropdownSeparator, type DropdownSeparatorProps, DropdownTrigger, type DropdownTriggerProps, EmptyState, type EmptyStateProps, type FilterPill, FormField, type FormFieldProps, Heading, type HeadingLevel, type HeadingProps, type HotkeyBinding, type HotkeyModifiers, IconButton, type IconButtonProps, Input, type InputProps, Modal, type ModalProps, MutationOverlay, type MutationOverlayProps, type MutationOverlayStatus, Navbar, type NavbarProps, NotificationBell, type NotificationBellProps, PageShell, type PageShellProps, type PageShellVariant, Pagination, type PaginationProps, Pill, Popover, type PopoverPlacement, type PopoverProps, ProgressBar, type ProgressBarProps, type ProgressBarVariant, ProgressButton, type ProgressButtonProps, RadioGroup, type RadioGroupProps, RadioItem, type RadioItemProps, ScrollArea, type ScrollAreaProps, SearchInput, type SearchInputProps, SectionCard, type SectionCardProps, Select, type SelectProps, Sidebar, type SidebarProps, type Size, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, type SpinnerSize, Stack, type StackProps, StageProgress, type StageProgressProps, StatCard, type StatCardProps, type StatCardTrend, type Step, Stepper, type StepperProps, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Table, TableBody, type TableBodyProps, TableCell, type TableCellProps, TableHead, type TableHeadProps, TableHeader, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, type TabsProps, type TabsVariant, TagInput, type TagInputProps, Text, type TextColor, type TextProps, type TextSize, Textarea, type TextareaProps, type ToastData, type ToastPosition, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, Tooltip, type TooltipPlacement, type TooltipProps, Transition, type TransitionPreset, type TransitionProps, type UseClipboardReturn, type UseDisclosureReturn, type UseHotkeysOptions, type UseIntersectionObserverOptions, type UseIntersectionObserverReturn, type UseSharedNowOptions, VisuallyHidden, type VisuallyHiddenProps, cn, focusSafely, getFocusableElements, useClipboard, useDebounce, useDisclosure, useHotkeys, useIntersectionObserver, useMediaQuery, useSharedNow, useToast };
package/dist/index.js CHANGED
@@ -1230,13 +1230,24 @@ function TabPanel({ value, children, className }) {
1230
1230
  }
1231
1231
  );
1232
1232
  }
1233
- var Card = forwardRef(function Card2({ hoverable, variant = "surface", className, ...props }, ref) {
1233
+ var padClass = {
1234
+ none: "",
1235
+ sm: "p-3",
1236
+ md: "p-5",
1237
+ lg: "p-6"
1238
+ };
1239
+ var Card = forwardRef(function Card2({ hoverable, variant = "surface", padding = "md", className, ...props }, ref) {
1234
1240
  return /* @__PURE__ */ jsx(
1235
1241
  "div",
1236
1242
  {
1237
1243
  ref,
1238
1244
  ...props,
1239
- className: cn(variant === "glass" ? "glass" : "surface", hoverable && "surface-hover", className)
1245
+ className: cn(
1246
+ variant === "glass" ? "glass" : "surface",
1247
+ hoverable && "surface-hover",
1248
+ padClass[padding],
1249
+ className
1250
+ )
1240
1251
  }
1241
1252
  );
1242
1253
  });
@@ -686,6 +686,7 @@ a {
686
686
  inset 0 0 0 1px rgba(255, 255, 255, 0.09)
687
687
  );
688
688
  }
689
+ /* Section title — heading inside a card */
689
690
  /* Gradient text */
690
691
  .text-gradient {
691
692
  background: linear-gradient(
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memelabui/ui",
3
- "version": "0.6.1",
3
+ "version": "0.7.0",
4
4
  "description": "MemeLab shared UI component library — React + Tailwind + Glassmorphism",
5
5
  "type": "module",
6
6
  "sideEffects": [