Architecture Overview

The Composable Pyramid

The UMD Design System is organized into three tiers. Each tier builds on the one below, and you can enter at whichever level matches your needs.

Application Layer

Ready-to-use UI elements, dynamic content, and full web components.

Elements @universityofmaryland/web-elements-library Foundational UI element builders: Atomic, Composite, and Layout.

Feeds @universityofmaryland/web-feeds-library Dynamic content feeds: academic, experts, news, events, inTheNews.

Components @universityofmaryland/web-components-library Full web components with Shadow DOM: structural, content, interactive, feed groups.

Infrastructure Layer

CSS utilities, web component model, and element construction.

Styles @universityofmaryland/web-styles-library Static CSS files, Tailwind integration, and token stylesheets.

Model @universityofmaryland/web-model-library Web component model: Attributes, Register, Slots, Lifecycle.

Builder @universityofmaryland/web-builder-library ElementBuilder fluent API for constructing elements with lifecycle management.

Foundation Layer

Raw design values, SVG assets, and helper functions. No UI opinions.

Tokens @universityofmaryland/web-token-library Design primitives: color, spacing, media queries, font definitions.

Icons @universityofmaryland/web-icons-library SVG icon and logo assets across 13 categories.

Utilities @universityofmaryland/web-utilities-library Shared helper functions across 15 categories: DOM, events, animation, and more.

Package Dependency Table

Package	npm Name	Depends On	Used By	Tier
Tokens	`@universityofmaryland/web-token-library`	none	Utilities, Styles, Elements	Foundation
Icons	`@universityofmaryland/web-icons-library`	none	Elements	Foundation
Utilities	`@universityofmaryland/web-utilities-library`	Tokens, Styles	Elements, Feeds	Foundation
Styles	`@universityofmaryland/web-styles-library`	Tokens	Utilities, Model, Builder, Elements	Infrastructure
Model	`@universityofmaryland/web-model-library`	Styles (peer)	Components	Infrastructure
Builder	`@universityofmaryland/web-builder-library`	Utilities, Styles (peer)	Elements	Infrastructure
Elements	`@universityofmaryland/web-elements-library`	Tokens, Builder, Utilities, Styles (peer), Icons (peer)	Feeds, Components	Application
Feeds	`@universityofmaryland/web-feeds-library`	Tokens, Elements, Utilities	Components	Application
Components	`@universityofmaryland/web-components-library`	All packages above	(top level)	Application

The ElementModel Pattern

Every element creation function in the design system returns an ElementModel -- a DOM node paired with its scoped CSS. This consistent contract is used by Elements, Feeds, and Builder throughout the system.

Interface

interface ElementModel {
  element: HTMLElement | DocumentFragment;
  styles: string;
  update?: (props: Record<string, unknown>) => void;
  destroy?: () => void;
}

element -- The constructed DOM node or fragment, ready for insertion.
styles -- A CSS string scoped to this element. Injected into Shadow DOM or a style tag.
update -- Optional callback to reactively update the element with new props.
destroy -- Optional cleanup callback for removing event listeners and references.

Two-Step Usage Pattern

Creating and mounting an element follows a consistent two-step pattern:

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

// Step 1: Create the element model
const model = textLockup.headline({
  headline: 'Welcome to UMD',
  text: 'The flagship university of the state of Maryland.',
  isThemeDark: false,
});

// Step 2: Mount the element and inject styles
const container = document.getElementById('app');
container.appendChild(model.element);

const styleTag = document.createElement('style');
styleTag.textContent = model.styles;
document.head.appendChild(styleTag);

// Later: update reactively
model.update?.({ headline: 'Updated Headline' });

// Cleanup when done
model.destroy?.();

In Web Components (Shadow DOM), the styles string is injected into the shadow root automatically. For standalone usage, append a style tag to the document head or a container element.

Choosing Your Entry Point

Use the decision tree below to find the right starting package for your use case.

I want to...	Start with	Guide
Drop in HTML components with no JavaScript	Components CDN	CDN Quick Start
Use web components in a build-tool project	Components npm	npm Installation
Add CSS utilities without web components	Styles Static CSS	Static CSS Guide
Integrate with Tailwind CSS	Styles + Tailwind	Tailwind Integration
Build UI elements programmatically	Elements	Elements Use Cases
Render dynamic news/events feeds	Feeds	Feeds Use Cases
Build custom web components	Model + Builder	Model & Builder Guide
Access raw design values (colors, spacing, fonts)	Tokens	Tokens Use Cases

Not a developer?

Visit designsystem.umd.edu for visual examples and design guidance.