@rafael_dias/akoma

v0.9.0

Published

18 days ago

A human Vue 3 design system with expressive App and trustworthy Site moods.

0High
0Medium
0Low

rafael_dias

vue vue3 design-system ui components 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

| Mood | Feel | Use for | Activate | |------|------|---------|----------| | App (default) | Tactile, optimistic, relaxed | Products and apps | — | | Site | Composed, precise, trustworthy | Finance, B2B and institutional sites | <html data-mood="site"> |

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.

| Palette | Use for | |---------|---------| | violet | Default App | | evergreen | Default Site | | teal | Productivity, study, wellness | | ocean | Data, analytics | | amber | Warm consumer apps | | rose / coral | Lifestyle, creative | | slate | Neutral B2B |

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)

| Component | Description | |-----------|-------------| | AkIcon | Cuida Icons wrapper | | AkButton | Primary / secondary / ghost / danger | | AkIconButton | Icon-only actions | | AkBadge | Status pills | | AkChip | Filter & category chips | | AkCard | Flat surface with slots | | AkList / AkListRow | Grouped flat rows | | AkSectionHeader | Uppercase section labels | | AkProgress | Progress bars | | AkDivider | Section separators | | AkSwitch | Toggle settings | | AkTabBar / AkTabBarItem | Bottom navigation (Cuida icons) | | AkSheet | Mobile bottom sheet for detail/forms | | AkPageHeader | Page chrome — label / title / meta / actions | | AkFab | Floating primary action above the tab bar | | AkInput | Labeled text field | | AkTextarea | Multi-line field | | AkEmptyState | Empty list placeholder | | AkShimmer | Loading skeleton | | AkAmbientBg | Soft background orbs |

Scripts

| Command | Description | |---------|-------------| | npm run dev | Interactive documentation | | npm run build | Build library for npm (dist/) | | npm run build:docs | Build static docs (dist-docs/) | | npm run preview | Preview docs build |

Design guides (Markdown)

Guides live in content/ and ship with the package:

| File | Topic | |------|-------| | philosophy.md | North star, pillars, anti-patterns | | moods.md | App vs Site | | colors.md | Accent palettes | | icons.md | Cuida Icons | | patterns.md | Mood app PWA conventions (shell, page chrome, sheets) | | decisions.md | Design decision log | | implementation.md | Migration checklist |

// 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.