Building the Yale Digital Experience Together

The YaleSites platform is built on a collaborative open-source model that empowers the entire Yale community. As a developer, you have the opportunity to contribute features that not only benefit your specific department or project but enhance the digital experience for everyone at Yale.

yalesites github

Our Technical Architecture

YaleSites is built on three primary repositories working together:

1. Yale Design System

Our design system is the foundation of visual consistency across Yale’s web presence, built with:

  • HTML, CSS, and JavaScript
  • Storybook component library
  • Reusable UI components ensuring consistent branding and accessibility

2. Atomic Theme

The Atomic theme serves as the critical bridge between our design system and the CMS:

  • Takes Drupal data and formats it for our Drupal-agnostic design system
  • Provides easy-to-follow variables and settings for implementation
  • Applies Drupal-specific theming for edge cases where design system solutions aren’t applicable

3. Drupal CMS Environment

The content management system integrates our design system with:

  • Custom-built content structures specific to Yale’s needs
  • Flexible block-based content creation tools
  • User-friendly administrative interface

Getting Started as a Developer

All YaleSites code repositories are publicly available on GitHub. Access to contributor permissions requires approval from the YaleSites team.

Request Access to our Github

Development Guidelines

Leveraging Existing Patterns

The YaleSites platform uses established design patterns for consistency across all components:

  • Follow naming conventions for block options (e.g., “Tall” and “Short” size options)
  • Create intuitive field labels with helpful descriptions
  • Ensure settings are universally understandable

Building Blocks vs. Layouts

Before creating a specialized block, consider whether a layout solution might better serve the need:

  • Use section layouts (50/50, 70/30, 33/33/33) for flexible content arrangements
  • Combine existing blocks within layouts for complex presentations
  • Reserve new blocks for truly unique content needs

Collaboration Process

  1. Set up your local environment following the GitHub repository README
  2. Create a feature branch for your development work
  3. Build and test your feature in your local environment
  4. Push to development for additional testing
  5. Create a pull request and assign YaleSites team members for review in each relevant area:
    • Accessibility specialist
    • UX designer
    • Development lead
    • Product manager
  6. Address feedback from the YaleSites review team

User-Focused Development

Remember that our platform serves a diverse community with varying technical expertise. As you develop, keep these user archetypes in mind:

  • Uninformed Users: Limited technical knowledge, focused on content updates
  • Intermediate Users: Familiar with basics but seeking more creative flexibility
  • Expert Users: High technical knowledge, building complex solutions

Design your features to accommodate all skill levels, with appropriate guardrails and intuitive interfaces.