@pxlkit/ui-kit-core

@pxlkit/ui-kit-core

The framework-neutral core of the Pxlkit retro UI kit — new in Pxlkit 2.2.0.
Design tokens, the Tailwind CSS theme, class recipes, pixel glyphs, locale data and DOM behaviour — shared by the React kit and its Vue and Angular editions, so all three render the same markup and behave the same way.

Do I need to install this?

Usually not directly — it comes with your framework's kit:

Each kit's stylesheet imports Tailwind CSS v4 and this package's theme, and points Tailwind at the class names both packages use, so one @import of it — in place of @import "tailwindcss"; — is all the CSS setup there is, once Tailwind CSS v4 runs in your build (its Vite or PostCSS plugin — your kit's README has the step). Without Tailwind in the build, the components render unstyled.

Install it yourself when you build your own components on the same design system, in any framework or none:

npm install @pxlkit/ui-kit-core

What's inside

Everything is plain TypeScript, safe to import on the server: DOM helpers check for window / document and degrade to no-ops. The one runtime dependency is @floating-ui/dom, which positions floating content.

Examples

Compose the kit's classes in your own markup:

import { cn, focusRing, sizeClass, surfaceClasses, toneMap } from '@pxlkit/ui-kit-core';

const s = surfaceClasses('pixel');
const t = toneMap.cyan;
const className = cn('inline-flex items-center', s.border, s.radius, s.font, sizeClass.md, t.border, t.text, focusRing);

Trap focus and lock scrolling while a dialog of your own is open:

import { lockScroll, trapFocus } from '@pxlkit/ui-kit-core';

const releaseFocus = trapFocus(() => dialogElement);
const releaseScroll = lockScroll();
// …on close:
releaseFocus(); // focus returns to the element that opened the dialog
releaseScroll(); // scroll locks stack across every kit on the page

Theming

The stylesheet defines the --retro-* palette for the light theme (:root) and the dark theme (.dark on <html> or any ancestor), maps it onto Tailwind utilities (bg-retro-bg, text-retro-cyan, …) and adds the pixel utilities (pxl-corner-*, pxl-shadow*, pxl-nudge-*). Override any variable after importing your kit's stylesheet:

@import "@pxlkit/ui-kit/styles.css";

:root { --retro-green: #22c55e; }
.dark { --retro-green: #4ade80; }

Using the theme in your own styles

• Styles Tailwind compiles separately (a Vue <style> block, Angular component styles, CSS modules) must reference the theme before @apply can use it — otherwise the build stops with Cannot apply unknown utility class 'bg-retro-…':

  @reference "@pxlkit/ui-kit-vue/styles.css"; /* or @pxlkit/ui-kit/styles.css, @pxlkit/ui-kit-angular/styles.css */
  
  .panel { @apply bg-retro-surface text-retro-text font-pixel; }
  

• pxl-corner-*, pxl-shadow* and pxl-nudge-* are plain classes: use them in markup; they take no variants and @apply rejects them.
• A cut corner (pxl-corner-*) is a clip-path, which also clips a drop shadow on the same element: put pxl-shadow on an element whose corners are whole, or on a wrapper. pxl-nudge-hover and pxl-nudge-active give the pixel press feel without the shadow — 1px on hover, 2px while pressed — as the kits' pixel buttons do.
• On the pixel surface a cut corner clips a focus ring drawn outside the element, so keyboard focus lights the 2px edge inside: automatically on a pxl-corner-* element that takes focus; elsewhere add pxl-focus-inset with a variant (focus-visible:pxl-focus-inset, group-focus-visible:pxl-focus-inset, has-[input:focus-visible]:pxl-focus-inset). --pxl-focus-color sets its colour (currentColor; Highlight in forced-colors mode).

Related Packages

Documentation

Browse every component at pxlkit.xyz/ui-kit and the setup guide at pxlkit.xyz/docs.

License

MIT License — code package. See the repo licensing overview for split-license scope details.

Created by Joangel De La Rosa