bigtablet-design-system/README.md at main · Bigtablet/bigtablet-design-system

Bigtablet Design System

The unified UI library powering Bigtablet products.
Crafted for clarity. Built on tokens. Ships with dark mode.

Documentation · Storybook · NPM · 🇰🇷 한국어

import { ThemeProvider, Button, Modal, useToast } from "@bigtablet/design-system";
import "@bigtablet/design-system/style.css";

export default function App() {
  const toast = useToast();
  return (
    <ThemeProvider>
      <Button onClick={() => toast.success("Saved")}>Save</Button>
    </ThemeProvider>
  );
}

A complete React + TypeScript design system maintained by Bigtablet for internal product work. Open-sourced for reference - external use welcome, but minor versions may include breaking changes.

What's inside

40+ components across forms, display, feedback, navigation, overlay, and layout
13 token domains - colors, typography, spacing, motion, radius, elevation, and more - exposed as SCSS variables and CSS custom properties (plus a SCSS-only layout domain)
Light + dark mode out of the box. [data-theme="dark"] or prefers-color-scheme, no theme provider required (but available via ThemeProvider for runtime toggling)
Vanilla JS bundle for non-React backends - Thymeleaf, JSP, PHP, Django
Accessibility tested with axe-core in CI · keyboard nav · ARIA throughout

Install

pnpm add @bigtablet/design-system react@^19 react-dom@^19 lucide-react

Requires React 19 + lucide-react ≥ 0.552. Next.js is an optional peer dependency at >=15.

One-line setup - auto-detect package manager + framework

curl -fsSL https://raw.githubusercontent.com/Bigtablet/bigtablet-design-system/main/scripts/setup.sh | sh

Detects npm / yarn / pnpm / bun and React / Next.js, installs deps, prints CSS + provider setup steps.

Providers

import { ThemeProvider, AlertProvider, ToastProvider } from "@bigtablet/design-system";

<ThemeProvider>
  <AlertProvider>
    <ToastProvider>{children}</ToastProvider>
  </AlertProvider>
</ThemeProvider>

Use the hooks anywhere:

const toast = useToast();
const { showAlert } = useAlert();

toast.success("Saved");
showAlert({ title: "Delete?", showCancel: true, onConfirm: ... });

Components

Forms	Button · IconButton · TextField · Textarea · Checkbox · Radio · RadioGroup · Toggle · Dropdown · DatePicker · FileInput · ImageCropper · OtpInput
Display	Card · MediaCard · Hero · Avatar · Badge · Chip · ListItem · Table · Divider · Icon · Accordion
Feedback	Alert · Toast · Spinner · TopLoading · LinearProgress · Skeleton · EmptyState · ErrorState
Navigation	Tabs · Sidebar · BottomNav · NavBar · Breadcrumb · Menu · Pagination
Overlay	Modal · Drawer · Tooltip · Popover
Layout	Container · Section · Stack · Grid
System	ThemeProvider

→ Full API · docs/COMPONENTS.md

Design tokens

@use "@bigtablet/design-system/scss/token" as token;

.card {
  background: token.$color_bg_solid;
  color: token.$color_text_heading;
  padding: token.$spacing_16;
  border-radius: token.$radius_md;
  box-shadow: token.$elevation_level1;
}

/* from @bigtablet/design-system/style.css */
.card {
  background: var(--bt-color-bg-solid);
  color: var(--bt-color-text-heading);
  border: 1px solid var(--bt-color-border-default);
  box-shadow: var(--bt-elevation-level1);
}

The React entry's style.css only emits --bt-color-*, --bt-elevation-*, --bt-focus-*, --bt-sidebar-*, and --bt-bottom-nav-*. Spacing, radius, and typography are SCSS-only on this entry - use scss/token for them (--bt-spacing-* / --bt-radius-* exist only in the Vanilla bundle).

colors · spacing · typography · radius · elevation · motion · z-index · breakpoints · border-width · opacity · skeleton · icon · a11y · layout^{SCSS only}

Vanilla JS

For server-rendered apps (Thymeleaf, JSP, PHP, Django):

<link rel="stylesheet" href="https://unpkg.com/@bigtablet/design-system/dist/vanilla/bigtablet.min.css">
<script src="https://unpkg.com/@bigtablet/design-system/dist/vanilla/bigtablet.min.js"></script>

<button class="bt-button bt-button--md bt-button--filled">Filled</button>

→ Full guide · docs/VANILLA.md

Development

pnpm install
pnpm storybook        # localhost:6006
pnpm test             # Vitest unit
pnpm test:storybook   # a11y + Playwright
pnpm build            # tsup + SCSS copy

The published Storybook lives at bigtablet.github.io/bigtablet-design-system and redeploys from main.

Documentation


📚 Components	Props API + usage per component
🔄 Migration	Deprecated prop migration guide
🎨 Theming	Light/dark theme system guide
🏗️ Architecture	Project structure + design principles
🤝 Contributing	Dev setup + workflow
🧪 Testing	Test patterns + a11y testing
🌐 Vanilla JS	HTML/CSS/JS integration

License

Licensed under the Bigtablet License.

_{Made with care by the Bigtablet team.}

_{GitHub · Issues · NPM}

Navigation Menu

Uh oh!