@h0nio/ui

H0N UI

H0N UI is the Vue 3 component library and design-system foundation built for H0N World. It exists first to give H0N products a consistent visual language, interaction model, and implementation contract. The package is also published for teams that want to use the same components in their own Vue applications.

Documentation · Components · Quick Start · Changelog · npm · GitHub

What is included

• accessible Vue components for forms, navigation, overlays, feedback, data display, content, and layout;
• shared themes, appearance settings, localization, toast services, and public CSS design tokens;
• typed root and selective component imports;
• keyboard interaction, focus management, reduced-motion, RTL, forced-colors, and SSR-aware behavior;
• live documentation with executable examples and machine-readable resources for AI coding agents.

H0Dropdown reveals arbitrary floating content from a consumer-owned trigger:

<H0Dropdown :min-width="220" :max-height="320">
    <H0Button>Actions</H0Button>
    <template #content="{ close }">
        <H0Button @click="close">New file</H0Button>
    </template>
</H0Dropdown>

Use exactly one trigger which forwards attributes and events to its focusable root. Content supports custom markup, forms, or library components. See the Dropdown documentation for state control, sizing and keyboard behavior.

Requirements

• Vue 3.5 or newer;
• a modern browser supported by your Vue application;
• a Vue build tool with ESM and CSS import support, such as Vite.

Installation

Use the package manager already selected by your project:

pnpm add @h0nio/ui

npm install @h0nio/ui

H0N UI installs @h0nio/icons as a runtime dependency for its internal controls, so no second installation is needed to use UI components. Applications that import icon definitions directly should declare @h0nio/icons themselves:

pnpm add @h0nio/icons

<script setup lang="ts">
import searchIcon from '@h0nio/icons/search'
import { H0Icon } from '@h0nio/ui'
</script>

<template>
    <H0Icon :icon="searchIcon" />
</template>

Prefer individual icon subpaths for tree shaking. @h0nio/ui/icons remains available as a compatibility facade for the previous small system set.

Register the plugin

Import the shared stylesheet once and register the plugin on your existing Vue application instance:

import { createApp } from 'vue'
import H0Nui from '@h0nio/ui'
import '@h0nio/ui/style.css'

import App from './App.vue'

createApp(App)
    .use(H0Nui, {
        animation: 'high',
        density: 'default',
        radiusSize: 'lg',
        theme: 'system',
        typographySize: 'md'
    })
    .mount('#app')

Plugin options can configure theme, animation, density, radius, typography, locale, theme persistence, and the global toast service. See Quick Start for the complete contract and defaults.

Use components

Public components and types can be imported from the package root:

<script setup lang="ts">
import { H0Button, H0Card } from '@h0nio/ui'
</script>

<template>
    <H0Card>
        <template #header>Create project</template>
        <template #description>Build with the shared H0N visual language.</template>

        <H0Button tone="primary">Continue</H0Button>
    </H0Card>
</template>

For selective imports, load the component family and either its matching stylesheet or the global stylesheet:

import { H0Button } from '@h0nio/ui/components/Button'
import '@h0nio/ui/components/Button/style.css'

Do not combine multiple copies of global and selective styles. Use @h0nio/ui/style.css once when an application consumes several component families.

Runtime appearance

Choose an accent palette independently of light/dark mode at installation:

app.use(H0Nui, { theme: 'system', accent: 'telegram' })

accent accepts default (existing colors), telegram (blue and cool surfaces), or uber (monochrome). Each preset includes light and dark palettes. The default is default. With storageKey enabled, accent persists under <storageKey>:accent and valid saved appearance takes precedence over configuration. Storage is off by default. The service applies data-h0n-accent alongside data-h0n-theme to its target.

The plugin provides app-scoped runtime services. Appearance can be changed from a Vue setup context:

import { useH0Theme } from '@h0nio/ui'

const appearance = useH0Theme()

appearance.setTheme('dark')
appearance.setAccent('uber')
appearance.setDensity('compact')
appearance.setAnimation('low')

Animation accepts off | low | medium | high | recommended (default low). Recommended combines available resource/graphics hints with a bounded foreground frame sample. The system reduced-motion preference always resolves to Off, even when High was requested. Static loading and control semantics remain available.

import { useH0Animation } from '@h0nio/ui'

const motion = useH0Animation()
motion.setPreference('recommended')
// Read quality.value, recommendedQuality.value, recommendationReason.value,
// isEvaluating.value, enabled.value, reducedMotion.value, continuous.value,
// and rich.value to coordinate application effects with the library.

The recommendation is a conservative heuristic, not a guarantee that browser GPU acceleration is enabled. See Animations for signal limitations, SSR, refresh and lifecycle behavior.

Application CSS can use stable public variables with the --h0n-ui-* prefix. Component-local variables and internal class names are not part of the public styling contract.

UI for AI agents

H0N UI publishes versioned resources that help coding agents install the package, select the correct component, and implement only supported APIs:

• AI installation prompt — copy the complete prompt and give it to an agent with access to your project;
• llms.txt — compact library overview, package boundaries, workflow, and component index;
• component catalog v1 — exact imports, APIs, examples, accessibility guidance, and use/avoid recommendations;
• consumer AGENTS.md — reusable policy template for projects that consume H0N UI;
• UI for Agents documentation — human-readable guidance for using these resources.

For a new integration, start with the installation prompt. For ongoing component work, confirm the installed package version, then use llms.txt, the matching catalog record, component documentation, and the installed TypeScript declarations.

Documentation and support

• Documentation
• All components
• Design principles
• Release notes
• Issue tracker
• Security policy

Contributing

Development is organized as a pnpm workspace containing the publishable library and its documentation application. Before contributing, read the contribution guide, architecture, and release process.

License

MIT. Solar Icons artwork used by internal controls is credited in LICENSE-THIRD-PARTY.