GivingTuesday Data Commons Style Framework

A comprehensive SCSS framework implementing the official GivingTuesday Data Commons 2025 Brand Guidelines. Built for seamless integration across WordPress, Reveal.js, Leaflet maps, React applications, Tailwind CSS, and static SPAs.

Features

Brand-compliant design tokens - Colors, typography, spacing following official guidelines
Tailwind CSS v4 support - CSS-first theme integration
Platform-specific modules - Optimized styles for different use cases
CSS Custom Properties - Runtime theming without recompilation
JavaScript token exports - ES modules, CommonJS, and JSON for React/design tools
Validation utilities - Enforce brand rules programmatically
Responsive mixins - Mobile-first breakpoint system
Accessibility-first - WCAG 2.1 AA compliant contrast ratios

Quick Start

Installation

From GitHub (recommended):

npm install github:givingtuesday/gt-styles

# Or with a specific branch/tag
npm install github:givingtuesday/gt-styles#main

Clone and build locally:

git clone https://github.com/givingtuesday/gt-styles.git
cd gt-styles
npm install
npm run build

Basic Usage

SCSS Import

// Import everything
@use 'gt-styles/scss/core';

// Or import specific modules
@use 'gt-styles/scss/core/variables' as *;
@use 'gt-styles/scss/core/mixins' as *;

CSS Link

<!-- Full SPA stylesheet -->
<link rel="stylesheet" href="gt-styles/dist/css/modules/spa/gt-spa.css">

<!-- Or specific modules -->
<link rel="stylesheet" href="gt-styles/dist/css/modules/wordpress/gt-wordpress.css">

JavaScript Tokens

// ES Module
import { colors, typography, getColor } from 'gt-styles/dist/tokens/tokens.js';

// CommonJS
const { colors, spacing } = require('gt-styles/dist/tokens/tokens.cjs');

// Use in CSS-in-JS
const styles = {
  color: colors.navy,
  fontFamily: typography.fontFamilies.primary,
};

Tailwind CSS v4

The framework includes native Tailwind CSS v4 support with CSS-first configuration.

Setup

Install the package:

npm install github:givingtuesday/gt-styles
npm install tailwindcss@^4.0.0

Import in your CSS:

@import "tailwindcss";
@import "gt-styles/tailwind";

Load fonts in your HTML:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Montserrat:wght@300;400;500;600;700&display=swap" rel="stylesheet">

Available Classes

Colors:

<!-- Background -->
<div class="bg-red">Red background</div>
<div class="bg-navy">Navy background</div>
<div class="bg-lavender">Lavender background</div>
<div class="bg-beige">Beige background</div>
<div class="bg-teal">Teal background</div>

<!-- Text -->
<p class="text-navy">Navy text</p>
<p class="text-copy">Body copy color</p>
<p class="text-red">Red accent text</p>

Typography:

<h1 class="font-primary text-3xl font-semibold">Montserrat Heading</h1>
<p class="font-secondary text-base leading-body">Georgia body text</p>
<code class="font-mono">Monospace code</code>

Components:

<!-- Buttons -->
<button class="btn btn-primary">Primary Button</button>
<button class="btn btn-secondary">Secondary Button</button>
<button class="btn btn-outline">Outline Button</button>
<button class="btn btn-teal">Teal Button</button>

<!-- Cards -->
<div class="card">
  <div class="card-body">
    <h3 class="heading-3">Card Title</h3>
    <p class="body-text">Card content</p>
  </div>
</div>

<!-- Typography Presets -->
<h1 class="heading-1">Display Heading</h1>
<h2 class="heading-2">Section Heading</h2>
<p class="body-text">Body paragraph with Georgia font</p>
<span class="overline">Overline Label</span>
<span class="label-text">Form Label</span>

<!-- Badges -->
<span class="badge badge-primary">New</span>
<span class="badge badge-teal">Featured</span>

<!-- Alerts -->
<div class="alert alert-info">Info message</div>
<div class="alert alert-success">Success message</div>
<div class="alert alert-warning">Warning message</div>

<!-- Forms -->
<label class="label">Email Address</label>
<input type="email" class="input" placeholder="you@example.com">

Utilities:

<!-- Photo radius (50px max per brand guidelines) -->
<img src="..." class="rounded-photo">

<!-- Gradient backgrounds -->
<div class="bg-gradient-lavender-navy">Gradient section</div>
<div class="bg-gradient-lightblue-beige">Another gradient</div>

<!-- Sections with consistent padding -->
<section class="section">Standard section (80px padding)</section>
<section class="section-lg">Large section (128px padding)</section>

<!-- GT Container -->
<div class="container-gt">Responsive centered container</div>

<!-- Links -->
<a href="#" class="link">Teal link with hover</a>

Spacing (8px base unit):

<!-- Padding: p-1 = 8px, p-2 = 16px, p-3 = 24px, p-4 = 32px, etc. -->
<div class="p-4">32px padding</div>
<div class="px-6 py-3">48px horizontal, 24px vertical</div>
<div class="mt-10">80px top margin</div>

Selective Imports

Import only what you need:

/* Theme only (colors, typography, spacing variables) */
@import "tailwindcss";
@import "gt-styles/tailwind/theme";

/* Add utilities separately */
@import "gt-styles/tailwind/utilities";

Color Palette

Primary Colors

Name	Hex	CSS Variable	Usage
Red	`#ED132E`	`--gt-red`	Primary brand, CTAs, logos
Navy	`#001548`	`--gt-navy`	Headlines, text on light
Black	`#000000`	`--gt-black`	Body text alternative

Secondary Colors

Name	Hex	CSS Variable	Usage
Lavender	`#CAC7F8`	`--gt-lavender`	Backgrounds, graphics
Light Blue	`#6CF4FF`	`--gt-light-blue`	Backgrounds, accents
Beige	`#FDF7F7`	`--gt-beige`	Light backgrounds

Digital Colors

Name	Hex	CSS Variable	Usage
Teal	`#0fb5c3`	`--gt-teal`	Links, interactive elements
Teal Hover	`#10c8d8`	`--gt-teal-hover`	Hover states
Copy	`#1b1a19`	`--gt-copy`	Body text

Typography

Font Families

Primary: Montserrat (headlines, labels, UI)
Secondary: Georgia (body copy)

// Use via mixins
@include h1;  // Montserrat SemiBold, 72px, line-height 1.1
@include h2;  // Montserrat SemiBold, 48px
@include body-text;  // Georgia, 16px, line-height 1.4
@include label-text;  // Montserrat uppercase, tracking wide

Type Scale

Style	Font	Size	Weight	Line Height
H1	Montserrat	72px	600	1.1
H2	Montserrat	48px	600	1.1
H3	Montserrat	32px	400	1.2
H4	Montserrat	24px	500	1.2
Body	Georgia	16px	400	1.4
Label	Montserrat	18px	400	1.3

Spacing

All spacing uses an 8px base unit:

$spacer-1: 8px;
$spacer-2: 16px;
$spacer-3: 24px;
$spacer-4: 32px;
// ... up to $spacer-20: 160px

// Use via function
padding: spacer(4);  // 32px
margin: gt-space(3); // 24px

Platform Modules

WordPress / Gutenberg

@use 'gt-styles/scss/modules/wordpress/gt-wordpress';

Includes:

Gutenberg block styles
Alignment utilities (alignwide, alignfull)
Color palette classes for block editor
Custom GT blocks (stats, CTA, cards)

Reveal.js Presentations

@use 'gt-styles/scss/modules/reveal/gt-reveal';

Features:

Branded slide backgrounds
Section header variants
Two-column layouts
Statistics display
Code block styling

Leaflet Maps

@use 'gt-styles/scss/modules/leaflet/gt-leaflet';

Includes:

Popup and tooltip styling
Custom marker classes
Legend component
Choropleth palettes
Control overrides

React Components

@use 'gt-styles/scss/modules/react/gt-react';

Provides:

Button variants and states
Form elements
Cards, badges, alerts
Modal, tabs, accordion
Loading states (skeleton, spinner)

Static SPA

@use 'gt-styles/scss/modules/spa/gt-spa';

Complete stylesheet including:

CSS reset
Typography
Layout utilities
All components
Header/footer
Responsive utilities

Mixins Reference

Media Queries

@include media-up('md') { ... }    // min-width: 768px
@include media-down('lg') { ... }  // max-width: 991.98px
@include media-between('sm', 'lg') { ... }

Components

@include button-base;      // Base button styles
@include button-primary;   // Red background
@include button-secondary; // Navy background
@include button-outline;   // Bordered variant

@include card;             // Card with shadow
@include input;            // Form input styling
@include container('lg');  // Centered container

Layout

@include flex-center;      // Center both axes
@include flex-between;     // Space between
@include grid(3, $spacer-4); // 3-column grid

Brand Rules

Forbidden Color Combinations

Never combine Red (#ED132E) and Lavender (#CAC7F8)

import { isValidColorCombo } from 'gt-styles/dist/tokens/tokens.js';

isValidColorCombo('#ED132E', '#CAC7F8'); // false
isValidColorCombo('#ED132E', '#001548'); // true

Typography-Safe Colors

These colors should NOT be used for text:

Light Blue (#6CF4FF)
Lavender (#CAC7F8)
Beige (#FDF7F7) - except on dark backgrounds

import { isTypographySafe } from 'gt-styles/dist/tokens/tokens.js';

isTypographySafe('#6CF4FF'); // false
isTypographySafe('#001548'); // true

Photo Border Radius

Maximum border radius for photos: 50px

@include photo-radius; // border-radius: 50px

File Structure

gt-styles/
├── scss/
│   ├── core/
│   │   ├── _variables.scss      # Design tokens
│   │   ├── _custom-properties.scss # CSS variables
│   │   ├── _functions.scss      # Helper functions
│   │   ├── _mixins.scss         # Reusable patterns
│   │   ├── _typography.scss     # Font imports & styles
│   │   └── _index.scss          # Barrel export
│   ├── modules/
│   │   ├── reveal/              # Reveal.js theme
│   │   ├── leaflet/             # Leaflet map styles
│   │   ├── wordpress/           # WordPress/Gutenberg
│   │   ├── react/               # React components
│   │   └── spa/                 # Static SPA
│   └── gt-styles.scss           # Main entry
├── tailwind/
│   ├── index.css                # Main entry (import this)
│   ├── gt-theme.css             # @theme definitions
│   └── gt-utilities.css         # Component & utility classes
├── dist/
│   ├── css/                     # Compiled CSS
│   └── tokens/
│       ├── tokens.js            # ES module
│       ├── tokens.cjs           # CommonJS
│       └── tokens.json          # JSON for design tools
├── demos/
│   ├── brand-pdf-style.html     # PDF brand style demo
│   ├── website-style.html       # Website style demo
│   ├── reveal-demo.html         # Presentation demo
│   └── leaflet-demo.html        # Map demo
└── scripts/
    └── build-tokens.js          # Token generator

Build Commands

# Build everything
npm run build

# Build CSS only
npm run build:css

# Build tokens only
npm run build:tokens

# Watch for changes
npm run watch

Theming

Dark Mode

<html data-theme="dark">

CSS custom properties automatically adjust for dark backgrounds.

High Contrast

<html data-theme="high-contrast">

Enhances contrast for accessibility compliance.

Custom Theme

Override CSS custom properties:

:root {
  --color-primary: #custom-color;
  --color-background: #another-color;
}

Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

Contributing

Fork the repository
Create a feature branch
Make changes following existing conventions
Ensure all demos render correctly
Submit a pull request

License

MIT License - See LICENSE file for details.

Built with care for the GivingTuesday Data Commons by the GivingTuesday team.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
assets		assets
demos		demos
dist		dist
scripts		scripts
scss		scss
tailwind		tailwind
.gitignore		.gitignore
README.md		README.md
_quarto.yml		_quarto.yml
index.qmd		index.qmd
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

GivingTuesday Data Commons Style Framework

Features

Quick Start

Installation

Basic Usage

SCSS Import

CSS Link

JavaScript Tokens

Tailwind CSS v4

Setup

Available Classes

Selective Imports

Color Palette

Primary Colors

Secondary Colors

Digital Colors

Typography

Font Families

Type Scale

Spacing

Platform Modules

WordPress / Gutenberg

Reveal.js Presentations

Leaflet Maps

React Components

Static SPA

Mixins Reference

Media Queries

Components

Layout

Brand Rules

Forbidden Color Combinations

Typography-Safe Colors

Photo Border Radius

File Structure

Build Commands

Theming

Dark Mode

High Contrast

Custom Theme

Browser Support

Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages