@design-ai/cli 4.55.0

package/knowledge/illustration/mascot-design.md

@@ -0,0 +1,208 @@
+<!-- hand-written -->
+---
+title: Mascot design (characters and brand creatures)
+applies_to: [mascot, character, brand, korean]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Mascot design
+
+A mascot is a recurring character that **embodies the brand**. Done right (Kakao Friends, Duolingo's owl, Mailchimp's Freddie, Mint's piggy), the mascot becomes more recognizable than the wordmark.
+
+Done wrong, mascots feel childish, off-brand, or worse — distracting.
+
+This file covers when mascots fit, how to design them, and how to maintain them across surfaces.
+
+## When mascots fit
+
+| Brand context | Mascot fit |
+| --- | --- |
+| Consumer fintech (Toss, Kakao) | Strong fit |
+| Consumer wellness / education | Strong fit |
+| Children's apps | Strong fit (almost required) |
+| Fun / casual SaaS (Mailchimp, Slack-adjacent) | Good fit |
+| Enterprise B2B | Risky — usually feels off-brand |
+| Healthcare / financial services (B2B) | Bad fit — unprofessional |
+| Government / civic | Bad fit |
+| Luxury / premium consumer | Bad fit |
+
+The mascot must match brand voice. Toss's gentle "money characters" wouldn't work for Linear; Linear's geometric severity wouldn't work for Toss.
+
+## What makes a good mascot
+
+### 1. Distinctive silhouette
+
+You should recognize the mascot from a black silhouette alone. Test:
+- Print the mascot in solid black at 24px.
+- Show it to someone unfamiliar.
+- They should be able to say "that's a [thing]."
+
+If they can't — silhouette isn't strong enough.
+
+### 2. Simple geometry
+
+Mascots that scale to icon size and stay recognizable:
+- 5-10 primary shapes
+- 1-2 distinctive features (Duolingo owl: round body + green; Mint: piggy + green; Kakao Ryan: round + ear-less + impassive face)
+- Avoid: thin lines that disappear at small sizes; complex patterns that pixelate
+
+### 3. Consistent personality
+
+Mascots have a personality that comes through across poses:
+- Duolingo owl: cheerful but passive-aggressive (especially recent versions)
+- Kakao Ryan: stoic, expressionless, reactive
+- Mint piggy: friendly, neutral
+- Toss money: gentle, calm
+
+Define personality in 3-5 adjectives before the mascot is drawn. Otherwise, illustrators / animators interpret differently.
+
+### 4. Adaptable to expressions
+
+The mascot needs to express:
+- Happiness / success
+- Sadness / disappointment
+- Surprise / excitement
+- Concern / warning
+- Neutral / waiting
+
+Without each of these, the mascot can't appear in all the contexts a UI needs.
+
+### 5. Scalable across formats
+
+The mascot must work as:
+- 24-48px icon (app icon, tiny inline)
+- 100-200px spot illustration (empty / success / error states)
+- 400-1200px hero illustration
+- Animated (Lottie / Rive)
+- 3D / printed / sticker (merchandise)
+
+Test all sizes in the design phase.
+
+## Korean mascot economy
+
+Korea has a well-developed mascot culture:
+
+| Brand | Mascot | Style |
+| --- | --- | --- |
+| **Kakao** | Kakao Friends (라이언/어피치/무지/콘/네오/제이지/튜브/프로도) | Round, soft, expressive |
+| **Toss** | Money characters / generic round friends | Soft, calm, minimal |
+| **Naver** | NaverPay characters, LINE Friends | Range — minimal to playful |
+| **GS25** | 무무씨 | Friendly, retail-coded |
+| **Coupang** | Rocket / Pang | Energy, speed |
+| **TmoneyGO** | T-money character | Transit-coded |
+| **Pang Pang** (KEB Hana) | Bear character | Bank-warmth |
+
+Common traits in Korean mascots:
+- Round, plump silhouette (cute / 귀여움 / kawaii-adjacent)
+- Few facial features (Kakao Ryan style — no mouth)
+- Minimal expression range (subtlety > exaggeration)
+- Coordinated with brand color (Kakao yellow, Naver green)
+
+Korean B2C without a mascot reads as either premium-minimal (Toss-tier) or under-branded.
+
+## Designing a mascot
+
+### Brief
+
+Before drawing:
+1. **What is it?** (animal, abstract creature, object personified)
+2. **Why this?** (relevance to brand — Mint = piggy bank; Duolingo = wise owl; Kakao Ryan = was originally a lion concept stripped of mane)
+3. **Voice / personality** (3-5 adjectives)
+4. **Required expressions** (joy, sad, surprise, neutral — which 5-7?)
+5. **Required poses** (standing, waving, holding, falling, working — which 8-10?)
+6. **Color** (1 primary, max 1 accent)
+7. **Where will it appear?** (icon? hero? loading screen? animation?)
+
+### Design phase
+
+1. **20+ thumbnails** — sketches at 1cm size. Pick top 3.
+2. **Refinement** — tighten silhouette. Test against silhouette test.
+3. **Expression sheet** — same character, 5-7 expressions. Confirm consistency.
+4. **Pose sheet** — same character, 8-10 poses.
+5. **Style guide** — proportions, colors, line weight, off-limit modifications.
+
+### Style guide must include
+
+- **Construction grid** — proportions in head-units (head : body ratio).
+- **Allowed views** (front, 3/4, side — all? just one?)
+- **Forbidden modifications** (don't recolor, don't skew, don't add accessories without approval).
+- **Minimum size** — below this, simplify or use icon variant instead.
+- **Spacing rules** — clear space around mascot when adjacent to other elements.
+
+## Animation considerations
+
+Mascots are heavily animated. Key animations:
+
+| Animation | Use |
+| --- | --- |
+| **Idle** (subtle breathing / blinking) | Loading screens, ambient |
+| **Reaction** (success cheer, error sad) | Confirmation moments |
+| **Walk / move** | Onboarding, transitions |
+| **Talk / mouth movement** | Voice / chat moments |
+
+For animation: use Lottie or Rive (see [`motion/motion-tools.md`](../motion/motion-tools.md)). Designer creates in After Effects (Lottie) or rive.app (Rive); engineer drops in.
+
+Reduced-motion: show static frame (hero pose). Don't auto-loop on every screen — battery drain.
+
+## Mascot governance
+
+Mascots drift faster than other system elements. Without governance:
+- Different illustrators draw the mascot slightly differently.
+- Marketing redraws for one campaign and the redraw enters the system.
+- 18 months later, you have 3 versions of the mascot.
+
+Required governance:
+- **One owner** (illustrator or design lead).
+- **Version-controlled source files** (Figma library, Adobe Illustrator masters in repo).
+- **Mandatory review** for every new mascot illustration.
+- **Asset library** — engineers can't ship a mascot illustration not in the library.
+- **Refresh cadence** — every 18-24 months, full audit + retouch.
+
+## Cultural sensitivity
+
+Mascots represent the brand internationally if the brand goes global:
+
+- **Animal symbolism varies**: owl (wise in West / unlucky in some Asian contexts); pig (lucky in China / negative in Muslim-majority markets); white tiger (revered in Korea).
+- **Skin tone for human characters**: design with a range.
+- **Gender**: avoid heavily gender-coded mascots if global.
+- **Religious symbols**: avoid (crosses, lotus, etc.) unless intentional.
+
+Korean brand entering global market: many Korean mascots translate well (Kakao Friends are popular in Asia / Southeast Asia), but Western markets may need positioning work.
+
+## Mascot vs illustrator's brand
+
+A common mistake: the mascot's style becomes the illustrator's style, and as soon as the illustrator leaves, the brand's mascot drifts.
+
+Mitigation:
+- Document the mascot completely (no implicit knowledge in one person's head).
+- Treat the mascot as brand asset, not illustrator asset.
+- Source files belong to the company, not the freelancer.
+
+## When mascots become liabilities
+
+Mascots can outlive their welcome:
+- Mascot dates (1990s-style mascots aged badly into 2010s).
+- Mascot misaligns with brand evolution (childish mascot when brand goes premium).
+- Mascot becomes meme target (in unflattering ways).
+
+Plan for mascot retirement / redesign every 5-10 years. Sudden retirement causes user backlash (Mailchimp's Freddie redesign, Twitter logo replacement); plan transitions.
+
+## Don't
+
+- Don't add a mascot just to have one. The brand must need it.
+- Don't have multiple mascots that compete. Pick one primary; supporting cast is OK.
+- Don't put the mascot in every screen — overuse kills the magic.
+- Don't let the mascot drift across artists without governance.
+- Don't use the mascot in serious / sensitive contexts (errors involving money loss, account security failures). Drop the mascot for these moments.
+- Don't design the mascot before the brand voice is set.
+
+## Cross-reference
+
+- [`knowledge/illustration/illustration-systems.md`](illustration-systems.md) — system foundation
+- [`knowledge/illustration/spot-illustrations.md`](spot-illustrations.md) — mascot in spot illustrations
+- [`knowledge/illustration/hero-illustrations.md`](hero-illustrations.md) — mascot in heroes
+- [`knowledge/patterns/brand-identity.md`](../patterns/brand-identity.md) — brand foundation
+- [`knowledge/motion/motion-tools.md`](../motion/motion-tools.md) — animating mascots (Lottie / Rive)
+- [`knowledge/i18n/korean-app-store-visual.md`](../i18n/korean-app-store-visual.md) — Korean market visual conventions

package/knowledge/illustration/spot-illustrations.md

@@ -0,0 +1,246 @@
+<!-- hand-written -->
+---
+title: Spot illustrations (empty / success / error / onboarding)
+applies_to: [illustration, empty-state, error-state, onboarding]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Spot illustrations
+
+Spot illustrations are **purposeful, small** illustrations that appear at moments where the UI needs emotional clarity. Empty states, success confirmations, error pages, onboarding screens, paywall moments.
+
+This is the most common illustration use case. Get it right and the system works; get it wrong and every screen feels different.
+
+## What "spot" means
+
+- 80–240px square (display size).
+- One subject, one idea.
+- Conveys a single emotion or state.
+- Decorative or supplementary — never the only conveyance of meaning.
+
+Bigger than an icon (24–48px), smaller than a hero (400px+).
+
+## Five canonical spot moments
+
+### 1. Empty state — "no data yet"
+
+| Sub-context | Illustration suggestion |
+| --- | --- |
+| First-run empty (user has no data ever) | Encouraging, action-prompting (open box, blank canvas, sprout) |
+| Filtered empty (user filtered to nothing) | Magnifying glass, "no match" character |
+| Search empty (query returned nothing) | Same as filtered |
+| Failure empty (data load failed) | Use error state, not empty |
+
+**Voice**: encouraging, not pitying. "탐색 시작하기" not "데이터가 없습니다".
+
+Cite [`examples/component-empty-state.md`](../../examples/component-empty-state.md).
+
+### 2. Success state
+
+| Sub-context | Illustration suggestion |
+| --- | --- |
+| Payment success | Checkmark + confetti / receipt motif (use motion sparingly) |
+| Submission success | Letter sent, paper plane |
+| Account created | Welcome, sprout, key |
+| Goal completed | Trophy, milestone marker |
+
+**Voice**: warm, not over-the-top. Don't celebrate routine actions ("Logged in!" doesn't need a fireworks illustration).
+
+For Korean fintech 결제 완료: gentle checkmark + brand color, no confetti.
+
+### 3. Error state
+
+| Sub-context | Illustration suggestion |
+| --- | --- |
+| 404 not found | Lost character, broken link, signpost |
+| 500 server error | Tools / wrench / "we're fixing it" |
+| Permission denied | Locked door, "no entry" |
+| Rate limited / quota | Hourglass, "slow down" |
+| Generic failure | Cloud with X, simple sad-face symbol |
+
+**Voice**: humble, helpful. Take responsibility. "잠시 후 다시 시도해 주세요" is better than "Something went wrong."
+
+Avoid:
+- Cartoon mascots crying (childish).
+- Skull / death / ominous imagery (alarming).
+- Robots / 1990s clip-art (dated).
+
+### 4. Onboarding step
+
+| Sub-context | Illustration suggestion |
+| --- | --- |
+| Welcome | Wave / handshake / sunrise |
+| Setup step 1 | Door opening, key, blank canvas |
+| Permission request | Specific to permission (camera = lens, location = pin, notification = bell) |
+| Final / "you're ready" | Rocket, ribbon, completed checklist |
+
+**Voice**: encouraging, low-friction. Each illustration unique to its step (no repetition of one mascot pose).
+
+### 5. Permissions / privacy explainer
+
+| Sub-context | Illustration suggestion |
+| --- | --- |
+| Notification permission | Bell with notification dot |
+| Location permission | Pin on map |
+| Camera / mic | Lens / microphone outline |
+| Contacts | People silhouettes |
+| Biometric (Face ID, fingerprint) | Face outline / fingerprint |
+
+**Voice**: trust-building. Show what's being asked for visually so the user understands.
+
+## Composition rules
+
+### Single subject
+
+One main element. Not five things in one illustration.
+
+```
+✓ Empty state: one open box.
+✗ Empty state: open box, sad face, magnifier, "no data" text in illustration, arrows pointing.
+```
+
+### Use white space (or background)
+
+Spot illustrations breathe. Don't fill the bounding box edge-to-edge — leave 10-20% padding inside the canvas.
+
+### Centered or off-center consistently
+
+Pick a rule: all spot illustrations centered, OR all left-anchored, OR all bottom-anchored. Mixing positions across the system reads as inconsistent.
+
+### Color anchoring
+
+One **dominant** color (usually `--color-brand-default` or `--color-brand-light`).
+One **secondary** color (usually `--color-fg-muted` or `--color-bg-secondary`).
+That's it. No additional colors.
+
+Exception: skin tones in character illustrations require a third token (see [`mascot-design.md`](mascot-design.md)).
+
+### Stroke vs fill
+
+Match the system's chosen style — see [`illustration-systems.md`](illustration-systems.md) "Defining your style".
+
+## Sizing rules
+
+| Context | Size |
+| --- | --- |
+| Mobile empty state | 120–160px |
+| Desktop empty state | 160–240px |
+| Inline (within a card / tile) | 80–120px |
+| Onboarding screen (modal) | 200–280px |
+| Onboarding screen (full-bleed) | 240–320px |
+| Toast / inline notification | None — use icon, not illustration |
+
+Don't go larger than 320px for spot illustrations. That's hero territory.
+
+## Layout patterns
+
+### Empty state layout
+
+```
+        [illustration  120-200px]
+              ↑ centered
+        [Headline — 18-22px, semibold]
+        [Description — 14-16px, regular, max 2 lines]
+              ↓ optional
+              [Primary CTA]
+              [Secondary link]
+```
+
+Total vertical: ~280-360px. Centered in available space.
+
+### Error state layout (full-page 404)
+
+```
+        [Illustration 200-280px]
+        
+        404
+        [Headline]
+        [Description with link back]
+        [Search OR Home CTA]
+```
+
+### Onboarding step layout
+
+```
+        [Illustration 240-320px]
+        [Headline]
+        [Description]
+        ────
+        [Step indicator 1/3]
+        [Skip] [Next →]
+```
+
+## Production checklist
+
+For each spot illustration:
+
+- [ ] Renders correctly at 1×, 2×, 3× (test on retina + non-retina)
+- [ ] Has a light AND dark mode variant (or uses theme tokens)
+- [ ] Optimized SVG (no inline styles, no metadata, see [`svg-optimization.md`](svg-optimization.md))
+- [ ] Accessible: `<img alt="">` if decorative, `<img alt="...">` if conveying state
+- [ ] File size < 30kB SVG (most should be < 10kB)
+- [ ] Named per convention: `illo-{state}-{specific}.svg` (e.g., `illo-empty-search.svg`)
+- [ ] Exported at native size + 2x bitmap fallback for non-SVG contexts (email, etc.)
+
+## Accessibility
+
+Spot illustrations are usually decorative — the surrounding text already conveys meaning. In that case:
+
+```html
+<img src="empty-search.svg" alt="" aria-hidden="true" />
+<h2>찾으시는 결과가 없어요</h2>
+```
+
+Don't add redundant alt text ("a person looking through a magnifying glass at empty space"). The text already says what's happening.
+
+If the illustration **is** the only conveyance (e.g., a status badge), then alt text is required:
+
+```html
+<img src="payment-success.svg" alt="결제가 완료되었습니다" />
+```
+
+For animated illustrations (Lottie / SVG SMIL): respect `prefers-reduced-motion` — show the static frame. See [`motion/motion-tools.md`](../motion/motion-tools.md).
+
+## Theming
+
+SVG illustrations should theme via `currentColor` and CSS variables:
+
+```svg
+<svg viewBox="0 0 240 240" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="120" cy="120" r="100" fill="var(--color-brand-light, #E0F2FF)" />
+  <path d="..." stroke="currentColor" stroke-width="2" fill="none" />
+</svg>
+```
+
+```css
+.empty-state-illustration {
+  color: var(--color-brand-default);
+}
+
+@media (prefers-color-scheme: dark) {
+  /* CSS variable cascade handles it; no per-illustration override needed */
+}
+```
+
+Avoid baking brand color into the SVG as a literal hex. The whole point of a system is one source of truth.
+
+## Don't
+
+- Don't use one mascot for all 50 spot illustrations — boring, repetitive.
+- Don't use 5 different mascots — fragmenting.
+- Don't make empty-state illustrations bigger than the headline. The headline is the message.
+- Don't draw something that contradicts the message ("error" with a happy character).
+- Don't over-celebrate routine success ("You added 1 item to cart!" with confetti = annoying).
+- Don't hardcode brand color in the SVG file. Use `currentColor` or CSS variables.
+- Don't ship the same illustration for "no data" and "no search results" — different moments need different cues.
+
+## Cross-reference
+
+- [`knowledge/illustration/illustration-systems.md`](illustration-systems.md) — system foundation
+- [`knowledge/illustration/hero-illustrations.md`](hero-illustrations.md) — large brand-led
+- [`knowledge/illustration/mascot-design.md`](mascot-design.md) — when characters are central
+- [`knowledge/illustration/svg-optimization.md`](svg-optimization.md) — file optimization
+- [`examples/component-empty-state.md`](../../examples/component-empty-state.md) — empty state component
+- [`knowledge/motion/motion-tools.md`](../motion/motion-tools.md) — Lottie for animated spots