@design-ai/cli 4.55.0

package/knowledge/icons/curated-sets.md

@@ -0,0 +1,225 @@
+---
+title: Curated icon sets
+source: refs/ui-ux-pro-max/src/ui-ux-pro-max/data/icons.csv
+upstream: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
+extracted_at: 2026-05-19
+applies_to: [icons, react, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Curated icon sets
+
+Common UI icons indexed by **library** and **category**. Pick a single library per project — mixing icon sets in one UI looks unprofessional (different stroke weights, different cap rules).
+
+## Libraries indexed
+
+| Library | Icons cataloged | Strengths |
+| --- | --- | --- |
+| **Phosphor** | 100 | Most variants (Thin/Light/Regular/Bold/Fill/Duotone), 1200+ icons. Clean for product UIs. |
+| **Phosphor (primary) + Heroicons (fallback)** | 1 | — |
+| **Phosphor (react-native)** | 4 | — |
+
+## Common icons by category
+
+### Action
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `plus` | add create new insert | Phosphor | Add button create new item |
+| `minus` | remove subtract decrease delete | Phosphor | Remove item quantity decrease |
+| `trash` | delete remove discard bin | Phosphor | Delete action destructive |
+| `pencil-simple` | pencil modify change update | Phosphor | Edit button modify content |
+| `floppy-disk` | disk store persist save | Phosphor | Save button persist changes |
+| `download-simple` | export save file download | Phosphor | Download file export |
+| `upload-simple` | import file attach upload | Phosphor | Upload file import |
+| `copy` | duplicate clipboard paste | Phosphor | Copy to clipboard |
+| `share` | social distribute send | Phosphor | Share button social |
+| `magnifying-glass` | find lookup filter query | Phosphor | Search input bar |
+| `funnel` | sort refine narrow options | Phosphor | Filter dropdown sort |
+| `gear` | gear cog preferences config | Phosphor | Settings page configuration |
+
+### Commerce
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `shopping-cart` | cart checkout basket buy | Phosphor | Shopping cart e-commerce |
+| `shopping-bag` | purchase buy store bag | Phosphor | Shopping bag purchase |
+| `credit-card` | payment card checkout stripe | Phosphor | Payment credit card |
+| `currency-dollar` | money price currency cost | Phosphor | Price money currency |
+| `tag` | label price discount sale | Phosphor | Price tag label |
+| `gift` | present reward bonus offer | Phosphor | Gift reward offer |
+| `percent` | discount sale offer promo | Phosphor | Discount percentage sale |
+
+### Communication
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `envelope` | email message inbox letter | Phosphor | Email contact inbox |
+| `chat-circle` | chat comment bubble conversation | Phosphor | Chat comment message |
+| `phone` | call mobile telephone contact | Phosphor | Phone contact call |
+| `paper-plane-tilt` | submit dispatch message airplane | Phosphor | Send message submit |
+| `bell` | notification alert ring reminder | Phosphor | Notification bell alert |
+
+### Data
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `chart-bar` | analytics statistics graph metrics | Phosphor | Bar chart analytics |
+| `chart-pie` | statistics distribution breakdown | Phosphor | Pie chart distribution |
+| `trend-up` | growth increase positive trend | Phosphor | Growth trend positive |
+| `trend-down` | decline decrease negative trend | Phosphor | Decline trend negative |
+| `activity` | pulse heartbeat monitor live | Phosphor | Activity monitor pulse |
+| `database` | storage server data backend | Phosphor | Database storage |
+
+### Development
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `code` | develop programming syntax html | Phosphor | Code development |
+| `terminal` | console cli command shell | Phosphor | Terminal console |
+| `git-branch` | version control branch merge | Phosphor | Git branch |
+| `github-logo` | repository code open source | Phosphor | GitHub repository |
+
+### Device
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `device-mobile` | mobile phone device touch | Phosphor | Mobile smartphone |
+| `device-tablet` | ipad device touch screen | Phosphor | Tablet device |
+| `monitor` | desktop screen computer display | Phosphor | Desktop monitor |
+| `laptop` | notebook computer portable device | Phosphor | Laptop computer |
+| `printer` | print document output paper | Phosphor | Printer print |
+
+### Files
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `file` | document page paper doc | Phosphor | File document |
+| `file-text` | document text page article | Phosphor | Text document article |
+| `folder` | directory organize group files | Phosphor | Folder directory |
+| `folder-open` | expanded browse files view | Phosphor | Open folder browse |
+| `paperclip` | attachment attach file link | Phosphor | Attachment paperclip |
+| `link` | url hyperlink chain connect | Phosphor | Link URL hyperlink |
+| `clipboard` | paste copy buffer notes | Phosphor | Clipboard paste |
+
+### Guideline
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `icon-fallback-rules` | icon fallback, phosphor, heroicons, any icon, extended set | Phosphor (primary) + Heroicons (fallback) | Icon library strategy and fallback rules |
+
+### Layout
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `grid-four` | tiles gallery layout dashboard | Phosphor | Grid layout gallery |
+| `list-bullets` | rows table lines items | Phosphor | List view rows |
+| `columns` | layout split dual sidebar | Phosphor | Column layout split |
+| `arrows-out` | fullscreen expand enlarge zoom | Phosphor | Fullscreen maximize |
+| `arrows-in` | reduce shrink collapse exit | Phosphor | Minimize reduce |
+| `sidebar` | panel drawer navigation menu | Phosphor | Sidebar panel |
+
+### Location
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `map-pin` | location marker place address | Phosphor | Location pin marker |
+| `map` | directions navigate geography location | Phosphor | Map directions |
+| `compass` | compass direction pointer arrow | Phosphor | Navigation compass |
+| `globe` | world international global web | Phosphor | Globe world |
+
+### Media
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `image` | photo picture gallery thumbnail | Phosphor | Image photo gallery |
+| `video` | movie film play record | Phosphor | Video player media |
+| `play` | start video audio media | Phosphor | Play button video audio |
+| `pause` | stop halt video audio | Phosphor | Pause button media |
+| `speaker-high` | sound audio speaker music | Phosphor | Volume audio sound |
+| `microphone` | microphone record voice audio | Phosphor | Microphone voice record |
+| `camera` | photo capture snapshot picture | Phosphor | Camera photo capture |
+
+### Navigation
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `list` | hamburger menu navigation toggle bars | Phosphor | Mobile navigation drawer toggle sidebar |
+| `arrow-left` | back previous return navigate | Phosphor | Back button breadcrumb navigation |
+| `arrow-right` | next forward continue navigate | Phosphor | Forward button next step CTA |
+| `caret-down` | dropdown expand accordion select | Phosphor | Dropdown toggle accordion header |
+| `caret-up` | collapse close accordion minimize | Phosphor | Accordion collapse minimize |
+| `house` | homepage main dashboard start | Phosphor | Home navigation main page |
+| `x` | close cancel dismiss remove exit | Phosphor | Modal close dismiss button |
+| `arrow-square-out` | open new tab external link | Phosphor | External link indicator |
+
+### Security
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `lock` | secure password protected private | Phosphor | Lock secure |
+| `lock-open` | open access unsecure public | Phosphor | Unlock open |
+| `shield` | protection security safe guard | Phosphor | Shield protection |
+| `key` | password access unlock login | Phosphor | Key password |
+| `eye` | view show visible password | Phosphor | Show password view |
+| `eye-slash` | hide invisible password hidden | Phosphor | Hide password |
+
+### Social
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `heart` | like love favorite wishlist | Phosphor | Like favorite love |
+| `star` | rating review favorite bookmark | Phosphor | Star rating favorite |
+| `thumbs-up` | like approve agree positive | Phosphor | Like approve thumb |
+| `thumbs-down` | dislike disapprove disagree negative | Phosphor | Dislike disapprove |
+| `bookmark` | save later favorite mark | Phosphor | Bookmark save |
+| `flag` | report mark important highlight | Phosphor | Flag report |
+
+### Status
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `check` | success done complete verified | Phosphor | Success state checkmark |
+| `check-circle` | success verified approved complete | Phosphor | Success badge verified |
+| `x-circle` | error failed cancel rejected | Phosphor | Error state failed |
+| `warning` | warning caution attention danger | Phosphor | Warning message caution |
+| `warning-circle` | info notice information help | Phosphor | Info notice alert |
+| `info` | information help tooltip details | Phosphor | Information tooltip help |
+| `circle-notch` | loading spinner processing wait | Phosphor | Loading state spinner |
+| `clock` | time schedule pending wait | Phosphor | Pending time schedule |
+
+### Style Config
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `bold-typography-icon-system` | bold typography, editorial, mono label, phosphor, weight reg | Phosphor (react-native) | Bold Typography Mobile style: weight="regular". Size 20px fo |
+| `cyberpunk-icon-system` | cyberpunk, neon, glow, hud, phosphor, weight regular, accent | Phosphor (react-native) | Cyberpunk Mobile HUD style: weight="regular", color={colors. |
+| `academia-icon-system` | academia, library, brass, ornate, phosphor, weight thin, mut | Phosphor (react-native) | Academia (Scholarly Mobile) style: weight="thin" (thin engra |
+| `web3-bitcoin-icon-system` | web3, bitcoin, defi, crypto, neon orange, holographic, blurv | Phosphor (react-native) | Bitcoin DeFi Mobile style: weight="regular", color={colors.b |
+
+### Time
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `calendar` | date schedule event appointment | Phosphor | Calendar date |
+| `arrows-clockwise` | reload sync update refresh | Phosphor | Refresh reload |
+| `arrow-counter-clockwise` | undo back revert history | Phosphor | Undo revert |
+| `arrow-clockwise` | redo forward repeat history | Phosphor | Redo forward |
+
+### User
+| Icon | Keywords | Library | Best for |
+| --- | --- | --- | --- |
+| `user` | profile account person avatar | Phosphor | User profile account |
+| `users` | team group people members | Phosphor | Team group members |
+| `user-plus` | add invite new member | Phosphor | Add user invite |
+| `sign-in` | signin authenticate enter | Phosphor | Login signin |
+| `sign-out` | signout exit leave logout | Phosphor | Logout signout |
+
+## Picking an icon library
+
+| Situation | Pick |
+| --- | --- |
+| New React project, Tailwind, default-shadcn | **Lucide** |
+| Need many weight variants (thin/regular/bold) | **Phosphor** |
+| Heavy dashboard / data tools | **Tabler** |
+| Material Design alignment | **Material Symbols** (variable font) |
+| Tailwind-team alignment | **Heroicons** |
+| Multi-language support including CJK glyphs | **Remix** |
+
+## Rules
+
+1. **One library per UI.** Mixing produces inconsistent stroke widths and cap rules.
+2. **Stay in one weight.** If you use Phosphor's `regular`, don't sprinkle `bold` for emphasis — pick weight by component (e.g., menu = regular, primary action = bold) and apply consistently.
+3. **24px is the default size.** 16px for inline-with-text, 32–48px for hero/empty states.
+4. **Icons that convey meaning need an accessible name.** `<Icon aria-label="Close">` or paired text. Decorative icons get `aria-hidden="true"`.
+5. **Match icon size to text leading.** If body line-height is 24px, body-line icons should be 16–20px (sit on the cap-height).
+
+## Cross-reference
+
+- [knowledge/components/INDEX.md](../components/INDEX.md) — components that consume icons
+- [knowledge/a11y/keyboard-and-focus.md](../a11y/keyboard-and-focus.md) — icon accessibility

package/knowledge/illustration/hero-illustrations.md

@@ -0,0 +1,234 @@
+<!-- hand-written -->
+---
+title: Hero illustrations (marketing landing-page artwork)
+applies_to: [illustration, marketing, hero, landing]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Hero illustrations
+
+Hero illustrations are large, brand-led illustrations that anchor a landing page or major marketing surface. Larger investment, longer-lasting, harder to get right than spot illustrations.
+
+## What "hero" means
+
+- 480–1200px wide (display).
+- Often above-the-fold or above-the-section-fold.
+- Carries significant brand weight — replaces the photo / video that would otherwise be in that slot.
+- Usually one per major page section (1 in hero, 1 per feature, etc.).
+
+## Three hero illustration archetypes
+
+### 1. Conceptual / metaphorical
+
+The illustration represents an abstract concept the product enables.
+
+```
+"Money flows automatically" → illustration of stylized money trails connecting accounts.
+"Code reviews in 30 seconds" → illustration of code with checkmarks emerging.
+"Your team, in sync" → people visualized as gears or musical notes harmonizing.
+```
+
+Strengths:
+- Evocative, memorable.
+- Communicates value beyond what a screenshot shows.
+
+Risks:
+- Easy to be vague ("clouds and arrows" mean nothing).
+- Easy to be cliché (lightbulb = idea, gears = work).
+
+### 2. Product-in-context (illustrated mockup)
+
+A stylized illustration of the product being used — phone in hand, laptop with the dashboard rendered as illustration.
+
+```
+[Illustrated phone outline] [actual screenshot inside]
+```
+
+Or fully illustrated:
+
+```
+[Illustrated person] [holding illustrated phone] [showing illustrated app]
+```
+
+Strengths:
+- Shows the product without committing to a real screenshot (which dates fast).
+- Easier to make consistent across pages.
+
+Risks:
+- Can feel less authentic than a real screenshot.
+- Detail level must match throughout.
+
+### 3. Character-driven scene
+
+Mascot or human characters in a scene that depicts product usage or value.
+
+```
+[Character A using product, Character B receiving the result]
+```
+
+Strengths:
+- Strong emotional connection.
+- Memorable.
+
+Risks:
+- Production cost (good character art is expensive).
+- Inclusivity concerns (characters represent people; representation matters).
+- Drift across illustrations (hard to keep characters on-model).
+
+## Production scope
+
+Hero illustrations are an order of magnitude more work than spot illustrations:
+
+| Type | Production hours (rough) |
+| --- | --- |
+| Spot illustration (existing system) | 2-6 |
+| Spot illustration (new style) | 8-16 |
+| Hero illustration (existing system) | 12-24 |
+| Hero illustration (new style / character) | 40-80+ |
+
+Plan accordingly. Hero illustrations should be high-leverage (used on the landing page for years) — don't make a custom hero for every minor page.
+
+## Composition
+
+### Subject placement
+
+| Pattern | Use |
+| --- | --- |
+| Centered | Brutalist hero, balanced text-illustration relationship |
+| Right-anchored | Text-led layout (text left, illustration right) |
+| Left-anchored | Illustration-led layout (illustration left, text right) |
+| Diagonal / dynamic | Stronger motion / energy |
+| Background-spanning | Full-bleed, text overlays on safe area |
+
+The illustration's placement must coordinate with the page layout.
+
+### Eye flow
+
+Illustration directs the eye. If a character is looking at something, the user follows that gaze. Use this:
+
+- Character looking at the headline → user reads headline.
+- Character looking at CTA → user clicks CTA.
+- Character looking at viewer → user feels addressed (works for testimonials).
+
+Don't have characters looking off-frame at nothing — wastes attention.
+
+### Aspect ratio
+
+| Surface | Ratio |
+| --- | --- |
+| Desktop hero | 16:9 or 4:3 |
+| Mobile hero | 4:5 or 1:1 (taller, fewer landscape illustrations work on phone) |
+| Sidebar / column | 1:1 |
+| Section banner | 16:5 (wide thin) |
+
+Plan multiple aspect ratios from the start. Cropping a 16:9 illustration to 4:5 on mobile rarely works.
+
+## Color and brand
+
+Hero illustrations carry more brand color than spot illustrations:
+
+- **Primary brand color**: 30-50% of illustration's visual weight.
+- **Secondary brand colors**: 20-30%.
+- **Neutrals (light/mid/dark)**: 20-30%.
+- **Accent colors**: max 10%, only if system permits.
+
+Avoid 5+ colors of equal weight — looks chaotic.
+
+Bake colors into tokens, not raw hex. For dark mode: produce a separate variant or use `currentColor` + CSS variables strategically.
+
+## Detail level
+
+A hero illustration has more detail than a spot. Define the level:
+
+| Level | Lines | Shapes | Surface |
+| --- | --- | --- | --- |
+| Low detail | 5-15 | 10-25 | Most spots |
+| Medium detail | 15-50 | 25-100 | Most heroes |
+| High detail | 50+ | 100+ | Editorial heroes |
+
+Match across the system. Don't have one feature page with a 20-shape illustration and another with a 200-shape illustration.
+
+## Animation in heroes
+
+Hero illustrations can be:
+- **Static** (default) — fastest load, most reliable.
+- **Looped** (subtle ambient motion — floating shapes, breathing) — adds life, watch performance.
+- **Scroll-driven** — illustration changes as user scrolls (advanced; performance-heavy).
+
+If animating: see [`motion/marketing-motion.md`](../motion/marketing-motion.md) and [`motion/motion-tools.md`](../motion/motion-tools.md). Lottie or Rive likely.
+
+## Performance
+
+Heroes are above-the-fold. They impact LCP:
+
+| Format | Typical hero file size | LCP impact |
+| --- | --- | --- |
+| SVG (medium detail) | 30-100kB | Negligible |
+| SVG (high detail) | 100-400kB | Moderate; consider WebP fallback |
+| PNG (1x) | 200-800kB | High |
+| PNG (2x retina) | 800kB-3MB | Severe |
+| WebP | 100-400kB (vs PNG) | Better than PNG |
+| Lottie JSON | 50-300kB | Moderate (renders after JSON parse) |
+| Lottie .lottie binary | 30-150kB | Moderate |
+
+For SVG with > 200 shapes: bench against bitmap. Sometimes a 200kB WebP is faster to render than a 100kB SVG with hundreds of paths.
+
+Always: lazy-load below-the-fold heroes; preload above-the-fold; provide poster image for animated heroes.
+
+## Korean market — hero illustrations
+
+Korean B2C / fintech hero illustrations follow distinct conventions:
+
+- **Mascot-led** — Kakao Friends (라이언/어피치), Toss money characters, NaverPay characters dominate. Big-name brands.
+- **Soft, rounded, warm** — pastel + brand color, less stark than Western minimal.
+- **Less abstract** — Korean B2C audiences trend toward concrete imagery (a real character, a real action) over abstract metaphor.
+- **High emotion** — characters express clear feelings (joy, calm, focus). Not the cool detachment of Linear / Stripe illustrations.
+
+For Korean B2B (enterprise SaaS): still leans more abstract / geometric, similar to Western styles.
+
+See [`mascot-design.md`](mascot-design.md) for character work depth.
+
+## Inclusive representation
+
+Hero illustrations with characters have representation concerns:
+
+- **Skin tones**: include a range, not all one tone.
+- **Body types**: not all thin / all stylized in one direction.
+- **Ages**: include older / younger characters where appropriate to the audience.
+- **Disability**: include canes, wheelchairs, hearing aids when relevant (and not just in "accessibility-themed" sections).
+- **Gender**: don't default all professional roles to one gender.
+
+For Korean market: same principles apply, with Korean / Asian feature representation as primary. Avoid Western-coded features in mascot characters intended for Korean audiences (looks foreign).
+
+## Consistency across heroes
+
+For multi-page sites with multiple heroes:
+
+- Same character set (or same mascot) across all heroes.
+- Same line weight / fill rules.
+- Same color palette.
+- Same perspective (all front-view, or all isometric — don't mix).
+- Same level of detail.
+
+Create a **hero illustration spec sheet** at the system level with these rules locked.
+
+## Don't
+
+- Don't ship a hero illustration that doesn't match the headline. Visual + text dissonance.
+- Don't use stock hero illustrations on a serious B2B SaaS landing page — every product has the same Storyset hero.
+- Don't ignore mobile aspect ratio at hero design time. Phone-first redesign is more expensive than dual-aspect from the start.
+- Don't bake brand color as raw hex — use tokens / CSS vars.
+- Don't go above 400kB without a strong reason. There's almost always a smaller way.
+- Don't auto-loop a busy hero (motion fatigue, battery drain).
+
+## Cross-reference
+
+- [`knowledge/illustration/illustration-systems.md`](illustration-systems.md) — system foundation
+- [`knowledge/illustration/spot-illustrations.md`](spot-illustrations.md) — small purposeful illustrations
+- [`knowledge/illustration/mascot-design.md`](mascot-design.md) — character work
+- [`knowledge/illustration/svg-optimization.md`](svg-optimization.md) — performance
+- [`knowledge/patterns/landing-hero-design.md`](../patterns/landing-hero-design.md) — overall hero strategy
+- [`knowledge/motion/marketing-motion.md`](../motion/marketing-motion.md) — animating heroes
+- [`examples/component-hero-block.md`](../../examples/component-hero-block.md) — hero component spec

package/knowledge/illustration/illustration-systems.md

@@ -0,0 +1,221 @@
+<!-- hand-written -->
+---
+title: Illustration systems (style, voice, system design)
+applies_to: [illustration, brand, marketing, empty-states]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Illustration systems
+
+Illustration is **brand-bearing** in a way most UI elements aren't. A button is a button. A spot illustration says "this is what we feel like." Inconsistent illustration reads as more amateurish than inconsistent typography.
+
+This file is the foundation for [`spot-illustrations.md`](spot-illustrations.md), [`hero-illustrations.md`](hero-illustrations.md), [`mascot-design.md`](mascot-design.md), and [`svg-optimization.md`](svg-optimization.md). Read these first.
+
+## What an illustration system is
+
+A reusable, opinionated set of:
+1. **Style rules** — line weight, color treatment, geometry, perspective.
+2. **Voice rules** — what feeling illustrations should convey.
+3. **Asset library** — the actual SVG / PNG / Lottie files.
+4. **Usage guidelines** — when to use illustration vs photo vs icon vs nothing.
+5. **Production rules** — how new illustrations are made consistent with existing.
+
+Without these: every illustrator (or every AI prompt) outputs different work. The system breaks within 3 months.
+
+## Six common illustration styles
+
+| Style | Look | Use |
+| --- | --- | --- |
+| **Flat geometric** | 2-color, no gradients, hard edges | Default for SaaS, fintech, product UI |
+| **Soft 3D** | Rounded, gradient-shaded, isometric | Premium consumer (Notion, Stripe ad units) |
+| **Hand-drawn / sketchy** | Imperfect lines, organic | Approachable, casual brands (Linear illustrations, Mailchimp) |
+| **Mascot-driven** | Recurring characters | Kakao, Toss, fintech consumer |
+| **Editorial** | Magazine-style, sophisticated | Long-form content, publications |
+| **Generative / AI hybrid** | Distinctive AI-look + human curation | Linear, Midjourney's own marketing, 2024+ |
+
+A system picks **one** primary style. Not two. Mixing flat-geometric with soft-3D in the same product reads as different brands.
+
+## Defining your style
+
+Spec the following before producing any illustration:
+
+### Geometric vs organic
+
+| | Geometric | Organic |
+| --- | --- | --- |
+| Lines | Straight, 45°/90°, perfect arcs | Curved, hand-drawn, irregular |
+| Shapes | Circles, rectangles, simple polygons | Blobs, irregular silhouettes |
+| Feeling | Precise, technical, modern | Warm, approachable, human |
+
+Pick one bias. Most fintech leans geometric; most consumer / wellness leans organic.
+
+### Line weight
+
+- **Stroke-only**: 1.5px or 2px stroke, no fill. Lightweight, modern.
+- **Stroke + fill**: stroke for outline, flat fill inside. Most common.
+- **Fill-only**: no stroke, color blocks define shapes. Cleanest at small sizes.
+- **Mixed weights**: thicker outline + thinner internal lines. Editorial feel.
+
+Stick to one rule. Don't have stroke widths varying between illustrations.
+
+### Color treatment
+
+- **Monochromatic** (one hue + tints/shades) — most restrained, brand-strong.
+- **Brand palette** (uses 3-5 brand tokens only) — most common.
+- **Limited extended** (brand + 2-3 accent neutrals) — for variety in long marketing pages.
+- **Full color** — only for editorial / hero illustrations; usually wrong for systems.
+
+Specify **which tokens** an illustration may use. E.g., "Spot illustrations use `--color-brand-default`, `--color-brand-light`, and `--color-fg-on-bg`. No other colors permitted."
+
+### Geometry rules
+
+- **Grid alignment** — all anchor points snap to 8px / 16px grid for crispness.
+- **Corner radius** — all rounded corners share one radius (e.g., 4px), or follow a tier (4px small, 8px medium, 16px hero).
+- **Stroke caps** — round vs square. Pick one.
+- **Stroke joins** — round vs miter. Pick one.
+
+### Perspective
+
+- **Flat / 2D** — most flexible, easiest to produce.
+- **Isometric** — 30°/60°/90° three-quarter view. Premium, more production cost.
+- **Front-view only** — rigid but consistent.
+- **Mixed** — usually wrong.
+
+## Voice — what illustrations should *feel*
+
+Illustration carries emotional weight. Define voice in 3-5 adjectives:
+
+| Brand | Illustration voice |
+| --- | --- |
+| Toss | Calm, gentle, money-warm |
+| Linear | Sharp, futuristic, controlled |
+| Stripe | Refined, geometric, technical-but-elegant |
+| Kakao | Friendly, character-driven, playful |
+| Notion | Approachable, human, slightly hand-drawn |
+
+Include voice in the system spec. Without voice, illustrators interpret style rules differently and the work drifts.
+
+## When to use illustration
+
+| Surface | Illustration appropriate? |
+| --- | --- |
+| Empty state | Yes — the canonical use |
+| Success / error / warning state | Yes — adds emotional clarity |
+| Onboarding | Yes — reduces friction |
+| Marketing hero | Sometimes — competing with photo / video |
+| Feature explanation | Yes — when concept is abstract |
+| App icon | No — that's identity design |
+| Inside dashboards / data UIs | No — visual noise |
+| Inside forms | No — distracts from input |
+| Inside dense product UI | No — generally |
+
+Default: NO illustration in product UI surfaces. Reserve for moments where it adds emotional information (empty / success / error / onboarding / marketing).
+
+## When NOT to use illustration
+
+- "Just because the page looks empty." Empty pages aren't broken — they're informative. Use illustration only if the user needs encouragement to act.
+- "To fill space." Whitespace is a feature.
+- "Because the brand is fun." Personality belongs in voice, color, motion. Not every screen needs a character.
+- "To replace explanation." Illustration supplements text, doesn't replace it.
+
+## Illustration vs photo vs icon vs nothing
+
+| | Illustration | Photo | Icon | Nothing |
+| --- | --- | --- | --- | --- |
+| Brand-bearing | High | Medium-low | Low | — |
+| Production cost | Medium-high | High (good photos) | Low | Zero |
+| Scales to size | Excellent (vector) | Limited | Excellent | — |
+| Consistency in system | Hard but possible | Hardest | Easy | — |
+| Performance cost | Low (SVG) | High (image) | Lowest | Zero |
+| When right | Branded moments, emotional surfaces | Real-world products, testimonial portraits | Inline UI, navigation | Dense data, forms, lists |
+
+Use the right one. Don't use illustration for everything.
+
+## System governance
+
+A real system needs:
+
+1. **Source files** — Figma library or Adobe Illustrator masters in version control.
+2. **Naming convention** — e.g., `illo-empty-search.svg`, `illo-success-payment.svg`, `illo-hero-onboarding-01.svg`.
+3. **Required reviews** — every new illustration reviewed against style + voice rules before merging.
+4. **Refresh cadence** — illustration ages faster than icons. Plan to refresh every 18-24 months.
+
+## Illustration kit options
+
+For teams without a custom system, start with a kit:
+
+| Kit | Style | License | Cost |
+| --- | --- | --- | --- |
+| **unDraw** | Flat geometric, 1-color | MIT-ish | Free |
+| **Storyset by Freepik** | Multiple styles, customizable | Free with attribution / Premium | Free / Paid |
+| **IconScout illustrations** | Many styles | Premium | Paid |
+| **Humaaans** | Mix-and-match characters | CC0 | Free |
+| **Open Peeps** | Hand-drawn characters | CC0 | Free |
+| **Blush** | Customizable scenes | Free / Paid | Mixed |
+
+For Korean market: most kits are Western-coded (people, contexts). Custom or Kakao-style mascot work usually required for true Korean B2C.
+
+## AI-assisted illustration
+
+2024+: Midjourney, DALL-E, Adobe Firefly can produce illustrations in a defined style. Workflow:
+
+1. **Train style** — generate 50+ samples of your defined style, curate the best.
+2. **Use as reference** — feed best samples back as style references for new prompts.
+3. **Always retouch** — AI output never ships raw. Adjust line weight, colors, anchor points to match system.
+4. **License check** — verify AI tool's license permits commercial use; document provenance.
+
+AI is good for:
+- Iteration speed (50 directions in an hour)
+- Inspiration / mood-board generation
+- Filling gaps (one-off illustrations the system doesn't have)
+
+AI is bad for:
+- Consistent system production at scale (variance is the point of AI; consistency is the point of a system)
+- Brand-critical hero illustrations (uncanny / generic risk)
+- Mascot continuity (faces drift across generations)
+
+## Korean illustration conventions
+
+Korean B2C apps lean heavily into:
+- **Mascots** (Kakao Friends — 라이언/어피치/무지, Toss money characters, NaverPay's caricatures).
+- **Soft, rounded geometry** (warm consumer feel).
+- **Pastel + warm-neutral palette** (less stark than Western minimal).
+- **Character-driven empty states** (mascot expressing the empty state's emotion).
+
+Korean B2B / fintech (Toss, KakaoBank) is more restrained: flat geometric with limited mascot use.
+
+See [`mascot-design.md`](mascot-design.md) for character-design depth.
+
+## Technical concerns
+
+| Format | When | Pros | Cons |
+| --- | --- | --- | --- |
+| **SVG** | Default for UI illustration | Vector, themeable, small | More effort to author |
+| **PNG (2x/3x)** | Complex shading, photo-realism | Easy to author | Bigger files, no theme |
+| **WebP** | Photo-realistic, large | Smaller than PNG | Less broad support (now near-universal) |
+| **Lottie** | Animated illustration | Designer-led motion | Larger runtime, see [`motion/motion-tools.md`](../motion/motion-tools.md) |
+| **AVIF** | Highest compression | Smallest files | Tooling still maturing |
+
+Default: **SVG**. Use Lottie when the illustration animates. Use PNG only when SVG can't represent the visual (heavy shading, watercolor, painterly).
+
+For SVG specifics: see [`svg-optimization.md`](svg-optimization.md).
+
+## Don't
+
+- Don't mix illustration styles within a product. One bias per system.
+- Don't ship illustrations with raw hex colors — use CSS variables / SVG `currentColor` for theming.
+- Don't ignore dark mode — illustrations need a dark variant or token-aware coloring.
+- Don't use stock illustrations without checking license + uniqueness — same illustration on 50 SaaS landing pages is bad branding.
+- Don't ship 500kB illustrations — see [`svg-optimization.md`](svg-optimization.md).
+- Don't make every screen "fun." Restraint is a feature.
+
+## Cross-reference
+
+- [`knowledge/illustration/spot-illustrations.md`](spot-illustrations.md) — empty / success / error / onboarding
+- [`knowledge/illustration/hero-illustrations.md`](hero-illustrations.md) — marketing-led
+- [`knowledge/illustration/mascot-design.md`](mascot-design.md) — character / mascot system
+- [`knowledge/illustration/svg-optimization.md`](svg-optimization.md) — SVG specifics
+- [`knowledge/patterns/brand-identity.md`](../patterns/brand-identity.md) — illustration as brand
+- [`knowledge/icons/curated-sets.md`](../icons/curated-sets.md) — icons (different concern)