pencil-generate-library: 토큰, 테마 및 컴포넌트 순서대로
코드와 일치하는 .pen 파일에 디자인 시스템을 구축합니다. pencil-use를 먼저 로드하세요: execute 규칙이 들어 있습니다. 이 스킬은 작업 순서와 디자인 시스템 결정 사항을 담고 있습니다.
1. 가장 중요한 규칙
이 작업은 절대 한 번의 호출로 끝나지 않습니다. 작은 시스템도 15~40회의 execute 호출이 필요하며, 더 큰 시스템은 훨씬 더 많이 필요합니다. 가장 작은 유용한 단위로 작업하고, 확인하고, 보여준 다음 계속 진행하세요. 한 번의 긴 코드 조각으로 구축된 시스템은 망가지고 복구하기 어렵습니다.
2. Pencil이 다른 도구와 다른 점
다른 곳에서 차용한 모델이 아닌 Pencil의 실제 모델로 계획하세요:
| 필요 기능 | Pencil에서의 구현 |
|---|---|
| 토큰 | color, number, string, boolean 유형의 문서 variables, $name으로 참조 |
| 모드(라이트, 다크) | 테마 축(Theme axes). 변수 값은 {value, theme: {mode: "dark"}} 목록입니다. 프레임은 theme 속성으로 값을 선택합니다 |
| 별칭(의미론적->원시적) | 값이 다른 변수인 변수: value: "$gray-900" |
| 텍스트 스타일 | 없음. 글꼴 변수(패밀리, 크기, 줄 높이, 두께를 문자열 또는 숫자로)와 필요한 경우 작은 텍스트 컴포넌트를 사용하세요 |
| 그림자 스타일 | 없음. 그림자 효과는 색상, 흐림 및 오프셋에 변수를 사용합니다 |
| 컴포넌트 | reusable: true인 모든 노드 |
| 변형(Variants) | 변형 세트 없음. 변형당 하나의 컴포넌트, 슬래시로 이름 지정: Button/Primary, Button/Outline |
| 불리언 옵션(아이콘 표시) | 해당 부분에서 인스턴스 재정의 enabled: false |
| 교체 가능한 아이콘 | 아이콘 노드에서 인스턴스 재정의: {icon: "plus"} |
| 교체 가능한 콘텐츠 | 컴포넌트 내부의 slot 프레임, 권장 컴포넌트 ID 포함 |
| 공유 라이브러리 | 앱에서 .lib.pen으로 변환된 파일(단방향, 취소 불가), 화면 파일에서 가져오기 |
3. 워크플로
Phase 0 발견(DISCOVERY) 코드와 파일 읽기, 쓰기 없음 -> 체크포인트: 계획 승인
Phase 1 파운데이션(FOUNDATIONS) 변수 및 테마 -> 체크포인트: 토큰 요약 승인
Phase 2 파일 레이아웃(FILE LAYOUT) 캔버스 영역, 파운데이션 보드 -> 체크포인트: 보드 스크린샷 승인
Phase 3 컴포넌트(COMPONENTS) 한 번에 하나씩, 원자 -> 분자 순서 -> 각 컴포넌트 후 체크포인트
Phase 4 QA 및 라이브러리(QA AND LIBRARY) 감사, 수정, 선택적 .lib.pen -> 체크포인트: 최종 승인
각 체크포인트에서 다음 단계의 이름을 지정하세요. 토큰에 대해 "좋아 보인다"는 컴포넌트 시작 승인이 아닙니다.
Phase 0. 발견(Discovery) (읽기 전용)
0a. 코드에서 토큰 찾기, 다음 순서로:
- CSS 사용자 정의 속성 (
:root { --background: ... },.dark { ... }또는[data-theme="dark"]). - Tailwind config 또는 Tailwind v4
@theme블록. - 토큰 파일 (DTCG
.tokens.json, Style Dictionary). - CSS-in-JS의 테마 객체 또는 네이티브 테마 파일 (iOS asset catalogs, Android
colors.xml).
다크 모드 메커니즘, 간격 및 반경 스케일, 글꼴 및 타입 스케일, 그림자를 기록하세요.
0b. 코드에서 컴포넌트 찾기: UI 기본 요소 목록(Button, Input, Checkbox, Badge, Avatar, Card...), 해당 props, 어떤 props가 변형(variant, size, state)인지, 어떤 것이 불리언인지, 어떤 것이 children을 받는지.
0c. 파일 읽기:
Print(GetVariables())
Get(n => n.reusable && Print(n.id, "|", n.name))
Get(document, (n, c) => { if (c.depth === 1) { Print(n.id, "|", n.type, "|", n.name); c.skipChildren() } })
또한 가져온 라이브러리에 대해 get_app_state를 확인하세요. 파일에 이미 있는 명명 규칙과 일치시키세요.
0d. 사용자와 범위 확정: 이번 라운드의 정확한 토큰 목록과 정확한 컴포넌트 목록. 6~10개의 컴포넌트로 구성된 첫 번째 라운드가 적당한 크기입니다.
0e. 코드를 Pencil에 매핑하고 충돌 해결. 다음 표를 제시하세요:
코드 토큰 Pencil 변수 Light Dark 상태
--background --background #FFFFFF #0A0A0A 신규
--primary --primary #1D4ED8 #3B82F6 존재, 값 다름 (확인 필요)
컴포넌트 Pencil 컴포넌트 상태
Button variant x size Button/Primary, Button/Secondary, Button/Outline, Button/Ghost (size via theme axis) 신규
코드와 파일이 일치하지 않을 때는 무엇을 우선시할지 물어보세요. 혼자 결정하지 마세요.
체크포인트: 계획을 보여주고 승인을 기다리세요.
Phase 1. 파운데이션(Foundations)
명명 규칙. 코드의 이름을 유지하여 디자인과 코드가 왕복할 수 있도록 하세요: CSS 변수 --muted-foreground는 Pencil 변수 --muted-foreground가 되고, $--muted-foreground로 참조됩니다. 이름을 $로 시작하지 마세요. 이름에 :를 사용하지 마세요. 코드에 이름이 없으면 역할에 따라 짧은 케밥 이름을 사용하세요: surface, text, text-muted, border, accent, space-4, radius-md.
레이어.
- 원시 값(Primitives): 원시 값, 테마 없음 (
gray-50...gray-950,blue-500,space-1...space-16). - 의미론적 값(Semantics): 역할 이름, 테마 적용, 원시 값 참조 (
--background: light$white, dark$gray-950). - 컴포넌트는 의미론적 값만 사용합니다.
$gray-900을 직접 참조하는 컴포넌트는 테마와 함께 전환되지 않습니다.
시스템 크기.
- 약 50개 토큰 미만: 하나의 플랫 세트,
light및dark가 있는 하나의mode축. - 더 큰 경우: 위와 같이 원시 값과 의미론적 값을 사용하고, 코드에 실제로 있을 때만 추가 테마 축을 사용하세요 (
density: comfortable, compact;brand: a, b).
작은 배치로 작성, 호출당 하나의 패밀리(원시 색상, 그 다음 의미론적 색상, 간격 및 반경, 그 다음 타입)로 작성하고 다시 읽으세요:
SetVariables({
"gray-50": {type: "color", value: "#FAFAFA"},
"gray-900": {type: "color", value: "#171717"},
"gray-950": {type: "color", value: "#0A0A0A"},
"white": {type: "color", value: "#FFFFFF"}
})
SetVariables({
"--background": {type: "color", value: [{value: "$white", theme: {mode: "light"}}, {value: "$gray-950", theme: {mode: "dark"}}]},
"--foreground": {type: "color", value: [{value: "$gray-900", theme: {mode: "light"}}, {value: "$gray-50", theme: {mode: "dark"}}]}
})
const v = GetVariables()
Print(Object.keys(v.variables).length, "variables", "|", JSON.stringify(v.themes))
mode축의 첫 번째 값이 제품에서 사용하는 기본값(보통light)인지 확인하세요.- 테마가 적용된 모든 변수에 사용하는 모든 테마 값에 대한 값을 제공하세요. 값이 누락되면 잘못된 색상이 자동으로 표시됩니다.
- 변경되지 않아야 하는 값(간격, 반경)은 테마 전체에서 동일하게 유지하세요.
- 타이포그래피:
--font-sans(문자열), 크기(text-sm14,text-base16...), 줄 높이는 비율(leading-normal1.5), 두께는 문자열("400","600"). - 그림자: 그림자 색상 변수와 코드에 그림자 스케일이 있는 경우 흐림 및 오프셋에 대한 숫자 변수.
- 기존 파일에서 명시적 동의 없이
SetVariables(..., true)를 절대 사용하지 마세요: 모든 변수를 지웁니다.
종료 기준: 계획의 모든 토큰이 올바른 유형으로 존재하고, 테마가 적용된 모든 토큰이 모든 테마 값을 가지며, 별칭이 기존 변수를 가리킵니다.
체크포인트: 패밀리별 개수, 테마 축 및 추측해야 했던 모든 값을 보여주세요.
Phase 2. 파일 레이아웃 및 파운데이션 보드
캔버스를 읽기 쉽게 유지하세요:
- 왼쪽 상단의 Foundations 프레임: 색상 견본, 타이포그래피 샘플, 간격 막대, 반경 샘플.
- 오른쪽 또는 아래쪽의 Components 영역, 컴포넌트 패밀리당 하나의 프레임(
Buttons,Inputs,Cards), 제목과 짧은 사용법 메모와 함께 컴포넌트를 포함합니다. - 더 아래쪽과 오른쪽의 Screens는 컴포넌트와 절대 섞지 마세요.
- 모든 루트 프레임에
FindEmptySpace를 사용하세요.
견본과 샘플은 변수에 바인딩되어야 하므로 토큰이 변경될 때 보드가 업데이트됩니다. 루프로 견본을 만드세요:
boardId = Insert(document, {type: "frame", name: "Foundations / Color", layout: "vertical", gap: 16, padding: 32, fill: "$--background", x: 0, y: 0})
rowId = Insert(boardId, {type: "frame", name: "Semantic colors", gap: 16})
for (const name of ["--background", "--foreground", "--primary", "--muted", "--border"]) {
const s = Insert(rowId, {type: "frame", name: "Swatch " + name, layout: "vertical", gap: 8})
Insert(s, {type: "rectangle", name: "Chip", width: 96, height: 64, cornerRadius: 8, fill: "$" + name, stroke: "$--border", strokeWidth: 1})
Insert(s, {type: "text", name: "Label", content: name, fontSize: 12, fill: "$--foreground"})
}
TakeScreenshot([boardId])
그런 다음 theme: {mode: "dark"}와 함께 보드를 복사하여 옆에 배치하세요: 어떤 것이 밝게 유지되면 토큰에 다크 값이 누락된 것입니다.
체크포인트: 두 테마의 보드 스크린샷.
Phase 3. 컴포넌트, 한 번에 하나씩
의존성 순서로: 원자 먼저(Icon wrappers, Badge, Avatar, Button, Input, Checkbox, Toggle), 그 다음 분자(Input group with label and hint, Menu item, Tab), 그 다음 유기체(Card, Dialog, Sidebar, Table row). 다른 컴포넌트를 포함하는 컴포넌트는 그 후에 빌드해야 하며, 다시 그린 복사본이 아닌 해당 컴포넌트의 인스턴스를 포함해야 합니다.
각 컴포넌트에 대해:
3a. 그리기 전에 API 설계. 코드 props에서:
- 색상이나 구조를 변경하는 변형 축은 별도의 컴포넌트가 됩니다:
Button/Primary,Button/Secondary,Button/Outline,Button/Ghost,Button/Destructive. - 토큰 값(크기, 밀도)만 변경하는 축은 더 많은 컴포넌트 대신 테마 축이 될 수 있습니다:
button-padding-y및button-padding-x와 같은 테마가 적용된 숫자 변수에size: md, sm, lg(첫 번째 값이 기본값). 그러면 하나의 컴포넌트가 인스턴스의theme: {size: "sm"}을 통해 모든 크기를 제공합니다. 테스트 완료 및 작동 확인됨. 코드가 동일한 방식으로 작동할 때 사용하세요. 그렇지 않으면 크기 컴포넌트도 만드세요. - 전역 스위치(목업에서 모든 배지 표시 또는 숨기기)는
enabled: "$show-badge"에 바인딩된 불리언 변수가 될 수 있습니다. 모든 인스턴스를 한 번에 변경하므로 데모 토글용으로 유지하고 인스턴스별 옵션에는 사용하지 마세요. - 개수를 합리적으로 유지하세요. 변형 * 크기 * 상태가 약 30개 컴포넌트를 넘어가면 패밀리를 분할하거나 축을 테마로 이동하세요.
- 상태: 사용자가 표시하려는 경우에만
Disabled또는Focus컴포넌트; 호버 및 프레스는 종종 문서화만 됩니다. - 불리언(아이콘 포함, 힌트 포함)은 변형이 아닙니다: 전체 컴포넌트를 빌드하고 인스턴스당
enabled: false로 부분을 숨기세요. - 아이콘은 변형이 아닙니다: 하나의 아이콘 노드,
icon재정의로 교체. - 자유 콘텐츠 영역은 슬롯입니다:
slot: [recommendedComponentIds],width: "fill_container"및 고정 높이(예:height: 40)가 있는 프레임.fit_content로 크기가 조정된 빈 슬롯은 0으로 축소되어 사라집니다.
3b. 기본 컴포넌트 빌드 한 번의 호출로: reusable: true, 레이아웃, 패딩, 갭, 반경 및 채움이 모두 변수에서 오는 프레임, 이름이 지정된 자식(Label, Icon, Content). 해당 id와 자식 id를 전역 변수에 캡처하세요.
const pos = FindEmptySpace({width: 600, height: 200, direction: "right", padding: 80})
buttonsId = Insert(document, {type: "frame", name: "Buttons", layout: "vertical", gap: 24, padding: 32, x: pos.x, y: pos.y})
btnPrimaryId = Insert(buttonsId, {type: "frame", name: "Button/Primary", reusable: true, gap: 8, padding: ["$button-padding-y", "$button-padding-x"], cornerRadius: "$radius-md", fill: "$--primary", alignItems: "center", justifyContent: "center"})
btnIconId = Insert(btnPrimaryId, {type: "icon", name: "Icon", library: "lucide", icon: "plus", width: 16, height: 16, fill: "$--primary-foreground"})
btnLabelId = Insert(btnPrimaryId, {type: "text", name: "Label", content: "Button", fontFamily: "$--font-sans", fontSize: "$text-sm", fontWeight: "500", fill: "$--primary-foreground"})
TakeScreenshot([btnPrimaryId])
3c. 다른 변형 빌드. 컴포넌트의 Copy는 새 컴포넌트가 아닌 인스턴스를 만듭니다. 독립적인 변형 컴포넌트를 얻으려면 한 번의 호출 내에서 작은 도우미 함수를 사용하여 각 변형을 다시 빌드하고 변형 테이블을 반복하세요:
const make = (name, fill, fg, stroke) => {
const id = Insert(buttonsId, {type: "frame", name, reusable: true, gap: 8, padding: ["$button-padding-y", "$button-padding-x"], cornerRadius: "$radius-md", fill, alignItems: "center", justifyContent: "center", ...(stroke ? {stroke, strokeWidth: 1} : {})})
Insert(id, {type: "icon", name: "Icon", library: "lucide", icon: "plus", width: 16, height: 16, fill: fg})
Insert(id, {type: "text", name: "Label", content: "Button", fontFamily: "$--font-sans", fontSize: "$text-sm", fontWeight: "500", fill: fg})
return id
}
btnSecondaryId = make("Button/Secondary", "$--secondary", "$--secondary-foreground")
btnOutlineId = make("Button/Outline", "$--background", "$--foreground", "$--border")
btnGhostId = make("Button/Ghost", "#00000000", "$--foreground")
변형 전체에서 자식 이름을 동일하게 유지하세요(Label, Icon). 그래야 인스턴스를 이름으로 재정의할 수 있고 변형 전환이 계속 작동합니다.
3d. 패밀리 배치 패밀리 프레임 내부의 읽기 쉬운 그리드에: 변형당 한 행, 크기 또는 상태당 한 열, 작은 텍스트 헤더 포함. 절대 위치가 아닌 gap이 있는 행 프레임을 사용하세요.
3e. 문서화: 패밀리 프레임에 제목과 2~3줄의 사용법 메모(어떤 변형을 언제 사용할지, 하나의 기본 동작 규칙).
3f. 확인:
- 패밀리 프레임에 대한 하드코딩된 확인: 의도적인 투명한 채움(
#00000000은 고스트 변형의 투명 채움으로 작동)을 제외한 16진수 채움 없음. - 호출의
issues detected블록(접힌 프레임, 빈 슬롯).ctx.problems클리핑 검사는 현재 버전에서 오경보를 제공합니다: 스크린샷으로 확인하세요. - 인스턴스 테스트: 각 변형의 인스턴스 하나를 스크래치 프레임에 삽입하고, 레이블을 긴 텍스트로 재정의하고 아이콘을 숨긴 다음 라이트 및 다크에서 스크린샷을 찍습니다(스크래치 프레임의
theme). 그 후 스크래치 프레임을 삭제하세요.
컴포넌트당 체크포인트: 스크린샷, 변형 목록 및 ID. 다음 컴포넌트를 승인 없이 시작하지 마세요.
Phase 4. QA 및 라이브러리
- 토큰 감사: 컴포넌트에서 사용하는 모든 변수가 존재합니다. 테마가 적용된 모든 변수가 모든 테마 값을 가집니다.
- 바인딩 감사: 컴포넌트 내부에 의도적으로 나열된 값을 제외하고 16진수 색상 또는 원시 간격이 없습니다.
- 대비: 두 테마 모두에서 배경에 대한 텍스트(본문 텍스트의 경우 4.5:1, 큰 텍스트의 경우 3:1
…
[번역이 잘렸습니다]