@commonpub/ui

@commonpub/ui

Headless Vue 3 component library with CSS custom property theming.

Overview

Accessible, headless UI components built with Vue 3 Composition API (<script setup lang="ts">). Components define structure and behavior only. All visual styling is controlled via CSS custom properties (var(--*)). Zero hardcoded colors or fonts.

Includes 7 built-in themes (12 theme CSS files) and a theming API for runtime theme switching with inline token overrides.

Installation

pnpm add @commonpub/ui

Components

Usage

<script setup lang="ts">
import { Button, Input, Dialog, Tabs } from '@commonpub/ui';

const name = ref('');
const nameError = ref('');
const showModal = ref(false);
</script>

<template>
  <Button @click="handleClick" variant="primary">
    Save Project
  </Button>

  <Input
    v-model="name"
    label="Project Name"
    :error="nameError"
  />

  <Dialog v-model:open="showModal" title="Confirm Delete">
    <p>Are you sure you want to delete this project?</p>
  </Dialog>
</template>

All components accept a class prop for external styling:

<Button class="my-custom-button">Click me</Button>

Theming

Built-in Themes

7 built-in themes (BUILT_IN_THEMES):

Stoa is the current CommonPub default (the server-side fallback resolves to stoa/stoa-dark). Consumer apps (e.g., deveco.io) add their own theme CSS overrides on top of these.

Importing Theme CSS

// Import the themes you want (the layer bundles all of them automatically)
import '@commonpub/ui/theme/base.css';
import '@commonpub/ui/theme/dark.css';
import '@commonpub/ui/theme/stoa.css';
import '@commonpub/ui/theme/stoa-dark.css';

Runtime Theme Switching

import { applyThemeToElement, getThemeFromElement, isValidThemeId } from '@commonpub/ui';

// Apply theme via data-theme attribute
applyThemeToElement(document.documentElement, 'dark');

// Apply with custom token overrides
applyThemeToElement(document.documentElement, 'base', {
  'color-primary': '#ff6600',
  'font-heading': '"Custom Font", sans-serif',
});

// Read current theme
const { themeId, overrides } = getThemeFromElement(document.documentElement);

Token Contract

The full token surface is defined in theme/base.css. All tokens are CSS custom properties:

• Surface colors: --color-surface, --color-surface-alt, --color-surface-raised
• Text colors: --color-text, --color-text-secondary, --color-text-muted
• Brand colors: --color-primary, --color-accent (with hover and text variants)
• Semantic colors: --color-success, --color-warning, --color-error, --color-info
• Typography: --font-heading, --font-body, --font-mono, sizes, weights, line heights
• Spacing: --space-1 through --space-24
• Borders: Widths, radii (--radius-sm through --radius-full)
• Shadows: --shadow-sm through --shadow-xl
• Z-index: --z-dropdown, --z-modal, --z-toast, --z-tooltip
• Layout: --nav-height, --sidebar-width, --content-max-width

Validating Token Overrides

import { validateTokenOverrides, TOKEN_NAMES } from '@commonpub/ui';

const { valid, invalid } = validateTokenOverrides({
  'color-primary': '#ff0000',   // valid
  'not-a-token': 'value',       // invalid
});

Accessibility

All components meet WCAG 2.1 AA:

• Keyboard navigable (Tab, Enter, Space, Escape, Arrow keys)
• ARIA attributes on all interactive elements
• Focus indicators with --focus-ring token
• prefers-reduced-motion respected
• All components tested with axe-core

Component Standards

• Headless: Structure and behavior only, no visual opinions
• class prop: Every component accepts class for external styling
• Vue 3 Composition API: <script setup lang="ts"> syntax
• Events: Use Vue emit pattern

Development

pnpm build        # Build with vite-plugin-vue
pnpm test         # Run tests (including axe-core a11y)
pnpm typecheck    # Type-check with vue-tsc

Dependencies

• vue (peer): Vue 3.4+