University of Maryland Web Elements Library

Foundational UI building blocks for the UMD Design System, providing atomic elements that combine to create complex, accessible, and brand-compliant University of Maryland digital experiences.

Overview

The UMD Web Elements Library provides the essential building blocks used to construct the UMD Web Components Library. Think of elements as atoms in a design system - they are the smallest, indivisible units that maintain meaning and functionality. These elements handle core UI patterns like buttons, images, text layouts, and containers while remaining unopinionated about their final appearance, relying on the Styles Library for visual presentation.

Installation

# Using npm
npm install @universityofmaryland/web-elements-library

# Using yarn
yarn add @universityofmaryland/web-elements-library

Peer Dependencies

Elements are styled by the Styles package:

npm install @universityofmaryland/web-styles-library

Quick Start

import { Composite, Atomic } from '@universityofmaryland/web-elements-library';

// Create a card element
const card = Composite.card.block({
  headline: document.createElement('h3'),
  text: document.createElement('p'),
  image: document.querySelector('img'),
  isThemeDark: true,
});

// Add to DOM
document.querySelector('.container').appendChild(card.element);

// Apply associated styles
const style = document.createElement('style');
style.textContent = card.styles;
document.head.appendChild(style);

Architecture

Element Categories

Atomic Elements

The most basic building blocks:

• actions - Buttons and interactive elements
• animations - Animation patterns and effects
• assets - Images, videos, and media handling
• buttons - Specialized button components
• events - Event-related display elements
• layout - Basic layout structures
• textLockup - Text grouping patterns

Composite Elements

Combinations of atomic elements forming UI patterns:

• accordion - Expandable content sections
• alert - Notification and alert displays
• banner - Banner and promotional elements
• card - Content cards (block, list, overlay)
• carousel - Image and content sliders
• footer - Footer compositions
• hero - Hero sections (see detailed documentation below)
• layout - Complex layout patterns
• media - Media display compositions
• navigation - Navigation structures
• pathway - User journey elements
• person - Profile and bio displays
• quote - Quote and testimonial blocks
• slider - Content slider variations
• social - Social media integrations
• stat - Statistics displays
• tabs - Tabbed interfaces

Element Return Structure

All elements return a consistent interface:

interface ElementModel {
  element: HTMLElement | DocumentFragment;
  styles: string;
  events?: {
    load?: () => void;
    resize?: () => void;
    destroy?: () => void;
  };
}

Integration with Other Packages

Styles Package Dependency

Elements rely entirely on the Styles package for visual presentation:

import { Composite } from '@universityofmaryland/web-elements-library';
// Styles are automatically included in the element.styles property

Components Package Relationship

Components are built using Elements:

• Elements provide structure and behavior
• Components add web component wrapper and lifecycle
• Elements can be used standalone for custom implementations

Usage in Feeds Package

Feed layouts use Elements for content display:

// Feeds internally use card and grid elements
import { card } from '@universityofmaryland/web-elements-library/Composite';

Common Element Patterns

Actions Elements

import { Atomic } from '@universityofmaryland/web-elements-library';

// Text-based action
const textAction = Atomic.actions.text({
  text: 'Learn More',
  url: '/learn-more',
  isStyled: true,
});

// Icon action
const iconAction = Atomic.actions.icon({
  icon: 'arrow-right',
  url: '#',
  ariaLabel: 'Next page',
});

Card Elements

import { Composite } from '@universityofmaryland/web-elements-library';

// Block card
const blockCard = Composite.card.block({
  headline: document.querySelector('h3'),
  text: document.querySelector('p'),
  image: document.querySelector('img'),
  actions: document.querySelector('.actions'),
  isThemeDark: false,
});

// Overlay card
const overlayCard = Composite.card.overlay({
  headline: headlineElement,
  text: textElement,
  image: imageElement,
  isTypeColor: true,
  isThemeDark: true,
});

Hero Elements

The hero category offers multiple variations for impactful layouts:

Standard Hero

const hero = Composite.hero.standard({
  headline: document.createElement('h1'),
  eyebrow: document.createElement('span'),
  text: document.createElement('p'),
  actions: document.createElement('div'),
  image: imageElement,
  includesAnimation: true,
  isThemeDark: true,
});

Minimal Hero

const minimalHero = Composite.hero.minimal({
  headline: document.createElement('h1'),
  text: document.createElement('p'),
  eyebrow: document.createElement('span'),
});

Overlay Hero

const overlayHero = Composite.hero.overlay({
  headline: headlineElement,
  text: textElement,
  image: imageElement,
  hasBorder: true,
  isTransparent: false,
  isSticky: true,
  isTextCenter: true,
});

Custom Variations

Grid Hero - Content blocks in grid layout:

const gridHero = Composite.hero.custom.grid({
  headline: headlineElement,
  blocks: [block1, block2, block3, block4],
  image: backgroundImage,
  isThemeDark: true,
});

Expand Hero - With expandable content:

const expandHero = Composite.hero.custom.expand({
  headline: headlineElement,
  text: textElement,
  expandedContent: hiddenContent,
  includesAnimation: true,
});

Layout Elements

import { Composite } from '@universityofmaryland/web-elements-library';

// Sticky columns
const stickyLayout = Composite.layout.stickyColumns({
  leftColumn: sidebarContent,
  rightColumn: mainContent,
  stickyOffset: 100,
});

// Image expand layout
const imageExpand = Composite.layout.image.expand({
  image: imageElement,
  caption: 'Image caption',
  isExpanded: false,
});

TypeScript Support

Full TypeScript definitions for type safety:

import type {
  ElementModel,
  HeroStandardProps,
  CardBlockProps,
  ThemeProps,
} from '@universityofmaryland/web-elements-library';

const heroProps: HeroStandardProps = {
  headline: document.createElement('h1'),
  isThemeDark: true,
  includesAnimation: false,
};

Browser Support

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

Performance Considerations

• Lightweight - Minimal JavaScript, no framework dependencies
• Tree-shakeable - Import only needed elements
• Efficient - Reusable element instances
• Lazy-loadable - Load elements on demand

Accessibility

All elements follow WCAG 2.1 AA standards:

• Semantic HTML structure
• ARIA attributes where needed
• Keyboard navigation support
• Screen reader compatibility
• Focus management utilities

Documentation

• Element Reference - Complete API documentation
• Design System - Full design system docs

Testing

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

# Test specific category
npm test -- composite/hero

Contributing

See the main repository for contribution guidelines.

License

University of Maryland