AgentCard
AI 에이전트 상태 카드 — 이름·역할·상태·결과 4요소. 상태 칩은 색+텍스트 병행으로 색맹 안전합니다.
마지막 업데이트 2026-06-11
한눈에#
AI 에이전트의 이름·역할·상태·결과 4요소를 담는 상태 카드입니다 — 상태 칩은 색+텍스트를 병행해 색맹 환경에서도 구분됩니다.
- 이름·역할·상태·결과 4요소
- 상태 4종(idle·running·done·error)
- 색+텍스트 병행
- AA 상태 칩
running 점은 호흡 애니메이션(reduced-motion 존중) — 점은 장식, 의미는 색+라벨이 전달
사용 시점#
AI 에이전트의 상태·결과를 카드로 보여주면 AgentCard — 정체성만이나 범용 컨테이너는 다른 컴포넌트입니다.
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
쓴다 — 에이전트 이름·역할 + 상태(실행 중·완료·오류) + 결과 요약을 한 카드로
대신 Avatar — 상태·결과 없이 사용자·팀 정체성만 표시할 때
대신 Card — 에이전트가 아닌 범용 콘텐츠 컨테이너가 필요할 때
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
AgentCard를 직접 조작해 보세요
속성·테마·토큰을 바꾸고 React·Flutter 코드를 확인하는 풀스크린 빌더로 엽니다.
플레이그라운드는 넓은 작업 영역이 필요해 웹·태블릿에서 편집할 수 있어요.
변형 — 아바타 슬롯#
기본은 이름 첫 글자, avatar로 아이콘/이미지를 교체합니다.
크기#
고정 크기가 없는 유동 카드입니다 — 그리드/리스트 어느 쪽에도 배치 가능. 이름·역할이 길면 말줄임(ellipsis) 처리됩니다.
상태#
기본 라벨(대기/실행 중/완료/오류)은 stateLabel로 문맥에 맞게 바꿉니다 —
예: state="running" stateLabel="분석 중".
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
name | string | — | 에이전트 이름 — 아바타 폴백 첫 글자로도 사용 |
role | string | — | 에이전트 직무 표기 (예: "코드 리뷰어") |
state | 'idle' | 'running' | 'done' | 'error' | — | 상태 어휘 — §11 Design QA와 동일 |
result | ReactNode | — | 작업 결과 요약 슬롯 — 미제공 시 결과 영역 미렌더 |
avatar | ReactNode | — | 아바타 슬롯 — 미제공 시 이름 첫 글자 |
stateLabel | string | — | 상태 라벨 오버라이드 (기본: 대기/실행 중/완료/오류) |
ref | Ref<HTMLDivElement> | — | 루트 <div>로 전달되는 ref (React 19 ref-as-prop) |
접근성#
- 상태는 색 + 텍스트 라벨 병행 — 점(dot)은 장식(
aria-hidden)이라 색맹 환경에서도 라벨로 구분됩니다 - 상태 칩 색은
status-text토큰 쌍 — 라이트/다크 모두 AA 대비가 빌드 게이트로 보장됩니다 running점의 호흡 애니메이션은prefers-reduced-motion을 존중합니다- 도메인
roleprop은 ARIArole속성과 타입 수준에서 분리되어 있습니다(Omit)
토큰#
component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).
| 속성 | 토큰 |
|---|---|
| 카드 | color.surface · color.border · radius.lg |
| 아바타 | color.primary-subtle + color.primary-text · radius.full |
| 칩 idle | color.surface-muted + color.text-muted |
| 칩 running | color.primary-subtle + color.primary-text |
| 칩 done/error | color.success/error 8% 혼합 배경 + *-text (12%는 AA 4.39:1 미달 — 8% 고정) |
| 결과 영역 | color.surface-muted · radius.md |