A small design system for every zdanowicz app

Design tokens in the W3C DTCG format, compiled to CSS variables with light and dark themes. Plain-HTML components as z-* classes, an icon sprite, and optional JS for the theme toggle and command palette. Works in React, server-rendered Go or Express, or a static page; no build step for consumers. Self-host z.js and icons.svg; load z.css with its sri.json hash.

Use it

Static / server-rendered: link a pinned version. Copy this exactly: ?v= is the file's content hash (cache bust), integrity its SRI hash.

<link rel="stylesheet" href="https://ui.zdanowicz.dev/v0.2.0/z.css?v=8c44af5d8c"
      integrity="sha384-2JYpBiRi6LaPuAzJCJM39Dk/H3H6X1eRjTsTYAtekjAoUiF10rHMlvwWZ/rJixNS" crossorigin="anonymous">
<script src="/z.js" defer></script>  <!-- self-hosted copy of dist/z.js -->
<svg class="z-icon z-status--progress" aria-hidden="true"><use href="/icons.svg#status-progress"/></svg>

npm projects: a git dependency pinned to a tag, then import the CSS once.

npm i github:zdanowicz-dev/ui#v0.2.0
import "@zdanowicz/ui/z.css";

Serve icons.svg from your own origin (SVG <use> is same-origin). Theme follows the OS; set data-theme="light|dark" on <html> to force one.

Rules

• Use semantic tokens only (--z-color-fg-muted), never raw hex. Raw palette values are not exposed as variables.
• One accent. Status colours mean state, not decoration.
• Body text is 13px; one type scale (11, 12, 13, 15, 20, 22, 32).
• Targets at least 24px (WCAG 2.2 2.5.8); controls are 32px by default.
• Every interactive element is a real button, a, or form control; focus is always visible.
• Contrast is checked at build time (WCAG 2.2 AA) in both themes: see Tokens.