# Image Generation & Curation Guidelines

> **Plugin**: ASU Canvas Course Builder
> **Version**: 1.0.0
> **Purpose**: Standards for generating, searching, vetting, and embedding images in Canvas course pages.

The `images` skill references this document. These guidelines ensure every image in a course is instructionally purposeful, accessible, accurately attributed, and legally safe.

---

## Core Principles (Mayer's Multimedia Learning)

Every image decision should pass through these empirically-grounded filters:

| Principle | Rule | Implication |
|---|---|---|
| **Multimedia** | Words + pictures > words alone | Use images — but only instructional ones |
| **Coherence** | Extraneous material harms learning | No decorative filler. Every image earns its place. |
| **Signaling** | Cues guide attention to key info | Use arrows, labels, highlights, numbering in diagrams |
| **Spatial Contiguity** | Related text and images must be adjacent | Use the Image + Concept Card component, not separated layouts |
| **Segmenting** | Complex visuals should be learner-paced | Break complex diagrams into stepped sequences |

**The test**: Before adding any image, ask: *"Does this image help the learner understand the objective, or is it just filling space?"* If the latter, omit it.

---

## Search-First Principle

**Always attempt to find a real, vetted image before generating one with AI.**

This is especially critical for:
- Scientific/biological/medical content
- Technical diagrams with precise relationships
- Historical or cultural imagery
- Any image where factual accuracy matters

**Workflow**:
1. Identify the image need and its purpose
2. Search OpenVerse / vetted sources for a suitable real image
3. **If a good match is found** → use it (preferred)
4. **If no good match is found** → inform the user: *"I searched for [concept] but couldn't find a high-quality image from a vetted source. Would you like me to generate one with AI instead?"*
5. **Never silently generate** an AI image when a searched image would be more appropriate — always give the user the choice

**When AI generation IS appropriate** (without searching first):
- User explicitly asks to "create" or "generate" an image
- The concept is abstract, branded, or custom (no real-world equivalent exists)
- Process flows, decision trees, or custom diagrams unique to the course
- Conceptual illustrations that are course-specific

**When AI generation is NOT appropriate** (always search first):
- Biological structures, anatomical diagrams, chemical processes
- Historical photographs or cultural artifacts
- Real-world examples, locations, or environments
- Data visualizations (never AI-generate these — use HTML/CSS/Chart.js)
- Scientific processes where accuracy is critical

---

## Audience & Representation (ASU Online)

Every ASU course built with this plugin is **college-level**, delivered to **ASU Online**. That sets a hard default for any image that depicts people: the audience is adult college learners, and the imagery must look like it.

**Default audience: adult college learners.** When an image shows people (students, professionals, learners in a scenario), depict **adults: college-age (18+) and older**, including working-adult and returning learners. ASU Online students are frequently employed adults consolidating a credential, not traditional-age-only cohorts.

**Represent the real ASU Online learner population.** Show diversity intentionally across race and ethnicity, age, gender, and visible disability, in realistic online-study settings (home office, laptop, headphones, library). One generated set should not be four people of the same demographic. Diversity is a default, not a special request.

**K-12 and child imagery is a MISMATCH by default.** Children, K-12 classrooms, school-bus / juvenile / cartoonish aesthetics, and "back to school" childhood tropes are wrong for a college audience. Treat them as a rejection unless the **course topic explicitly requires** them (for example a child-development, early-childhood-education, K-12-teaching-methods, or pediatric course). When unsure whether the topic warrants child imagery, ask the user before generating.

**Scenario language follows the imagery.** If a page scenario describes "a student," default the wording and the picture to an **online college student / adult learner**, not a schoolchild.

**Photorealistic adult learners are allowed** for learner-representation imagery (this is the one carve-out to the "no photorealistic human faces" constraint in the prompt template, which still holds for diagrams and concept art). Keep them realistic and respectful; no likeness of identifiable real individuals.

This rule is a write-time default. Apply it whenever building a generation prompt or vetting a searched image. The `images` skill reads `course-config.json` `course.level` / `course.tier` (always college: introductory / advanced / graduate) to reinforce it.

---

## Image Placement & Layout Guidelines

Images should enhance the visual flow and reading experience of a page, not just sit above text blocks. Consider the full page layout when deciding where and how to place images.

### Layout Decision Guide

| Context | Recommended Component | Why |
|---|---|---|
| Image is the main focus, needs a full caption | **Component 13**: Instructional Image (full-width) | Gives the image prominence and room for detailed caption/attribution |
| Image illustrates a concept being explained in adjacent text | **Component 14**: Image + Concept Card | Follows Mayer's Spatial Contiguity — keeps image and explanation together |
| Comparing two images, conditions, or approaches | **Component 15**: Image Comparison | Side-by-side makes differences immediately visible |
| Multiple related images for a single topic | **Image Gallery** (3-up) | Shows breadth without overwhelming the page |
| Hero/banner for a module or section opener | **Component 13** at 16:9 aspect | Sets visual tone for the section |

### Placement Rules

1. **Vary your layouts.** Don't place 3 full-width images in a row — alternate between full-width (Component 13) and side-by-side (Component 14) layouts. Mix image placements to create visual rhythm.
2. **Use Image + Concept Cards** when the image supports a concept being explained. Place the image to the left or right of the explanation text. This is often better than a full-width image followed by a paragraph.
3. **Consider the page as a whole.** Before placing an image, scan the current page HTML. If there are already 2+ full-width images, use a side-by-side layout for the next one. If the page is text-heavy with no images, a full-width instructional image can break up the content effectively.
4. **Hero images go at the top.** If a module overview or lesson page needs a hero/banner image, place it at the very top (after the Module Header Banner component), at 16:9 aspect ratio.
5. **Don't over-image.** 1-3 images per page is ideal. More than 4 images on a single page creates cognitive overload (Mayer's Coherence Principle). If you have more, consider spreading them across pages.
6. **Match aspect ratio to layout.** Full-width images work best at 16:9 or 4:3. Image + Concept Cards work best at 1:1 or 3:4. Comparison images should be the same aspect ratio.

---

## Image Purpose Categories

Every image must be classified before use. This determines alt text treatment, placement, and review rigor.

| Purpose | Definition | Alt Text | Review Level |
|---|---|---|---|
| **Instructional** | Directly teaches a concept, shows a process, illustrates a relationship | Full descriptive alt text | Full review (accuracy, relevance, accessibility) |
| **Contextual** | Sets scene, provides motivation, connects to real world | Brief descriptive alt text | Standard review (relevance, inclusivity) |
| **Decorative** | Purely aesthetic, no informational content | `alt=""` (empty — screen readers skip) | Discouraged per Mayer's Coherence Principle |

**Default**: Assume instructional unless explicitly classified otherwise.

---

## Prompt Engineering for AI Image Generation

### Prompt Structure Template

```
[STYLE]: Clean, professional [style keyword] for a college-level [discipline] course.
[SUBJECT]: [Detailed description of what to show — be specific about elements, relationships, layout]
[CONTEXT]: Educational [image type] illustrating [learning objective reference].
[COMPOSITION]: [Aspect ratio guidance, framing, visual hierarchy]
[CONSTRAINTS]: No text overlay. No watermarks. No photorealistic human faces
  (carve-out: adult-learner representation photos may be photorealistic; see
  Audience & Representation). White or light neutral background. High contrast
  for accessibility. Only include elements necessary to convey the concept.
[PEOPLE]: When the image depicts people, show adult college learners (18+ and
  older, including working adults), diverse across race, age, gender, and
  ability, in a realistic online-study setting. No children or K-12 settings
  unless the course topic explicitly requires them.
[COLOR]: Clear, distinct colors. Avoid red-green only differentiation (colorblind accessibility).
  ASU maroon (#8C1D40) and gold (#FFC627) may be incorporated for branding where appropriate.
```

### Style Directory

| Style | When to Use | Prompt Keywords |
|---|---|---|
| **Clean diagram** | Process flows, cycles, mechanisms, systems | "clean educational diagram, labeled, flat design, white background, clear arrows" |
| **Conceptual illustration** | Abstract concepts, metaphors, principles | "conceptual illustration, minimalist, professional, symbolic" |
| **Infographic** | Data relationships, comparisons, hierarchies | "infographic style, clean layout, organized sections, clear visual hierarchy" |
| **Isometric** | Systems, architectures, spatial relationships | "isometric illustration, 3D perspective, clean lines, technical" |
| **Scientific illustration** | Biological/chemical structures, anatomical | "scientific illustration, detailed, labeled, textbook quality, accurate" |
| **Icon set** | Feature lists, navigation, process steps | "flat icon, simple, single color, consistent style, 64px" |

### Aspect Ratio Guide

| Ratio | Use Case | Imagen 4 Support |
|---|---|---|
| `1:1` | Concept cards, thumbnails, icons | Yes |
| `16:9` | Page banners, hero images, wide diagrams | Yes |
| `4:3` | In-content illustrations, standard images | Yes |
| `3:4` | Sidebar images, portrait diagrams | Yes |
| `9:16` | Rarely used in courses | Yes |

### Model Selection

| Model | Best For | Cost | Access |
|---|---|---|---|
| **Nano Banana (Gemini native)** | **Primary model.** Best text reproduction, conversational editing, iterative refinement, any image containing labels/text | ~$0.05-0.15/image (token-based) | Google AI API key via proxy |
| **Imagen 4 Fast** | Quick iterations when text fidelity isn't needed | ~$0.02/image | Google AI API key via proxy |
| **Imagen 4 Standard** | Final quality for text-free illustrations | ~$0.04/image | Google AI API key via proxy |
| **Imagen 4 Ultra** | Maximum detail, complex text-free scenes | ~$0.06/image | Google AI API key via proxy |

**Default**: Nano Banana for all generation. It produces the highest quality text in images and supports conversational editing.
**Use Imagen 4 when**: The image is purely visual with no text/labels and you want batch generation (multiple options at once). Imagen 4 cannot do conversational refinement.
**Never use Imagen 4 for**: Images that include text, labels, annotations, or titles — Imagen struggles with accurate text reproduction. Always use Nano Banana for these.

### Negative Prompt Defaults

Always include these constraints unless the user specifically overrides:

```
No text overlay, no watermarks, no signatures, no borders, no frames,
no photorealistic human faces, no stock photo aesthetic, no lens flare,
no vignette, no busy backgrounds
```

**Additional for educational content**:
```
No decorative elements that don't serve the learning objective,
no misleading visual metaphors, no culturally specific symbols without context
```

**Audience (when people are depicted)**:
```
No children, no minors, no K-12 classroom or school settings, no juvenile or
cartoonish aesthetic, no "back to school" childhood tropes
```
(Omit this block only when the course topic is explicitly about children, e.g. early-childhood education or pediatrics.)

---

## Prohibited Uses — Hard Blocks

These categories must NEVER be generated with AI. Redirect to the `images` skill's search mode for vetted alternatives.

| Category | Why | Alternative |
|---|---|---|
| **Medical/anatomical illustrations** | AI frequently produces inaccurate anatomy | Search HHMI BioInteractive, NIH, Wikimedia |
| **Historical photographs** | AI cannot produce historically accurate depictions | Search Library of Congress, Smithsonian, Wikimedia |
| **Data visualizations** (charts, graphs) | AI-generated charts contain fabricated data | Use Chart.js, HTML tables, or real data tools |
| **Text-heavy images** | WCAG 1.4.5 prohibits images of text | Use styled HTML instead |
| **Images of identifiable real people** | Consent, likeness rights, deepfake concerns | Use authentic licensed photography |
| **Maps presented as factual** | AI maps contain geographic errors | Use OpenStreetMap, USGS, or vetted sources |

## Warned Uses — Require Extra Review

| Category | Risk | Mitigation |
|---|---|---|
| **Images depicting people** (abstract/silhouette) | AI amplifies demographic stereotypes (Bianchi et al., 2023) | Review for bias in race, gender, age, body type. Ensure diverse representation across course. |
| **Scientific process diagrams** | Subtle accuracy errors possible | Flag for subject-matter expert (SME) review before publishing |
| **Discipline-specific imagery** | Domain accuracy varies by model training | Cross-reference against authoritative sources |

---

## Image Search — Vetted Sources

### Primary: OpenVerse API (CC-licensed aggregator)

OpenVerse indexes images from verified Creative Commons sources with reliable license metadata.

- **Endpoint**: `GET https://api.openverse.org/v1/images/`
- **License filter**: `license=cc0,by,by-sa` (safest tiers)
- **Pre-built attribution**: Response includes formatted attribution string
- **Sources indexed**: Flickr, Wikimedia Commons, rawpixel, NASA, museum collections, universities

### Supplemental Direct Sources (no API key required)

| Source | Best For | License | URL Pattern |
|---|---|---|---|
| **Wikimedia Commons** | Scientific diagrams, historical, educational | CC-BY, CC-BY-SA, PD | `commons.wikimedia.org/w/api.php` |
| **Smithsonian Open Access** | Science, art, history, natural history | CC0 (public domain) | `api.si.edu/openaccess/api/v1.0/` |
| **Library of Congress** | Historical photos, maps, prints | Public domain (mostly) | `loc.gov/search/?fo=json` |
| **NASA Image Gallery** | Space, Earth science, astronomy | Public domain (US gov) | `images-api.nasa.gov/` |
| **NIH/NCI Visuals** | Medical, health, biology | Public domain (US gov) | `visualsonline.cancer.gov` |
| **HHMI BioInteractive** | Biology diagrams, animations | Educational use | `biointeractive.org` |

### License Tiers (Safest to Most Restrictive)

| Tier | Licenses | Usage |
|---|---|---|
| **Tier 1 (Safest)** | CC0, Public Domain | No restrictions, no attribution required |
| **Tier 2 (Safe)** | CC-BY, CC-BY-SA | Free use with attribution (required) |
| **Tier 3 (Conditional)** | CC-BY-NC, CC-BY-NC-SA | Non-commercial only — verify institutional status |
| **Tier 4 (Restricted)** | CC-BY-ND, CC-BY-NC-ND | No modifications — cannot crop, annotate, or remix |

**Default search filter**: Tier 1 + Tier 2 only. Tier 3-4 only when Tier 1-2 yields no results.

---

## Image Review Checklist

Every image — searched or generated — must pass this checklist before upload to Canvas.

### Review Card Fields

| Field | Searched Images | Generated Images |
|---|---|---|
| **Source** | API source + direct URL | Model name + full prompt used |
| **License** | License type + license URL | "AI-generated — see disclosure" |
| **Attribution** | Pre-built attribution line | AI disclosure line |
| **Relevance** | Mapped to specific learning objective ID | Mapped to specific learning objective ID |
| **Accuracy** | Visual inspection — is content correct? | Visual inspection + SME flag if scientific |
| **Audience fit** | Adults appropriate for a college audience? No K-12/child imagery unless the topic requires it | Same: adult college learners, no children unless topic requires |
| **Inclusivity** | People depicted? Diversity across race, age, gender, ability | People depicted? Diversity represented, bias check |
| **Accessibility** | Contrast OK? Text-free? Clear at small sizes? | Contrast OK? Text-free? Clear at small sizes? |
| **Resolution** | Minimum 800px wide for full-width use | Generated at spec (1024px+ wide) |
| **Alt text** | Claude drafts, user confirms | Claude drafts, user confirms |
| **Caption** | Claude drafts, user confirms | Claude drafts + AI disclosure |

### Approval States

```
CANDIDATE → REVIEWED → APPROVED → UPLOADED → EMBEDDED
                ↓           ↓
             REJECTED    NEEDS_REVISION (regenerate / find alternative)
```

---

## Alt Text Writing Standards

### Formula

```
[Image type] showing [main subject] [key details relevant to learning objective]
```

### Examples

| Image | Good Alt Text | Bad Alt Text |
|---|---|---|
| Diagram of cellular respiration | "Diagram showing the three stages of cellular respiration: glycolysis, Krebs cycle, and electron transport chain with ATP yield at each stage" | "Biology diagram" |
| Photo of tectonic plates | "Satellite photograph showing the San Andreas Fault where the Pacific and North American plates meet" | "Fault line photo" |
| Flowchart of research methods | "Flowchart showing the six steps of the scientific method from observation through conclusion, with feedback loop from conclusion to hypothesis" | "Research flowchart" |

### Rules

- **Maximum**: 125 characters for simple images. Use `aria-describedby` + long description paragraph for complex diagrams.
- **Never start with**: "Image of..." or "Picture of..." — screen readers already announce "image."
- **AI-generated images**: Always append `(AI-generated illustration)` at the end.
- **Decorative images**: Use `alt=""` (empty string). Never omit the `alt` attribute entirely.
- **Images containing text**: Alt text must include ALL text shown in the image.
- **Functional images** (links/buttons): Describe the action, not the image ("Search" not "magnifying glass").

### Long Description Pattern (Complex Diagrams)

```html
<figure style="margin: 25px 0; text-align: center;">
  <img src="..." alt="Diagram of the water cycle — see detailed description below"
       aria-describedby="water-cycle-desc" style="...">
  <figcaption>Figure 1: The water cycle</figcaption>
</figure>
<div id="water-cycle-desc" style="background-color: #f8f4f0; border-left: 4px solid #8C1D40; padding: 15px; border-radius: 0 8px 8px 0; margin: 10px 0;">
  <p style="color: #595959; font-size: 13px; margin: 0;">
    <strong>Image description:</strong> The diagram shows the continuous movement of water through Earth's systems.
    Evaporation rises from oceans (shown with upward blue arrows), forms clouds through condensation,
    falls as precipitation over land and sea, and returns to oceans through surface runoff and groundwater flow.
    Transpiration from plants contributes additional water vapor. Each stage is labeled with arrows showing direction of flow.
  </p>
</div>
```

---

## AI Disclosure Requirements

All AI-generated images in courses must include disclosure. This follows UNESCO and EDUCAUSE guidance.

### Caption Disclosure Format

```
[Figure caption text]
AI-generated illustration using [model name]. Not a factual photograph.
```

### Attribution Line in course-config.json

```json
{
  "source": {
    "type": "generated",
    "model": "imagen-4-standard",
    "prompt": "Clean educational diagram showing...",
    "generated_at": "2026-03-20T14:45:00Z",
    "ai_disclosure": "AI-generated illustration using Google Imagen 4"
  }
}
```

---

## Canvas Embedding Standards

### File Organization

All course images are uploaded to Canvas Files in a structured folder hierarchy:

```
course files/
  images/
    m0/          ← Module 0 images
    m1/          ← Module 1 images
    m2/          ← Module 2 images
    ...
    shared/      ← Cross-module images (logos, recurring diagrams)
```

### Embed URL Pattern

```html
<img src="/courses/{{COURSE_ID}}/files/{{FILE_ID}}/preview"
     alt="{{ALT_TEXT}}"
     style="max-width: 100%; height: auto;">
```

### Image Optimization

| Metric | Target |
|---|---|
| **Max file size** | 500KB for standard images, 200KB preferred |
| **Format** | PNG for diagrams/illustrations, JPEG for photographs, SVG for simple graphics |
| **Min width** | 800px for full-width images, 400px for side-by-side |
| **Max width** | 2048px (Canvas downscales beyond this) |
| **Color profile** | sRGB |

### Responsive Behavior

Always include these inline styles for responsive images:

```css
max-width: 100%; height: auto; display: block;
```

This ensures images scale on mobile devices within Canvas's responsive layout.
