@rafael_dias/akoma

Akoma

A human design system for Vue 3 — calm, clear, and trustworthy. Natural neutrals, generous space, quiet personality, and hierarchy built through rhythm before borders.

Built with Vue 3 Composition API + TypeScript. Styles use CSS variables (no Tailwind).

Two moods, one family

Both moods share DM Sans, an optional Lora editorial accent, components, spacing, and accessible interaction states. Their palettes, radii, and surface treatment adapt to context. Dark mode works in both via data-theme="dark".

Design guides ship as Markdown in the npm package and in the docs under Guides (/philosophy).

Quick start

npm install
npm run dev

Interactive docs (local): http://localhost:5173

Published docs: https://rafaelgondi.github.io/akoma-vue/

Library usage (after publish)

npm install @rafael_dias/akoma @sysvale/cuida-icons

import { createApp } from 'vue'
import { Akoma, AkButton } from '@rafael_dias/akoma'
import '@rafael_dias/akoma/style.css'

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

Fonts

style.css does not load DM Sans / Lora — a third-party @import inside a published package is render-blocking and can't be self-hosted. Pick one:

// Opt-in Google Fonts CDN
import '@rafael_dias/akoma/fonts.css'

# Or self-host (recommended for production)
npm install @fontsource/dm-sans @fontsource/lora

Or import components à la carte:

<script setup lang="ts">
import { AkButton, AkInput } from '@rafael_dias/akoma'
</script>

Dark mode & mood

document.documentElement.dataset.theme = 'dark'
document.documentElement.dataset.mood = 'site'
document.documentElement.dataset.accent = 'teal' // optional brand color

Accent palettes (v0.8)

Eight named palettes — apps are not locked to purple. Mood controls shape; accent controls brand color. Each palette exposes five chromatic shades: --accent-lighter, --accent-light, --accent, --accent-dark, --accent-darker.

import { accentPaletteIds, applyAccentPalette } from '@rafael_dias/akoma'

applyAccentPalette(document.documentElement, 'teal')

Completion intensity (v0.8.6)

Map a 0–1 rate to the five accent shades for heatmaps and progress fills:

import { completionShade, completionShadeClass } from '@rafael_dias/akoma'

const cls = completionShadeClass(completionShade(0.8)) // ak-completion-shade--dark

Theme helper (v0.8.7)

import { useAkomaTheme } from '@rafael_dias/akoma'

const { mode, setMode, toggleMode } = useAkomaTheme({
  mood: 'app',
  accent: 'evergreen',
  storageKey: 'my-app-theme',
})

theme-color meta syncs from --bg automatically.

App shell (v0.8.8)

<div class="ak-app-root">
  <main class="ak-app-main">
    <div class="ak-app-scroll">…</div>
  </main>
</div>

Components (v0.8)

Scripts

Design guides (Markdown)

Guides live in content/ and ship with the package:

// Vite
import philosophy from '@rafael_dias/akoma/content/philosophy.md?raw'

See content/README.md for Node usage.

Project structure

akoma/
├── src/                 # Library source
│   ├── components/      # Vue SFCs
│   ├── styles/          # tokens, base, motion
│   ├── plugin.ts
│   └── index.ts
├── docs/                # Interactive playground
├── content/             # Markdown guides (npm + docs)
├── vite.config.ts       # Docs app
└── vite.lib.config.ts   # npm library build

Publish to npm

npm run build
npm publish --access public

The package is published publicly as @rafael_dias/akoma.