Image / Embed

Live Demo

Responsive Image with Caption

Rendered

Image with Aspect Ratios

Rendered

16:9

4:3

1:1

3:2

4:5

Video Embed (16:9)

Vimeo

YouTube

Decorative vs Informative Image

Rendered

Decorative alt=""

Informative alt="…"

Code sample

<!-- Responsive image with caption -->
<div class="caat-image">
  <figure class="caat-image__figure">
    <img class="caat-image__img"
         src="photo.jpg"
         alt="Descriptive alt text for screen readers">
    <figcaption class="caat-image__caption">Caption text here.</figcaption>
  </figure>
</div>

<!-- Aspect ratio container (16:9) -->
<div class="caat-image caat-image--16-9">
  <img class="caat-image__img" src="photo.jpg" alt="Description">
</div>

<!-- Vimeo embed (responsive 16:9) -->
<div class="caat-embed">
  <div class="caat-embed__wrapper">
    <iframe class="caat-embed__iframe"
            src="https://player.vimeo.com/video/VIDEO_ID?h=HASH&title=0&byline=0&portrait=0&texttrack=en"
            title="Video title for accessibility"
            allow="autoplay; fullscreen; picture-in-picture"
            allowfullscreen></iframe>
  </div>
</div>

<!-- YouTube embed (responsive 16:9) -->
<div class="caat-embed">
  <div class="caat-embed__wrapper">
    <iframe class="caat-embed__iframe"
            src="https://www.youtube.com/embed/VIDEO_ID?rel=0"
            title="Video title for accessibility"
            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
            allowfullscreen></iframe>
  </div>
</div>

<!-- Decorative image (empty alt) -->
<img class="caat-image__img" src="decorative.jpg" alt="" role="presentation">

<!-- Informative image (descriptive alt) -->
<img class="caat-image__img" src="chart.jpg" alt="Bar chart showing pension fund growth from 2020 to 2025">

1. Summary

2. Design Tokens

3. Authoring Fields

4. Validation

5. Content Guidance

• Alt text should describe the content and function of the image, not its appearance: "Chart showing 12% pension growth" not "a bar chart".
• Use decorative mode only for purely ornamental images (backgrounds, separators, abstract textures).
• Captions provide supplementary context — do not duplicate alt text in the caption.
• For video embeds, always provide a descriptive title: "2025 CAAT Annual Report Summary".
• Prefer WebP format for performance; provide JPEG/PNG fallback via AEM renditions.
• Use aspect-ratio constraints when images must align in a grid layout.
• Keep embed URLs pointed to the embed endpoint (e.g., youtube.com/embed/…), not the watch URL.

6. Semantic HTML

Informative image with caption

<div class="caat-image">
  <figure class="caat-image__figure">
    <img class="caat-image__img"
         src="/content/dam/caat/images/photo.jpg"
         alt="Descriptive text about image content"
         loading="lazy">
    <figcaption class="caat-image__caption">Caption text.</figcaption>
  </figure>
</div>

Decorative image

<div class="caat-image">
  <img class="caat-image__img"
       src="/content/dam/caat/images/decorative.jpg"
       alt=""
       role="presentation"
       loading="lazy">
</div>

Video embed

<div class="caat-embed">
  <div class="caat-embed__wrapper">
    <iframe class="caat-embed__iframe"
            src="https://www.youtube.com/embed/VIDEO_ID"
            title="Accessible video title"
            allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
            allowfullscreen
            loading="lazy"></iframe>
  </div>
</div>

7. CSS Contract

8. Accessibility

9. SEO

• Use descriptive, keyword-rich alt text for informative images — aids Google Image Search indexing.
• Use semantic <figure> / <figcaption> elements to associate captions with images.
• Filename should be human-readable: pension-growth-chart-2025.webp not IMG_4521.jpg.
• Include loading="lazy" on below-fold images to improve Core Web Vitals (LCP).
• Use structured data (ImageObject) for key images when applicable.
• Embeds are not indexable — provide surrounding text context and a transcript for videos.

10. Analytics

Analytics are captured through the shared data-analytics-component attribute on the component root (emitted automatically) and reported to the central data layer. Event names and payloads follow the organisation's standard analytics schema — defined centrally with the analytics team, not invented per component — so no bespoke tracking is specified here.

11. AEM Notes

• Resource type: caat/components/image-embed
• Sling Model: ImageEmbedModel — exposes src, alt, caption, aspectRatio, decorative, embedUrl, embedTitle, lazyLoad.
• HTL template: image-embed.html — uses data-sly-test to switch between image and embed variants.
• Renditions: AEM generates responsive renditions (320w, 640w, 960w, 1280w). Uses srcset and sizes for art direction.
• Client library: caat.components.image-embed — CSS only; optional JS for lazy-loading polyfill and analytics.
• Policy: Authors can restrict allowed aspect ratios and embed domains per template policy.
• Allowed parents: Layout Container, Article Body, Card Body, Hero.

12. Dialog Model

Simplified model — shows field intent and Granite UI resource types, not the literal cq:dialog node tree (e.g. select options are authored as child items nodes).

{
  "jcr:primaryType": "nt:unstructured",
  "sling:resourceType": "cq/gui/components/authoring/dialog",
  "tabs": {
    "properties": {
      "variant": {
        "sling:resourceType": "granite/ui/components/coral/foundation/form/select",
        "label": "Variant",
        "name": "./variant",
        "required": true,
        "options": ["image", "embed"]
      },
      "imageAsset": {
        "sling:resourceType": "granite/ui/components/coral/foundation/form/pathfield",
        "label": "Image asset",
        "name": "./fileReference",
        "rootPath": "/content/dam/caat",
        "required": true
      },
      "altText": {
        "sling:resourceType": "granite/ui/components/coral/foundation/form/textfield",
        "label": "Alt text",
        "name": "./alt",
        "maxlength": 125
      },
      "caption": {
        "sling:resourceType": "granite/ui/components/coral/foundation/form/textfield",
        "label": "Caption",
        "name": "./caption"
      },
      "aspectRatio": {
        "sling:resourceType": "granite/ui/components/coral/foundation/form/select",
        "label": "Aspect ratio",
        "name": "./aspectRatio",
        "options": ["auto", "16:9", "4:3", "1:1"]
      },
      "decorative": {
        "sling:resourceType": "granite/ui/components/coral/foundation/form/checkbox",
        "label": "Decorative image",
        "name": "./decorative"
      },
      "embedUrl": {
        "sling:resourceType": "granite/ui/components/coral/foundation/form/textfield",
        "label": "Embed URL",
        "name": "./embedUrl"
      },
      "embedTitle": {
        "sling:resourceType": "granite/ui/components/coral/foundation/form/textfield",
        "label": "Embed title",
        "name": "./embedTitle"
      },
      "lazyLoad": {
        "sling:resourceType": "granite/ui/components/coral/foundation/form/checkbox",
        "label": "Lazy load",
        "name": "./lazyLoad",
        "checked": true
      }
    }
  }
}

13. QA Acceptance Checklist

• Responsive image scales to 100% container width without distortion.
• Caption renders below the image with correct muted styling.
• Aspect-ratio containers (16:9, 4:3, 1:1) crop images correctly with object-fit: cover.
• Video embed wrapper maintains 16:9 ratio at all viewport sizes.
• Decorative images render with empty alt="" and role="presentation".
• Informative images have descriptive alt text announced by screen readers.
• Iframe has title attribute readable by assistive technology.
• Images have loading="lazy" when below the fold.
• Border-radius applies consistently across image and embed variants.
• Focus ring visible on interactive embeds during keyboard navigation.
• Analytics events (image-viewed, embed-play) fire correctly.
• Cross-browser tested: Chrome, Firefox, Safari, Edge.
• Mobile: images and embeds render correctly at 320px viewport.

14. Definition of Done