---
title: "Introduction"
description: "The Propay Design System: one set of shadcn-vue components, tokens and patterns shared by every Propay Vue/Nuxt system. Each system picks its colours; the components stay the same."
canonical_url: "https://handbook.propay.co.za/design-system/introduction"
---
# Introduction

> The Propay Design System: one set of shadcn-vue components, tokens and patterns shared by every Propay Vue/Nuxt system. Each system picks its colours; the components stay the same.

## Purpose

Every system we build should **look and behave the same**: the same buttons, forms, tables, dialogs, spacing and wording, so that users and developers move between Propay products without relearning them. Systems may choose their **own colour scheme**, but never their own components.

The design system is built on [shadcn-vue](https://www.shadcn-vue.com) using the preset **abT3AW** (style `reka-nova`, Inter, Lucide icons, neutral base), with **Propay blue #004899** as the default primary colour.

## What you will find here

- **Getting started**: set up a new Nuxt or Laravel + Inertia + Vue project with the preset and the `@propay` registry.
- **Theming**: the theme contract. Which variables a system may change, and how to create a system theme.
- **Foundations**: [colour](https://handbook.propay.co.za/design-system/foundations/colour), [typography](https://handbook.propay.co.za/design-system/foundations/typography), [radius, spacing and elevation](https://handbook.propay.co.za/design-system/foundations/shape), [icons and motion](https://handbook.propay.co.za/design-system/foundations/icons-and-motion).
- **Components**: [button](https://handbook.propay.co.za/design-system/components/button), [badge](https://handbook.propay.co.za/design-system/components/badge), [field and input](https://handbook.propay.co.za/design-system/components/field), [select, checkbox, radio and switch](https://handbook.propay.co.za/design-system/components/form-controls), [alert](https://handbook.propay.co.za/design-system/components/alert), [toast](https://handbook.propay.co.za/design-system/components/toast), [card](https://handbook.propay.co.za/design-system/components/card), [table](https://handbook.propay.co.za/design-system/components/table), [dialog and sheet](https://handbook.propay.co.za/design-system/components/dialog), [dropdown menu](https://handbook.propay.co.za/design-system/components/dropdown-menu), [tabs](https://handbook.propay.co.za/design-system/components/tabs), [tooltip](https://handbook.propay.co.za/design-system/components/tooltip), [skeleton and spinner](https://handbook.propay.co.za/design-system/components/skeleton).
- **Patterns**: [app shell](https://handbook.propay.co.za/design-system/patterns/app-shell), [page header](https://handbook.propay.co.za/design-system/patterns/page-header), [data table](https://handbook.propay.co.za/design-system/patterns/data-table), [form layout](https://handbook.propay.co.za/design-system/patterns/form-layout), [destructive confirm](https://handbook.propay.co.za/design-system/patterns/destructive-confirm), [empty and loading states](https://handbook.propay.co.za/design-system/patterns/empty-states), [auth vs app](https://handbook.propay.co.za/design-system/patterns/auth).
- **AI agents**: install the design-system skill for Claude Code and Cursor, and connect the shadcn-vue MCP server.
- **Downloads**: the whole design system as one offline HTML page, plus a zip of tokens, registry files and agent skills.

## Principles

1. **Reuse before invent.** Use the stock shadcn-vue component first, a `@propay` component second, and only build something new when two or more systems need it (see [Governance](https://handbook.propay.co.za/design-system/governance)).
2. **Tokens, not values.** Components only reference semantic CSS variables (`bg-primary`, `text-muted-foreground`, `border-border`). No hex codes, no `bg-blue-700`.
3. **Colour is a theme, structure is not.** A system theme changes the brand set only. Radius, spacing, typography and neutrals are fixed.
4. **Accessible by default.** WCAG 2.2 AA. Every theme passes an automated contrast check at build time.
5. **One source of truth.** These pages generate the agent skill and the downloadable HTML, so what humans read and what agents read never drift.

## Scope

- **In scope:** Vue 3, Nuxt and Laravel + Inertia + Vue front ends.
- **Out of scope (for now):** Blade, Livewire, WireUI and Filament UIs. Existing systems on those stacks keep their current design docs.

## How it is built

<table>
<thead>
  <tr>
    <th>
      Output
    </th>
    
    <th>
      Where
    </th>
    
    <th>
      Built from
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      These pages
    </td>
    
    <td>
      <code>
        content/11.design-system/
      </code>
    </td>
    
    <td>
      Authored markdown
    </td>
  </tr>
  
  <tr>
    <td>
      Live previews
    </td>
    
    <td>
      <code>
        /design-system/preview/
      </code>
    </td>
    
    <td>
      <code>
        design-system/
      </code>
      
       (Vite + shadcn-vue)
    </td>
  </tr>
  
  <tr>
    <td>
      Registry
    </td>
    
    <td>
      <code>
        /r/<name>.json
      </code>
    </td>
    
    <td>
      <code>
        design-system/registry.base.json
      </code>
      
       + tokens
    </td>
  </tr>
  
  <tr>
    <td>
      Agent skill
    </td>
    
    <td>
      <code>
        /agent-skills/propay-design-system/
      </code>
    </td>
    
    <td>
      <code>
        design-system/skill/
      </code>
      
       + these pages
    </td>
  </tr>
  
  <tr>
    <td>
      Download
    </td>
    
    <td>
      <code>
        /design-system/propay-design-system.html
      </code>
      
       and <code>
        .zip
      </code>
    </td>
    
    <td>
      All of the above
    </td>
  </tr>
</tbody>
</table>

Everything is regenerated on every handbook build (`npm run ds:build` runs in `prebuild`).


## Sitemap

See the full [sitemap](https://handbook.propay.co.za/sitemap.md) for all pages.