---
name: upg-design-system
description: "UPG Visual Design System: shared reference for all /upg-* skills"
user-invocable: false
category: meta
---

# UPG Visual Design System

This is the shared design reference for all `/upg-*` skills. Every skill that produces visual output MUST follow these guidelines for consistency.

## Brand

- **Name:** Always write "Unified Product Graph" in full; never just "UPG" in user-facing text
- **Logo mark:** Use on key screens (`/upg`, `/upg-show-status`, `/upg-sync-export`)
- **Standard URL:** unifiedproductgraph.org

### Logo Mark

The dot cluster logo in a code block, followed by a bold H1 for the name:

```
  · ·
   ◉
  · ·
```
# Unified Product Graph

The logo is the dot cluster (renders in monospace). The name is a markdown H1 (renders large and bold). Use at the top of `/upg`, `/upg-show-status`, and `/upg-sync-export`. Other skills don't need the logo; keep it special.

## Section Dividers

Use dashed lines between major sections:

```
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
```

These go between logical sections (header, lifecycle, metrics, actions, footer). Not between every paragraph.

## Entity Type Emojis

Always prefix entity names with their type emoji.

*This table is the canonical display reference for the types listed. It is also mirrored by the live `get_catalog_entry({ kind: 'type_label', id: entity_type }).emoji` field — use the live field for any type not in this table, or when you need to verify a specific emoji against the current spec.*

| Type | Emoji | Domain |
|---|---|---|
| product | 🎯 | Strategic |
| outcome | 🎯 | Strategic |
| objective | 🎯 | Strategic |
| key_result | 🎯 | Strategic |
| metric | 📊 | Strategic |
| persona | 👤 | User |
| job | 💼 | User |
| need | 🔥 | User |
| opportunity | 💡 | Discovery |
| solution | 🔧 | Discovery |
| competitor | ⚔️ | Discovery |
| hypothesis | ⚗️ | Validation |
| experiment | 🧪 | Validation |
| learning | 📝 | Validation |
| feature | 📦 | Execution |
| epic | 📋 | Execution |
| user_story | 📄 | Execution |
| release | 🚀 | Execution |
| research_study | 🔬 | Research |
| insight | 💎 | Research |

## Score Dots (1-5 Scales)

Use spaced filled/empty circles for any 1-5 rating:

```
● ● ● ● ●   5/5
● ● ● ● ○   4/5
● ● ● ○ ○   3/5
● ● ○ ○ ○   2/5
● ○ ○ ○ ○   1/5
○ ○ ○ ○ ○   0/5
```

Use for: reach, pain, frequency, severity, importance, satisfaction, confidence, effort, impact, tech comfort.

Display dimensions on a single line with labels:

```
reach ● ● ● ● ●   pain ● ● ● ● ○   freq ● ● ● ○ ○
```

For RICE breakdowns, use single-letter abbreviations:

```
R ● ● ● ● ●   I ● ● ● ● ●   C ● ● ● ○ ○   E ● ● ● ○ ○
```

## Filled Bars (Larger Scales)

Use `▓` (filled) and `░` (empty) for RICE totals, percentages, and health metrics:

```
RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 30
RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░ 20
RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░ 15
```

Scale bars to max 30 characters. The highest value gets a full bar; others are proportional.

For percentages:

```
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░   85%
▓▓▓▓▓░░░░░░░░░░░░░░░   25%
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  100%
```

## Status Dots

Use colored emoji dots for entity state. One dot, inline or right-aligned:

| Status | Dot |
|---|---|
| shipped / validated / achieved | 🟢 |
| in_progress / active / testing | 🟡 |
| planned / proposed / drafted | 🔵 |
| untested | ⚪ |
| blocked / invalidated | 🔴 |
| deferred / deprecated / archived | ⚫ |

Display: `🟡 active` or right-aligned at end of a tree line.

> Hypothesis phases are `drafted` → `active` → `validated` / `invalidated` / `archived`. Derive valid phases live via `list_catalog({ kind: 'status_values', entity_type })` or `get_catalog_entry({ kind: 'lifecycle', id: entity_type })`; never hard-code phase names.

## Nested Detail Blocks

Inside trees, use solid-border boxes for detail cards:

```
├─ 🔧 Personalized action checklist              🟡 proposed
│  ┌──────────────────────────────────────────┐
│  │  R ● ● ● ● ●   I ● ● ● ● ●            │
│  │  C ● ● ● ○ ○   E ● ● ● ○ ○            │
│  │  RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 30 │
│  └──────────────────────────────────────────┘
```

Use `┌─┐│└─┘` (solid lines). Boxes always close. Keep content inside aligned.

## Tables

Use markdown tables for structured comparisons (metrics, benchmarks, RICE breakdowns, entity lists). Tables auto-align and handle emoji width well.

| Solution | Reach | Impact | Confidence | Effort | RICE |
|---|---|---|---|---|---|
| **Personalized checklist** | ● ● ● ● ● | ● ● ● ● ● | ● ● ● ○ ○ | ● ● ● ○ ○ | **30** |
| Interactive tour | ● ● ● ● ○ | ● ● ● ● ○ | ● ● ● ○ ○ | ● ● ● ● ○ | **20** |

## Text Formatting

- **Bold** for key values: names, scores, percentages, important labels
- *Italic* for quotes, attributions, framework names, insights
- `code` for file names, commands, specific values like `47%`
- > Blockquotes for human insights, motivations, callouts, and coaching

## Annotation Arrows

Use `←` for inline callouts:

```
RICE ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 30   ← highest
Validation  25%  ▓▓▓▓▓░░░░░░░░░░░░░░░      ← risk
```

## Benchmark Checks

Use `✓` and `✗` for checklists and benchmarks:

```
✓ product   ✓ personas   ✓ outcomes   ✗ 5+ hypotheses
```

## Tree Connectors

Standard tree hierarchy characters:

```
├─   branch with siblings below
└─   last branch
│    vertical continuation
```

## Smart Ending Pattern (CRITICAL)

**Every cognitive skill that creates entities MUST end with a smart recommendation, not a menu.**

After creating entities, the skill should:

1. Call `get_graph_digest()` to check the current state
2. Determine which of the 8 business areas has the biggest gap
3. Recommend ONE specific next skill based on that gap
4. Always offer `/upg-show-journey` as the "see full picture" fallback

**Good ending (smart, contextual):**
```
✓ Added business model to your graph.

Your graph now covers 6 of 8 business areas.
The biggest gap: 📣 Reaching; you haven't thought about how people find your product.

→ Run /upg-new-launch to define your positioning and channels.

Or /upg-show-journey to see your full progress across all 7 phases.
```

**Bad ending (menu dump; DON'T DO THIS):**
```
Next steps:
- /upg-new-persona: Add more personas
- /upg-new-discovery: Run a discovery session
- /upg-new-hypothesis: Structure a bet
- /upg-check-gaps: Check for gaps
- /upg-show-status: Health dashboard
```

The business areas to check (in priority order):
1. 🎯 **Identity**: product, vision, mission
2. 👤 **Understanding**: persona, job, need, research_study, insight
3. 💡 **Discovery**: opportunity, solution, competitor, hypothesis, experiment, learning
4. 📣 **Reaching**: ideal_customer_profile, positioning, messaging, acquisition_channel, content_strategy
5. 💰 **Converting**: value_proposition, pricing_tier, funnel, funnel_step
6. 📦 **Building**: feature, user_story, epic, release, user_journey, user_flow
7. 🏦 **Sustaining**: business_model, revenue_stream, cost_structure, unit_economics, pricing_strategy
8. 📊 **Learning**: outcome, metric, objective, key_result, retrospective

Map each empty/thin area to a skill:
- Identity → `/upg-new-strategy`
- Understanding → `/upg-new-persona`
- Discovery → `/upg-new-discovery`
- Reaching → `/upg-new-launch` or `/upg-walk-region marketing`
- Converting → `/upg-walk-region business_model`
- Building → `/upg-walk-region product_spec`
- Sustaining → `/upg-walk-region business_model`
- Learning → `/upg-new-okr` or `/upg-walk-region team_org`

If ALL areas are covered, celebrate and point to `/upg-show-journey`.

## Footer Pattern

After the smart ending, add the standard footer with a dashed divider:


On `/upg-show-status` and `/upg-check-gaps` (where maturity is 3+), the footer can be slightly more direct:

```
can show patterns the CLI can't. → /upg-sync-push to sync
```

## Tone

- Warm, encouraging, exciting: never dry or clinical
- Product coach voice: direct, specific, actionable
- "You're asking the right questions" not "Your graph is incomplete"
- Celebrate progress, highlight gaps as opportunities
- The CLI should feel like a delightful tool, not a spreadsheet