Packets Design System (Packets) Copyright (c) 2026, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov.
NOTICE. This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit others to do so.
Packets is a design system created as a cross organizational collaboration at ESnet. It is intended to be a source of truth for common UI/UX patterns. It leverages a design tokens powered system and currently provides artifacts for CSS-only, Web Component & React GUIs with the intent of adding support for other GUI solutions moving forward.
Packets is officially open source as of version 2.0.0! The monorepo can be found here in our GitHub instance.
- Decide on the approach you'd like to use. Here's a quick reference table:
| Feature | CSS Components | Web Components | React Components |
|---|---|---|---|
| Framework | None required | Framework-agnostic | React only |
| JavaScript | Optional | Included | Required |
| Bundle Size | Smallest (CSS only) | Medium (JS + CSS) | Largest (React + components) |
| TypeScript | N/A (CSS only) | Full type definitions | Full type definitions |
| Learning Curve | Easiest | Medium | Medium |
| Interactivity | Basic, HTML Built-in | Full interactivity | Full interactivity |
| Best For | Static sites, server-rendered apps | Vanilla/Framework-agnostic apps | React applications |
| Installation | npm install @esnet/packets-ui-css |
npm install @esnet/packets-ui-css @esnet/packets-ui-web |
npm install @esnet-packets-ui-css @esnet/packets-ui-react |
- Add the
packetsclass to the<body>or root level tag of your project. - (Optional) Add
darkorlightclasses to the tag you chose, e.g.<body class="packets dark">. - Add the following to your
<head>element to fetch our fonts from Google's CDN:<link rel="preconnect" href="https://fonts.googleapis.com" /> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin /> <link href="https://fonts.googleapis.com/css2?family=Signika:wght@300..700&family=Source+Code+Pro:ital,wght@0,200..900;1,200..900&family=Source+Sans+3:ital,wght@0,200..900;1,200..900&display=swap" rel="stylesheet" />
- git clone git@github.com:esnet/packets-design-system.git
- Run
pnpm installon the root of the project. - Run
pnpm run buildalso in the root of the project. - Run
make docs-buildto build the documentation Docker container - Run
make docs-runand open http://localhost:9888 to access the Storybook - To stop, Ctrl-C
- Run
make docs-cleanto clean up the Docker container.
make lint - Run linting
make format - Format code with prettier
make clean - Clean build artifacts
make docs-build - Build Docker image with all 4 Storybooks
make docs-run - Run documentation container on port 9888
make docs-stop - Stop running documentation container
Packets uses Playwright to execute visual regression tests to ensure that components stay styled predictably and correctly from commit to commit. Because screenshots are executed in a docker container in our CI process, they must also be generated in the same docker container to ensure tests pass. These Makefile commands should help ease the burden of managing the screenshots in a docker container.
make pull-image - Pull the Playwright Docker image
make screenshots-build - Build docker image and all packages
make screenshots-generate - Generate new screenshots for all packages
make screenshots-regenerate - Clean then generate screenshots for all packages
make screenshots-clean - Delete all screenshot directories
make screenshots-test - Run all tests (React, Web, CSS)
make screenshots-test-react - Run React component tests only
make screenshots-test-web - Run Web Component tests only
make screenshots-test-css - Run CSS-only tests only
To add a new component:
- Build the CSS-only component (
packages/ui-css/src/components) and create Storybook documentation (apps/css-docs/src) - Build the Web component (
packages/ui-web/src/components) and create Storybook documentation (apps/web-docs/src) - Build the React component (
packages/ui-react/src/components) and create Storybook documentation (apps/web-docs/src)
- make pull-image # First time only
- make screenshots-build # Build packages
- make screenshots-regenerate # Update screenshots if needed
- make screenshots-test # Run tests