paleui

v0.1.0

Published

13 days ago

Pale UI

0High
0Medium
0Low

ahme-dev

paleui css ui front-end theme component library css library

PaleUI

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.

Features

CSS-only: No runtime JavaScript.
Semantic HTML first: Built around native elements, roles, and ARIA.
Theme-compatible: Uses shadcn/ui CSS variables.
Scoped and modular: Import everything or only the files you need.
Visually tested: Components are covered by Playwright snapshots where practical.

Usage

PaleUI can be installed via a package manager, or included directly in your HTML.

Basic usage

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.

Install via npm

npm install paleui

Then import the styles you need. You can import everything at once or only specific components:

@import "paleui/lib/all.css";       /* Base styles + every component */

/* Modular imports */
@import "paleui/lib/main.css";      /* Tokens, dark mode, shared animations */
@import "paleui/lib/accordion.css"; /* Accordions */
@import "paleui/lib/alert.css";     /* Alerts */
@import "paleui/lib/badge.css";     /* Badges */
@import "paleui/lib/button.css";    /* Buttons */
@import "paleui/lib/card.css";      /* Cards */
@import "paleui/lib/typography.css";/* Typography defaults */

The published package ships generated CSS in lib/. In this repository, packages/paleui/lib/ is generated by pnpm run --filter paleui build and is not committed.

Include via CDN

For quick prototyping or static sites, include PaleUI directly from a CDN:

<link rel="stylesheet" href="https://unpkg.com/paleui/lib/all.css">

<link rel="stylesheet" href="https://unpkg.com/paleui/lib/main.css">
<link rel="stylesheet" href="https://unpkg.com/paleui/lib/accordion.css">
<link rel="stylesheet" href="https://unpkg.com/paleui/lib/alert.css">
<link rel="stylesheet" href="https://unpkg.com/paleui/lib/badge.css">
<link rel="stylesheet" href="https://unpkg.com/paleui/lib/button.css">
<link rel="stylesheet" href="https://unpkg.com/paleui/lib/card.css">
<link rel="stylesheet" href="https://unpkg.com/paleui/lib/typography.css">

Theming

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 "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 */
}

Goals

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.

Contributing

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-env and Autoprefixer - Compiles generated CSS to lib/
Biome - Linter and formatter
Prettier with prettier-plugin-astro - Formats .astro files
Playwright - End-to-end testing

Generation

Both the library CSS and the documentation site are generated from the same TypeScript schema files:

Component schemas in packages/paleui/src/ui/*.ts define anatomy, styles, dimensions, states, and examples.
CSS: src/generate-css.ts renders each schema to a CSS file, which PostCSS compiles to lib/*.css.
Docs: scripts/generate-docs.ts renders each schema to an Astro page in packages/site/src/pages/components/ (gitignored, generated before each build).

Structure

packages/paleui - Core CSS library (TypeScript schemas in src/ui/, compiled by PostCSS to lib/)
packages/site - Documentation site (Astro, pages generated from core schemas)

Setup

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.

Tasks

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 Docker
pnpm run test:run:docker-down - Stop the Docker test container
pnpm run test:run:ui - Run Playwright tests with UI (local)
pnpm run test:update - Update Playwright snapshots
pnpm run check - Run Biome checks without fixing
pnpm run fix - Run Biome and Prettier to lint and format code

Committing

The project follows conventional commit conventions:

feat - New feature or enhancement for the lib
fix - Bug fix for the lib
docs - Changes to the site or other forms of documentation
test - Test modifications
chore - Maintenance tasks, configuration, or tooling changes