Web component system for hijinx.world
README.md

Hijinx World UI #

Design system for Hijinx World!

Install #

pnpm add @hijinx-world/ui

Load the styles once, then the components. Importing everything:

import "@hijinx-world/ui/styles/tokens.css";
import "@hijinx-world/ui/styles/fonts.css";
import "@hijinx-world/ui/styles/theme.css";
import "@hijinx-world/ui/styles/components.css";
import "@hijinx-world/ui";

Or only the ones a page uses: import "@hijinx-world/ui/components/button";.

Load the styles in the <head>, not from a script that runs late. components.css styles the components before their scripts run, so links and badges work without JavaScript, and controls keep their size while they load.

The component scripts use browser APIs. On a site that renders on the server (Astro, Next), import them in client code only, for example an Astro <script>.

The package does not ship icons. Put an inline <svg> with currentColor in a slot or in the <a>. It shows without JavaScript and loads no file. In Astro, astro-icon makes one at build time:

<hx-button><Icon name="pixelarticons:download" slot="start" aria-hidden="true" />download</hx-button>
<hx-button arrow="next"><Icon name="pixelarticons:arrow-right" aria-hidden="true" /></hx-button>

arrow makes a square button for one icon. A <wa-icon> from your own icon library also works. If the site imports Web Awesome itself, use a version that @hijinx-world/ui accepts, so the site has one copy.

Write the native element inside, so it is in the HTML:

<hx-button><a href="/feed" aria-current="page">feed</a></hx-button>
<hx-badge>latest</hx-badge>
<hx-home-icon><a href="/">Home</a></hx-home-icon>

Put target, rel, download, aria-current and aria-label on the <a>. To disable a link, remove its href.

A card uses the slot names of wa-card. The element without a slot is the body. Its first child is the title, and an <hr> is the squiggle. A link in the title makes the whole card a link:

<hx-card orientation="horizontal" squiggle="hover" shadow>
  <img slot="media" src="/hero.avif" alt="" />
  <div>
    <h2><a href="/articles/x">Title</a></h2>
    <hr />
    <p>Description</p>
  </div>
  <p slot="footer">
    <span>By <strong>Liza Desya</strong></span
    ><time datetime="2026-10-01">Oct 1, 2026</time>
  </p>
</hx-card>

<hx-card appearance="accent" orientation="horizontal">
  <div>
    <h1>About</h1>
    <hr />
    <p>Text</p>
  </div>
  <dl slot="aside">
    <div>
      <dt>Editor</dt>
      <dd>Liza Desya</dd>
    </div>
  </dl>
</hx-card>

For controls or prose, use panel. It styles only the header bar:

<hx-card panel shadow role="region" aria-label="Filters">
  <div slot="header">filters</div>
  <form>…</form>
</hx-card>

Overriding styles #

components.css puts the component styles in the hx cascade layer, so any unlayered site rule beats them. With Tailwind, declare the layer after base, or the preflight reset removes padding and borders. A layer takes its place where it is first named, so declare the whole order once at the top of the site's main stylesheet, Web Awesome's layers first, and import the package styles from that file:

@layer wa-native, wa-base, wa-utilities, wa-color-palette, wa-color-variant, wa-theme, wa-theme-dimension, wa-theme-overrides, theme, base, hx, components, utilities;
@import "tailwindcss";
@import "@hijinx-world/ui/styles/tokens.css";
@import "@hijinx-world/ui/styles/theme.css";
@import "@hijinx-world/ui/styles/components.css";

To use the hijinx colours as Tailwind utilities, point the theme at the --hx- tokens with @theme inline. The utilities then read the token directly, so overriding a token on part of the page reaches them:

@theme inline {
  --color-brand: var(--hx-color-brand);
}

Rules for an element inside a component (hx-button > a) are not in a layer, so a site's global a:hover does not change a link button. To restyle one, use the same selector.

Development #

Written in TypeScript. Needs Node 22.18 or later, which runs the .ts scripts directly, and pnpm.

pnpm install
pnpm dev               # preview page
pnpm build             # package into dist/
pnpm typecheck         # tsc, no output
pnpm lint
pnpm check <name>      # static and browser checks for one component, e.g. pnpm check toggle

New components follow .claude/skills/create-component/SKILL.md.

Work on a site at the same time #

To make a site use this repository instead of the npm release, add a pnpm override to the pnpm-workspace.yaml of the site. Use the path from the site to this repository:

overrides:
  "@hijinx-world/ui": "link:../path/to/hijinx-world-ui"

Then run pnpm install in the site.

  • The site reads dist/. Run pnpm build here after each change.
  • If the site shows "already defined" for a wa- element, it has two copies of Web Awesome. Add resolve: { dedupe: ["@awesome.me/webawesome"] } to the Vite config of the site.
  • Do not commit the override or the lockfile of the site. To go back to the npm release, remove the override and run pnpm install.

License #

Code is MIT. Fonts are under the SIL Open Font License 1.1; the license texts are in fonts/licenses/ (src/ in the repository, dist/ in the package). Bundled icons and other third-party material are listed in THIRD_PARTY_NOTICES.md. The "Hijinx World" name and logo are not covered by the MIT license.