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 run start         # Storybook at http://localhost:6006

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

Scripts

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