Component Library and Macros

**Referenced Files in This Document** - [base.njk](file://src/_includes/layouts/base.njk) - [iaa-base.njk](file://src/_includes/layouts/iaa-base.njk) - [knowledge.njk](file://src/_includes/layouts/knowledge.njk) - [case-study-card.njk](file://src/_includes/macros/case-study-card.njk) - [client-marquee.njk](file://src/_includes/macros/client-marquee.njk) - [testimonial-card.njk](file://src/_includes/macros/testimonial-card.njk) - [service-capability-card.njk](file://src/_includes/macros/service-capability-card.njk) - [news-article-card.njk](file://src/_includes/macros/news-article-card.njk) - [team-flip-card.njk](file://src/_includes/macros/team-flip-card.njk) - [cta-section.njk](file://src/_includes/macros/cta-section.njk) - [10-logo-marquee.css](file://src/assets/css/modules/10-logo-marquee.css) - [11-testimonials-carousel.css](file://src/assets/css/modules/11-testimonials-carousel.css) - [carousel-system.js](file://src/assets/js/modules/carousel-system.js) - [theme-toggling.js](file://src/assets/js/modules/theme-toggling.js) - [site.json](file://src/_data/site.json)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document explains the component library and Nunjucks macro system used across the site. It focuses on reusable UI components implemented as Nunjucks macros for cards, carousels, forms, and layout templates. It also covers the layout system built around base templates, the relationship between macros and CSS modules, component state management via JavaScript, and integration with the content management system. Practical examples demonstrate parameter passing, conditional rendering, and composition patterns. Theming support and accessibility features are highlighted throughout.

Project Structure

The component library centers on two primary areas:

  • Layout templates under src/_includes/layouts/, including a base template and specialized variants for alliance and knowledge pages.
  • Nunjucks macros under src/_includes/macros/, implementing reusable UI blocks such as cards, carousels, and CTAs.
graph TB
subgraph "Layout Templates"
base["base.njk"]
iaa["iaa-base.njk"]
knowledge["knowledge.njk"]
end
subgraph "Macros"
cs_card["case-study-card.njk"]
client_marquee["client-marquee.njk"]
testimonial["testimonial-card.njk"]
svc_card["service-capability-card.njk"]
news_card["news-article-card.njk"]
team_card["team-flip-card.njk"]
cta["cta-section.njk"]
end
subgraph "CSS Modules"
marquee_css["10-logo-marquee.css"]
testimonials_css["11-testimonials-carousel.css"]
end
subgraph "JS Modules"
carousel_js["carousel-system.js"]
theme_js["theme-toggling.js"]
end
knowledge --> base
iaa --> base
cs_card --> marquee_css
client_marquee --> marquee_css
testimonial --> testimonials_css
svc_card --> testimonials_css
news_card --> testimonials_css
team_card --> testimonials_css
cta --> base
carousel_js --> testimonials_css
theme_js --> base

Diagram sources

  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [iaa-base.njk:1-99](file://src/_includes/layouts/iaa-base.njk#L1-L99)
  • [knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)
  • [case-study-card.njk:1-20](file://src/_includes/macros/case-study-card.njk#L1-L20)
  • [client-marquee.njk:1-27](file://src/_includes/macros/client-marquee.njk#L1-L27)
  • [testimonial-card.njk:1-18](file://src/_includes/macros/testimonial-card.njk#L1-L18)
  • [service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [team-flip-card.njk:1-18](file://src/_includes/macros/team-flip-card.njk#L1-L18)
  • [cta-section.njk:1-18](file://src/_includes/macros/cta-section.njk#L1-L18)
  • [10-logo-marquee.css:1-79](file://src/assets/css/modules/10-logo-marquee.css#L1-L79)
  • [11-testimonials-carousel.css:1-93](file://src/assets/css/modules/11-testimonials-carousel.css#L1-L93)
  • [carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)
  • [theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)

Section sources

  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [iaa-base.njk:1-99](file://src/_includes/layouts/iaa-base.njk#L1-L99)
  • [knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)

Core Components

This section introduces the key macros and their roles in building pages.

  • Case Study Card macro

    • Purpose: Render a portfolio case study with optional quote and author attribution.
    • Parameters: Accepts a single item object containing image, category, client, title, content, and optional quote fields.
    • Conditional rendering: Quote block renders only when a quote is present.
    • Accessibility: Uses semantic headings and blockquote with cite.

  • Client Marquee macro

    • Purpose: Render a horizontally scrolling logo marquee with optional grayscale toggle and configurable speed.
    • Parameters: Items array of logo objects, base path for images, animation speed, and grayscale flag.
    • Behavior: Duplicates items to enable seamless looping; applies grayscale by default unless disabled.

  • Testimonial Card macro

    • Purpose: Render a testimonial either as a compact case quote or a full testimonial card.
    • Parameters: Quote text, author, role, and an isCaseStudy flag.
    • Conditional rendering: Switches markup based on the flag to match different presentation contexts.

  • Service Capability Card macro

    • Purpose: Present a service with image, headline, body, and a learn-more link with accessible label.
    • Parameters: Service object with image, alt text, title, body, url, and optional card class.

  • Additional macros (for composition patterns):

    • News Article Card: Renders a carousel-friendly text card or a full article card with expandable content and optional PDF link.
    • Team Flip Card: A flip card with front/back sides for profile teaser and short bio.
    • CTA Section: A themed call-to-action section with optional highlight text and customizable button.

Section sources

  • [case-study-card.njk:1-20](file://src/_includes/macros/case-study-card.njk#L1-L20)
  • [client-marquee.njk:1-27](file://src/_includes/macros/client-marquee.njk#L1-L27)
  • [testimonial-card.njk:1-18](file://src/_includes/macros/testimonial-card.njk#L1-L18)
  • [service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [team-flip-card.njk:1-18](file://src/_includes/macros/team-flip-card.njk#L1-L18)
  • [cta-section.njk:1-18](file://src/_includes/macros/cta-section.njk#L1-L18)

Architecture Overview

The system combines Nunjucks templates and macros with CSS modules and JavaScript modules to deliver a cohesive, accessible, and theme-aware UI.

sequenceDiagram
participant CMS as "Content Source"
participant Eleventy as "11ty Build"
participant Layout as "base.njk / iaa-base.njk"
participant Macro as "Nunjucks Macro"
participant CSS as "CSS Module"
participant JS as "JS Module"
CMS->>Eleventy : "Provide data and content"
Eleventy->>Layout : "Render with layout context"
Layout->>Macro : "Invoke macro with parameters"
Macro-->>Layout : "HTML output"
Layout-->>Eleventy : "Final HTML"
Eleventy-->>CSS : "Bundle styles"
Eleventy-->>JS : "Bundle scripts"
JS-->>Layout : "Enhance interactivity"

Diagram sources

  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [iaa-base.njk:1-99](file://src/_includes/layouts/iaa-base.njk#L1-L99)
  • [case-study-card.njk:1-20](file://src/_includes/macros/case-study-card.njk#L1-L20)
  • [client-marquee.njk:1-27](file://src/_includes/macros/client-marquee.njk#L1-L27)
  • [testimonial-card.njk:1-18](file://src/_includes/macros/testimonial-card.njk#L1-L18)
  • [service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)
  • [10-logo-marquee.css:1-79](file://src/assets/css/modules/10-logo-marquee.css#L1-L79)
  • [11-testimonials-carousel.css:1-93](file://src/assets/css/modules/11-testimonials-carousel.css#L1-L93)
  • [carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)
  • [theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)

Detailed Component Analysis

Case Study Card Macro

  • Parameters: item object with image, alt text, category, client, title, content, and optional quote and quote author.
  • Conditional rendering: Quote box appears only when a quote exists.
  • Composition: Integrates with CSS modules for consistent spacing and typography.
flowchart TD
Start(["Render Case Study"]) --> HasQuote{"Has quote?"}
HasQuote --> |Yes| QuoteBox["Render quote block with cite"]
HasQuote --> |No| SkipQuote["Skip quote block"]
QuoteBox --> End(["Finish"])
SkipQuote --> End

Diagram sources

  • [case-study-card.njk:1-20](file://src/_includes/macros/case-study-card.njk#L1-L20)

Section sources

  • [case-study-card.njk:1-20](file://src/_includes/macros/case-study-card.njk#L1-L20)

Client Marquee Macro

  • Parameters: items array, base path, speed, grayscale flag.
  • Behavior: Builds a horizontal track with duplicated items for seamless looping; toggles grayscale via a class.
  • Styling: Implemented by 10-logo-marquee.css with hover effects and animation overrides.
flowchart TD
Start(["Render Marquee"]) --> ValidateItems{"Items provided?"}
ValidateItems --> |No| End(["Exit"])
ValidateItems --> |Yes| BuildPath["Normalize base path"]
BuildPath --> Loop1["First pass: append items"]
Loop1 --> Loop2["Second pass: append items again"]
Loop2 --> ApplyGrayscale{"Grayscale enabled?"}
ApplyGrayscale --> |Yes| AddClass["Add grayscale class"]
ApplyGrayscale --> |No| NoClass["No grayscale class"]
AddClass --> End
NoClass --> End

Diagram sources

  • [client-marquee.njk:1-27](file://src/_includes/macros/client-marquee.njk#L1-L27)
  • [10-logo-marquee.css:1-79](file://src/assets/css/modules/10-logo-marquee.css#L1-L79)

Section sources

  • [client-marquee.njk:1-27](file://src/_includes/macros/client-marquee.njk#L1-L27)
  • [10-logo-marquee.css:1-79](file://src/assets/css/modules/10-logo-marquee.css#L1-L79)

Testimonial Card Macro

  • Parameters: quote, author, role, isCaseStudy flag.
  • Conditional rendering: Switches between a compact case quote and a full testimonial card.
flowchart TD
Start(["Render Testimonial"]) --> IsCase{"isCaseStudy?"}
IsCase --> |Yes| CaseQuote["Render case quote with cite"]
IsCase --> |No| FullCard["Render full testimonial card"]
CaseQuote --> End(["Finish"])
FullCard --> End

Diagram sources

  • [testimonial-card.njk:1-18](file://src/_includes/macros/testimonial-card.njk#L1-L18)

Section sources

  • [testimonial-card.njk:1-18](file://src/_includes/macros/testimonial-card.njk#L1-L18)

Service Capability Card Macro

  • Parameters: service object with image, alt text, title, body, url, and optional card class.
  • Accessibility: Learn-more link includes an accessible label derived from the title.
flowchart TD
Start(["Render Service Card"]) --> GetClass["Resolve card class (default wide)"]
GetClass --> Image["Render image with alt"]
Image --> Content["Render title and body"]
Content --> Link["Render learn-more link with aria-label"]
Link --> End(["Finish"])

Diagram sources

  • [service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)

Section sources

  • [service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)

Layout System

  • base.njk: Main layout providing global head metadata, navigation, search modal, main content area, footer, and theme toggle. It includes SEO metadata, structured data, and links to fonts and styles.
  • iaa-base.njk: Specialized layout for alliance pages with distinct branding and navigation.
  • knowledge.njk: Extends base.njk to render knowledge articles with breadcrumbs, metadata, tags, and a back link.
graph LR
base["base.njk"] --> knowledge["knowledge.njk"]
base --> iaa["iaa-base.njk"]
knowledge --> content["Article content"]
iaa --> iaa_content["IAA-specific content"]

Diagram sources

  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [iaa-base.njk:1-99](file://src/_includes/layouts/iaa-base.njk#L1-L99)
  • [knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)

Section sources

  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [iaa-base.njk:1-99](file://src/_includes/layouts/iaa-base.njk#L1-L99)
  • [knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)

Carousels and Interactions

  • CSS modules define carousel tracks and cards for testimonials and related content.
  • JavaScript module initializes carousels, handles pagination dots, keyboard navigation, and drag-to-scroll gestures.
  • The system supports snapping, responsive item counts, and accessibility attributes.
sequenceDiagram
participant DOM as "Carousel Container"
participant JS as "carousel-system.js"
participant CSS as "11-testimonials-carousel.css"
DOM->>JS : "Initialize carousels"
JS->>DOM : "Measure items and compute snap points"
JS->>DOM : "Render pagination dots"
JS->>DOM : "Attach scroll and resize handlers"
JS->>DOM : "Enable keyboard navigation"
JS->>DOM : "Enable drag-to-scroll"
DOM-->>CSS : "Apply card and track styles"

Diagram sources

  • [11-testimonials-carousel.css:1-93](file://src/assets/css/modules/11-testimonials-carousel.css#L1-L93)
  • [carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)

Section sources

  • [11-testimonials-carousel.css:1-93](file://src/assets/css/modules/11-testimonials-carousel.css#L1-L93)
  • [carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)

Theming Support and Accessibility

  • Theming: The base layout includes a theme toggle switch and a theme-aware script that toggles body classes based on visible sections. CSS modules adapt visuals for light/dark modes.
  • Accessibility: Layouts and macros consistently use semantic HTML, ARIA attributes (e.g., aria-labels, aria-expanded), and keyboard navigation where applicable.
flowchart TD
Start(["Page Load"]) --> ThemeToggle["Theme Toggle UI"]
ThemeToggle --> BodyClasses["Toggle body classes (light/dark)"]
BodyClasses --> CSSAdapt["CSS adapts via variables and selectors"]
CSSAdapt --> End(["Consistent theming across components"])

Diagram sources

  • [base.njk:63-260](file://src/_includes/layouts/base.njk#L63-L260)
  • [theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)

Section sources

  • [base.njk:63-260](file://src/_includes/layouts/base.njk#L63-L260)
  • [theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)

Dependency Analysis

The following diagram maps macro-to-CSS and macro-to-JS dependencies for key components.

graph TB
cs["case-study-card.njk"] --> marq["10-logo-marquee.css"]
tm["testimonial-card.njk"] --> test_css["11-testimonials-carousel.css"]
svc["service-capability-card.njk"] --> test_css
news["news-article-card.njk"] --> test_css
team["team-flip-card.njk"] --> test_css
cta["cta-section.njk"] --> base["base.njk"]
carousel_js["carousel-system.js"] --> test_css
theme_js["theme-toggling.js"] --> base

Diagram sources

  • [case-study-card.njk:1-20](file://src/_includes/macros/case-study-card.njk#L1-L20)
  • [client-marquee.njk:1-27](file://src/_includes/macros/client-marquee.njk#L1-L27)
  • [testimonial-card.njk:1-18](file://src/_includes/macros/testimonial-card.njk#L1-L18)
  • [service-capability-card.njk:1-11](file://src/_includes/macros/service-capability-card.njk#L1-L11)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [team-flip-card.njk:1-18](file://src/_includes/macros/team-flip-card.njk#L1-L18)
  • [cta-section.njk:1-18](file://src/_includes/macros/cta-section.njk#L1-L18)
  • [10-logo-marquee.css:1-79](file://src/assets/css/modules/10-logo-marquee.css#L1-L79)
  • [11-testimonials-carousel.css:1-93](file://src/assets/css/modules/11-testimonials-carousel.css#L1-L93)
  • [carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)
  • [theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)
  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)

Section sources

  • [10-logo-marquee.css:1-79](file://src/assets/css/modules/10-logo-marquee.css#L1-L79)
  • [11-testimonials-carousel.css:1-93](file://src/assets/css/modules/11-testimonials-carousel.css#L1-L93)
  • [carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)
  • [theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)
  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)

Performance Considerations

  • Lazy loading: Images in macros and layouts use lazy loading to improve Core Web Vitals.
  • CSS-in-Modules: Scoped styles reduce cascade overhead and enable efficient bundling.
  • JavaScript initialization: Carousel initialization runs after DOM readiness and reinitializes on resize to avoid layout thrashing.
  • Conditional rendering: Macros avoid rendering unused elements (e.g., quote box) to minimize DOM size.

Troubleshooting Guide

  • Marquee not animating:

    • Verify items array is provided and non-empty.
    • Confirm base path ends with a slash if customizing.
    • Ensure CSS module is loaded and animation duration matches macro speed parameter.

  • Testimonial or news cards not snapping:

    • Check that container IDs and class names match the carousel initializer.
    • Confirm CSS track and item widths are defined and consistent.

  • Theme toggle not switching:

    • Ensure the theme toggle element exists and the theme-toggling script is executed.
    • Verify body classes are toggling and CSS respects the applied classes.

  • Accessibility warnings:

    • Confirm all interactive elements have appropriate aria-labels and roles.
    • Ensure focus order remains logical and keyboard navigation works.

Section sources

  • [client-marquee.njk:1-27](file://src/_includes/macros/client-marquee.njk#L1-L27)
  • [10-logo-marquee.css:1-79](file://src/assets/css/modules/10-logo-marquee.css#L1-L79)
  • [carousel-system.js:1-169](file://src/assets/js/modules/carousel-system.js#L1-L169)
  • [theme-toggling.js:1-24](file://src/assets/js/modules/theme-toggling.js#L1-L24)
  • [base.njk:63-260](file://src/_includes/layouts/base.njk#L63-L260)

Conclusion

The component library leverages Nunjucks macros for modular, reusable UI pieces, coordinated with CSS modules and JavaScript enhancements. The layout system provides consistent structure across pages, while theming and accessibility features ensure a high-quality user experience. By following the composition patterns and customization options outlined here, teams can efficiently build and maintain consistent, accessible interfaces.

Appendices

Practical Usage Patterns

  • Parameter passing:
    • Pass structured data objects to macros (e.g., service, item) to keep templates declarative.
    • Use default values for optional parameters (e.g., macro defaults for variant or theme).
  • Conditional rendering:
    • Use macro conditionals to show/hide sections (e.g., quote block, PDF link).
  • Component composition:
    • Combine multiple macros within a layout (e.g., marquee + cards).
    • Extend base layouts to create specialized pages (e.g., knowledge.njk).

Integration with Content Management

  • Site metadata and contact info are centralized in site.json and consumed by layouts and macros.
  • Layouts embed canonical URLs, Open Graph, Twitter, and structured data for SEO and social sharing.

Section sources

  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [base.njk:1-260](file://src/_includes/layouts/base.njk#L1-L260)
  • [knowledge.njk:1-43](file://src/_includes/layouts/knowledge.njk#L1-L43)