Getting Started

How to install, consume, and release updates to the WLTH Design System.

Overview

@wlth/design-system

A Nuxt layer providing the complete WLTH brand design system — custom color palettes, SuisseIntl fonts, semantic UI variables, Nuxt UI component defaults, and bespoke navigation components. Consumed by extending this layer in any Nuxt project.

Nuxt 4Nuxt UI v4Tailwind v4v1.0.0

Repository

github.com/rhyeezus/wlth-design-system

Open

Installation

Add the design system to any Nuxt project as a git dependency, then extend it in your Nuxt config.

1. package.json

{
  "dependencies": {
    "@wlth/design-system": "github:rhyeezus/wlth-design-system#v1.0.0"
  }
}

2. nuxt.config.ts

export default defineNuxtConfig({
  extends: ['@wlth/design-system']
})

3. Install

npm install

Pinned versions

Consuming apps pin to a specific git tag (e.g. #v1.0.0). The layer is immutable at that tag — upgrade by bumping the tag in your package.json.

Private repo?

Use the SSH form instead: "git+ssh://git@github.com/rhyeezus/wlth-design-system.git" — works on any machine with GitHub SSH configured. For CI/CD, consider migrating to GitHub Packages.

Starter scaffold

Minimum file structure for a consuming Nuxt 4 app.

app/
  app.vue
  app.config.ts        ← inside app/ for Nuxt 4
  layouts/
    default.vue        ← mount AppHeader + AppPageLoader here
  pages/
    index.vue
nuxt.config.ts
package.json
tsconfig.json          ← { "extends": "./.nuxt/tsconfig.json" }

app/app.config.ts

export default defineAppConfig({
  wlth: {
    product: 'broker',  // ← set to your product id
    navItems: [
      { label: 'Home', isHome: true, to: '/' },
      // add your app's routes here
    ]
  }
})

app/layouts/default.vue

<template>
  <div class="flex flex-col min-h-screen">
    <AppPageLoader />
    <AppHeader />
    <main class="flex-1">
      <slot />
    </main>
  </div>
</template>

tsconfig.json

{ "extends": "./.nuxt/tsconfig.json" }

tsconfig.json

Extending .nuxt/tsconfig.json enables IDE auto-imports for Nuxt composables (useRouter, usePageLoader, etc.) — avoids red underlines for auto-imported functions.

What ships to consumers

Only these files are included when a project installs this layer. The playground/ directory is excluded.

nuxt.config.ts

Layer entry point — what consuming apps extend

app.config.ts

Semantic color mapping + Nuxt UI component defaults

assets/css/tokens.css

Custom color palettes, SuisseIntl fonts, --ui-* semantic variables

app/components/

AppHeader, ProductSwitcher, ProductNav, EntitySelector and more

app/composables/

useHeader, useDashboard, usePageLoader

Release workflow

All changes go through a pull request on GitHub. Once merged to main, a new version tag is created — consuming apps stay on their pinned version until they choose to upgrade.

Feature branch

Create a branch from main for your changes

Pull request

Open a PR → review → merge to main

Bump version

Update version in package.json (semver: patch / minor / major)

Tag the release

git tag vX.Y.Z && git push origin vX.Y.Z

Consumers upgrade

Update the pinned tag in their package.json and run npm install

Upgrading the design system in your app

The design system is pinned by git tag in your consuming app's package.json. Running git pull in your app does not update it — npm has already resolved and cached the pinned version. To get a newer version of the design system you must explicitly bump the tag and reinstall.

Option A — latest from main (no version number needed)

npm install "github:rhyeezus/wlth-design-system"
npm run dev

Option B — pin to a specific release tag

npm install "github:rhyeezus/wlth-design-system#v1.1.0"
npm run dev

Both commands update package.json automatically

You don't need to edit any files manually. npm install writes the new reference into your package.json and package-lock.json for you.

zsh: event not found?

zsh treats # as a comment character, so the tag suffix will cause an error if unquoted. Always wrap the full string in quotes as shown above.

git pull won't update the dependency

Pulling your consuming repo only updates your own code. The design system version is locked to whatever tag is in your package.json — only bumping that tag and reinstalling will pull in design system changes.

Design principles

Rules for keeping the design system clean and consistent when adding or changing components.

Style via app.config.ts, not wrapper components

Component appearance must be controlled through ui.* slot and variant overrides in app/app.config.ts. Do not create wrapper components (e.g. AppSlideover, AppButton) just to apply styling defaults — this fragments the component API and forces consumers to learn non-standard names.

Bespoke components for new behaviour only

A new component in app/components/ is justified only when it adds layout, logic, or composition that cannot be expressed through Nuxt UI props and slots — e.g. AppHeader, NotificationsTray. Pure styling is never a reason.

Stay close to Nuxt UI defaults

Override only what is necessary to meet the WLTH brand. Prefer semantic token variables (--ui-*, text-highlighted, border-muted) over hard-coded colour values so that light/dark mode and future rebrands work automatically.

Accept Nuxt UI limitations gracefully

Some sub-component properties (e.g. the Slideover close button color/variant) are hardcoded in the Nuxt UI source and cannot be overridden from app.config.ts. Document the limitation in the relevant slot comment rather than working around it with a wrapper component.

Local development

Run the playground to preview and test design system changes before publishing.

# From the design system root
npm run dev
# → opens playground at localhost:3000

Docs site

The playground (this site) is deployed automatically to Vercel on every push to main. No extra steps required — your normal commit and push workflow is all you need.

git add .
git commit -m "your message"
git push
# → Vercel detects the push and redeploys the docs site automatically

Static build

Vercel runs npm run generate:vercel, which produces a fully static site. No server required.