zinc-design-tokens

v0.0.16

Published

16 days ago

Design tokens that power all Procrewz UIs.

Downloads

618

0High
0Medium
0Low

rubenmesta

Procrewz Design Tokens

Design tokens that power all Procrewz UIs. Built with Style Dictionary for multi-platform support.

Brand Colors

| Color | Hex | Usage | |-------|-----|-------| | Procrewz Purple | #5A4295 | Primary brand color | | Procrewz Magenta | #9B4B95 | Secondary brand color | | Procrewz Navy | #2B2E69 | Accent brand color |

Installation

npm install procrewz-design-tokens

Quick Start

Salesforce LWC

The easiest way to use tokens in Salesforce Lightning Web Components:

npx procrewz add theme-provider

Custom folder structure? Use the --path option:

npx procrewz add theme-provider --path ./src/lwc
npx procrewz add theme-provider --path ./custom-app/main/default/lwc

This command:

Auto-detects your LWC directory (reads sfdx-project.json or scans for lwc folders)
Creates a themeProvider component with all CSS variables
If already exists, updates only the token CSS file

Usage in your LWC components:

<!-- myComponent.html -->
<template>
  <c-theme-provider>
    <div class="card">
      <h2 class="title">Hello World</h2>
      <p class="description">This uses design tokens!</p>
    </div>
  </c-theme-provider>
</template>

/* myComponent.css */
.card {
  background: var(--color-surface-default);
  border: var(--border-width-1) solid var(--color-border-default);
  border-radius: var(--radius-lg);
  padding: var(--spacing-24);
  box-shadow: var(--shadow-md);
}

.title {
  color: var(--color-brand-primary);
  font-size: var(--font-size-xl);
  font-weight: var(--font-weight-bold);
  line-height: var(--font-line-height-tight);
  margin-bottom: var(--spacing-8);
}

.description {
  color: var(--color-text-muted);
  font-size: var(--font-size-md);
  line-height: var(--font-line-height-normal);
}

React / Next.js / Web Apps

Import the CSS file in your app entry point:

// App.jsx or _app.tsx
import 'procrewz-design-tokens/web';

Or import directly in CSS:

@import 'procrewz-design-tokens/dist/web/tokens.css';

Usage:

// Button.jsx
function Button({ children, variant = 'primary' }) {
  return (
    <button className={`btn btn-${variant}`}>
      {children}
    </button>
  );
}

/* Button.css */
.btn {
  height: var(--sizing-control-md);
  padding: 0 var(--spacing-16);
  border-radius: var(--radius-md);
  font-weight: var(--font-weight-medium);
  font-size: var(--font-size-sm);
  transition: background-color var(--transition-duration-fast) var(--transition-timing-ease-out);
  cursor: pointer;
  border: none;
}

.btn-primary {
  background-color: var(--color-interactive-primary-default);
  color: var(--color-text-inverse);
}

.btn-primary:hover {
  background-color: var(--color-interactive-primary-hover);
}

.btn-primary:active {
  background-color: var(--color-interactive-primary-active);
}

.btn-primary:disabled {
  background-color: var(--color-interactive-primary-disabled);
  cursor: not-allowed;
}

.btn-secondary {
  background-color: var(--color-interactive-secondary-default);
  color: var(--color-text-inverse);
}

.btn-secondary:hover {
  background-color: var(--color-interactive-secondary-hover);
}

Mobile (Swift / React Native)

Import the JavaScript module:

import {
  ColorBrandPrimary,
  ColorBrandSecondary,
  ColorBrandAccent,
  Spacing16,
  RadiusMd,
} from 'procrewz-design-tokens';

// Use in React Native
const styles = StyleSheet.create({
  button: {
    backgroundColor: ColorBrandPrimary,
    borderRadius: parseInt(RadiusMd),
    padding: parseInt(Spacing16),
  },
});

Token Categories

Colors

Core Palettes

| Token | Example | |-------|---------| | --color-purple-{50-900} | Primary brand palette | | --color-magenta-{50-900} | Secondary brand palette | | --color-navy-{50-900} | Accent brand palette | | --color-gray-{50-900} | Neutral palette |

Semantic Colors

| Token | Usage | |-------|-------| | --color-brand-primary | Primary brand color (#5A4295) | | --color-brand-secondary | Secondary brand color (#9B4B95) | | --color-brand-accent | Accent brand color (#2B2E69) | | --color-text-default | Default text color | | --color-text-muted | Secondary/muted text | | --color-text-inverse | Text on dark backgrounds | | --color-background-default | Page background | | --color-background-subtle | Subtle background variation | | --color-surface-default | Card/container background | | --color-surface-raised | Elevated surfaces (modals) | | --color-surface-sunken | Recessed surfaces (inputs) | | --color-border-default | Default borders | | --color-border-subtle | Subtle borders |

Interactive Colors

| Token | Usage | |-------|-------| | --color-interactive-primary-{default,hover,active,disabled} | Primary buttons | | --color-interactive-secondary-{...} | Secondary buttons | | --color-interactive-accent-{...} | Accent buttons | | --color-interactive-neutral-{...} | Ghost/neutral buttons | | --color-interactive-destructive-{...} | Delete/danger buttons |

Status Colors

| Token | Usage | |-------|-------| | --color-status-success-{bg,text,icon,border} | Success states | | --color-status-warning-{...} | Warning states | | --color-status-error-{...} | Error states | | --color-status-info-{...} | Info states |

Spacing

--spacing-0    /* 0 */
--spacing-2    /* 0.125rem (2px) */
--spacing-4    /* 0.25rem (4px) */
--spacing-6    /* 0.375rem (6px) */
--spacing-8    /* 0.5rem (8px) */
--spacing-10   /* 0.625rem (10px) */
--spacing-12   /* 0.75rem (12px) */
--spacing-14   /* 0.875rem (14px) */
--spacing-16   /* 1rem (16px) - Base unit */
--spacing-20   /* 1.25rem (20px) */
--spacing-24   /* 1.5rem (24px) */
--spacing-32   /* 2rem (32px) */
--spacing-40   /* 2.5rem (40px) */
--spacing-48   /* 3rem (48px) */
--spacing-64   /* 4rem (64px) */
--spacing-80   /* 5rem (80px) */
--spacing-96   /* 6rem (96px) */

Sizing

/* Icon sizes */
--sizing-icon-xs    /* 12px */
--sizing-icon-sm    /* 16px */
--sizing-icon-md    /* 20px */
--sizing-icon-lg    /* 24px */
--sizing-icon-xl    /* 32px */
--sizing-icon-2xl   /* 40px */

/* Control heights (buttons, inputs) */
--sizing-control-xs   /* 24px */
--sizing-control-sm   /* 32px */
--sizing-control-md   /* 40px */
--sizing-control-lg   /* 48px */
--sizing-control-xl   /* 56px */

/* Avatar sizes */
--sizing-avatar-xs    /* 24px */
--sizing-avatar-sm    /* 32px */
--sizing-avatar-md    /* 40px */
--sizing-avatar-lg    /* 48px */
--sizing-avatar-xl    /* 64px */
--sizing-avatar-2xl   /* 96px */

/* Accessibility */
--sizing-touch-target-min   /* 44px (WCAG 2.5.5) */

Typography

/* Font Family */
--font-family-base

/* Font Sizes */
--font-size-xs    /* 0.75rem (12px) */
--font-size-sm    /* 0.875rem (14px) */
--font-size-md    /* 1rem (16px) */
--font-size-lg    /* 1.25rem (20px) */
--font-size-xl    /* 1.5rem (24px) */

/* Font Weights */
--font-weight-regular   /* 400 */
--font-weight-medium    /* 500 */
--font-weight-semibold  /* 600 */
--font-weight-bold      /* 700 */

/* Line Heights */
--font-line-height-tight     /* 1.25 */
--font-line-height-normal    /* 1.5 */
--font-line-height-relaxed   /* 1.75 */

Border Radius

--radius-none     /* 0 */
--radius-sm       /* 0.25rem (4px) */
--radius-md       /* 0.5rem (8px) */
--radius-lg       /* 0.75rem (12px) */
--radius-xl       /* 1rem (16px) */
--radius-2xl      /* 1.5rem (24px) */
--radius-3xl      /* 2rem (32px) */
--radius-full     /* 9999px (pill shape) */
--radius-circle   /* 50% */

Border Width

--border-width-0   /* 0 */
--border-width-1   /* 1px */
--border-width-2   /* 2px */
--border-width-4   /* 4px */

Shadows

--shadow-sm    /* Subtle shadow */
--shadow-md    /* Default shadow */
--shadow-lg    /* Pronounced shadow */
--shadow-xl    /* Heavy shadow */

Transitions

/* Duration */
--transition-duration-fast     /* 150ms */
--transition-duration-base     /* 200ms */
--transition-duration-slow     /* 300ms */
--transition-duration-slower   /* 500ms */

/* Timing Functions */
--transition-timing-linear
--transition-timing-ease-in
--transition-timing-ease-out
--transition-timing-ease-in-out

Z-Index

--z-index-base            /* 0 */
--z-index-dropdown        /* 1000 */
--z-index-sticky          /* 1020 */
--z-index-fixed           /* 1030 */
--z-index-modal-backdrop  /* 1040 */
--z-index-modal           /* 1050 */
--z-index-popover         /* 1060 */
--z-index-tooltip         /* 1070 */

Project Structure

procrewz-design-tokens/
├── tokens/
│   ├── core/                    # Primitive values
│   │   ├── color/
│   │   │   ├── base.json        # White, black, transparent
│   │   │   ├── gray.json        # Neutral palette
│   │   │   ├── purple.json      # Primary brand palette
│   │   │   ├── magenta.json     # Secondary brand palette
│   │   │   └── navy.json        # Accent brand palette
│   │   ├── font/
│   │   │   ├── family.json
│   │   │   ├── size.json
│   │   │   ├── weight.json
│   │   │   └── line-height.json
│   │   ├── border/
│   │   │   └── width.json
│   │   ├── sizing/
│   │   │   └── component.json
│   │   ├── spacing.json
│   │   ├── radius.json
│   │   ├── shadow.json
│   │   ├── opacity.json
│   │   ├── z-index.json
│   │   └── transition/
│   │       ├── duration.json
│   │       └── timing.json
│   │
│   └── semantic/                # Context-aware aliases
│       └── color/
│           ├── background.json
│           ├── border.json
│           ├── brand.json
│           ├── focus.json
│           ├── icon.json
│           ├── interactive.json
│           ├── state.json
│           ├── status.json
│           ├── surface.json
│           └── text.json
│
├── dist/                        # Compiled output
│   ├── web/tokens.css           # :root variables
│   ├── lwc/tokens.css           # :host variables
│   └── js/tokens.js             # ES6 exports
│
├── cli/                         # CLI tools
│   └── commands/
│       └── add-theme-provider.js
│
└── bin/
    └── procrewz                 # CLI entry point

Development

Build Tokens

npm run build        # Build to /build
npm run dist         # Clean, build, and copy to /dist
npm run clean        # Remove build artifacts

Publish

npm version patch    # Bump version
npm publish          # Publish to npm

CLI Reference

`npx procrewz add theme-provider`

Installs the theme provider component into your Salesforce LWC project.

Options:

npx procrewz add theme-provider                           # Auto-detect LWC directory
npx procrewz add theme-provider --path ./src/lwc          # Specify custom path
npx procrewz add theme-provider --path ./custom-app/lwc   # Works with renamed folders

How it finds your LWC directory:

Reads sfdx-project.json — Checks packageDirectories for LWC paths
Scans for lwc folders — Finds any folder named lwc containing LWC components
Validates — Confirms it's a real LWC folder by checking for .js-meta.xml files

Supported folder structures:

# Standard Salesforce DX
force-app/main/default/lwc/

# Renamed source folder
src/main/default/lwc/

# Custom package names
my-package/main/default/lwc/

# Simplified structure
app/lwc/

# Multiple packages (uses first found, or specify with --path)
package-a/main/default/lwc/
package-b/main/default/lwc/

Behavior:

Creates themeProvider/ directory if it doesn't exist
Always overwrites themeProvider.css with latest tokens
Only creates .html, .js, .js-meta.xml if they don't exist

Example output:

🔧 Procrewz: Install Theme Provider

✔ Found LWC directory: force-app/main/default/lwc
✔ Created themeProvider component directory
✔ Updated themeProvider.css with token variables
✔ Created themeProvider.html
✔ Created themeProvider.js
✔ Created themeProvider.js-meta.xml

🎉 Theme Provider installation complete!

You can now wrap LWC components with <c-theme-provider>.

If multiple LWC directories are found:

✔ Found LWC directory: force-app/main/default/lwc
  ℹ Found 2 LWC directories, using first one.
  Other directories found:
    • package-b/main/default/lwc
  Use --path to specify a different directory.