# Pixelize Design Library A comprehensive React component library built with TypeScript, providing a rich set of UI components for modern web applications. > **Building with this library (including via an AI assistant)?** Read > [COMPONENT-GOTCHAS.md](./COMPONENT-GOTCHAS.md) first โ€” it documents known silent-failure traps > and which near-duplicate component to pick for what. It ships with this package, so it's > available at `node_modules/pixelize-design-library/COMPONENT-GOTCHAS.md` too. > Building a whole screen? [DESIGN-GUIDE.md](./DESIGN-GUIDE.md) (also shipped) covers page anatomy, > spacing, type, color roles and the four page states. ## Features - ๐ŸŽจ **Modern Design System** - Consistent and beautiful components - ๐Ÿ“ฑ **Responsive** - Mobile-first design approach - โ™ฟ **Accessible** - Built with accessibility in mind - ๐Ÿ”ง **TypeScript** - Full TypeScript support - ๐ŸŽฏ **Customizable** - Easy theming and customization - ๐Ÿ“ฆ **Tree-shakable** - Import only what you need ## Prerequisites Before you begin, ensure you have the following installed: - Node.js (v18 or higher) - npm (v7 or higher) or yarn - React and React DOM `^18.3.1` ## Installation Install the library, then its peer dependencies: ```bash npm install pixelize-design-library ``` ```bash npm install @chakra-ui/react@^2.8.2 @emotion/react@^11.11.4 @emotion/styled@^11.11.5 framer-motion@^10.18.0 ``` `react` and `react-dom` are peers pinned to `^18.3.1`. **React 19 is not supported** โ€” the pin tracks Chakra 2.8. ### Versioning Everything ships on the `latest` dist-tag. Stable `3.x` takes a caret range: ```json "pixelize-design-library": "^3.0.0" ``` There are no prereleases from 3.0.0 onward. The old `2.4.2-beta.N` line was folded into 3.0.0; if you are still pinned to one, change the pin to `3.0.0`. What changed in each release, and what breaks in 3.0.0: [CHANGELOG.md](CHANGELOG.md). ## Quick Start ```tsx import React from 'react'; import { Button, Card, TextInput } from 'pixelize-design-library'; function App() { return (
); } export default App; ``` ## Theming and filled surfaces Nine brand presets with light/dark palettes. Wrap your app in `PixelizeThemeProvider` and read tokens via `useCustomTheme()`. **Do not** pair a scale's `[500]` swatch with `colors.white` or `onPrimary` for custom filled UI โ€” white often fails WCAG on `[500]` and ink falls back to black (e.g. black text on red badges). Use library components (`Button`, `Tag`, `Badge`) or: ```ts import { resolveFilledSurface, useCustomTheme } from "pixelize-design-library"; const { colors } = useCustomTheme(); const solid = resolveFilledSurface(colors.red, colors); // solid.fill, solid.color, solid.hoverFill, solid.hoverColor, โ€ฆ ``` Full rules for app developers and AI assistants: [`src/Theme/THEME-CONTRACT.md`](src/Theme/THEME-CONTRACT.md) (ยง *Filled surfaces in consumer apps*). After upgrading, rebuild the library (`npm run build`) and run `npm run pixelize` in consumer frontends. ## Components ### Layout & Navigation - **Accordion** - Collapsible content sections - **Breadcrumbs** - Navigation breadcrumb trail - **Card** - Container component for content - **Modal** - Overlay dialog component - **NavigationBar** - Main navigation component - **SideBar** - Side navigation panel ### Form Controls - **Button** - Interactive button component - **ButtonGroupIcon** - Icon-based button group - **Checkbox** - Checkbox input control - **DatePicker** - Date selection component - **Dropdown** - Action menu (a menu button, not a value picker) - **MultiSelect** - Typed email-chip input (no options list) - **NumberInput** - Numeric input field - **PinInput** - PIN/OTP input component - **RadioButton** - Radio button input - **RadioButtonGroup** - Group of radio buttons - **RangeSlider** - Single or dual-thumb slider with tick marks - **Search** - Search input component - **SearchSelect** - Searchable select dropdown - **Select** - Native or themed popup picker, single or multi, optionally searchable - **ToggleSwitch** - On/off switch (`Switch` is a deprecated two-option pill) - **TextInput** - Text input field - **InputTextArea** - Multi-line text input - **NoteTextArea** - Textarea with a title and file attach (not rich text; use `Editor`) ### Data Display - **Table** - Data table component - **MediaViewer** - Full-screen viewer for images, video, audio, PDF, Office, text and archives - **Timeline** - Timeline visualization - **Skeletons** - Loading skeleton components - **ProgressBar** - Progress indicator ### Charts & Visualization - **ApexBarChart** - Bar chart component - **ApexPieChart** - Pie chart component ### Feedback & Status - **AlertDialog** - Confirm dialog for destructive actions - **ConfirmDialog** - Cancel/Confirm prompt, with optional typed confirmation - **NotificationBell** - Badge/bell button - **NotificationPanel** / **NotificationList** / **NotificationItem** - the tray, its body and one row - **Loading** - Blocking loading overlay (`Backdrop` for a lighter scrim) - **Spinner** - Themed inline spinner - **Toaster** - Toast notification system - **useToaster** - Hook for toast management - **ToolTip** - Tooltip component ### User & Profile - **Avatar** / **AvatarGroup** - Fill derived from `name`, so it follows brand and dark mode - **ProfileCard** - User profile card - **ProfilePhotoViewer** - Profile photo viewer - **VerifyEmailOtp** - Email verification component ### Editor - **Editor** - Rich text editor component The lists above are the common components. Every export, including the helpers, hooks and tokens, is in the [Exports index](#exports-index). ## Usage Examples ### Basic Button Usage ```tsx import { Button } from 'pixelize-design-library'; function MyComponent() { return (
); } ``` ### Form with Validation ```tsx import { useState } from 'react'; import { TextInput, Button, Card } from 'pixelize-design-library'; function LoginForm() { const [email, setEmail] = useState(''); const [password, setPassword] = useState(''); return ( setEmail(e.target.value)} required /> setPassword(e.target.value)} required /> ); } ``` ### Data Table ```tsx import { Table } from 'pixelize-design-library'; const columns = [ { id: 'name', label: 'Name' }, { id: 'email', label: 'Email' }, { id: 'role', label: 'Role' } ]; // every row needs a unique id const data = [ { id: 1, name: 'John Doe', email: 'john@example.com', role: 'Admin' }, { id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'User' } ]; function DataTable() { return ( ); } ``` ## Theming The library ships **9 brand themes** (`lavender`, `meadow`, `radiant`, `skyline`, `slate`, `emerald`, `rosewood`, `storefront`, `zinc`), each with a **light and a dark palette**. ### Existing apps (unchanged) `withTheme` is the original default export and still renders **light only**. Upgrading the package changes nothing visually: ```tsx import withTheme, { ThemesList } from 'pixelize-design-library'; export default withTheme(App, ThemesList.lavender); ``` ### Opting into light / dark / system Wrap the app in `PixelizeThemeProvider` instead. It defaults to **`system`** (follows the OS) and persists the user's choice to `localStorage`. ```tsx import { PixelizeThemeProvider, ThemeSwitcher } from 'pixelize-design-library'; function Root() { return ( ); } // Drop the switcher anywhere inside the provider: // icon toggle // Light / System / Dark // + brand picker ``` | `PixelizeThemeProvider` prop | Default | Meaning | | ---------------------------- | ------- | ------- | | `brand` | `"lavender"` | Which brand theme to use | | `defaultMode` | `"system"` | `"light"` \| `"dark"` \| `"system"` | | `storageKey` | `"pixelize-theme"` | localStorage key | | `disablePersistence` | `false` | Don't read/write localStorage | | `onBrandChange` / `onModeChange` | โ€” | Fire on user-driven changes only | | `themeOverrides` | โ€” | Chakra theme object merged over the brand theme | | `reducedMotion` | `"components"` | `"global"` applies one reduced-motion rule to the whole document | ### Reading or changing the theme in code ```tsx import { useThemeMode, useCustomTheme } from 'pixelize-design-library'; const { mode, resolvedMode, setMode, toggle, brand, setBrand } = useThemeMode(); const theme = useCustomTheme(); // returns the palette for the ACTIVE color mode ``` `useCustomTheme()` returns the dark palette automatically in dark mode, so components that read their colors from it are dark-aware with no extra work. ### Building components Read colors from the theme โ€” never hardcode a hex, or the component will be stuck in light mode: ```tsx const theme = useCustomTheme(); // โœ… adapts // โŒ breaks in dark ``` `colors.white` is a **foreground** token (the label on a filled button) and stays white in dark mode. For a white **surface**, use `colors.background[50]`. ### Design tokens (shared with the mobile library) `lightPalettes`, `darkPalettes`, `palettes`, `themeNames`, and `buildDarkPalette` are exported for apps that build custom themes. The token source (`src/Theme/tokens/`) is pure TypeScript with no Chakra, React, or CSS imports, so it is portable to React Native. ```ts import { lightPalettes, buildDarkPalette } from 'pixelize-design-library'; const myDark = buildDarkPalette(lightPalettes.emerald); ``` ## TypeScript Support All components are built with TypeScript and include full type definitions: ```tsx import { Button, ButtonProps } from 'pixelize-design-library'; interface CustomButtonProps extends ButtonProps { customProp?: string; } function CustomButton({ customProp, ...props }: CustomButtonProps) { return