Raven Design System 2.0

A design-token-first component library for Carleton University, built with React 18, Storybook 10, TypeScript, and SCSS. The successor to cuweb/rds.

Design tokens are defined in c2b.config.json and generated by @troychaplin/component2block into CSS custom properties (--rds--*), base element styles, and WordPress theme files.

Package

@cuweb/raven-design-system

Important

@cuweb/rds-icons is a private package — auth required before installing. This package lists @cuweb/rds-icons as a peer dependency. It is hosted on GitHub Packages (not public npm), so any project that installs @cuweb/raven-design-system — including in CI — needs a GitHub token with read:packages scope, or installation fails with 401 Unauthorized.

Local setup (one-time per machine):

gh auth refresh --scopes read:packages
echo "//npm.pkg.github.com/:_authToken=$(gh auth token)" >> ~/.npmrc

Or generate a classic PAT at https://github.com/settings/tokens with read:packages scope and add the same _authToken line to ~/.npmrc manually.

CI setup (GitHub Actions in the same cuweb org):

- uses: actions/setup-node@v4
  with:
      node-version-file: '.nvmrc'
      registry-url: 'https://npm.pkg.github.com'
      scope: '@cuweb'
- run: npm ci # or: pnpm install --frozen-lockfile
  env:
      NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The built-in GITHUB_TOKEN automatically has read:packages access for packages in the same org — no extra secrets needed.

CI setup (external CI — Vercel, Netlify, CircleCI, etc.): Store a classic PAT as a secret named NODE_AUTH_TOKEN and inject it into the install step's environment.

See the rds-icons README → Consuming this package for full details and troubleshooting.

Quick start

# Requires Node 22+ (see .nvmrc)
nvm use

# Authenticate to GitHub Packages first (see the callout above if you haven't)
pnpm install

# First time only: download Playwright browser binaries (used by pnpm test:storybook)
pnpm exec playwright install chromium

pnpm dev          # Storybook at http://localhost:6006

For full contributor onboarding (PAT alternative, troubleshooting) see docs/contributing/local-setup.md.

Scripts

Command	Description
pnpm dev	Run c2b generate then start Storybook dev server
pnpm build	Vite library build + c2b generate
pnpm build-storybook	Build static Storybook for deployment
pnpm c2b	Regenerate tokens, base styles, and WP theme files
pnpm typecheck	TypeScript type checking (no emit)
pnpm lint	ESLint across src/
pnpm lint:fix	ESLint with auto-fix
pnpm format	Prettier write
pnpm format:check	Prettier check (no write)
pnpm test	Vitest unit tests
pnpm test:watch	Vitest in watch mode
pnpm test:storybook	Vitest + axe a11y checks across all stories (requires Playwright)
pnpm test:coverage	Vitest with coverage report
pnpm size	Bundle size check against limits

Formatting & code style

Formatting is enforced automatically so contributors don't create diffs based on personal editor preferences:

• EditorConfig (.editorconfig) sets base whitespace rules (2-space indent, LF line endings, trimmed trailing whitespace) recognized by most editors.
• Prettier (.prettierrc) formats TS/TSX/SCSS/JSON/Markdown. .prettierignore excludes build output and generated files (dist/, storybook-static/, src/styles/auto/, etc.).
• ESLint (eslint.config.mjs) lints src/ for code quality (React, hooks, jsx-a11y, Storybook rules), with eslint-config-prettier disabling any formatting rules that could conflict with Prettier.
• VSCode workspace settings (.vscode/settings.json, committed to the repo) set Prettier as the default formatter with format-on-save and ESLint auto-fix-on-save enabled. .vscode/extensions.json recommends the Prettier, ESLint, and EditorConfig extensions so VSCode prompts new contributors to install them.
• .gitattributes normalizes line endings to LF across operating systems.
• Husky + lint-staged: on every commit, .husky/pre-commit runs lint-staged first, which formats and auto-fixes only the files staged in that commit (Prettier for TS/TSX/SCSS/JSON/MD, ESLint --fix for TS/TSX). It then runs the full pnpm lint and pnpm typecheck as a final check across the whole project. .husky/pre-push runs pnpm test:storybook.

Run pnpm format any time to format the whole project, or pnpm format:check to verify formatting without writing changes.

Project structure

c2b.config.json              # Design token definitions (source of truth)
src/
  styles/
    main.scss                # Consumer-facing stylesheet entry
    auto/                    # Generated by c2b (do not edit)
      tokens.css             # CSS custom properties
      base-styles.scss       # Element styles + layout classes
    base/
      _globals.scss          # Hand-authored global styles
      _mixins.scss           # SCSS mixins
  components/                # React components (each with co-located SCSS)
  layouts/                   # Full-page layout stories
  docs/                      # Storybook documentation pages
    stylebook/               # Live token demos (colors, type, spacing, effects)
dist/
  cutheme/                   # WordPress theme.json + integrate.php (generated)

Package Usage

Next.js / modern frameworks

// Import the full stylesheet once (tokens + globals + components)
import '@cuweb/raven-design-system/styles';

// Import components
import { Button } from '@cuweb/raven-design-system';

WordPress block themes

Enqueue dist/style.css from the theme. Token integration for the block editor is handled via dist/cutheme/theme.json and integrate.php, generated by @troychaplin/component2block.

WordPress custom block plugins

Import per-component CSS in a block's stylesheets:

// block-name/src/editor.scss
@import '@cuweb/raven-design-system/components/Button/style.css';

Design tokens

All CSS variables use the --rds-- prefix (double dash). Token categories:

• Colors — primary (with dark variant), secondary, semantic (success, warning, error, info), neutrals (black through white)
• Typography — font family (Inter), fluid font sizes (body + heading scales), font weights, line heights
• Spacing — viewport-scaled gap and padding values
• Effects — shadows, border radii, gradients
• Layout — content size (1024px), wide size (1280px)

Accessibility

Every Storybook story is tested against axe with test: 'error' — stories that fail accessibility checks will not pass CI.

Documentation

Docs are organized by audience under docs/:

• docs/consumers/ — installing and using RDS in Next.js, WordPress, and other contexts
• docs/contributing/ — local setup, architecture, conventions, testing
• docs/maintenance/ — releasing, branch protection, automation prompts

For contributors, CONTRIBUTING.md is the entry point.

For a live, browsable reference, visit the Storybook deployment.

Links

• Storybook (GitHub Pages)
• Source
• Changelog