Pixerate/pixerate-canvas

Pixerate 캔버스

캔버스는 xyflow(React Flow / SvelteFlow) 그래프입니다. 노드(node) 와 엣지(edge) 의 배열로 구성됩니다. 노드는 { id, type, position: { x, y }, width?, height?, parentId?, zIndex?, data } 형태이며, 엣지는 { id, source, target, label? } 형태입니다. 디자인 기능이 알고 있는 모든 정보는 node.data에 저장되므로 복사, 붙여넣기 및 JSON에서도 유지됩니다.

• data.label / data.name: 텍스트 내용 및 레이어 이름. data.shape: 쉐이프 노드 ({ kind: rect | ellipse | polygon | star | path, fill, stroke, strokeWidth, ... }).
• data.layout: 오토 레이아웃 프레임 (mode horizontal / vertical / grid, gap, padding, alignMain, alignCross, sizing); 이 프레임의 자식 노드는 parentId가 해당 프레임인 노드들로, 노드 배열 순서대로 정렬됩니다. data.childLayout: 자식의 사이징(fixed / hug / fill) 및 제약 조건.
• data.component (메인 컴포넌트), data.componentSet (변형 세트), data.instance ({ componentId, properties }) 및 data.componentOverrides.
• data.locked, data.animation (키프레임 트랙), data.tokenBindings (디자인 토큰).

위치는 캔버스(흐름) 단위입니다. 자식의 위치는 부모를 기준으로 상대적입니다. 노드 ID는 get_editor_state에서, 컴포넌트 및 세트 ID는 list_components에서 가져옵니다. ids 또는 id를 인자로 받는 도구는 생략 시 현재 선택 영역을 기본값으로 사용하므로, 방금 canvas_select로 선택한 경우가 아니라면 명시적으로 ID를 전달하세요. 네임스페이스, run_commands 배치 및 오류 코드는 pixerate-agent-tools를 참조하세요.

워크플로우 스킬

다음 작업을 수행할 때는 워크플로우 스킬도 함께 로드하세요. 여기에는 방법, 단계 간 확인 사항 및 함정이 포함되어 있으며 아래 도구를 사용합니다.

• pixerate-canvas-design-system-components: 컴포넌트, 인스턴스, 변형 세트 및 오버라이드.
• pixerate-canvas-layout: 정렬, 분배, 순서 및 잠금.

작업 방법

1. 읽기. get_editor_state를 includeDocument: false로 호출하면 canvas.nodes 및 canvas.edges를 반환합니다. 디자인 시스템의 경우 list_components도 호출하고, 인스턴스를 변경하기 전에 inspect_instance를 호출하세요.
2. 먼저 구조를 계획하세요. 어떤 프레임, 어떤 재사용 가능한 컴포넌트와 변형, 어떤 간격 스케일을 사용할지 결정합니다. 메인 컴포넌트를 한 번 빌드한 다음 인스턴스를 배치하고, 노드를 수동으로 복사하지 마세요.
3. 쓰기. 전용 도구를 사용하여 그래프 편집(canvas_add_node, canvas_connect, canvas_update_node) 및 컴포넌트(create_component, create_instance, ...) 작업을 수행합니다. 정렬, 쉐이프, 애니메이션 명령과 같이 여러 단계가 하나의 실행 취소 단계여야 하는 경우(이전 단계에서 반환한 ID를 사용하는 매개변수 "$0.ids[0]" 포함) atomic: true와 함께 run_commands를 사용하세요.
4. 정리. 그래프에는 canvas_layout을, 디자인에는 canvas.align* / canvas.distribute*를, 레이어 순서는 canvas.bringToFront 등을, 완성된 배경은 canvas.lock을 사용하여 잠급니다.
5. 확인. 배치가 완료되면 view_editor(기본 뷰포트, JPEG, 1024px)를 사용하고, 전체 그림을 보려면 scope: "canvas"를 사용하세요. 겹침, 정렬 불량, 잘린 텍스트를 수정한 후 canvas_select 또는 canvas_highlight를 사용하여 사용자에게 보여줍니다.

사용자와 함께 작업하는 경우 (사용자가 빌드 중이고 요청 없이 추가하는 경우): 편집 대신 제안하세요. propose_nodes는 사용자가 수락하거나 거부할 수 있는 고스트를 표시하며, 그 전까지는 캔버스나 히스토리에 아무것도 도달하지 않습니다. 각 제안은 작고 하나의 아이디어(캡션, 시리즈의 다음 카드, 누락된 커넥터)에 집중하고, title과 한 문장의 rationale을 제공하며, nearNodeId로 보완하는 노드에 고정하세요. 사용자가 요청하지 않는 한 자신의 제안을 수락하지 마세요. 사용자가 제안의 기반을 변경할 때는 reject_proposal로 오래된 제안을 철회하세요. list_proposals는 missing 아래에 표시됩니다.

모범 사례

• 디자인 시스템 사고. 두 번 이상 나타나는 것은 모두 컴포넌트여야 합니다. 하나의 메인을 빌드하고, 상태 및 크기에 대해 combine_as_variants를 사용한 다음(State=Default, State=Hover, Size=Small), create_instance를 모든 곳에 사용합니다. 메인을 변경하면 모든 인스턴스가 변경됩니다. 오버라이드는 사용별 콘텐츠(레이블 텍스트, 아이콘 교체)에만 사용하세요. 변형 속성과 값의 이름을 일관되게 지정하고(속성은 Title Case, 값은 짧게) 조합이 고유하도록 유지하세요.

• 변형 전환 시 유지되어야 하는 레이어 이름은 안정적인 data.name을 사용하세요. 일치 항목이 없으면 data.label로 폴백되며, 텍스트의 경우 내용이므로 변형마다 다릅니다.

• 컴포넌트 속성 사용, 분리 금지. set_instance_properties로 변형을 전환하고 텍스트 또는 부울 속성을 설정하고, swap_instance로 다른 컴포넌트로 교체하세요. 인스턴스가 더 이상 메인을 따르지 않아야 하는 경우에만 분리하세요.

• 간격 스케일. 기본 단위(4 또는 8)를 선택하고 간격과 패딩에 배수를 사용하세요. 행과 스택은 자식의 위치를 수동으로 지정하는 대신 오토 레이아웃 프레임(data.layout)에 배치하여 콘텐츠가 변경될 때 리플로우되도록 하세요.

• 정렬 및 분배. 공유된 가장자리나 중앙에 정렬한 다음 동일한 간격으로 분배하세요. 가장자리가 정렬되면 디자인이 질서 정연하게 보입니다. 앵커로 사용할 노드는 잠그세요. 잠긴 노드는 절대 움직이지 않지만 선택 범위에는 계속 포함됩니다.

• 레이어링. 배경은 뒤쪽에, 콘텐츠는 위에, 오버레이는 맨 위에 배치하세요. 재스택 명령을 사용하세요. 명령은 형제 그룹별로 zIndex를 설정하고 배열을 재정렬하지 않습니다.

• 그래프 레이아웃. 흐름을 한 방향(LR 파이프라인, TB 계층 구조)으로 배치하고, 엣지를 짧게 유지하며, 관계가 명확하지 않은 경우에만 엣지에 레이블을 지정하세요.

• 모션. 도착하는 요소에는 ease-out(또는 약간의 오버슈트가 있는 ease-out-back)을, 떠나는 요소에는 ease-in을, 두 고정 위치 사이의 이동에는 ease-in-out을 사용하고, 회전과 같은 연속적인 모션에만 linear를 사용하세요. UI 전환은 약 150400ms, 진입은 약 600ms 미만으로 유지하고, 모든 것을 한 번에 움직이지 말고 관련 요소를 3080ms 간격으로 delay를 사용하여 지연시키세요. opacity, x, y, scale 및 rotation을 애니메이션으로 만들고, 색상 트윈은 OKLab에서 보간됩니다.

• 브러시 스트로크. 사용자가 손으로 그린 느낌(스케치, 잉크, 연필, 마커)을 원할 때 브러시를 사용하세요. 다이어그램 및 UI에는 일반 스트로크를 사용하세요. 곡선을 따라 2~8 캔버스 단위마다 점을 보내고, 다양한 너비의 여러 점 대신 짧은 pressure 프로필(가늘어지는 끝: [0.2, 0.9, 1, 0.9, 0.2])로 선의 모양을 만드세요. width를 생략하면 프리셋 자체 크기를 사용합니다(canvas.listBrushes로 확인 가능). 표시를 더 가늘거나 굵게 만들 때만 전달하세요.

• 브러시 특성. 각 프리셋은 고유한 특성으로 그려집니다. 목탄과 파스텔은 넓고 입자가 거칠며(종이의 질감을 잡음), 크레용과 초크도 마찬가지입니다. 연필은 가늘고 약간 거칠며, 잉크, 마커, 붓펜, 볼펜, 젤펜, 파인라이너는 깔끔합니다(파인라이너는 너비가 일정함). 에어브러시는 부드러운 스프레이입니다. 입자와 지터는 스트로크마다 시드(seed)되므로 스트로크는 항상 동일하게 보이며, 인접한 스트로크는 한 장의 종이를 공유합니다. 원하는 느낌에 맞는 브러시를 선택한 다음 색상을 선택하세요. 스케치에는 모든 브러시를 사용하지 말고 하나 또는 두 개의 브러시를 사용하세요. 기본 색상(볼펜 파란색, 하이라이터 노란색, 초크)이 있는 브러시는 color를 전달하지 않으면 해당 색상으로 칠하고, color를 전달하면 다른 색상을 사용합니다. 밝음/어두움 기본값(초크)은 캔버스의 색상 구성표에 따라 결정됩니다(canvas.setColorScheme, 호스트는 일반적으로 자체 테마와 일치).

• 사람을 위해 펜을 설정하는 것이지, 그림을 그리는 것이 아닙니다. canvas.selectBrush는 사람이 손으로 그리는 데 사용할 브러시를 브러시 선택기와 마찬가지로 선택합니다. 사람이 색상을 잠그지 않았거나(canvas.setColorLocked, "내 색상 유지") keepColour를 전달하지 않는 한 브러시의 기본 색상을 사용합니다. 이렇게 사용된 기본값은 다른 색상이 설정될 때까지 구성표를 따릅니다. 사람이 설정한 잠금을 존중하세요. 색상을 변경하기 위해 잠금을 해제하지 마세요. 이는 편집기 상태이며 실행 취소 단계가 아니며, 자체 brush 및 color를 사용하는 canvas.drawFreehand에는 영향을 미치지 않습니다.

• 포인트가 아닌 제스처로 주석을 답니다. 디자이너가 인쇄물에 마크업하는 방식으로 작업에 마크업하려면 제스처 명령(canvas.circle, canvas.underline, canvas.arrow, canvas.bracket, canvas.strike, canvas.cross, canvas.check)을 노드 ID({ "nodeId": "..." }) 또는 박스와 함께 사용하여 canvas.drawFreehand의 포인트를 계산하는 대신 사용하세요. 한 번의 호출로 하나의 손으로 그린 표시가 그려집니다. 주석은 캔버스에서 무언가를 가리키면서 이야기할 때 유용합니다. 선택 항목을 동그라미로 표시하고, 중요한 줄에 밑줄을 긋고, 견본에서 사용된 곳으로 화살표를 그리고, 설명하는 그룹을 괄호로 묶고, 거부된 옵션에 취소선 또는 십자 표시를 하고, 승인된 옵션에 체크 표시를 합니다. 캔버스에서 참조되는 것이 없을 때는 건너뛰고, 포인트당 몇 개의 표시로 유지하세요. 표시로 덮인 페이지는 아무 말도 하지 않습니다.

• 제스처 스타일. 한 번의 리뷰 패스에는 하나의 색상을 사용하고(빨간색 또는 강한 파란색 펜은 대부분의 디자인 위에 마크업으로 읽힘), 하이라이터는 원과 밑줄에만 사용하며, 손으로 그린 느낌을 원한다면 패스의 모든 표시에 동일한 brush(marker 또는 ink-pen)를 사용하세요. 표시는 요청에 의해 시드되므로 다시 요청하면 동일한 표시가 그려집니다. 다른 결과를 원하면 다른 seed를 전달하세요. 표시에 단어가 필요한 경우 괄호 옆이나 화살표 꼬리에 여백 노트(텍스트 노드)를 넣으세요.

도구 참조

읽기

도구	용도
get_editor_state	캔버스 그래프(canvas.nodes, canvas.edges)를 읽고, 기본적으로 프롬프트 문서도 읽습니다. 캔버스 전용 작업에서는 includeDocument: false를 전달하여 결과를 작게 유지하고, 프롬프트만 필요한 경우 includeCanvas: false를 전달합니다. 먼저 호출하고 사용자 편집 후 다시 호출하세요.
view_editor	편집기 이미지 가져오기: scope viewport(기본값) 또는 canvas(전체 그림 범위), format jpeg(기본값) 또는 png, maxEdge 픽셀(기본값 1024). 배치 후 겹침, 균형 및 가독성을 평가하는 데 사용하세요. 에이전트 커서는 제외됩니다.
capture_view	결과를 확인하기 위해 캔버스 일부를 스크린샷합니다. region viewport(기본값, 화면과 동일), content(모든 노드), selection, nodes(get_editor_state의 ids 사용) 또는 rect(캔버스 단위), padding(기본값 16), maxEdge(기본값 1024), format png(기본값) 또는 jpeg. 결과는 캡처된 rect 및 scale을 제공하므로 이미지 픽셀(px, py)은 캔버스 포인트(rect.x + px / scale, rect.y + py / scale)입니다. 방금 추가한 항목을 전체 세부 정보로 검사하려면 nodes를 선호하세요. includeOverlays가 없는 한 선택 상자와 에이전트 커서는 제외됩니다.
list_components	메인 컴포넌트(id, 이름, 변형 값, 인스턴스 수)와 해당 변형 옵션이 포함된 컴포넌트 세트를 나열합니다. create_instance, swap_instance 또는 변형 도구를 호출하기 전에 호출하여 ID와 정확한 속성 이름 및 값을 가져오세요.
inspect_instance	하나의 인스턴스(또는 그 안의 레이어, 기본값은 첫 번째 선택된 노드)를 설명합니다. 메인, 변형, 유형이 있는 컴포넌트 속성 값 및 레이어별 오버라이드를 포함합니다. set_instance_properties 또는 reset_overrides를 호출하기 전에 호출하여 올바른 속성 이름과 오버라이드 그룹을 사용하세요.

쓰기: 그래프

도구	용도
canvas_add_node	노드 추가: node(id는 선택 사항이며 사용되지 않아야 함, type은 호스트에 등록됨, data, position, width, height, 프레임의 경우 parentId). position을 생략하면 nearNodeId 옆의 side(기본값 right)에 겹치지 않도록 자동 배치하며, 해당 노드에서 엣지도 연결합니다. 또는 마지막 노드 옆에 배치합니다. 새 노드 id와 엣지 id를 반환합니다.
canvas_connect	source에서 target으로 엣지 추가(두 개의 다른 기존 노드), 선택적 label. 엣지 id를 반환합니다.
canvas_update_node	필드를 노드의 data에 병합합니다(예: { "label": "Checkout" }). 병합은 얕은 병합으로 처리합니다. shape 또는 layout과 같은 중첩 객체는 전체를 전달하세요. 노드를 이동하거나 크기를 조정하지 않습니다.
canvas_remove_nodes	노드와 해당 엣지를 삭제합니다. 모든 ID가 존재해야 합니다. 파괴적입니다. 사용자가 만든 콘텐츠를 제거하기 전에 사용자에게 확인하세요.
canvas_layout	그래프를 자동으로 정렬합니다. direction LR(기본값), TB, RL 또는 BT. incremental(기본값 true)은 이미 위치가 있는 노드를 유지합니다. 모든 것을 다시 배치하려면 false를 전달하세요. 정확히 (0, 0)에 있는 노드는 배치되지 않은 것으로 간주됩니다.
canvas_select	선택 항목을 바꿉니다(빈 목록은 선택을 해제). 사용자에게 결과를 표시하고 선택 항목에 작용하는 명령을 대상으로 지정하는 데 사용하세요.
canvas_highlight	사용자에게 노드를 가리키기 위해 노드를 깜빡입니다. color(기본값 #3b82f6), durationMs(기본값 2000, 최대 60000). 아무것도 변경하지 않습니다.

확장 및 축소

확장 가능한 노드(하위 작업으로 열리는 작업, 단계로 열리는 Gantt 막대)가 있는 호스트는 이러한 기능을 추가합니다. 확장은 노드의 하위 노드를 표시하고 주변 노드를 이동하여 공간을 만듭니다. 축소는 하위 노드를 제거하고 이동된 노드를 원래 위치로 되돌립니다. 보기 변경일 뿐, 편집이 아닙니다. 실행 취소 단계가 아니며 문서에 저장되지 않습니다. 호스트가 하위 노드가 무엇인지 결정합니다.

도구	용도
list_explodable_nodes	확장할 수 있는 노드(id, label, exploded, collapsing), 현재 exploded 및 collapsing인 ID, 여러 개를 동시에 열 수 있는지 여부(multiple), 확장이 비활성화된 경우 readOnly 이유를 나열합니다. 먼저 호출하세요. 확장 가능한 ID의 유일한 소스입니다.
explode_node	node(list_explodable_nodes의 ID)를 확장합니다. multiple이 아니면 이전에 확장된 노드가 축소됩니다(collapsed에 다시 나타남). 이미 확장된 노드를 확장해도 변경 사항이 없습니다(changed: false). 이제 exploded인 ID를 반환합니다. 그런 다음 get_editor_state 또는 capture_view를 사용하여 하위 노드를 읽거나 확인하세요.
collapse_node	확장된 node를 축소합니다. 여전히 exploded인 ID와 여전히 collapsing인 ID를 반환합니다(축소 애니메이션이 종료되면 하위 노드가 사라짐). 노드가 확장되지 않은 경우 실패합니다.

제안(편집하지 말고 제안)

에이전트가 추가를 제안하도록 허용하는 호스트는 이러한 기능을 추가합니다. 제안은 고스트로 표시되는 새 노드와 엣지입니다(드래그, 선택 또는 저장 불가). 수락하면 하나의 실행 취소 단계로 추가되며 제안한 사람(agent:<id>)이 만든 것으로 기록됩니다. 거부하면 캔버스와 해당 히스토리는 그대로 유지됩니다.

|

…[번역을 위해 잘림]