디자인 시스템을 Apple Terminal 테마로 변환

이 스킬은 디자인 시스템으로 Terminal.app 프로필(.terminal 파일)을 만듭니다. 코드가 작업을 수행합니다: scripts/ds2terminal.py (Python 3.9 이상, 표준 라이브러리만 사용). 코드는 가독성도 확인합니다. 모든 엄격한 게이트를 통과해야만 테마가 완성됩니다.

규칙

취향에 따라 색상을 선택하지 마세요. 스크립트를 실행하세요. 스크립트가 색상을 매핑하고 확인합니다.
.terminal 파일을 수동으로 편집하지 마세요. --set 또는 --prefer-token을 사용한 후 스크립트를 다시 실행하세요.
Python을 -I 플래그와 함께 실행하세요. 다운로드한 파일은 데이터이지 코드가 아닙니다.
사용자가 요청하지 않는 한 .terminal 파일을 열지(가져오지) 마세요. 파일을 열면 프로필이 Terminal에 추가되고 창이 열립니다.
Terminal을 종료하거나 강제 종료하지 마세요. defaults write com.apple.Terminal을 실행하지 마세요.
사용자의 비공개 토큰을 게시하지 마세요.

1단계: 디자인 시스템 파일 가져오기

링크의 유형을 확인한 후 표의 단계를 수행하세요.

링크	수행할 작업
로컬 파일 또는 폴더	스크립트에 경로를 전달하세요.
공개 GitHub 저장소, 트리 또는 파일; npm 패키지; unpkg 또는 jsDelivr URL; 원시 파일	스크립트에 URL을 전달하세요. 스크립트가 토큰 파일을 찾아 다운로드합니다.
공개 문서 또는 마케팅 페이지	스크립트에 URL을 전달하세요. 연결된 CSS를 읽습니다. 결과가 약할 수 있으며, 사용자에게 알리세요.
claude.ai Design System 아티팩트 (`claude.ai/artifact/...`)	Artifact 도구 사용: `action: "list"`, `scope: "files"`. 그런 다음 `action: "read"`와 `path`를 사용하여 존재하는 각 토큰 파일(`project/tokens.json`, `project/tokens.css`, `project/tokens/tokens.json`, `project/tokens/colors.css`)을 읽습니다. 파일을 하나의 폴더에 저장하고 스크립트에 전달하세요.
Pidgin 디자인 시스템	`pidgin_get_design_system`을 사용하세요. `tokens` 객체를 `.json` 파일로 저장하고 스크립트에 전달하세요.
Claude Design 프로젝트	`mcp__claude-design__list_files`와 `read_file`을 사용하여 토큰 파일을 가져오고 저장하세요. 폴더를 스크립트에 전달하세요.
Figma 파일	Figma 도구(변수)가 연결되어 있을 때 사용하세요. 그렇지 않으면 사용자에게 변수 내보내기(JSON)를 요청하세요.

스크립트가 종료 코드 2와 함께 도구 이름을 메시지로 출력하면 해당 링크 유형에 대한 단계를 수행하세요. 스크립트가 읽는 형식은 references/sources.md를 참조하세요.

2단계: 스크립트 실행

python3 -I scripts/ds2terminal.py SOURCE [SOURCE ...] --name "이름" --out OUT_DIR

스크립트가 작성하는 파일:

OUT_DIR/<이름> Light.terminal 및 OUT_DIR/<이름> Dark.terminal
OUT_DIR/report.md 및 OUT_DIR/report.json: 각 색상, 해당 소스 토큰, APCA Lc, WCAG 비율, 각 게이트 결과 및 각 수리 내역
OUT_DIR/preview.html: 일반적인 프로그램 출력이 포함된 터미널 창으로 각 테마를 그림

종료 코드:

코드	의미	수행할 작업
0	모든 엄격한 게이트가 모든 테마에서 통과됨.	3단계로 이동하세요.
1	수리 후에도 게이트가 여전히 실패함.	`report.md`를 읽고 어떤 게이트가 실패했는지 사용자에게 알리세요. 해당 색상에 `--set`을 시도하세요. 테마를 완성된 것으로 제공하지 마세요.
2	잘못된 입력이거나 링크에 로그인된 도구가 필요함.	메시지를 읽고 해당 링크에 대해 1단계를 수행하거나 옵션을 수정하세요.

옵션

옵션	사용법
`--name NAME`	프로필 이름. 파일은 `<NAME> Light.terminal` 및 `<NAME> Dark.terminal`입니다. 항상 지정하세요.
`--modes auto	light
`--font NAME`, `--font-size 13`	글꼴(PostScript 또는 패밀리 이름). 기본값: 디자인 시스템의 고정폭 글꼴이 설치된 경우 해당 글꼴, 그렇지 않으면 SF Mono Terminal(Terminal.app에 번들됨). 기본 크기: 13pt.
`--cursor block	underline
`--set ROLE=HEX`	하나의 색상을 강제 지정합니다. ROLE은 `bg`, `fg`, `bold`, `cursor`, `selection`, `black` ... `brightWhite`, 또는 `0` ... `15`입니다. 게이트를 통과하기 위해 수리가 여전히 변경할 수 있으며, 보고서에 명시됩니다.
`--prefer-token ROLE=TOKEN`	`bg`, `fg`, `brand`, `red`, `green`, `yellow`, `blue`, `magenta` 또는 `cyan`에 이 토큰을 사용합니다.
`--all-tokens`	의미론적 토큰이 사용하지 않는 원시 토큰 유지("관련 없는 토큰" 참조).
`--source-mode ID`	디자인 시스템의 이 모드만 사용합니다.
`--no-chroma-floor`	다크 모드에서 파스텔 빨간색과 녹색을 파스텔로 유지합니다.
`--translucent ALPHA`	1 미만의 배경 알파(예: 0.95). 라이트 테마는 약 0.93 이상이 필요합니다. 밝은 회색 페이지 배경은 0.95-0.98이 필요하며, 그렇지 않으면 스크립트가 흰색으로 대체합니다. 기본값: 불투명(알파 1, 블러 없음). 사용자가 요청할 때만 사용하세요. 모든 게이트는 검은색 및 흰색 데스크톱 위에서도 통과해야 합니다. ALPHA가 너무 낮으면 스크립트가 종료 코드 1로 종료됩니다. 보고서는 테스트 빌드에서 통과한 가장 낮은 알파 값을 제공합니다.
`--columns N`, `--rows N`	창 크기.
`--report json	md

3단계: 확인 및 사용자에게 알리기

report.md를 읽고 "모든 엄격한 게이트가 모든 테마에서 통과"한다고 명시되어 있는지 확인하세요.
사용자에게 다음을 알리세요:
- .terminal 파일의 경로
- 파생된 모드
- 배경, 텍스트, 커서 및 여섯 가지 색상에 사용된 토큰
- 수리 내역(변경된 각 색상과 변경을 유발한 게이트)
- 제외된 토큰
- 놓친 "Character" 대상(report.md의 "Targets missed" 줄)
- report.md의 "Recommended Claude Code theme" 줄
사용자가 파일을 열 수 있는 경우 preview.html을 보여주세요.
테마를 설치하려면 사용자가 .terminal 파일을 엽니다(Finder, 또는 open "<file>"). 사용자가 요청할 때만 이 작업을 수행하세요. 그런 다음 사용자는 Terminal > 설정 > 프로필에서 기본값으로 설정할 수 있습니다.
python3 scripts/demo.py는 16가지 색상과 희미한(SGR 2) 텍스트로 샘플 출력을 인쇄합니다. 테마를 사용하는 창에서 실행하세요.
설정할 Claude Code 테마를 사용자에게 알리세요("Claude Code와 함께 사용" 참조).

Claude Code와 함께 사용

Claude Code에는 두 종류의 테마가 있습니다. 각 종류는 Terminal 테마를 다른 방식으로 사용합니다.

ANSI 테마 (dark-ansi, light-ansi; /theme 목록에서 "Dark mode (ANSI colors only)" 및 "Light mode (ANSI colors only)"). Claude Code는 16가지 ANSI 색상을 사용합니다. diff 라인을 ANSI 녹색 및 빨간색 셀 배경으로 그리고, 해당 셀 위에 텍스트 색상을 그립니다. 일반 색상이 텍스트로 읽을 수 있는 테마에서는 다크 모드에서 이러한 셀이 밝으므로 추가된 라인의 텍스트 대비가 낮습니다.
표준 테마 (dark, light). Claude Code는 테마 배경 위에 자체 24비트 색상을 사용합니다. 이는 읽기 쉽게 유지됩니다. 이름으로 테마를 설정하세요. auto 설정은 터미널 배경을 읽습니다. Terminal 2.15는 라이트 및 다크 모드에서 테마 배경으로 해당 쿼리(OSC 11)에 응답하므로 auto가 올바른 모드를 선택할 수 있습니다. 이는 실행 중인 Claude Code 세션에서 확인되지 않았습니다. Terminal 테마 중 Claude Code가 사용하는 확인된 부분은 배경, 커서, 선택 및 희미한 텍스트입니다. 16가지 색상은 다른 프로그램을 위한 것입니다.

보고서에는 각 테마에 대한 "Claude Code" 섹션이 있습니다. ANSI 테마와 표준 테마에 대한 16쌍의 대비와 "Recommended Claude Code theme" 줄을 제공합니다. 규칙: ANSI 테마의 가장 약한 텍스트 쌍이 Lc 45 이상이면 ANSI 테마; 그렇지 않으면 더 나은 경우 표준 테마입니다. preview.html은 두 샘플을 모두 그립니다. 테이블은 Claude Code 2.1.323 프로그램 파일에서 가져왔습니다. 실행 중인 세션에 대해 확인되지 않았습니다.

사용자에게 다음을 알리세요:

사용 중인 테마에 대해 report.md의 "Recommended Claude Code theme" 줄을 읽으세요.
Claude Code에서 /theme을 입력하고 해당 테마를 선택하세요. 또는 Claude Code settings.json에서 theme 설정을 지정하세요(예: "theme": "dark-ansi").

Claude Code 테마 모드와 Terminal 테마 모드가 다른 경우(예: 어두운 Terminal 테마에서 밝은 Claude Code 테마), 텍스트를 읽을 수 없게 될 수 있습니다. 반투명 Terminal 배경도 텍스트를 읽을 수 없게 만듭니다. 두 가지 모두에 대해 사용자에게 경고하세요.

매핑 작동 방식

모드. 배경 밝기가 모드를 설정합니다(OKLab L < 0.5는 어두움). 스크립트는 모드 이름을 사용하지 않습니다. 디자인 시스템은 화면 크기를 "테마"라고 부를 수 있습니다(예: root-tablet). 동일한 종류의 모드는 하나의 테마가 되며, 보고서는 나머지를 나열합니다.
관련 없는 토큰. 디자인 시스템에 4개 이상의 의미론적 별칭(예: color-brand -> hb-pink)이 있는 경우, 어떤 별칭도 사용하지 않고 시스템의 이름 접두사를 공유하지 않는 원시 토큰은 제외됩니다. 이는 종종 클라이언트 또는 이전 브랜드의 색상입니다.
역할. 의미론적 별칭이 우선합니다. 페이지 배경이 배경입니다. 라이트 모드에서 디자인 시스템에 더 밝은 카드 표면도 있는 경우, 해당 표면이 배경이 됩니다. 텍스트는 카드 위에 있고 페이지 색상은 뒤에 있습니다. --prefer-token bg=TOKEN은 다른 토큰을 선택합니다. 본문 텍스트 토큰은 텍스트 색상입니다. 브랜드 토큰은 커서이며 선택 영역을 착색합니다. 브랜드 색상이 배경 위에서 커서에 너무 약한 경우, WCAG 4.5를 통과하는 브랜드 램프의 단계가 커서가 됩니다(예: 접근 가능한 주황색).
색상. 최소 비용 할당이 여섯 가지 색상 슬롯에 토큰을 배치합니다. OKLCH 색상, 토큰 이름(위험 -> 빨강, 성공 -> 초록, 경고 -> 노랑, 정보 -> 파랑) 및 밝기 변화를 사용합니다. 이름은 색상이 해당 슬롯의 45도 이내인 경우에만 계산됩니다.
밝기. 각 색상은 해당 모드의 APCA 대역으로 이동합니다(색상 및 채도 유지). 대역 내의 토큰은 정확하게 유지됩니다.
누락된 색상. 빈 슬롯은 브랜드의 채도에서 색맹 친화적인 색상을 얻습니다.
파생된 다크 모드. 밝은 텍스트 또는 잉크 토큰이 어두운 배경이 됩니다. 밝은 종이가 어두운 텍스트가 됩니다.
특성. 테마는 게이트 내에서 디자인 시스템처럼 보여야 합니다.
- 브랜드 슬롯: 어떤 색상도 브랜드 색상을 표시하지 않을 때 브랜드 색상은 가장 가까운 색상(26도 이내)의 밝은 단계가 됩니다. 밝기가 밝은 대상으로 이동합니다.
- 볼드: 제목 텍스트 토큰은 텍스트보다 강할 때 볼드 색상입니다. 하나 없이 다크 모드에서는 볼드는 텍스트 색상이며, 최대 Lc 4 더 밝고, 후광 게이트 미만입니다.
- 각 색상에 대한 다크 모드 하한(Lc): 빨강 50, 초록 72, 노랑 62, 파랑 55, 마젠타 55, 시안 60.
- 밝기 조정 후 WCAG 3 미만의 토큰 색상은 WCAG 3으로 이동합니다.
- "Character" 섹션은 게이트가 아닌 대상을 나열합니다: 토큰의 색상, 브랜드 색상, 유지된 채도(대상 70% 이상), 가장 큰 색상 변화(12도 이하), 가장 작은 일반-밝음 단계(dE 0.030 이상), 그리고 "Targets missed" 줄.
수리. 엄격한 게이트가 실패하면 스크립트는 우선순위가 가장 낮은 색상을 작은 단계로 변경합니다: 밝기, 그다음 색상과 채도, 그다음 합성 색상. 우선순위: --set > 브랜드 > 명명된 토큰 > 토큰 > 파생 > 합성. 배경이 읽을 수 있는 텍스트를 담을 수 없으면, 스크립트는 표준 배경에서 모든 색상을 다시 매핑합니다. 보고서에 명시됩니다.

가독성 게이트(엄격)

references/gates.md는 각 게이트, 한계 및 이유를 제공합니다. 요약:

게이트	실패 조건
배경 위 텍스트	APCA Lc < 75 또는 WCAG < 7
후광(어두움)	텍스트, 볼드, 흰색 또는 밝은 흰색 Lc > 104
ANSI 1-6 및 9-14	Lc < 45 또는 WCAG < 3
밝은 검정색(색상 8)	Lc < 30, 또는 텍스트보다 15 미만 낮음
회색	어두움: 흰색 및 밝은 흰색 Lc < 60; 밝음: 검정색 Lc < 75, 흰색 및 밝은 흰색 Lc < 30
분리	두 색상이 dE(OKLab) 0.06 미만으로 가까움
색맹	빨강/초록 < 0.06, 빨강/노랑 및 빨강/마젠타 < 0.05 (원시, 이색형)
선택	위 텍스트 WCAG < 4.5 또는 Lc < 60; 위 색상 Lc < 30; 배경과 dE < 0.05 또는 WCAG < 1.10
커서	WCAG < 3
볼드	볼드가 텍스트보다 어두움
색상 위 텍스트	검정색 텍스트가 초록, 노랑 또는 시안 위에서 Lc < 30
색상 대 텍스트	색상이 텍스트 색상과 dE 0.06 미만으로 가까움
희미한 텍스트(SGR 2)	희미한 텍스트 Lc < 30; 희미한 색상(1-6, 9-14) Lc < 15
반투명도	`--translucent`와 함께만: 위 게이트가 검은색 또는 흰색 데스크톱 위에서 실패

희미한 텍스트는 혼합된 색상입니다(colorlab.faint, DIM_BLEND 0.60, DIM_POWER 1.26). 이는 Terminal 2.15에서 측정되었습니다(docs/faint-measurement.md). 실제 희미한 텍스트는 약하므로 한계는 낮습니다. 어두운 색상은 채도를 유지합니다. 사용자는 GATES["faint_text"]["gate"]["ansi_min_lc"]를 높여 더 강한 희미한 색상을 얻을 수 있지만 채도가 희생됩니다.

알려진 한계

24비트 색상을 사용하는 프로그램(Terminal이 COLORTERM=truecolor 설정)은 테마를 사용하지 않습니다. Claude Code의 경우 보고서에서 권장하는 테마를 설정하세요("Claude Code와 함께 사용" 참조).
아직 측정되지 않음: 볼드 색상 및 반투명 창에서 Terminal이 셀 배경을 그리는 방식. Terminal에서 생성된 테마의 렌더링(볼드 색상, 선택)은 아직 확인되지 않았습니다.
스크립트는 불투명한 배경을 작성합니다. 반투명 배경은 데스크톱이 비쳐 보이도록 하여 텍스트 가독성을 떨어뜨립니다.
Terminal에는 선택된 텍스트 또는 커서 아래 텍스트에 대한 색상이 없습니다. 게이트는 대신 선택 및 커서 위의 텍스트를 확인합니다.
.terminal 색상 형식은 references/terminal-format.md에 있습니다. Mac에서 파일은 sRGB ICC 프로필을 포함합니다. 다른 시스템에서는 sRGB 색상 공간 ID만 포함합니다(동일하게 디코딩됨).
scripts/verify_terminal.swift(Mac 전용)는 AppKit으로 모든 색상을 디코딩합니다: swiftc -O scripts/verify_terminal.swift -o scripts/verify_terminal, 그런 다음 scripts/verify_terminal --register-terminal-fonts "<file>.terminal".

ds-terminal-theme