Skip to content

Log: Learning Mascot Generator

Date: 2026-03-29 Skill: Book Installer > Learning Mascot Model: Claude Opus 4.6 (1M context) Task: Design and implement a learning mascot (pedagogical agent) for the Ecology intelligent textbook

Context

The user already has mascots in two other intelligent textbook projects:

  • Biology: Gregor the Tree Frog — lime-green tree frog, white lab coat, magnifying glass
  • Bioinformatics: Olli the Octopus — soft teal octopus, small round glasses, eight arms hinting at graph/network structure

The requirement was to create a mascot that is visually and conceptually distinct from both existing mascots.

Design Decisions

Character Type

Options presented:

Option Character Reasoning
A Bee Pollination, ecosystem services, interconnection, keystone species
B Fox Clever, adaptable, found across many biomes — ecological resilience
C Hawk / Eagle Apex predator, "seeing the big picture" — systems thinking
D Beaver Ecosystem engineer, builds and transforms habitats — sustainability
E Wolf Trophic cascades (Yellowstone), pack dynamics — community ecology

Claude's recommendation: Bee (iconic for ecology, visually distinct)

User's choice: Beaver — ecosystem engineer, builder, transformer of habitats

Personality Traits

Selected: Industrious, curious, practical, encouraging

Rationale: Matches the textbook's systems thinking focus. "Industrious" and "practical" connect to the beaver's role as an ecosystem engineer. "Curious" supports the scientific inquiry theme. "Encouraging" supports students through challenging content.

Name

Options presented:

Option Name Reasoning
A Bailey the Beaver Friendly, gender-neutral, easy to remember
B Birch the Beaver Nature connection (birch trees, beaver habitat)
C Bucky the Beaver Playful, energetic, memorable
D Brooks the Beaver Streams/watersheds — core ecology concept
E Echo the Beaver "Eco" + ripple effects through systems

Claude's recommendation: Echo (evokes "eco-logy" and cascading effects)

User's choice: Bailey — friendly, gender-neutral, easy to remember

Catchphrases

Options presented:

  • "Let's build on that!" — beaver + constructing knowledge
  • "Everything's connected!" — core ecology/systems thinking message
  • "Let's dam up some knowledge!" — playful beaver pun
  • "Let's dig into this!" — curiosity + beaver behavior

User's choice:

  • Primary: "Everything's connected!" — directly reflects the textbook's systems thinking theme
  • Secondary: "Let's build on that!" — beaver metaphor for building knowledge

Visual Appearance

Selected design:

  • Body: Warm brown fur with lighter tan underbelly
  • Features: Bright, curious dark eyes, friendly buck-toothed smile, broad flat tail
  • Accessory: Small green hard hat (matches site theme color primary: green)
  • Hands: Always free — no tools or props held (user specifically requested this for clear gesturing)
  • Art style: Modern flat vector, bold outlines, warm earthy colors

User's modification: Removed the originally proposed rolled-up blueprint/map. Kept hands completely free for gesturing across all poses. Retained the green hard hat.

Implementation Method

Selected: Custom CSS admonitions with body-floated images (Option 2 from the skill guide)

Key implementation details:

  • Mascot images are placed inside the admonition body as <img class="mascot-admonition-img">, floated left at 90px
  • Title bars are clean text only — no mascot icons in the title bar
  • Default MkDocs admonition icons are hidden via display: none on ::before
  • Requires md_in_html markdown extension for <img> tags inside admonitions
  • This matches the pattern used in the Biology project's mascot.css

Files Created

File Purpose
docs/img/mascot/image-prompts.md 7 fully self-contained AI image generation prompts
docs/css/mascot.css Custom admonition styles with body-floated mascot images
docs/learning-graph/mascot-test.md Test page showing all 7 admonition variants

Files Modified

File Change
mkdocs.yml Added css/mascot.css to extra_css; added mascot test page to nav
CLAUDE.md Added Bailey character guidelines, voice, placement rules, do's and don'ts

Image Generation

All 7 poses were generated by the user using ChatGPT/DALL-E with the prompts from image-prompts.md. Each prompt includes the full base character description inline (no [BASE] shorthand) for consistency.

Poses Generated

Pose Filename Usage
Neutral neutral.png General sidebars, default
Welcome welcome.png Chapter openings
Thinking thinking.png Key concepts and insights
Tip tip.png Helpful hints and study strategies
Warning warning.png Common mistakes and misconceptions
Celebration celebration.png Section completions and achievements
Encouraging encouraging.png Difficult content, student support

Post-Processing: Padding Trim

All 7 images were trimmed using the padding trimmer script to remove excess transparent padding added by the AI image generator:

1
python claude-skills/src/image-utils/trim-padding-from-image.py docs/img/mascot/FILENAME.png

Results:

Image Before After
neutral.png 1024x1024 623x793
welcome.png 1024x1024 655x778
thinking.png 1024x1024 522x852
tip.png 1024x1024 575x711
warning.png 1024x1024 663x722
celebration.png 1024x1024 633x897
encouraging.png 1024x1024 519x746

Skill Template Update

During this session, the upstream skill template was also updated:

File: claude-skills/skills/book-installer/references/learning-mascot.md

Key changes:

  1. Removed Options 1 (inline images) and 3 (JavaScript auto-detection) — consolidated to the single proven CSS admonition approach
  2. Removed all ::before title-bar icon CSS — mascot images never go in the title bar
  3. Added display: none rule for default MkDocs icons in mascot admonitions
  4. Changed image placement to body-floated <img class="mascot-admonition-img">
  5. Added md_in_html as a required markdown extension
  6. Updated mascot size from 60px to 90px
  7. Added rule that AI image prompts must be fully self-contained (no [BASE] shorthand)
  8. Added image path guidance explaining directory depth for correct src paths

Admonition Color Scheme

Admonition Type Title Bar Color Background Hex
mascot-welcome Forest green Light green #2e7d32 / #e8f5e9
mascot-thinking Warm brown Light brown #795548 / #efebe9
mascot-tip Teal Light teal #00897b / #e0f2f1
mascot-warning Red Light red #c62828 / #ffebee
mascot-celebration Purple Light purple #6a1b9a / #f3e5f5
mascot-encourage Blue Light blue #0277bd / #e1f5fe
mascot-neutral Slate gray Light gray #546e7a / #eceff1