PaleUI is a user interface library designed to provide a clean and modern look for web applications. Inspired by shadcn/ui, PicoCSS, and DaisyUI, it aims to deliver the best of all three worlds: a modern, minimalist design aesthetic, semantic HTML elements, and accessibility features, all without relying on JavaScript.
- CSS-only: No runtime JavaScript.
- Semantic HTML first: Built around native elements, roles, and ARIA.
- Theme-compatible: Uses
shadcn/uiCSS variables. - Scoped and modular: Import everything or only the files you need.
- Visually tested: Components are covered by Playwright snapshots where practical.
PaleUI is published on JSR and can be installed with a package manager.
Import all.css for the complete library, or import main.css plus the component files you need. main.css contains the design tokens, dark mode variables, and shared animations, and should be loaded before modular component styles.
Generated component styles are scoped to [data-paleui] by default. Put data-paleui on the element that should contain PaleUI components:
<main data-paleui>
<button>Button</button>
</main>PaleUI styles semantic HTML, roles, and data attributes directly. Current component markup, variants, states, and examples are documented on the generated documentation site from the same schema files that build the CSS.
pnpm add jsr:@ahme-dev/paleuiFor package managers without native JSR support, use the JSR CLI:
npx jsr add @ahme-dev/paleuiThe package includes generated CSS files in lib/. Depending on your build tool, import everything at once or only the files you need:
@import "@ahme-dev/paleui/lib/all.css"; /* Base styles + every component */
/* Modular imports */
@import "@ahme-dev/paleui/lib/main.css"; /* Tokens, dark mode, shared animations */
@import "@ahme-dev/paleui/lib/accordion.css"; /* Accordions */
@import "@ahme-dev/paleui/lib/alert.css"; /* Alerts */
@import "@ahme-dev/paleui/lib/badge.css"; /* Badges */
@import "@ahme-dev/paleui/lib/button.css"; /* Buttons */
@import "@ahme-dev/paleui/lib/card.css"; /* Cards */
@import "@ahme-dev/paleui/lib/typography.css";/* Typography defaults */JSR only exports JavaScript and TypeScript module entrypoints, so PaleUI's CSS files are included package files rather than JSR module exports. In this repository, packages/paleui/lib/ is generated by pnpm run --filter paleui build and is not committed.
For static sites, copy the CSS files from the installed package and include them directly:
<link rel="stylesheet" href="/paleui/all.css">PaleUI uses the same CSS variables as shadcn/ui, so any shadcn theme works out of the box. To use a custom theme, override the CSS variables in your stylesheet after importing PaleUI:
@import "@ahme-dev/paleui/lib/all.css";
:root {
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
--primary: oklch(0.205 0 0);
--input: oklch(0.922 0 0);
--ring: oklch(0.808 0 0);
--radius: 0.625rem;
/* ... other variables */
}For dark mode, add the dark class to any parent element (typically <html> or <body>) and define dark variants:
.dark {
--background: oklch(0.115 0 0);
--foreground: oklch(0.985 0 0);
/* ... other dark mode variables */
}Note: this is an early draft, and will likely be updated somewhat until a stable release is made.
PaleUI has several aims, in order of priority — a lower aim is ignored if it conflicts with a higher one:
1. Use CSS only. A modern, semantic, accessible UI foundation doesn't need JavaScript. PaleUI ships no JS and minimizes how much the user has to write when it's unavoidable.
2. Enforce semantic HTML and accessibility. Semantic elements, role attributes, and ARIA attributes are required — not optional. Examples include them too, to encourage proper practices.
3. Support older browsers. PaleUI targets at minimum the "widely available" Baseline (all major browsers for 30+ months), with polyfills and alternative builds where possible.
4. Stay compatible with shadcn/ui themes and components. PaleUI uses the same CSS variables and covers the same component set.
5. Be visually tested. Component output should be covered by visual regression tests as much as practical, including variants, states, themes, and browser differences.
6. Work in modern JS frameworks. PaleUI targets React, Vue, Svelte, and similar, not just plain HTML.
7. Stay small and modular. Distributed as both a single file and individual component files — use only what you need.
Contributions to PaleUI are welcome. The project uses a monorepo structure and is built with the following:
- pnpm - Package manager
- Node.js with tsx - For running TypeScript scripts
- TypeScript - Component schemas in
src/ui/define styles, variants, and examples - PostCSS with
postcss-preset-envand Autoprefixer - Compiles generated CSS tolib/ - Biome - Linter and formatter
- Prettier with
prettier-plugin-astro- Formats.astrofiles - Playwright - End-to-end testing
Both the library CSS and the documentation site are generated from the same TypeScript schema files:
- Component schemas in
packages/paleui/src/ui/*.tsdefine anatomy, styles, dimensions, states, and examples. - CSS:
src/generate-css.tsrenders each schema to a CSS file, which PostCSS compiles tolib/*.css. - Docs:
scripts/generate-docs.tsrenders each schema to an Astro page inpackages/site/src/pages/components/(gitignored, generated before each build).
packages/paleui- Core CSS library (TypeScript schemas insrc/ui/, compiled by PostCSS tolib/)packages/site- Documentation site (Astro, pages generated from core schemas)
1. Dev Container: Open in VS Code and use "Dev Containers: Reopen in Dev Container". Includes pnpm, Biome, and Playwright pre-configured.
2. Local: Install Node.js and pnpm, clone the repo, and run pnpm install. Playwright must also be configured with required browsers, unless Docker is available for the preconfigured test image.
Development:
pnpm run dev- Start development mode (library + site + doc generation watching for changes)pnpm run build- Build for production (generates docs, builds library, then site)
Testing and Formatting:
pnpm run test:run- Run Playwright tests (local + devcontainer)pnpm run test:run:docker-up- Run Playwright tests using Dockerpnpm run test:run:docker-down- Stop the Docker test containerpnpm run test:run:ui- Run Playwright tests with UI (local)pnpm run test:update- Update Playwright snapshotspnpm run check- Run Biome checks without fixingpnpm run fix- Run Biome and Prettier to lint and format code
The project follows conventional commit conventions:
feat- New feature or enhancement for the libfix- Bug fix for the libdocs- Changes to the site or other forms of documentationtest- Test modificationschore- Maintenance tasks, configuration, or tooling changes