# mirk A form-focused HTML/CSS UI kit. Seventeen form components plus a content tier (note, hint, list, badge, table, page scaffold) as **semantic BEM classes** in one hand-written CSS file, plus one tiny delegated script. No build step, no React, no web components, Tailwind optional. Published as `mirk-interface` on npm. Every component is built on native HTML elements with a pixel-bevel look set in Departure Mono. State lives where the platform already keeps it: in native attributes, in CSS state selectors, and in real DOM nodes. That means a component's visible state round-trips through `outerHTML`, so a saved-and-reopened file renders correctly before any script runs. mirk targets malleable HTML (Hyperclay), but nothing in it is Hyperclay-specific: it is plain CSS and one small delegated runtime that work on any page. ## Live showcase Open `index.html` from the [GitHub repo](https://github.com/panphora/mirk-interface) in any browser or static server. The showcase IS the documentation: every component, every variant, with the exact markup you copy. ## Quick start Two ways to load mirk. The drop-in path is primary and needs no build and no Tailwind. The Tailwind path is optional, for when you want utilities to override mirk classes. ### Primary: drop-in, zero install, no Tailwind Add these two tags once, then paste any component snippet where you need it. ```html ``` `mirk.css` ships the font, the 28 theme tokens, and all fifteen components, and it renders fully on its own. This is the path for a single-file HTML artifact, a Hyperclay app, a Rails view, a static page, anywhere you just want components without a toolchain. Those URLs are served straight from npm by jsDelivr, no setup. The `@2` pin tracks the latest 2.x release, so you get patches and minor updates but never a breaking major. Pin exactly with `mirk-interface@2.0.0` to freeze a version, or drop the pin (`.../npm/mirk-interface/mirk.css`) to ride the newest major. The same files are on unpkg too: `https://unpkg.com/mirk-interface@2/mirk.css`. The font loads automatically, `mirk.css` references it by a relative path that resolves to `https://cdn.jsdelivr.net/npm/mirk-interface@2/fonts/...` on the CDN. ### Boot a full page `mirk.css` also ships a one-class page scaffold. Put `mirk-page` on `` and you get a centered reading column with mirk typography: headings sized for the pixel face (Departure Mono has one weight, so hierarchy comes from size), underlined links, bordered inline `code`, a recessed `
`, a hairline `
`, and flow spacing between blocks. Save this as an `.html` file and open it — that is the whole setup:

```html





my mirk page




  
getting started

  
A mirk page

  
Plain HTML plus mirk classes. Paste any component below.


  




```

A fuller template ships as [`starter.html`](starter.html) in the repo. Every scaffold rule rides `:where()` (zero specificity), so any utility class or plain rule of your own overrides it. See [Page scaffold](#page-scaffold) for the details.

### Optional: Tailwind, to override mirk with utilities

Import Tailwind first, then mirk.

```css
@import "tailwindcss";
@import "mirk-interface/mirk.css";
```

Now `class="mirk-input mirk-input--large w-full font-sans"` works: utilities win over the component layer because mirk lives in `@layer components`, with zero `!important`. Use this path when you already build with Tailwind and want to tweak mirk components with utility classes. Tailwind is never required.

## How it works

Two architectural hinges hold the kit together.

### 1. mirk lives in `@layer components`

Tailwind v4 emits `@layer theme, base, components, utilities`, so utilities always win over the component layer. To make mirk self-sufficient even without Tailwind, `mirk.css` declares its own `@layer base, components;` up front. That gives it a defined cascade order on a bare page, and still slots into Tailwind's order when Tailwind is present. The result: you can override any mirk class with a utility, no specificity hacks, no `!important`, whether or not Tailwind is on the page.

### 2. `outerHTML` round-trips the visible state

mirk is designed for malleable HTML (Hyperclay), where the page can save its own `outerHTML` back to a file and reopen it later. So mirk keeps state where serialization can capture it, in three buckets:

- **Native elements hold their own state.** A checkbox's `checked`, an input's `value`, a select's `selected` option all live in the DOM and persist in markup.
- **CSS-only state needs no JS.** Visuals derive from `:checked`, `:focus-visible`, `:has()`, and friends, so nothing has to be re-applied on load.
- **JS-built state lives in the DOM.** Tag chips are real elements with hidden inputs, the slider's fill reads an inline `--mirk-value` on the wrapper. Both serialize.

A saved-and-reopened file is therefore correct before any script runs. mirk.js only animates live interaction, it never bootstraps state.

## Theming

mirk follows the visitor's OS theme by default and lets you force a mode per subtree.

- **OS default:** colors use `light-dark()`, so the kit matches the visitor's system light/dark preference with no configuration.
- **Force a mode globally:** put `class="dark"` or `class="light"` (or `data-theme="dark"` / `data-theme="light"`) on a wrapper near the root.
- **Force a mode per subtree:** the same classes/attributes on any wrapper force that mode for just that subtree, so you can pin a panel to dark while the rest of the page follows the OS.
- **Tokens:** 28 namespaced `--mirk-*` custom properties drive every color, bevel edge, and focus ring. Override them on a wrapper to retheme, rather than editing component classes. The namespace means mirk never collides with a host page's own custom properties.
- **Default palette — Pixel Quiet:** with no theme attribute, `:root` paints **Pixel Quiet**, a calm, soft-bevel palette (warm cream / deep navy) with warmer ink and a terracotta destructive. It follows the OS light/dark like any mirk page.
- **Built-in secondary — Full Volume:** the original louder, higher-contrast pixel-bevel palette ships as an opt-in variant, `data-theme="full-volume"`. It follows the OS like the default and composes with the `.dark` / `.light` aliases, so `data-theme="full-volume" class="dark"` is Full Volume forced dark. Add your own brand theme the same way, an explicit `[data-theme="..."]` block of token overrides.

```html


  





  


```

## Components

In order: button, text input, textarea, number, dropdown, checkbox, radio, toggle, slider, date, file picker, image input, tags, sortable, chip, field, progress — plus invalid states on every constrainable control. Then the content tier — the pieces around a form that make a whole page: note, hint, list, badge, table, page scaffold. Everything from field onward is pure CSS (none of it needs mirk.js).

A note on conventions used below:

- **Sizes:** `--small` / `--large` are mutually exclusive modifiers, medium is the base with no size class.
- **Shapes:** `--round` (a gradient pill frame) or `--rounded` (rounded corners) where supported, rect is the base with no shape class.
- **Needs mirk.js:** only the components that say so. The rest are pure CSS over native elements.

---

### Button

A pixel-bevel push button rendered from a native `
```

```html


```

```html


```

```html


```

```html


```

```html


```

```html


```

**Class API:** block `mirk-button` / part `__label` / modifiers `--small`, `--large`, `--round`, `--quiet`.

The inner `__label` span is mandatory for both shapes: rect uses it to nudge the text on `:active`, and round renders it as the inner pill fill (the `--round` element is just the gradient frame, so without the label there is no visible face). Pair the round modifier with a size modifier, each pairing re-homes padding and radius onto the label. Honors the native `disabled` attribute and shows a focus ring on `:focus-visible`. Theme via the bevel/pill/canvas tokens, do not set a flat `border` or `border-radius` on `.mirk-button` directly or you flatten the bevel.

`--quiet` drops the bevel for a flatter read: a borderless text button (a transparent border keeps the hit area and baseline aligned with neighbouring bevel buttons) for tertiary actions. It composes with the size modifiers. Note the kit has no flat "solid" fill: a button reads as clickable *because* it is embossed, so the strongest action is a brighter bevel, not a flat block. (The [Chip](#chip)'s action stack follows this: an embossed primary, a bevel secondary, and a `--quiet` dismiss.)

---

### Text input

A single-line text field rendered directly on a bevelled, full-width native ``. Two shapes (rect default, rounded) and three sizes.

```html


```

```html


```

```html


```

```html


```

```html


```

```html


```

```html



```

**Class API:** block `mirk-input` (no parts) / modifiers `--small`, `--large`, `--rounded`.

The class is applied straight to the native ``, so the whole component is one self-contained element and any native attribute works (`type`, `placeholder`, `value`, `name`, `id`, `required`, `disabled`). State round-trips via native attributes (set the `value` attribute to persist a typed value in markup). rect is the base (`border-radius: 0` is baked in), add `--rounded` only for rounded corners. `.mirk-input` is `width: 100%`, so constrain it with a sized or max-width parent. Pair with a `