Skip to main content

Installation

Getting the HTML / CSS library into a project. It lives in lib/html, and one command copies it into yours — there is no package to install and nothing to build.

Requirements​

DependenciesNone
Build stepNone
BrowsersAny with CSS custom properties

Steps​

HTML / CSS

Fetch the library

One command. degit copies the folder out of the repo without its git history — no clone, no submodule, and nothing added to your dependencies.

npx degit chronsyn/ui/lib/html public/hourglass
# or, if you prefer unjs: npx giget gh:chronsyn/ui/lib/html public/hourglass

# public/hourglass/
#   hourglass-tokens.css   colour, type, space, radius, motion (light + dark)
#   hourglass.css          every component, as hg-* classes
#   hourglass.js           the four behaviours markup cannot do alone
#   index.html             a reference page — delete it if you like

Link the two stylesheets

Order matters: the tokens define the custom properties the components read. Dark mode follows the OS from this point on, with no JavaScript at all.

<link rel="stylesheet" href="/hourglass/hourglass-tokens.css" />
<link rel="stylesheet" href="/hourglass/hourglass.css" />

Add the script, and enhance

Only four things need JavaScript: building a reel's digit strips, moving the segmented thumb, trapping focus in a sheet, and queuing toasts. Everything else is CSS.

<script src="/hourglass/hourglass.js"></script>
<script>
  Hourglass.enhance(); // wires anything already in the page
</script>

Load the fonts

Optional. The system asks for Inter and JetBrains Mono and falls back to the platform's own faces — the scale works either way, but the mono is where most of the brand lives.

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link
  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap"
  rel="stylesheet"
/>

Render something

Every component is a class name. Nothing is registered, and nothing has to be initialised first.

<body class="hg-root">
  <div class="hg-stat">
    <span class="hg-stat__label">Tracked</span>
    <span class="hg-stat__value" data-hg-reel="4:40" aria-label="4 hours 40 minutes"></span>
    <span class="hg-stat__aside">Today</span>
  </div>

  <button class="hg-btn hg-btn--primary">Start a task</button>
</body>

Worth knowing​

Interaction is controlled by default: clicking a toggle fires hg:change and changes nothing until you set the state back. Add data-hg-auto to let a control flip itself — fine for a prototype, wrong for an application.

Hourglass.setTheme("dark" | "light" | null) forces a mode or hands control back to the OS.

Why a copy rather than a dependency​

There is no registry and no package. The command in step 1 copies the source into your repository, and from that moment the files are yours — read in review, edited when you need to, and compiled by your own pipeline like anything else you wrote.

That is deliberate, and it is the same trade shadcn/ui made. What you gain: no dependency to audit or wait on, no build output to trust, and nothing to configure — none of these guides has a step about transpiling a package, excluding it from pre-bundling, or compiling it for Angular, because vendored source has none of those problems.

What you give up is npm update. Taking a newer version means running the same command again and reading the diff. If you have edited the files, that diff is the conversation — which is also a good argument for keeping your changes in a wrapper of your own rather than in these files.

Taking an update​

Re-run the command from step 1. degit overwrites what is there, so commit first and let your diff show you what changed.

If you would rather review before overwriting, fetch into a scratch folder and diff the two:

npx degit chronsyn/ui/lib/html /tmp/hourglass-next
diff -ru src/hourglass /tmp/hourglass-next

Next​

Components — all 23, with props, types and code samples for your framework.