User Interface Overview

A comprehensive Nuxt module providing reusable UI components, composables, and utilities built with the official Kanton Basel-Stadt design system. This package streamlines development of Basel-Stadt applications by offering a consistent, accessible, and well-documented component library.

See also GitHub Repository.

Quick Setup

This package can only be used as a Nuxt module.

REMARK

It can be possible to get the components working in a non-Nuxt Vue application, but this is not officially supported and may require additional configuration.

See Nuxt UI Installation for Vue for how to set up Nuxt UI in a Vue application.

All component can be imported with import { ComponentName } from '@dcc-bs/common-ui.bs.js/components' and the composables with import { composableFunction } from '@dcc-bs/common-ui.bs.js/composables'.

1. Install the module to your Nuxt application with your preferred package manager:

# bun
bun add @dcc-bs/common-ui.bs.js

# npm
npm install @dcc-bs/common-ui.bs.js

# pnpm
pnpm add @dcc-bs/common-ui.bs.js

# yarn
yarn add @dcc-bs/common-ui.bs.js

2. Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    '@dcc-bs/common-ui.bs.js'
  ]
})

3. Add the CSS imports to your main css file:

@import "tailwindcss";
@import "@nuxt/ui";
@import "@dcc-bs/common-ui.bs.js";

4. Add the FirstRunOrchestrator to your app.vue to enable the first-run flow (Disclaimer → Changelogs → Onboarding):

<script lang="ts" setup>
const builder = useOnboardingBuilder()
    .addPhases<"Phase1" | "Phase2">([
        {
            name: "Phase1",
            onEnter: async () => { /* ... */ },
            onExit: async () => { /* ... */ },
        },
        {
            name: "Phase2",
            onEnter: async () => { /* ... */ },
            onExit: async () => { /* ... */ },
        },
    ])
    .switchPhase("Phase1")
    .addSteps([
        { popover: { title: "Step 1", description: "This is step 1" } },
        { popover: { title: "Step 2", description: "This is step 2" } },
    ])
    .switchPhase("Phase2")
    .addSteps([
        { popover: { title: "Step 3", description: "This is step 3" } },
    ]);
</script>

<template>
    <UApp>
        <FirstRunOrchestrator
            :onboarding-builder="builder"
            :disclaimer="{
                appName: 'My App',
                confirmationText: 'I have read and understood...',
            }"
        />
        <NuxtPage />
    </UApp>
</template>

That's it! You can now use common-ui.bs.js in your Nuxt app ✨

FirstRunOrchestrator

The FirstRunOrchestrator component coordinates the three first-run flows — Disclaimer, Changelogs, and Onboarding — ensuring they run in priority order without overlapping. It manages all completion state via cookies, so individual flow components no longer handle persistence themselves.

How It Works

1. Disclaimer (highest priority): Blocks until the user accepts the terms.
2. Changelogs: After the disclaimer is accepted, if there are new changelog entries since the user's last visit, the changelog modal is shown.
3. Onboarding (lowest priority): After changelogs are dismissed, the guided tour starts (if a builder is provided).

Each flow emits a finished event when complete. The orchestrator records the completion cookie, which reactively advances to the next pending flow.

Props

Prop	Type	Required	Description
onboardingBuilder	OnboardingStepBuilder<Phases>	No	The onboarding tour builder. If omitted, the Onboarding flow is skipped.
disclaimer	Partial<DisclaimerConfig>	No	Overrides for the runtime config disclaimer defaults (appName, version, contentHtml, postfixHtml, confirmationText).

Completion Cookies

The orchestrator owns all cookie writes. Individual flow components (Disclaimer, Changelogs, Onboarding) only emit finished events and do not write cookies themselves.

Cookie	Type	Default	Purpose
disclaimer-accepted	string	""	Set to the disclaimer version when the user accepts.
changelogs-last-read	string	""	Set to the latest release version when the user dismisses changelogs.
tour-completed	boolean	false	Set to true when the user completes or skips the onboarding tour.

TIP

The ChangelogsButton and DisclaimerButton components can reset these cookies to re-trigger their respective flows on demand.

Cookie Security in Production

In production, all first-run cookies are set with sameSite: "none", secure: true, and partitioned: true. This means your application must be served over HTTPS for the cookies to be stored. In development (import.meta.dev), cookies use sameSite: "lax" and are not secure or partitioned, so local HTTP workflows are unaffected.

Module Features

When using this Nuxt module:

• All components are automatically available globally without imports
• First-run orchestration (Disclaimer → Changelogs → Onboarding) via the FirstRunOrchestrator
• Internationalization (i18n) integration is automatically configured
• Design system assets are automatically included
• Kanton Basel-Stadt color palette is integrated with Tailwind CSS

Runtime Configuration

The module exposes runtime configuration options that allow you to disable certain features at runtime. These are available under runtimeConfig.public.commonUi in your nuxt.config.ts:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      commonUi: {
        disableChangelog: false,
        disableDisclaimer: false,
        disableOnboarding: false,
        disclaimer: {
          appName: "",
          version: "1.0.0",
        },
      },
    },
  },
})

Option	Type	Default	Description
disableChangelog	boolean	false	When set to true, the Changelogs component will not fetch or display changelogs.
disableDisclaimer	boolean	false	When set to true, the Disclaimer component modal will not be displayed.
disableOnboarding	boolean	false	When set to true, the Onboarding component will not start the guided tour.
disclaimer.appName	string	""	Default application name used in the disclaimer flow.
disclaimer.version	string	"1.0.0"	Disclaimer version. Changing this forces users to re-accept the disclaimer.

TIP

These options can also be set via environment variables such as NUXT_PUBLIC_COMMON_UI_DISABLE_CHANGELOG, NUXT_PUBLIC_COMMON_UI_DISABLE_DISCLAIMER, and NUXT_PUBLIC_COMMON_UI_DISABLE_ONBOARDING.

Internationalization

All components are fully localized using @nuxtjs/i18n. The library provides default translations, but you can override any of them in your application's i18n configuration.

Available Translation Keys

You can customize the following translation keys in your application:

{
    "common-ui": {
        "undo": "Undo",
        "redo": "Redo",
        "undo_tooltip": "Undo the last action",
        "redo_tooltip": "Redo the last undone action",
        "changelogs": {
            "title": "What's New",
            "close": "Close"
        },
        "health_status": {
            "offline_title": "System disruption",
            "offline_description": "Some services are unavailable, features may be limited"
        },
        "tour": {
            "skip": "Skip",
            "next": "Next",
            "prev": "Back",
            "finish": "Finish",
            "restart": "Help",
            "progress": "Step {{current}} of {{total}}"
        }
    },
    "disclaimer": {
        "confirmation_text": "I have read and understood...",
        "content": "<h2>Disclaimer and Important Usage..."
    }
}

To override these translations, add them to your application's i18n configuration files (e.g., locales/en.json, locales/de.json, etc.).

Components

For components see the Components section.

Composables

For composables see the Composables section.

Design System

This library uses the official Kanton Basel-Stadt design system colors, providing a consistent visual identity across all Basel-Stadt applications.

Available Color Palettes

• Green: Primary brand colors (green-50 to green-900)
• Blue: Secondary colors (blue-50 to blue-900)
• Purple: Accent colors (purple-50 to purple-900)
• Red: Error and warning states (red-50 to red-900)
• Gray: Neutral colors (gray-20 to gray-900)
• Teal: Supporting colors (teal-50 to teal-900)
• Yellow: Highlight colors (yellow-50 to yellow-900)
• Brown: Earth tone colors (brown-50 to brown-900)

The color system is fully integrated with Tailwind CSS and can be used with standard Tailwind color classes like bg-green-500, text-blue-600, etc.

Additional Resources

• GitHub Repository: DCC-BS/common-ui.bs.js
• NPM Package: @dcc-bs/common-ui.bs.js
• Design System: Kanton Basel-Stadt Designsystem
• License: MIT