shift3-design-system

v0.1.0

Published

4 months ago

Shift3 design system — design tokens (CSS / SCSS / TS) and Vue 3 components consumed as raw source by a Vue/Vite build.

0High
0Medium
0Low

sven_siertsema_business

design-system design-tokens scss vue vue3 components

@shift3/design-system

Design tokens and Vue 3 components for Shift3 products. Tokens ship as CSS custom properties, SCSS variables, and a TypeScript constant export. Components ship as raw .vue source — consumers need a Vue 3 + Vite (or compatible) build pipeline.

Install

npm install @shift3/design-system vue

vue@^3.5 is a peer dependency.

Use

1. Load a theme

// main.ts
import '@shift3/design-system/css/theme-light.css'
// or: '@shift3/design-system/css/theme-high-contrast-light.css'

A theme defines every CSS custom property (--surface-canvas, --text-default, --brand-primary, …) under :root and a [data-theme="..."] selector. Switch themes by toggling the attribute on <html>.

2. Import a component

<script setup lang="ts">
import ButtonPrimary from '@shift3/design-system/components/ButtonPrimary/ButtonPrimary.vue'
import '@shift3/design-system/components/ButtonPrimary/ButtonPrimary.scss'
</script>

<template>
  <ButtonPrimary label="Save" />
</template>

Component .scss files reference the package's own dist/scss/_tokens.scss and src/scss/mixins/* via relative paths, so they resolve correctly from inside node_modules with no extra configuration.

3. (Optional) Use SCSS tokens directly

@use "@shift3/design-system/scss/tokens" as *;

.my-thing {
  color: $text-default;
  background: $surface-panel;
}

4. (Optional) Read token names in TypeScript

import { tokenNames } from '@shift3/design-system'

Exports

| Specifier | Contents | |-----------|----------| | @shift3/design-system | TS constants (tokenNames, etc.) | | @shift3/design-system/css/theme-light.css | Light theme as CSS custom properties | | @shift3/design-system/css/theme-high-contrast-light.css | High-contrast light theme | | @shift3/design-system/scss/tokens | SCSS variables aliased to the CSS custom properties | | @shift3/design-system/scss/mixins/* | levitation, typography, border, etc. | | @shift3/design-system/components/<Name>/<Name>.vue | Raw Vue 3 SFC | | @shift3/design-system/components/<Name>/<Name>.scss | Per-component styles | | @shift3/design-system/manifest.json | Machine-readable token + component inventory |

Requirements for consumers

A Vue 3 toolchain that understands .vue SFCs (Vite, Nuxt, vue-cli).
A SCSS compiler if you import any .scss from this package (most Vite setups include sass as a dev dependency).

Design rationale

| Scale | Ratio | Why | |-------|-------|-----| | Spacers | Golden ratio (φ ≈ 1.618) | Fewer steps cover the full range | | Radii | Fibonacci / golden ratio | 6 values cover all rounding needs | | Shadows | 2× progression | Larger jumps for perceptible depth | | Typography | Major third (~1.25) | Finer control for readable text |

All scales use t-shirt sizing (3xs, 2xs, xs, s, m, l, xl, …). For pill shapes use border-radius: 9999px directly.

Development (for contributors to this package)

npm install
npm run build:tokens
npm --prefix server install
npm run dev          # docs site at http://localhost:3000

See BRAND.md for the rebranding workflow and CLAUDE.md for the full architecture overview.

License

MIT — see LICENSE.