Unicode Glyphs

Unicode Glyphs — Reference for Card & Terminal Systems

Core Principle

Two glyphs per card: glyph (SMP, rich display) + token (BMP, portability-safe fallback).

BMP vs SMP — The Critical Divide

Rule: glyph field = SMP playing card (QL/Finder/SwiftUI). token field = BMP fallback for scripts, cross-platform tooling, and conservative terminal surfaces.

Playing Cards (U+1F0A0–U+1F0FF) — Semantic Encoding

Suit → Team:

• ♠ Spades (U+2660) → CLI / infrastructure
• ♥ Hearts (U+2665) → Architecture / design
• ♦ Diamonds (U+2666) → Quality / QA
• ♣ Clubs (U+2663) → Platform / tooling

SMP card glyphs (primary use: glyph field; optional for macOS-local filenames):

• 🂠 U+1F0A0 Card Back = unrevealed / hidden estimate
• 🂡 U+1F0A1 Ace of Spades = P1/CLI
• 🂱 U+1F0B1 Ace of Hearts = P1/Arch
• 🃁 U+1F0C1 Ace of Diamonds = P1/Quality
• 🃑 U+1F0D1 Ace of Clubs = P1/Platform
• 🃏 U+1F0CF Black Joker = wildcard/emergency ← use this one

Joker rendering (do not use U+1F0BF):

The red joker's fallback is ◆ — indistinguishable from an intentional diamonds suit marker. Never use U+1F0BF.

Rank → Priority: Ace=P1, King/Queen=P2, Jack=P3, 2–10=P4

BMP Glyphs — Priority & Status

Dice U+2680–U+2685 (P1–P6 encoding, universally understood):

⚀ P1  ⚁ P2  ⚂ P3  ⚃ P4  ⚄ P5  ⚅ P6

Geometric shapes (state encoding):

● Running    ○ Pending    ■ Done    □ Blocked
▲ Urgent     ★ Featured   ◆ Critical

Chess pieces U+2654–U+265F (role encoding):

♔ King = critical  ♘ Knight = tricky  ♙ Pawn = atomic task

Special Marks

Block Elements (U+2580–U+259F)

Only glyphs guaranteed in every terminal font. Use for progress/density display, NOT identity:

▁▂▃▄▅▆▇█  — progress bars
░▒▓█      — density levels

Font Recommendations

Contrast caveat: Card glyphs typically read best over dark backgrounds. There is no Unicode "reverse" card-face variant; do inversion in UI styling (background/foreground), not by codepoint swap.

Filename Safety Rules

✅ Conservative portable set: ♠ ♥ ♦ ♣ ★ ⚀ ※ ∴ (all BMP)
⚠️ macOS/APFS local workflows can use SMP: 🂠 🂡 🂻 🃏

macOS 26.3 local validation with 🂠-feat-auth.jobcard succeeded for:

• rg, tail, eza, bat
• bop inspect feat-auth
• bop logs feat-auth
• bop logs -f feat-auth (running cards)

Portability warning remains: shell/tool behavior can diverge across Linux distros, remote CI, legacy terminals, and older scripting environments.

exa is deprecated in Homebrew; use eza.

Two-Glyph Architecture (jobcard Meta)

// In Meta struct:
pub glyph: Option<String>,  // SMP playing card — QL/Finder/SwiftUI hero
pub token: Option<String>,  // BMP fallback — pane title, safe aliases, portability mode

Example:

{
  "glyph": "🂡",     // Ace of Spades — QL preview hero
  "token": "⚀",      // Die face 1 — P1 priority in terminal
  "id": "feat-auth"   // keep ID stable; filename may carry glyph prefix
}

Stage Display Names

Never use .to_uppercase() or .capitalized on stage names — "QA" → "Qa" bug. Use a lookup table:

static STAGE_LABELS: &[(&str, &str)] = &[
    ("spec",      "Spec"),
    ("plan",      "Plan"),
    ("implement", "Code"),
    ("qa",        "QA"),
];

Quick Checklist

• Rich display surface (SwiftUI/QL)? → glyph field, SMP ok
• Terminal/filename surface? → token field by default; allow SMP filenames only for macOS-local workflows
• Priority visible at a glance? → dice ⚀–⚅
• Decision needed? → prepend ※
• Merge-ready? → ∴ in status
• Font recommendation needed? → JetBrains Mono + Nerd Fonts