# @memelabui/ui
Shared UI component library for MemeLab projects. Dark-first glassmorphism design system built with React, TypeScript, and Tailwind CSS.
[](https://www.npmjs.com/package/@memelabui/ui)
## Install
```bash
pnpm add @memelabui/ui
```
Peer dependencies: `react >= 18`, `react-dom >= 18`, `tailwindcss >= 3.4`.
## Setup
### 1. Tailwind preset
```ts
// tailwind.config.ts
import memelabPreset from '@memelabui/ui/preset';
export default {
presets: [memelabPreset],
content: ['./src/**/*.{ts,tsx}', './node_modules/@memelabui/ui/dist/**/*.{js,mjs}'],
};
```
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.
### 2. Import styles
```ts
// main.tsx (before your app code)
import '@memelabui/ui/styles';
```
This imports base styles, CSS variables (`--ml-*` tokens), glassmorphism utility classes, and component animations. Must be imported once at the root of your app.
### 3. Use components
```tsx
import { Button, Card, Input, ToastProvider } from '@memelabui/ui';
function App() {
return (
Login
);
}
```
---
## CSS Utility Classes
These classes are available globally after importing `@memelabui/ui/styles`. They provide the MemeLab visual foundation.
| Class | Purpose | When to use |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `.panel` | Opaque warm-charcoal panel — `bg`, inset hairline border, rounded. **No blur** — this stopped being glassmorphism in the Console rework | Visual shell for containers. **Does not include padding** — use `Card` component for padded cards |
| `.glass` | Deprecated alias of `.panel`, kept so markup that writes it compiles. Nothing in the package emits it since 0.50.0. Do not write it in new code | — |
| `.hit-target` | Expands a control's hit box to 40×40 without moving layout. The control must already be positioned, and its neighbours must be audited — two skirts at a 4px gap overlap and the later one steals the tap | Small icon buttons, clear/dismiss controls, where nothing sits within 8px |
| `.tooltip-disabled-anchor` | The focusable anchor `Tooltip` builds around a child that cannot be a trigger. It is a tab stop only when the subtree inside it has none — measured after render, not inferred from the child | Not for direct use |
| `.surface` | Surface panel — slightly more opaque `bg`, `blur(12px)`, border shadow | Alternative to `.glass` with stronger background. Also **no padding** |
| `.surface-hover` | Hover elevation transition — adds `box-shadow` on hover | Pair with `.glass` or `.surface` for interactive cards |
| `.section-title` | Card section heading — `font-semibold`, `border-bottom`, `mb-4` | Use inside `Card` for titled sections (settings, forms) |
| `.text-gradient` | Gradient text (violet to pink) | Branding, hero headings |
| `.animated-gradient` | Animated gradient background | Decorative elements, loading placeholders |
| `.page-container` | Centered max-w-80rem container with responsive padding | Page-level wrapper |
| `.orb` / `.orb-purple` / `.orb-blue` / `.orb-pink` | Decorative blurred orbs | Background effects (see `PageShell`) |
| `.pb-safe` / `.pt-safe` | iOS safe area padding | Mobile bottom/top bars |
| `.no-scrollbar` | Hides scrollbar | Horizontal scroll areas, custom scrolling |
| `.link-soft` | Subtle underline link | Secondary navigation links |
### Important: `.glass` / `.surface` vs `Card`
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).
**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.
```tsx
// Correct — Card handles padding automatically
Settings
// Avoid — raw classes require manual padding
Settings
```
---
## Components
### Cards & Containers
Use these to wrap content sections. Each has different levels of structure.
| Component | When to use | Key props |
| -------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `Card` | Generic content container with glassmorphism | `variant` (`'surface'` / `'glass'`), `hoverable`, `padding` (`'none'` / `'sm'` / `'md'` / `'lg'`) |
| `SectionCard` | Settings/config section with title, description, and optional right slot | `title`, `description?`, `right?`, `overlay?` |
| `StatCard` | Dashboard metric tile with clickable, compact, and compound variants | `value`, `label`, `icon?`, `trend?`, `size?`, `secondaryMetric?`, `href?`, `loading?` |
| `CollapsibleSection` | Expandable/collapsible content block | `title`, `defaultOpen?` |
**Choosing the right card:**
- Building a **settings form section** (title + form fields)? Use `SectionCard`
- Showing a **dashboard metric** (number + label + icon)? Use `StatCard`
- Need a **generic container** with glass/surface styling? Use `Card`
- Need an **expandable block**? Use `CollapsibleSection`
```tsx
// Settings page section
// Dashboard metric
// Generic glass card
Any content here
```
### Form Inputs
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.
| Component | When to use | Key props |
| -------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------- |
| `Input` | Single-line text input | `label?`, `error?`, `helperText?`, `hasError?` + all `` attrs |
| `SearchInput` | Search field with icon and clear button | `onClear?` + all `Input` props |
| `DateRangePicker` | Date range input with presets, calendar popover, and mobile drawer | `value`, `onChange`, `presets?`, `maxRangeDays?`, `compact?` |
| `Textarea` | Multi-line text input | `label?`, `error?` + all `