Chart Builder

chart-builder — plotly 차트 표준

발표 슬라이드, 임원·외부 보고, 내부 공유에 들어가는 production 차트를 일관 톤으로 빌드한다. 색·폰트·여백·hover·강조 패턴을 단일 모듈에 잠가, 사용자는 데이터·축·타이틀만 결정.

---

1. 사용 시점

트리거

• 발표 슬라이드용 차트 (Marp embed, 임원 보고, PA 평가 등)
• 보고서 HTML embed용 차트 (인터랙티브 hover 필요)
• 여러 차트를 같은 톤으로 묶어야 할 때 (한 발표 전체)
• 사용자가 "plotly 표준", "chart_lib", "차트 디자인", "막대/도넛/라인 일관 톤" 언급

사용하지 않을 때

• EDA·디버깅용 단발 plot (pandas .plot(), matplotlib plt.bar(...) 즉석 사용이 더 빠름)
• 매우 특이한 차트 타입(샘플 산점도 + 회귀선, 박스플롯, 히트맵 등 — 본 모듈 helper 5종에 없음)
• 차트 한 장에 단일 카테고리 색상이 5색 초과 필요한 케이스 (단일 hue 그라데이션 원칙 깸)

특이 케이스는 본 모듈의 색·폰트 상수(chart_lib.NAVY, chart_lib.FONT 등)만 import해서 plotly로 직접 작성.

---

2. 핵심 원칙 — 차트 본체와 chrome 분리

차트는 차트만 그린다.

| 차트 본체 (helper가 그림) | 카드/슬라이드 chrome (레이아웃이 그림) | |---|---| | 데이터 (막대/선/도넛) | 제목 (h1 / card-title) | | 축 + 축 단위 라벨 | 부제 (sub / card-sub) | | 범례 | 출처 footer | | hover 템플릿 | 좌측 빨간 인디케이터 띠 | | 도넛 가운데 텍스트 (본질) | 우측 강조 블록 |

왜? figure 안에 paper 좌표로 chrome을 박으면 (1) plot area를 chrome이 침범해 데이터 영역이 좁아지고, (2) 컨테이너 크기에 따라 paper 좌표가 어긋나 인디케이터·라벨이 차트 안으로 들어오거나 잘림. (자세한 검증: lib/demo/demo_before.png vs demo_after.png.)

Marp 슬라이드에 옮길 때도 동일 — 차트 PNG/iframe은 본문 영역만, 제목·부제·출처는 슬라이드 헤더/footer.

---

2.5 차트 정직성 (왜곡 금지)

데이터를 과장·왜곡하는 차트는 신뢰를 깎는다. helper 기본값이 정직 쪽으로 잠겨 있고, 직접 작성 시에도 지킨다.

• 라인은 직선(linear), 곡선(spline) 금지. line() 기본 shape="linear" (2026-06-04 사용자 승인 전역 승격). 곡선은 측정점 사이에 존재하지 않는 중간값·꼭짓점을 그려 허상 추세를 만든다. 반기·월 단위 이산 스냅샷은 연속 공정이 아니므로 직선 연결이 정직.
• 막대·면적은 0 기준선. y축을 0이 아닌 값에서 자르면(truncated axis) 작은 변동이 급등·급락처럼 과장된다. bar_*는 0 기준 유지, 직접 작성 시 fig.update_yaxes(range=[0, ...]). (라인 추세는 절단 허용하되, "급락처럼 보인다" 피드백이 나오면 0 기준으로.)
• 부분 기간은 명시. 진행 중 시즌(부분 집계)을 완전 시즌과 같은 막대로 두면 감소처럼 보인다 — 각주·동일 cutoff로 명시.

---

3. 표준 팔레트

NAVY      = "#1F3A5F"  # 기본 (formal)
NAVY_DARK = "#162B47"
BLUE      = "#4F81BD"  # 보조
LIGHT_BLUE = "#9FBADE"
PALE_BLUE  = "#D5E0F0"
RED       = "#C00000"  # 강조 (마지막 시즌, 1위 카테고리, 인디케이터)
GRAY      = "#7F7F7F"
LIGHT_GRAY = "#D0D5DD"
BG_PANEL  = "#F7F9FC"  # plot 배경
INK       = "#1A1A1A"
INK_SUB   = "#666"
INK_MUTED = "#999"
FONT      = "Malgun Gothic, sans-serif"

gradient_hues(n, base=NAVY, ...) — 단일 hue 그라데이션 n개. 도넛·100% 누적에서 카테고리 색.

---

4. helper API

import chart_lib as cl

# 그룹 막대 — 시즌별 추이 비교 (B5 표준)
cl.bar_grouped(
    categories=["2024-상", "2024-하", "2025-상", "2025-하"],
    series={"답변 평균": [...], "패치 평균": [...]},
    y_title="일 (자연일)",
    value_fmt={"답변 평균": ".2f", "패치 평균": ".1f"},
)

# 단순 막대 + 1개 강조
cl.bar_single(categories, values, y_title="시간 (h)",
              highlight_idx=0, value_fmt=".0f", orientation="v")

# 도넛 + 가운데 텍스트 (1위 자동 pull) — P4 표준
cl.donut(labels, values, highlight_idx=0,
         center_top="47%", center_bottom="사외 고객지원")

# 시계열 라인 + 마지막 점 강조
cl.line(x, series, y_title="건", emphasize_last_point=True)

# 100% 누적 가로/세로 막대
cl.stacked_100(categories, series, orientation="h")

모든 helper는 plotly.graph_objects.Figure를 반환. 데이터·축·범례·hover만 포함.

---

5. 카드(슬라이드) 레이아웃 — chrome 책임

items = [
    # (tag, title, subtitle, source, fig)
    ("B5", "응답속도", "답변·패치 평균 추이 · 최근 8반기",
     "고객지원이슈통계 (2025-2)", fig1),
    ("P4", "유지보수 시간 분포", "사외 고객지원 비중이 가장 큰 카테고리",
     "Jira worklog 합산", fig2),
    ...
]
cl.write_dashboard("out.html", items,
                    page_title="...", page_sub="...")

카드 컨테이너가 좌측 빨간 띠(::before) + 헤더(태그+제목+부제) + footer(출처)를 렌더한다.

Marp 슬라이드로 옮길 때: write_html(fig, "chart.png.html")로 차트 본체만 export → 슬라이드는 자체 헤더·footer를 가지므로 chrome 중복 없음.

---

6. 시각 검증 — 필수

차트를 그렸으면 반드시 PNG로 캡처해 Read로 본다. plotly는 빌드 에러를 안 내고도 paper 좌표나 hover 위치가 어긋날 수 있다.

python ~/.claude/skills/chart-builder/lib/capture_html.py \
   --out  --wait-ms 3000

• --width, --height: viewport (기본 1400×900)
• --wait-ms: plotly CDN + 렌더 대기 (기본 2500ms, 차트 많으면 3000+)
• --no-full-page: viewport만 (기본은 full page)

캡처 후 Read 도구로 PNG 시각 검수 — 카드 chrome이 차트를 가리는지, 도넛 가운데 텍스트가 hole 안인지, 범례 위치 등.

---

7. 프로젝트별 사용

Option A — 글로벌 직접 import (권장)

프로젝트 스크립트 첫 줄에 path 추가:

import sys, pathlib
sys.path.insert(0, str(pathlib.Path.home() / ".claude" / "skills" / "chart-builder" / "lib"))
import chart_lib as cl

Option B — 프로젝트 측 shim

프로젝트 scripts/chart_lib.py를 다음으로 교체:

"""글로벌 chart-builder skill로 redirect."""
import sys, pathlib
sys.path.insert(0, str(pathlib.Path.home() / ".claude" / "skills" / "chart-builder" / "lib"))
from chart_lib import *  # noqa: F401,F403

→ 기존 import chart_lib 코드 그대로 동작.

---

8. 의존성

• plotly>=6.0 — 차트 빌드
• playwright — 시각 검증 (HTML→PNG)
• 미설치 시: python -m pip install playwright && playwright install chromium

---

9. 안티 패턴

1. ❌ helper 인자에 title="..." 같은 chrome 추가 — 차트 본체 외부 책임
2. ❌ fig.add_annotation(text="..", x=-0.06, y=1.18, xref="paper") — paper 좌표 chrome 직접 박기
3. ❌ 카테고리 5색 초과로 색 변별 시도 — 단일 hue 그라데이션 또는 카테고리 묶기
4. ❌ 3D 차트, 회전 라벨, 점선 — presentation-design-principles.md §11 위배
5. ❌ 차트 빌드만 하고 PNG 시각 검증 생략 — §6 필수
6. ❌ formal 톤에 brand color 외 색 추가 — 강조는 RED 하나만

---

10. 관련 문서

• 발표 설계 원칙: ~/.claude/references/presentation-design-principles.md (§11 시각 기교에 본 원칙 요약)
• 슬라이드 공통 워크플로: ~/.claude/commands/slides-common.md
• formal 색상 시스템: ~/.claude/commands/formal-slides.md (주제별 1색 + 본 모듈의 NAVY/RED 강조)

---

11. 정본 위치 / 변경 규칙

• 정본: ~/.claude/skills/chart-builder/lib/chart_lib.py
• 변경 시: 본 SKILL.md 갱신 + SKILLS_INDEX.md(있으면) 일관성 확인
• 프로젝트별 shim은 정본을 따라감 (코드 중복 금지)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jjj5306
• Source: jjj5306/AgentSkills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.