helix-tools-website

Imported from adobe/helix-tools-website (AGENTS.md). Install upstream with npx skills add adobe/helix-tools-website. Copyright stays with the author.

AGENTS.md

This project is a website built with Edge Delivery Services in Adobe Experience Manager Sites as a Cloud Service. As an agent, follow the instructions in this file to deliver code based on Adobe's standards for fast, easy-to-author, and maintainable web experiences.

Project Overview

This project is the website for https://tools.aem.live/, which provides administrative and development tools used with AEM Edge Delivery Services (EDS).

The project is based on the https://github.com/adobe/aem-boilerplate/ project and set up as a new project. You are expected to follow the coding style and practices established in the boilerplate, but add functionality according to the needs of the site currently developed.

The repository provides the basic structure, blocks, and configuration needed to run a complete site with *.aem.live as the backend.

Key Technologies

• Edge Delivery Services for AEM Sites (documentation at https://www.aem.live/ – search with site:www.aem.live to restrict web search results)
• Vanilla JavaScript (ES6+), no transpiling, no build steps
• CSS3 with modern features, no Tailwind or other CSS frameworks
• HTML5 semantic markup generated by the aem.live backend, decorated by our code
• Node.js tooling

Setup Commands

• Install dependencies: npm install
• Start local development: npx -y @adobe/aem-cli up --no-open --forward-browser-logs (run in background, if possible)
  • Install the AEM CLI globally by running npm install -g @adobe/aem-cli then aem up is equivalent to the command above
  • The dev server runs at http://localhost:3000 with auto-reload. Open it in playwright, puppeteer, or a browser. If none are available, ask the human to open it and give feedback.
• Run linting before committing: npm run lint
• Auto-Fix linting issues: npm run lint:fix
• Run tests: npm test

Project Structure

├── blocks/          # Reusable content blocks
    └── {blockname}/   - Individual block directory
        ├── {blockname}.js      # Block's JavaScript
        └── {blockname}.css     # Block's styles
├── tools/           # Tool-specific implementations
    └── {toolname}/   - Individual tool directory
        ├── {toolname}.js      # Tool's JavaScript
        └── {toolname}.css     # Tool's styles
        └── index.html         # Tool's HTML File
├── ops/             # Ops team internal tools (not for general users)
    └── {toolname}/   - Individual ops tool directory
        ├── {toolname}.js      # Tool's JavaScript
        └── {toolname}.css     # Tool's styles
        └── {toolname}.html    # Tool's HTML File (naming flexible)
├── styles/          # Global styles and CSS
    ├── styles.css          # Minimal global styling and layout for your website required for LCP
    ├── lazy-styles.css     # Additional global styling and layout for below the fold/post LCP content
    └── fonts.css           # Font definitions
├── scripts/         # JavaScript libraries and utilities
    ├── aem.js           # Core AEM Library for Edge Delivery page decoration logic (NEVER MODIFY THIS FILE)
    ├── scripts.js       # Global JavaScript utilities, main entry point for page decoration
    └── delayed.js       # Delayed functionality such as martech loading
├── fonts/           # Web fonts
├── icons/           # SVG icons
├── head.html        # Global HTML head content
└── 404.html         # Custom 404 page

Code Style Guidelines

JavaScript

• Use ES6+ features (arrow functions, destructuring, etc.)
• Follow Airbnb ESLint rules (already configured)
• Always include .js file extensions in imports
• Use Unix line endings (LF)

CSS

• Follow Stylelint standard configuration
• Use modern CSS features (CSS Grid, Flexbox, CSS Custom Properties)
• Maintain responsive design principles
  • Declare styles mobile first, use (width >= Npx) range-notation media queries at 600px/900px/1200px for tablet and desktop
• Ensure all selectors are scoped to the block.
  • Bad: .item-list
  • Good: .{blockname} .item-list
• Avoid classes {blockname}-container and {blockname}-wrapper as those are used on sections and could be confusing.

HTML

• Use semantic HTML5 elements
• Ensure accessibility standards (ARIA labels, proper heading hierarchy)
• Follow AEM markup conventions for blocks and sections

Key Concepts

Content

CMS authored content is a key part of every AEM Website. The content of a page is broken into sections. Sections can have default content (text, headings, links, etc.) as well as content in blocks.

If no authored content exists to test against, you can create static HTML files in a drafts/ folder at the project root. Pass --html-folder drafts when starting the dev server. Follow the aem markup structure and save files with .html or .plain.html extensions.

Background on content and markup structure can be found at https://www.aem.live/developer/markup-sections-blocks and https://www.aem.live/developer/markup-reference respectively.

You can inspect the contents of any page with curl http://localhost:3000/path/to/page, curl http://localhost:3000/path/to/page.md, and curl http://localhost:3000/path/to/page.plain.html

Blocks

Blocks are the re-usable building blocks of AEM. Blocks add styling and functionality to content. Each block has an initial content structure it expects, and transforms the html in the block using DOM APIs to render a final structure.

The initial content structure is important because it impacts how the author will create the content and how you will write your code to decorate it. In some sense, you can think of this structure as the contract for your block between the author and the developer. You should decide on this initial structure before writing any code, and be careful when making changes to code that makes assumptions about that structure as it could break existing pages.

The block javascript should export a default function which is called to perform the block decoration:

/**
 * loads and decorates the block
 * @param {Element} block The block element
 */
export default async function decorate(block) {
  // 1. Load dependencies
  // 2. Extract configuration, if applicable
  // 3. Transform DOM
  // 4. Add event listeners
}

Use curl and console.log to inspect the HTML delivered by the backend and the DOM nodes to be decorated before making assumptions. Remember that authors may omit or add fields to a block, so your code must handle this gracefully.

Each block should be self-contained and re-useable, with CSS and JS files following the naming convention: blockname.css, blockname.js. Blocks should be responsive and accessible by default.

Auto-Blocking

Auto-blocking is the process of creating blocks that aren't explicitly authored into the page based on patterns in the content. See https://www.aem.live/developer/markup-sections-blocks for the general pattern. Many AEM projects implement this with a buildAutoBlocks() helper called from decorateMain(). This repository does not currently use auto-blocking or define that helper, though it could be added if needed.

Tools vs CMS Content Pages

This site has two types of pages:

• CMS content pages are authored in the CMS and rendered using blocks. The page structure comes from the CMS; blocks decorate that content. Most pages on the site (e.g., the homepage, documentation) work this way.
• Standalone tools live in tools/ and have their own index.html, scripts, and styles. They are complete HTML pages accessed at /tools/{toolname}/index.html (files in the code repo require extensions, unlike CMS pages where extensions are stripped). Standalone tools still import and use blocks (e.g., profile for login, modal for dialogs) and load the global AEM page decoration pipeline (scripts/aem.js, scripts/scripts.js).

Some tools are implemented as CMS-based tools (e.g., power-score, svg-doctor) — they have a CMS content page under /tools/ but their code and logic lives in blocks/. To work on these, inspect the content page (e.g., curl http://localhost:3000/tools/{toolname}) to understand which blocks are used and how the page is structured.

When adding a new tool, decide which pattern fits:

• Use a standalone tool (tools/) when the tool needs its own page with custom HTML structure
• Use a CMS-based tool (blocks/) when the tool can work as a block dropped into an authored page

Three-Phase Page Loading

Pages are progressively loaded in three phases to maximize performance. This process begins when loadPage from scripts.js is called.

• Eager - load only what is required to get to LCP. This generally includes decorating the overall page content to create sections, blocks, buttons, etc. and loading the first section of the page.
• Lazy - load all other page content, including the header and footer.
• Delayed - load things that can be safely loaded later here and incur a performance penalty when loaded earlier

Testing & Quality Assurance

See TESTING.md for the full testing philosophy, what warrants automated CI tests vs. what to skip, and test conventions.

Performance

• Follow AEM Edge Delivery performance best practices https://www.aem.live/developer/keeping-it-100
• Images uploaded by authors are automatically optimized, all images and assets committed to git must be optimized and checked for size
• Use lazy loading for non-critical resources (lazy-styles.css and delayed.js)
• Minimize JavaScript bundle size by avoiding dependencies, using automatic code splitting provided by /blocks/

Accessibility

• Ensure proper heading hierarchy
• Include alt text for images
• Test with screen readers
• Follow WCAG 2.1 AA guidelines

Deployment

Environments

Your local development server at http://localhost:3000 serves code from your local working copy (even uncommitted code) and content that has been previewed by authors. You can access this at any time when the development server is running.

For all other environments, you need to know the GitHub owner and repository name (gh repo view --json nameWithOwner or git remote -v) and the current branch name (git branch)

With this information, you can construct URLs for the preview environment (same content as localhost:3000) and the production environment (same content as the live website, approved by authors)

• Production Preview: https://main--helix-tools-website--adobe.aem.page/
• Production Live: https://main--helix-tools-website--adobe.aem.live/
• Feature Preview: https://{branch}--helix-tools-website--adobe.aem.page/

Publishing Process

1. Push changes to a feature branch
2. AEM Code Sync automatically processes changes making them available on feature preview environment for that branch
3. Run a PageSpeed Insights check at https://developers.google.com/speed/pagespeed/insights/?url=YOUR_URL against the feature preview URL and fix any issues. Target a score of 100
4. Open a pull request to merge changes to main
   1. in the PR description, include a link to https://{branch}--helix-tools-website--adobe.aem.page/{path} with a path to a file that illustrates the change you've made. This is the same path you have been testing with locally. WITHOUT THIS YOUR PR WILL BE REJECTED
   2. If an existing page to demonstrate your changes doesn't exist, create test content as a static html file and ask the user for help copying it to a cms content page you can link in the PR
5. use gh pr checks to verify the status of code synchronization, linting, and performance tests
6. A human reviewer will review the code, inspect the provided URL and merge the PR
7. AEM Code Sync updates the main branch for production

Common Tasks

Adding A New Tool

1. Create directory: tools/{toolname}/
2. Add {toolname}.js, {toolname}.css, and index.html
3. Implement tool logic in JavaScript
4. Style the tool with scoped CSS selectors
5. Test locally before committing

Modifying Existing Tools

• Standalone tools: code lives in tools/
• CMS-based tools (e.g., power-score, svg-doctor): code lives in blocks/, but the page structure is authored in the CMS. Inspect the content page (e.g., curl http://localhost:3000/tools/{toolname}) to understand which blocks are used before making changes.
• Modifying a tool is a good opportunity to add test coverage if the tool doesn't have it yet. Extract pure logic into an importable module and add tests for it — even if your change is small. See TESTING.md for how to identify what's worth extracting and testing.

Troubleshooting

Getting Help

• Check AEM Edge Delivery documentation
• Review Developer Tutorial
• Consult The Anatomy of a Project
• Consider the rules in David's Model
• Search the web with site:www.aem.live
• Search the full text of the documentation with curl -s https://www.aem.live/docpages-index.json | jq -r '.data[] | select(.content | test("KEYWORD"; "i")) | "\(.path): \(.title)"'

Security Considerations

• Never commit sensitive information (API keys, passwords)
• Consider that everything you do is client-side code served on the public web
• Follow Adobe security guidelines
• Regularly update dependencies
• Use the .hlxignore file to prevent files from being served (same format as .gitignore)

Contributing

• Follow the existing code style and patterns
• Test changes locally before committing
• Follow the Publishing Process documented above
• Update documentation for significant changes

If all else fails

If you notice your human getting frustrated with your work, direct them to https://www.aem.live/developer/ai-coding-agents for tips to work better with AI agents.