hackbuild-ui

The hack.build design system and Vue component library. Warm paper, black ink, one hot pink, typewriter type, hard shadows that look slightly off-register like a bad photocopy.

Three layers, each usable without the ones above it:

1. tokens.css. Every color, face, shadow, spacing step, and z index as CSS custom properties.
2. hackbuild.css. The class layer: every component as plain CSS, framework free. This is what the static style guide and acceptance test pages run on.
3. @hackbuild/ui. Vue 3 components that bind behavior to those classes. They ship no styles of their own, so the CSS stays the single source of truth.

A Tailwind v4 bridge (theme.css) maps the tokens into Tailwind theme variables for app code. Tailwind is optional and never required by the library itself.

Install

npm install @hackbuild/ui

Vue 3.4 or newer is a peer dependency.

Quick start

// main.ts
import { createApp } from 'vue'
import '@hackbuild/ui/fonts.css'    // or self-host the five faces
import '@hackbuild/ui/styles.css'
import App from './App.vue'

createApp(App).mount('#app')

<script setup lang="ts">
import { HbButton, HbPanel, HbKv } from '@hackbuild/ui'
</script>

<template>
  <HbPanel heading="Tuning">
    <HbKv label="center" value="433.920" />
    <HbButton>connect</HbButton>
  </HbPanel>
</template>

Put class="hb" on the body (or a root wrapper) to get the paper page surface, prose defaults, and the grain overlay. Add hb-halftone for the dot field used by tool UIs.

With Tailwind v4

/* app.css */
@import "tailwindcss";
@import "@hackbuild/ui/styles.css";
@import "@hackbuild/ui/theme.css";

Then bg-paper, text-ink, font-display, shadow-hard and friends work in your own markup. See docs/tailwind.md.

Package map

Path	What it is
src/styles/tokens.css	Design tokens. The source of truth.
src/styles/hackbuild.css	The class layer. Every component as CSS.
src/styles/tailwind.css	Tailwind v4 theme bridge.
src/styles/fonts.css	Google Fonts convenience import.
src/components/	Vue components, Hb prefix, no style blocks.
src/composables/	useToast.
assets/brand/	The mark, lockups, wordmark, favicon. Outlined paths.
docs/	Getting started, tokens, components, Tailwind, brand.
playground/	Vite app exercising every component.
site/	The design system website: component gallery, tokens, brand, full page demos.
hackbuild-design-system.html	The living style guide, self contained.
hackbuild-kerf-replica.html	The acceptance test: KERF rebuilt from system classes.
GUIDELINES.md	The design law. Where files disagree, it wins.

Exports

Specifier	Contents
@hackbuild/ui	Components, composables, cx, types.
@hackbuild/ui/styles.css	Tokens plus the full class layer.
@hackbuild/ui/tokens.css	Tokens alone.
@hackbuild/ui/theme.css	Tailwind v4 bridge.
@hackbuild/ui/fonts.css	Font import.
@hackbuild/ui/brand/*	Brand SVGs, for example @hackbuild/ui/brand/hackbuild-mark.svg.

Development

npm install
npm run dev        # playground at the printed port
npm run dev:site   # the design system website
npm run typecheck  # vue-tsc over library, playground and site
npm run build      # dist: ES modules, d.ts, styles
npm run build:site # static site into site/dist

Before shipping anything, run the checklist at the end of GUIDELINES.md, and look at the playground in a real browser at desktop width and 390 px.

Documentation

• docs/getting-started.md
• docs/tokens.md
• docs/components.md
• docs/icons.md
• docs/tailwind.md
• docs/brand.md