---
title: "No-Emoji Style Guide"
date: 2026-07-03
category: style
tags: [emoji, frontend, cli, terminal, icons]
problem_type: best_practice
component: cross-cutting
severity: convention
---

# No-Emoji Style Guide

## Problem

Emoji characters cause inconsistent rendering across terminals, OSes, and fonts. On Linux servers without Noto Color Emoji, they display as tofu blocks. They also clash with the project's Ant Design Vue Outlined icon family.

## Replacement Strategies

Three strategies based on context:

### KTD1: First-letter avatars (expert/persona avatars)

Use the first character of the expert name — uppercase for English, first CJK character for Chinese.

- `'🦊'` → `'F'` (Fox)
- `'🐼'` → `'P'` (Panda)
- `'🤖'` → `'A'` (AI)

Applies to: `configs/experts/*.yaml` avatar fields, test fixtures.

### KTD2: Ant Design Vue Outlined icons (UI banners/cards)

Use `@ant-design/icons-vue` components for visual icons in frontend components.

- `🏛️` → no icon (BoardBannerCard uses plain text)
- `⚖` → `<AuditOutlined />`
- `✓`/`✗` → `<CheckOutlined />`/`<CloseOutlined />`
- `↻` → `<ReloadOutlined />`
- `◆` → `<ApartmentOutlined />`
- `!` → `<WarningOutlined />`

Applies to: `useMessageRenderer.ts` shell.avatar, `ReviewResultCard.vue` statusIcon, `DebateBannerCard.vue`, `DebateConclusionCard.vue`, `UserBubble.vue`.

### KTD3: Text labels (CLI/shell/terminal output)

Use ASCII text labels with ANSI color codes for status markers.

- `✓` → `OK` (with `[bold green]` in Rich)
- `✗` → `FAIL` (with `[bold red]` in Rich)
- `⚠` → `WARN` (with `[bold yellow]` in Rich)
- `○` → `..` or `PENDING`
- `❌` → `[FAIL]`
- `✅` → `[OK]`

Applies to: `src/agentkit/cli/*.py` (Rich output), `scripts/*.sh` (shell output), `.gitea/workflows/*.yml` (CI logs).

## Unicode Ranges Covered

The `scripts/check-no-emoji.sh` pre-commit hook scans for:

| Range | Block |
|-------|-------|
| `1F000-1FFFF` | Emoji and Supplementary Symbols |
| `2600-27BF` | Misc Symbols and Dingbats (includes ✓ ✗) |
| `2300-23FF` | Miscellaneous Technical |
| `25A0-25FF` | Geometric Shapes (includes ◆ ○) |
| `2B00-2BFF` | Misc Symbols and Arrows |

**Excluded ranges** (pervasive in comments/docstrings, not emoji):

| Range | Block | Reason |
|-------|-------|--------|
| `2190-21FF` | Arrows | `→` is a pervasive docstring flow indicator |
| `2500-257F` | Box Drawings | `─` is a pervasive comment section separator |
| `2580-259F` | Block Elements | `█` `░` used in terminal progress bars |

Also detects escaped unicode sequences (`\u2713`, `\u2717`, `\u25c6`, etc.) in string literals, narrowed to emoji-like ranges only.

## Enforcement

- **Pre-commit hook**: `scripts/check-no-emoji.sh` runs on every commit
- **CI**: Add `bash scripts/check-no-emoji.sh` to `.gitea/workflows/` (deferred)
- **PR review**: Reviewers should check for emoji in code changes