Getting started

Install

Habitus is published to the internal Gitea registry, so the @livereader scope needs pointing at it. Add to your project's .npmrc:

@livereader:registry=https://git.livereader.com/api/packages/livereader/npm/

Reads are anonymous — no token needed to install.

npm install @livereader/habitus-vue

Set up

// main.ts
import { createApp } from "vue";
import { createHabitus } from "@livereader/habitus-vue";
import "@livereader/habitus-vue/styles";
import App from "./App.vue";

createApp(App).use(createHabitus()).mount("#app");

Then mark your root element so Habitus base styles apply:

<div
	id="app"
	data-habitus
></div>

Habitus scopes its base styles to [data-habitus] rather than applying them to html/body. A library should not restyle a host document that did not ask for it, and during a migration you will want parts of an app opted out.

Import order matters

WARNING

Import @livereader/habitus-vue/styles before your application CSS.

If your app also runs Tailwind, both stylesheets emit the same utility classes. The declarations are identical, so the duplication is harmless — but when you deliberately override a Habitus utility, the stylesheet that comes later wins. Import Habitus first and your overrides behave as expected.

Using components

createHabitus() registers every component globally, so templates can use them directly:

<template>
	<HabButton variant="primary">Save</HabButton>
</template>

In an app that only uses a handful, prefer explicit imports — they let your bundler drop the rest:

import { HabButton } from "@livereader/habitus-vue";
// or, narrowest:
import { HabButton } from "@livereader/habitus-vue/components/Button";

createApp(App)
	.use(createHabitus({ registerComponents: false }))
	.mount("#app");

If your app uses Tailwind

Import the token layer into your own CSS entry so your utilities and Habitus components draw on the same scale:

@import "tailwindcss";
@import "@livereader/habitus-vue/theme";

You still import @livereader/habitus-vue/styles for the component styles themselves. See Theming for what the tokens are and how to override them.

Dark mode

Habitus keys dark mode off a dark class, not prefers-color-scheme, so apps can offer an explicit toggle:

document.documentElement.classList.toggle("dark", isDark);