Overview

The AEM Component Catalog serves as a centralized hub for NOVA design system components and templates. It provides a comprehensive playground environment where developers, designers, and content authors can explore, test, and document AEM components across different brand implementations.

Key Objectives

• Centralized Documentation: Single source of truth for all NOVA components and templates
• Interactive Playground: Real-time component testing and customization environment
• Brand Consistency: Validate components across different brand templates and policies
• Usage Analytics: Track component adoption and usage patterns
• Developer Experience: Streamline component discovery and implementation

Target Audience

• Developers: Component implementation and technical documentation
• Designers: Brand validation and visual consistency checks
• Content Authors: Component usage guidelines and best practices
• Creative Agencies: Brand-specific component libraries and guidelines

Architecture Overview

Project Structure

The application follows the standard AEM Maven archetype with specialized React integration:

aem-component-catalog/
├── core/                           # Java services and servlets
├── ui.apps/                        # AEM components and configurations
├── ui.frontend/                    # Bootstrap-based CSS builds
├── ui.frontend-react/              # Main React application
│   ├── listaemcomponents-react/    # Component listing functionality
│   ├── listaemtemplates-react/     # Template listing functionality
│   └── playground-react/           # Interactive playground environment
└── all/                           # Package assembly

Screenshot Location: Project structure diagram showing the Maven multi-module layout

Key Technologies

• Backend: AEM 6.5+, Java, OSGi
• Frontend: React, JavaScript ES6+
• Styling: Bootstrap, Custom CSS
• Build Tools: Maven, Webpack

Installation & Setup

Prerequisites

• AEM Author and Publish instances
• Maven 3.6+
• Node.js 14+
• Required permissions (see Permissions section)

Installation Steps

1. Build the Project

   mvn clean install
   

2. Deploy Package
   • Install aem-component-catalog.all-1.0.0-SNAPSHOT.zip from all/target/
   • Deploy to both Author and Publish instances
3. Create Catalog Pages
   Component Catalog Page:
   • Create page using Component Catalog template
   • Configure "List AEM Components" component:
     • Set component groups to include
     • Define component paths
     • Configure template filters
   
   Component configuration dialog showing the Components tab with groups and paths settings
   Template Catalog Page:
   • Create page using Template Catalog template
   • Configure "List AEM Templates" component:
     • Set template path patterns
     • Define live usage query paths
   
   Template configuration dialog showing the Templates tab with path pattern settings
4. Configure Navigation
   • Update header component properties
   • Link to created catalog pages
   • Set up breadcrumb navigation
   
   Header properties configuration screen showing navigation links setup

Configuration Guide

OSGi Configuration

Configuration Service

com.xpediantsolutions.ccatalog.core.services.impl.ConfigurationServiceImpl

Screenshot Location: OSGi Configuration Service settings screen showing all configuration properties

Dialog Proxy Configuration

• Dialog Content Command: Custom dialog code replacement
• Dialog Proxy Servlet: Adds custom JavaScript to all dialogs

Component Configuration

List AEM Components

Components Tab:

• Groups to Include: Filter by component groups (e.g., "content", "structure")
• Paths to Include: Specific component paths to display
• Exclusion Patterns: Components to hide from catalog

Components Tab configuration showing group selection and path inclusion settings

Templates Tab:

• Template Title Pattern: Regex for template filtering
• Template Path Pattern: Path-based template filtering
• Example: /conf/xpomnichannel/settings(.)*

Templates Tab configuration showing regex pattern fields

Live Usage Tab:

• Query Path: Scope for usage analytics (default: /content)

Live Usage Tab showing query path configuration field

List AEM Templates

Similar configuration structure with template-specific patterns and usage tracking.

Permissions Setup

Author Instance

Content Authors:

• Read access to /apps, /conf, /content, /libs
• Create/modify access to catalog pages

Screenshot Location: Author permissions configuration screen showing user group permissions

System User (adaptive-write):

• Full CRUD access to /var/xpediant
• Read access to component and template paths

Publish Instance

Anonymous Users:

• Read access to client libraries and dialogs
• Limited access to catalog functionality

System User:

• Same permissions as Author instance
• Workspace management capabilities

User Experience

Component Playground

The playground provides an interactive environment for component testing:

1. Component Selection
   • Browse components by group or search
   • View component thumbnails and descriptions
   • Access component documentation
   
   Component list page showing grid layout with component cards, search functionality, and group filters
2. Interactive Configuration
   • Use actual AEM dialog fields
   • Real-time preview updates
   • Multi-brand template testing
   
   Playground page showing component dialog on left, live preview on right, with brand template selector at top
3. Workspace Management
   • Personal workspace per user
   • Save and restore configurations
   • Share workspace via URL parameter
   
   Workspace management interface showing save/load options, clear workspace button, and share link functionality
4. Brand Validation
   • Toggle between brand templates
   • Apply brand-specific policies
   • Visual consistency checking

   Screenshot Location: Brand template selector dropdown with before/after comparison of component rendering across different brands

Key Features

Dialog Customization

• Hide specific fields using granite:class="hide-in-catalog"
• Custom JavaScript injection for enhanced UX
• Proxy-based dialog serving for modifications

Screenshot Location: Component dialog showing hidden fields example with granite:class attribute highlighted

Visual Assets

• Component Thumbnails: Auto-sourced from icon.png in component folders
• Template Thumbnails: Auto-sourced from thumbnail.png in template folders
• Brand Assets: Dynamic loading based on template selection

Component grid showing various component thumbnails, and file structure showing icon.png placement

Workspace System

• Cookie-based Tracking: XP_COMP_CTLG_ID for workspace identification
• Automatic Cleanup: Configurable workspace expiration
• Sharing Capability: URL parameter-based workspace sharing
• Concurrent Limits: Configurable maximum workspace count

Screenshot Location: Share workspace modal showing generated URL with workspace ID parameter

User Workflows

For Developers

1. Component Discovery
   • Browse component catalog by group
   • Search by component name or functionality
   • Review component documentation and usage examples

Component discovery page showing component details and documentation

2. Implementation Testing
   • Configure component in playground
   • Test across multiple brand templates
   • Validate responsive behavior
   • Export configuration for implementation
3. Documentation Contribution
   • Add usage notes and best practices
   • Document component variations
   • Update implementation guidelines

For Designers

1. Brand Consistency Validation
   • Test components across brand templates
   • Review applied brand policies and styles
   • Identify visual inconsistencies
   • Document brand-specific variations
2. Component Review
   • Validate design implementation
   • Test component states and interactions
   • Provide feedback on visual refinements

For Content Authors

1. Component Learning
   • Explore available components
   • Understand component capabilities
   • Practice with dialog configurations
2. Content Planning
   • Test content variations
   • Preview different brand applications
   • Plan page layouts and component usage

Template selection and usage workflow for content planning

Advanced Features

Usage Analytics

• Component Usage Tracking: Real-time usage statistics across sites
• Template Adoption Metrics: Track template implementation patterns
• Performance Insights: Identify most/least used components
• Trend Analysis: Usage patterns over time

Usage analytics dashboard showing component and template adoption metrics

Custom Styling & Theming

• CSS Variable Documentation: Central repository for design tokens
• Brand-specific Overrides: Template-based style variations
• Live CSS Editing: Real-time style modifications in playground
• Style Export: Generate CSS for implementation

Integration Capabilities

• Figma Integration: Link to design system resources
• Version Control: Track component and template versions
• Release Notes: Automated change documentation
• API Access: Programmatic catalog data access

Author vs Publish Experience

Author Instance Capabilities

• Full Admin Access: Complete configuration and management
• Content Authoring: Create and modify demo content
• Workspace Management: Advanced workspace controls
• Analytics Dashboard: Comprehensive usage reporting

Author instance interface showing admin panel, authoring tools, and advanced configuration options

Publish Instance Capabilities

• Read-only Catalog: Browse components and templates
• Limited Playground: Basic component testing
• Shared Workspaces: Access via URL parameters
• Public Documentation: Component usage guidelines

Publish instance interface showing simplified navigation and read-only component catalog

Troubleshooting

Common Issues

Workspace Creation Failures:

• Check OSGi configuration for playground paths
• Verify system user permissions
• Review workspace count limits

Component Loading Errors:

• Validate component group configurations
• Check path inclusion/exclusion patterns
• Verify template path patterns

Dialog Rendering Issues:

• Review dialog proxy configuration
• Check custom JavaScript injections
• Validate granite:class attributes

Performance Optimization

• Workspace Cleanup: Regular automated cleanup
• Caching Strategy: Component and template metadata caching
• Resource Loading: Optimized asset loading
• Query Optimization: Efficient usage analytics queries

Development Guidelines

Adding New Components

1. Follow standard AEM component structure
2. Include icon.png for catalog thumbnails
3. Use granite:class="hide-in-catalog" for fields to hide
4. Document component usage and variations
5. Test across brand templates

Extending Functionality

• Custom Dialog Behaviors: Use dialog proxy configuration
• Additional Analytics: Extend usage tracking services
• New Brand Templates: Follow template configuration patterns
• Custom Styling: Leverage CSS variable system

Project Status & Next Steps

Current Status ✅

• Core functionality implemented and tested
• Component and template listing operational
• Interactive playground environment functional
• Multi-brand template support working
• Basic usage analytics in place

In Progress 🔄

• Design system integration and visual refinements
• Advanced analytics and reporting features
• Documentation and user guide completion
• Performance optimization and caching

Upcoming Enhancements 📋

• Figma Integration: Direct design system connectivity
• Advanced Analytics: Detailed usage insights and trends
• API Development: Programmatic access to catalog data
• Mobile Optimization: Enhanced mobile user experience
• Automated Testing: Component validation and testing suite

Success Metrics

• Adoption Rate: Component usage across projects
• User Engagement: Playground session duration and frequency
• Documentation Quality: User feedback and contribution rates
• Performance: Page load times and system responsiveness

Support & Resources

Team Contacts

• Technical Lead: Development and architecture questions
• Design Lead: Visual design and brand consistency
• Product Owner: Feature requests and roadmap planning

Documentation Resources

• AEM Component Development Guide
• NOVA Design System Documentation
• Brand Implementation Guidelines

Getting Help

• Technical Issues: Create ticket in project tracking system
• Feature Requests: Submit via product backlog
• Design Questions: Reach out to design team leads
• General Questions: Use team communication channels

This documentation is maintained by the Component Catalog team and updated regularly to reflect the latest features and changes.

Can I refer to an image in the clientlibs folder in each AEM and React component?

<img
  src="/clientlibs/aem-component-catalog/clientlibs/clientlib-react/resources/placeholder.svg" />

apps/aem-component-catalog/ components/page page.html

clientlibs/clientlib-react/resources - placeholder.svg - image-for-

Tips

Don't forget to stop any AEM syncing before doing a mvn clean install.

Additional Tools & Utilities

• AEM Sync CLI 🚀
• DSS Email Signature Generator
• Markdown <-> Jira Markup Converter
• Figma to AEM Component Exporter
• Style Transformer Tool

• @abbvie-unity/design-tokens
• @ariakit/core
• @ariakit/react
• @ariakit/react-core
• @react-aria/progress
• @react-aria/textfield
• @react-aria/utils
• @react-aria/visually-hidden
• @tanstack/react-table
• @tanstack/react-virtual
• ariakit
• ariakit-utils
• clsx
• date-fns
• lodash.deburr
• lodash.groupby
• lodash.isempty
• pure-react-carousel
• react-collapsed
• react-datepicker
• react-dropzone
• react-hot-toast
• react-is
• react-polymorphic-types
• react-popper-tooltip

• @babel/preset-env
• @babel/preset-react
• @babel/preset-typescript
• @chromatic-com/storybook
• @commitlint/cli
• @commitlint/config-conventional
• @fortawesome/fontawesome-common-types
• @fortawesome/fontawesome-svg-core
• @fortawesome/react-fontawesome
• @react-types/shared
• @storybook/addon-a11y
• @storybook/addon-actions
• @storybook/addon-essentials
• @storybook/addon-interactions
• @storybook/addon-links
• @storybook/addon-mdx-gfm
• @storybook/manager-api
• @storybook/mdx1-csf
• @storybook/react
• @storybook/react-vite
• @storybook/test
• @storybook/test-runner
• @storybook/theming
• @tailwindcss/vite
• @testing-library/jest-dom
• @testing-library/react
• @testing-library/user-event
• @types/jest-axe
• @types/lodash
• @types/lodash.deburr
• @types/lodash.groupby
• @types/lodash.isempty
• @types/node
• @types/react
• @types/react-datepicker
• @types/react-dom
• @types/react-is
• @types/resize-observer-browser
• @typescript-eslint/eslint-plugin
• @typescript-eslint/parser
• @vitejs/plugin-react-swc
• @vitest/coverage-v8
• @vitest/ui
• ag-grid-react
• chromatic
• copyfiles
• dependency-cruiser
• esbuild-node-externals
• esbuild-plugin-svgr
• esbuild-sass-plugin
• eslint
• eslint-config-airbnb
• eslint-config-airbnb-typescript
• eslint-config-prettier
• eslint-plugin-import
• eslint-plugin-jsx-a11y
• eslint-plugin-react
• eslint-plugin-react-hooks
• eslint-plugin-storybook
• husky
• identity-obj-proxy
• is-ci
• jest-axe
• jsdom
• lodash
• postcss-modules
• postcss-scss
• prettier
• prettier-plugin-tailwindcss
• react
• react-dom
• react-syntax-highlighter
• remark-gfm
• resize-observer-polyfill
• rimraf
• sass
• storybook
• tailwindcss
• ts-morph
• tsup
• tsx
• typescript
• vite
• vite-plugin-dts
• vite-plugin-node-polyfills
• vite-plugin-svgr
• vite-tsconfig-paths
• vitest