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
Copy

Peer Dependencies

Elements are styled by the Styles package:

npm install @universityofmaryland/web-styles-library
Copy

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);
Copy

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;
  };
}
Copy

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
Copy

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';
Copy

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',
});
Copy

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,
});
Copy

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,
});
Copy

Minimal Hero

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

Overlay Hero

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

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,
});
Copy

Expand Hero - With expandable content:

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

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,
});
Copy

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,
};
Copy

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
Copy

Contributing

See the main repository for contribution guidelines.

License

University of Maryland