miocene-ui-kit

A small Vue 3 UI kit for fast personal prototypes. It is intentionally lighter than a production design system: native elements, simple props, sprite icons, and CSS custom properties you can bend per prototype.

Install

yarn add miocene-ui-kit

import { createApp } from 'vue';
import MioceneUiKit from 'miocene-ui-kit';
import 'miocene-ui-kit/styles.css';

createApp(App).use(MioceneUiKit).mount('#app');

Direct imports work too:

import { MButton, MInput, MModal } from 'miocene-ui-kit';
import 'miocene-ui-kit/styles.css';

The Shape

• Vue 3, plain JavaScript.
• Components are named MButton, MInput, MAvatar, and so on.
• Native first: MModal uses <dialog>, MPopover uses the Popover API, form controls use real inputs.
• Sizes are sm, md, and lg.
• Most visual choices are CSS variables.

Components

The kit is split into two layers:

• Base components are small primitives: buttons, inputs, selects, tabs, cards, badges, and native overlay wrappers.
• Complex components are prototype patterns composed from base pieces: command palettes, global selectors, user menus, floaty controls, activity, and comments.

The source tree mirrors this split: base components live in src/components/base, and composed prototype patterns live in src/components/complex.

Base Components

| Area | Components | | --- | --- | | Actions | MButton, MButtonGroup | | Forms | MField, MInput, MSearchInput, MTextarea, MSelect, MCheckbox, MRadio, MCheckboxGroup, MRadioGroup, MToggle | | Identity and status | MAvatar, MAvatarGroup, MBadge, MIcon | | Layout and surfaces | MCard, MStack, MProgressiveBlur | | Native overlays | MModal, MPopover | | Navigation | MTabGroup, MTabs |

Complex Components

| Pattern | Components | | --- | --- | | App chrome | MFloaty, MUserMenu, MGlobalSelect | | Discovery | MCommandPalette, MSearchBlock | | Work surfaces | MControlPanel, MFloatingControlPanel | | Collaboration | MActivity, MComment |

Choosing Components

Some components are intentionally close to each other because prototypes need slightly different interface shapes:

| Need | Use | | --- | --- | | A real tab panel with tab content | MTabGroup | | Compact pill navigation without panels | MTabs | | A floating pill radio choice | MButtonGroup | | One small popover near a trigger | MPopover | | A user/account menu with sections | MUserMenu | | A modal command/search surface | MCommandPalette | | A product/project switcher with overlay | MGlobalSelect |

API Shape

Controlled values use v-model through modelValue and update:modelValue. Larger components expose semantic events such as select, action, quick-action, and section-action.

Choice components accept either simple arrays or object arrays:

['Sketch', 'Wireframe', 'Prototype']

[
  { label: 'Sketch', value: 'sketch' },
  { label: 'Wireframe', value: 'wireframe', disabled: true }
]

Use slots when content needs to become richer than a label, especially leading, trailing, header, footer, and actions.

<MField label="Prototype name" v-slot="{ id, describedBy }">
  <MInput :id="id" :aria-describedby="describedBy" placeholder="Checkout refresh" />
</MField>

<MButton :loading="saving">Save prototype</MButton>

<MButtonGroup
  v-model="view"
  label="View mode"
  size="md"
  :options="[
    { label: 'List', value: 'list', icon: 'task-1' },
    { label: 'Board', value: 'board', icon: 'business-1' }
  ]"
/>

<MModal v-model="open" title="Ready for review">
  <p>This flow is ready for a quick pass.</p>
  <template #footer>
    <MButton variant="secondary" @click="open = false">Later</MButton>
    <MButton @click="open = false">Ship it</MButton>
  </template>
</MModal>

<MCommandPalette v-model="commandOpen" :sections="commandSections" />

<MGlobalSelect
  v-model="space"
  :sections="spaceSections"
  :current-label="currentSpaceName"
/>

<MFloaty :actions="agentActions" :quick-actions="quickActions" />

<MActivity :items="timelineItems" />

Icons

Icons are loaded from the generated SVG sprite. MIcon injects the package sprite into the page the first time it renders, so consuming apps do not need to copy icon-sprite.svg into their own public/ folder.

<MIcon name="setting-4" />

The sprite prop is only needed when you want to point icons at a custom or separately hosted sprite:

import iconSprite from 'miocene-ui-kit/icon-sprite.svg?url';

<MIcon name="setting-4" :sprite="iconSprite" />

Theming

Override tokens globally, on a wrapper, or per screen.

.prototype-theme {
  --m_bg-color-default: light-dark(var(--m_shade-0), var(--m_shade-600));
  --m_text-color-default: light-dark(var(--m_shade-900), var(--m_shade-50));
  --m_control-bg-primary-default: light-dark(var(--m_shade-900), var(--m_shade-50));
  --m_border-radius-md: 6px;
}

Semantic colors use light-dark(). Set color-scheme to force a prototype area into a mode.

<main class="prototype-theme" style="color-scheme: dark;">
  ...
</main>

Token Reference

| Token | Purpose | | --- | --- | | --m_shade-0 | Base shade | | --m_shade-50 | Base shade | | --m_shade-100 | Base shade | | --m_shade-200 | Base shade | | --m_shade-300 | Base shade | | --m_shade-400 | Base shade | | --m_shade-500 | Base shade | | --m_shade-600 | Base shade | | --m_shade-700 | Base shade | | --m_shade-800 | Base shade | | --m_shade-900 | Base shade | | --m_shade-950 | Base shade | | --m_shade-1000 | Base shade | | --m_space-2 | Spacing primitive | | --m_space-4 | Spacing primitive | | --m_space-8 | Spacing primitive | | --m_space-12 | Spacing primitive | | --m_space-16 | Spacing primitive | | --m_space-20 | Spacing primitive | | --m_space-24 | Spacing primitive | | --m_space-32 | Spacing primitive | | --m_space-40 | Spacing primitive | | --m_space-48 | Spacing primitive | | --m_space-60 | Spacing primitive | | --m_space-80 | Spacing primitive | | --m_space-96 | Spacing primitive | | --m_space-120 | Spacing primitive | | --m_font-sans | Sans font stack | | --m_font-mono | Mono font stack | | --m_text-size-xs | Text size | | --m_text-size-sm | Text size | | --m_text-size-md | Text size | | --m_text-size-lg | Text size | | --m_text-size-xl | Text size | | --m_text-size-2xl | Text size | | --m_text-size-3xl | Text size | | --m_text-size-4xl | Text size | | --m_text-size-5xl | Text size | | --m_text-size-6xl | Text size | | --m_control-size-sm | Control height | | --m_control-size-md | Control height | | --m_control-size-lg | Control height | | --m_border-radius-sm | Corner radius | | --m_border-radius-md | Corner radius | | --m_border-radius-lg | Corner radius | | --m_border-radius-xl | Corner radius | | --m_border-radius-2xl | Corner radius | | --m_avatar-size-xs | Extra-small avatar size | | --m_avatar-size-sm | Small avatar size | | --m_avatar-size-md | Medium avatar size | | --m_avatar-size-lg | Large avatar size | | --m_avatar-size-xl | Extra-large avatar size | | --m_status-size | Avatar status indicator size | | --m_bg-color-default | Default page background | | --m_bg-color-primary | Primary page or surface background | | --m_text-color-default | Default text color | | --m_text-color-secondary | Secondary text color | | --m_control-bg-primary-default | Primary control background | | --m_control-text-primary-default | Primary control text | | --m_control-bg-secondary-default | Secondary control background | | --m_control-text-secondary-default | Secondary control text | | --m_content-border-contrast | Border color against the current surface | | --m_content-border-medium | Medium-contrast content border |

Develop

yarn dev
yarn test
yarn test:screenshots
yarn build
yarn build:storybook

Storybook runs on http://localhost:6006.

yarn test:screenshots builds Storybook, captures a curated set of rendered stories with Playwright, and writes inspectable PNGs to the ignored screenshots/ folder. It is a smoke test, not a pixel-perfect baseline test: it catches broken stories, empty renders, and runtime errors without making small visual experiments painful.