Pebble UX

A modern, accessible web component library built with TypeScript, Vite, and uhtml.

Features

• Custom Elements: Built-in elements where possible, extending native HTML elements
• Accessibility First: Full ARIA support and keyboard navigation
• Design System: Integrated design tokens with light/dark theme support
• Responsive: Mobile-first responsive design
• TypeScript: Full type safety and excellent developer experience
• Well Tested: Comprehensive test suite with browser testing

Components

• Form Controls: Button, Input, Textarea, Checkbox, Radio, Select
• Layout: Accordion, Tabs, Dialog, Drawer
• Feedback: Tooltip, Validation Message
• Media: Icon

Quick Start

npm install @pebble-ux/web-components

import "@pebble-ux/web-components";

// Use components in your HTML
<pbl-button>Click me</pbl-button>
<pbl-input placeholder="Enter text"></pbl-input>

Design tokens

Components take their colors, spacing, typography and radii from a generated design-token stylesheet. The component CSS references those variables with no inline fallbacks, so the file must be loaded — without it the components render unstyled. It is published as dist/tokens.css and exposed as the ./tokens.css export (./style.css is kept as an alias):

import "@pebble-ux/web-components";
import "@pebble-ux/web-components/tokens.css";

Use the exported subpath (tokens.css, or the style.css alias): the package exports map does not expose the deep dist/tokens.css path to bundlers.

Themes

light is applied on :root and dark is applied when data-theme="dark" is set on the root element:

<html data-theme="dark">

document.documentElement.setAttribute("data-theme", isDark ? "dark" : "light");

Overriding tokens

The file holds two layers: semantic tokens (--semantic-*) and per-component tokens (--button-*, --input-*, …) that reference them. Override the semantic layer to restyle everything at once, or a component token to restyle a single component:

:root {
  --semantic-color-brand-primary: oklch(0.545 0.215 262.741);
  --button-border-radius: 999px;
}

Regenerating

Tokens are generated from the DTCG JSON sources in tokens/. The output directory is required, otherwise the build exits with an error:

npm run tokens:build dist

Primitive tokens are resolved into the semantic and component layers at build time and are never emitted as custom properties.

Comming soon: theme builder app

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

PolyForm Noncommercial License 1.0.0