Getting started

The shortest useful page on this site. No options, no caveats, no “but what if you are on Nuxt” — one path that gets you to a working component. The branches start on installation and in configuration.

What you need

Install

And the part that only runs at build time and never reaches the bundle:

Configuration

The design system’s CSS is not imported as files — granum assembles it. It reads the package’s contents from the manifest the package declares as an export and never walks node_modules: it opens the package’s files only when the manifest cannot be trusted, and only the files the manifest lists. There is exactly one source of truth:

import { windEngine } from '@feugene/granum-engine-wind'
import { defineGranumConfig } from '@feugene/granum/vite'

export default defineGranumConfig({
  engine: windEngine(),
  providers: ['@feugene/granularity'],
  components: [{ provider: '@feugene/granularity', names: ['GrButton'] }],
  themes: { names: ['light', 'dark'] },
  appSources: { dirs: ['src'] },
})

components can be left out entirely — then every component of the provider lands in the CSS. Listing them narrows the sheet down to the set you need, and this is the one place where you pay for granularity with attention.

import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import { granum } from '@feugene/granum/vite'
import granumConfig from './granum.config.mjs'

export default defineConfig({ plugins: [Vue(), granum(granumConfig)] })

The config is read in one place, not two. The v1 preset had to be handed the same object both in content and in presets: let them drift apart and components arrived unstyled, with the build saying nothing. That fork is gone.

Two imports, and the order between them is load-bearing

import './reset.css'
import 'virtual:granum.css'

import { createApp } from 'vue'
import App from './App.vue'

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

@import '@unocss/reset/tailwind-compat.css' layer(reset);

There is one virtual CSS module now — virtual:granum.css. The tokens, the base layer, the themes, the component styles and the utilities their templates are drawn with all arrive in a single sheet: forgetting half the foundation and getting colours without geometry is no longer possible.

The first component

<script setup lang="ts">
import { GrButton } from '@feugene/granularity/components/GrButton'
</script>

<template>
  <GrButton tone="primary">Save</GrButton>
</template>

Importing from a subpath rather than from the package root is granularity itself. It pulls one component and its graph, not a barrel. granum rejects a component from the root as a build error, ComponentRootImportError.

Run vite. The button should be coloured, with rounded corners and a focus ring on Tab. If it is grey and bare, the sheet is not imported at all. If the background is there but the text is in the page’s colour and the padding is gone, the reset is imported after the sheet. Both cases are worked through on the troubleshooting page.

Next

• Installation — why the dependency list looks like this, icons, optional integrations.
• Configuration — defaults, locale, overrides at the application level.
• Theming — rebranding without touching components.
• Component catalogue — what there is at all.