🎨 Royal Voluntary Service Design System

The official design system package containing all design tokens from our Figma library, ready to use in your applications.

📦 Installation

npm install @royal-voluntary-service/theme

pnpm add @royal-voluntary-service/theme

yarn add @royal-voluntary-service/theme

🚀 Quick Start

With Tailwind CSS (Recommended)

Import the theme CSS variables into your Tailwind configuration:

/* In your main CSS file (e.g., globals.css, app.css) */
@import '@royal-voluntary-service/theme/theme.css';
@tailwind base;
@tailwind components;
@tailwind utilities;

Then use the design tokens with Tailwind's arbitrary value syntax:

<!-- Colors -->
<div class="bg-[var(--color-heritageBurgandy-500)] text-[var(--color-white)]">
  Heritage Burgundy Background
</div>

<!-- Spacing -->
<div class="p-[var(--padding-4)] m-[var(--margin-2)]">
  Consistent spacing
</div>

<!-- Typography -->
<h1 class="text-[var(--text-h1)]">Main Heading</h1>
<p class="text-[var(--text-body1)]">Body text</p>

<!-- Borders -->
<div class="rounded-[var(--radius-2)] border border-[var(--color-grey-300)]">
  Rounded card
</div>

With Vanilla CSS

@import '@royal-voluntary-service/theme/theme.css';

.hero-section {
  background-color: var(--color-heritageBurgandy-500);
  color: var(--color-white);
  padding: var(--padding-8);
  border-radius: var(--radius-3);
}

.card {
  background: var(--color-grey-50);
  padding: var(--padding-4);
  margin: var(--margin-2);
  border-radius: var(--radius-2);
}

🎯 Available Design Tokens

🎨 Colors

• Heritage Burgundy: --color-heritageBurgandy-{50-900, A100-A700}
• Purple: --color-purple-{50-900, A100-A700}
• Dark Purple: --color-darkPurple-{50-900, A100-A700}
• Standard Colors: Blue, Cyan, Teal, Green, Red, Orange, Yellow, etc.
• Neutrals: --color-grey-{50-900}, --color-blueGrey-{50-900}

📏 Spacing

• Padding: --padding-{0-16} (0rem to 7rem)
• Margin: --margin-{0-16} (0rem to 7rem)

📝 Typography

• Headings: --text-h1 to --text-h6
• Body: --text-body1, --text-body2
• UI: --text-button, --text-caption, --text-subtitle1, --text-subtitle2

🔲 Shape

• Border Radius: --radius-{none,1-5} (0rem to 1.5rem)

📱 Breakpoints

• Responsive: --breakpoint-{sm,md,lg,xl,2xl}

🧩 Framework Integration

Material-UI (MUI) Theme

import { theme } from '@royal-voluntary-service/theme';
import { ThemeProvider } from '@mui/material/styles';

function App() {
  return (
    <ThemeProvider theme={theme}>
      {/* Your app content */}
    </ThemeProvider>
  );
}

TypeScript Token Imports

// Manual token categories (stable API)
import { primary, secondary } from '@royal-voluntary-service/theme/semantics';
import { spacing } from '@royal-voluntary-service/theme/spacing';
import { fontSize } from '@royal-voluntary-service/theme/typography';
import { lg, md, sm } from '@royal-voluntary-service/theme/breakpoints';

// Auto-generated Figma tokens (synced from design system)
import { breakpoints } from '@royal-voluntary-service/theme/figma/breakpoints';
import { spacing as figmaSpacing } from '@royal-voluntary-service/theme/figma/spacing';
import { Blue, Text, background } from '@royal-voluntary-service/theme/figma/colors';
import { fontSize as figmaFontSize, fontWeight } from '@royal-voluntary-service/theme/figma/typography';
import { shape } from '@royal-voluntary-service/theme/figma/borderRadius';

// Use in your components
const buttonStyles = {
  backgroundColor: primary.main,
  padding: figmaSpacing.spacing04, // 16px from Figma
  fontSize: figmaFontSize.fontSize1rem, // 16px from Figma
  borderRadius: shape.radius01, // 4px from Figma
};

🎨 Design System Workflow

This package is automatically synchronized with our Figma design library:

1. Designers update design tokens in Figma variables
2. Automated sync extracts tokens via Figma API
3. TypeScript & CSS files are automatically generated
4. Developers consume the latest tokens through this package
5. Consistency is maintained across all applications

🔄 Figma Integration

✅ Complete Token Sync Active - Automatically syncs all design tokens from Figma

Current Sync Status

• 🔲 Breakpoints: 5 tokens synced (xs, sm, md, lg, xl)
• 🎨 Colors: 42+ color families with variants and states
• 📏 Spacing: 16 spacing tokens (4px to 112px increments)
• 📝 Typography: Font families, sizes (rem-based), and weights
• 🔄 Border Radius: 7 radius tokens with comprehensive coverage

Sync Commands

• Full Sync: npm run sync:figma - Syncs all token categories
• Simple Sync: npm run sync:figma:simple - Breakpoints only
• Test Connection: npm run test:connection - Verify Figma API access

Auto-Generated Files

src/figma/
├── breakpoints.ts    # 5 responsive breakpoints
├── colors.ts         # 42+ color families with nested variants
├── spacing.ts        # 16 spacing tokens (spacing01-spacing16)  
├── typography.ts     # Font families, sizes, and weights
└── borderRadius.ts   # 7 border radius values

• Figma Variables: Auto-synced to src/figma/ folder (⚠️ do not edit manually)
• Manual Sync: Run npm run sync:figma to pull latest tokens
• Webhook Support: Real-time updates when Figma file changes
• Pull Request Workflow: Changes create PRs for review before merging

👉 Quick Start Guide - Daily commands and workflow
👉 Setup Guide - Complete instructions for Figma integration
👉 Integration Summary - Overview of completed integration

📋 Usage Examples

Building a Card Component

<div class="
  bg-[var(--color-white)] 
  p-[var(--padding-4)] 
  rounded-[var(--radius-2)] 
  border 
  border-[var(--color-grey-200)]
  shadow-sm
">
  <h3 class="text-[var(--text-h6)] text-[var(--color-grey-900)] mb-[var(--margin-2)]">
    Card Title
  </h3>
  <p class="text-[var(--text-body2)] text-[var(--color-grey-700)]">
    Card content goes here...
  </p>
  <button class="
    bg-[var(--color-heritageBurgandy-500)] 
    text-[var(--color-white)] 
    px-[var(--padding-4)] 
    py-[var(--padding-2)] 
    rounded-[var(--radius-1)]
    text-[var(--text-button)]
    mt-[var(--margin-3)]
  ">
    Action Button
  </button>
</div>

Creating a Color Palette Component

.color-palette {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
  gap: var(--margin-2);
}

.color-swatch {
  height: 80px;
  border-radius: var(--radius-1);
  border: 1px solid var(--color-grey-300);
}

.swatch-burgundy-500 { background-color: var(--color-heritageBurgandy-500); }
.swatch-purple-500 { background-color: var(--color-purple-500); }
.swatch-cyan-500 { background-color: var(--color-cyan-500); }

🔄 Updates & Versioning

• Patch versions (0.0.x): Bug fixes, no breaking changes
• Minor versions (0.x.0): New tokens added, backward compatible
• Major versions (x.0.0): Breaking changes to existing tokens

📚 Resources

• Figma Design Library
• Component Documentation
• Design Guidelines

🤝 Contributing

This package is automatically generated from our Figma design system. For token updates or new design requests, please:

1. Contact the design team
2. Request changes through Figma
3. Design tokens will be updated in the next package release

📄 License

ISC