디자인 캔버스

디자인 캔버스은(는) 무엇을 하나요?

프로젝트 내에서 실제 HTML 파일로 화면을 디자인하고 로컬 디자인 뷰어에 표시합니다. 사용자는 모든 화면을 나란히 보고, 기기 크기와 라이트/다크 테마를 전환하고, PNG를 내보내고, 화면에 댓글을 달 수 있습니다. 댓글은 정확한 접두사와 함께 채팅 메시지로 다시 전달됩니다.

파일 (계약)

design/
  tokens.json            모든 디자인 토큰(두 테마 모두)의 단일 진실 공급원
                         브랜드 값이 있는 유일한 장소
  design-system.css      tokens.json에서 생성됨: [data-theme="light"] 및
                         [data-theme="dark"]에 대한 디자인 토큰 (절대 편집 금지)
  utilities.css          tokens.json에서 생성됨: 폐쇄형 유틸리티 어휘 (절대 편집 금지)
  design-system.md       브랜드 결정 사항을 짧은 글로 설명
  validate.mjs           검증기 (프로젝트당 한 번 복사 — 설정 참조)
  serve.mjs              뷰어용 작은 정적 서버 (프로젝트당 한 번 복사)
  viewer.html            뷰어 (프로젝트당 한 번 복사)
  mock.js                인터랙티브 화면용 모의 런타임 (프로젝트당 한 번 복사)
  mock.css               모의 런타임 클래스에 대한 정적 스타일 (프로젝트당
                         한 번 복사) — 토스트/오버레이/진입 전환 상태;
                         화면은 `../mock.css`로 링크; mock.js는 이러한
                         클래스만 토글하고 CSS를 주입하지 않음
  scripts/               프로젝트당 한 번 복사 (설정 참조)
    gen-tokens.mjs       tokens.json에서 design-system.css + utilities.css 재생성
    sync-components.mjs  각 컴포넌트 마커 영역을 부분에서 다시 구체화 (프로젝트당
                         한 번 복사)
    marker-parser.mjs    공유 마커 문법 파서 동기화 가져오기 런타임 (프로젝트당
                         한 번 복사)
  components/            컴포넌트 레지스트리 + 부분 시드 (프로젝트당
                         한 번 복사): components.json + 컴포넌트당 하나의 부분
  vendor/html-to-image.js  PNG 내보내기 라이브러리 (프로젝트당 한 번 복사)
  index.json             {"canvases": ["login", ...]} 뷰어가 나열할 수 있도록
  <canvas>/              캔버스당 하나의 폴더, 케밥-케이스 (login, dashboard)
    canvas.json
    data.json            선택적 가상 데이터; 선택적 "scenarios" 객체
                         명명된 최상위 재정의 (empty, critical…) 포함
    01-<screen>.html     화면당 하나의 완전한 HTML 문서
    assets/              선택적 로컬 이미지/스크립트

canvas.json (화면은 이 순서로 나타남):

{
  "title": "앱 로그인",
  "screens": [
    { "id": "login", "name": "로그인", "file": "01-login.html", "device": "mobile" },
    { "id": "cadastro", "name": "회원가입", "file": "02-cadastro.html", "device": "mobile" }
  ]
}

• device: mobile = 390×844, tablet = 834×1112, desktop = 1440×900; 선택적 width/height (정수 100–10000)가 이를 재정의합니다.
• group (선택 사항): 뷰어 스트립에서 화면을 제목이 있는 블록으로 그룹화하는 레이블 — 복잡한 프로젝트도 읽기 쉽게 유지 (예: "group": "체크아웃").
• transition (선택 사항): fade, slide-left 또는 none (기본값). Mock.go 후 화면의 진입 애니메이션입니다 — 동일 캔버스/교차 캔버스 규칙은 워크플로 3단계 참조.
• id는 고유하고 비어 있지 않음; name은 비어 있지 않음; title은 선택 사항.
• file은 캔버스 폴더를 기준으로 상대 경로: 절대 .., 선행 /, \) 또는 스키마 (http:, file:` …) 사용 금지.

프로젝트당 일회성 설정

design/이 아직 존재하지 않으면 생성하고 이 스킬의 폴더(SKILL.md가 포함된 폴더)에서 복사:

• scripts/validate.mjs → design/validate.mjs
• assets/viewer.html → design/viewer.html
• assets/serve.mjs → design/serve.mjs
• assets/mock.js → design/mock.js
• assets/mock.css → design/mock.css (모의 런타임 클래스용 스타일; 화면은 ../mock.css 링크)
• assets/docs.html → design/docs.html (사용 가이드, 뷰어의 📘 문서 버튼에서 링크)
• assets/vendor/html-to-image.js → design/vendor/html-to-image.js
• scripts/gen-tokens.mjs → design/scripts/gen-tokens.mjs
• assets/components/ → design/components/ (레지스트리 + 부분 시드)
• scripts/sync-components.mjs → design/scripts/sync-components.mjs
• scripts/marker-parser.mjs → design/scripts/marker-parser.mjs (공유 파서 모듈 동기화 가져오기, 런타임에 필요)
• scripts/export-tokens.mjs → design/scripts/export-tokens.mjs (W3C/DTCG 교환 내보내기: tokens.json → tokens.w3c.json; 파생 아티팩트, 절대 수동 편집 금지)

이 복사 목록의 규칙: 이미 존재하는 파일만 입력됩니다("só entra no copy list arquivo que já existe"). 아직 제공되지 않은 파일은 해당 계약 웨이브에서만 추가됩니다: export-tokens.mjs는 계약 웨이브 6(todo 30)에서 추가되었으며 위에 나열되어 있습니다 — 규칙이 충족됩니다(파일은 todo 26부터 존재함). (mock.css는 웨이브 3에서 추가되었으며 위에 나열되어 있습니다.)

tokens.json이 변경될 때마다 프로젝트 루트에서 두 개의 생성된 파일을 다시 생성하십시오:

node design/scripts/gen-tokens.mjs

design/index.json ({"canvases": []})을 만들고 캔버스를 생성할 때마다 새 캔버스 이름을 추가하십시오. 완전하고 유효한 예제는 이 스킬의 assets/example/에 있습니다 — 두 개의 캔버스에 걸쳐 작동하는 주식 앱 시스템입니다: login/ (로그인, 회원가입, 일반 링크에서 오버레이로 열리는 계정 삭제 확인 모달) 및 dashboard/ (긴 항목 목록, 동일 캔버스의 fade 전환과 스크롤 복원을 보여주는 "목록 업데이트" 새로고침 기능이 있는 인터랙티브 개요), 여기서 로그인 및 회원가입은 개요로 캔버스 간 이동하며, 개요는 가상 항목을 읽고, 명명된 시나리오를 지원하며, 로그인 캔버스로 로그아웃합니다. 새 디자인 시스템 또는 캔버스를 시작하기 전에 이를 읽고 적용하십시오. 시드 example/components/는 assets/components/의 바이트 동일 복사본입니다 ("example/components/ é cópia byte-idêntica de assets/components/ (fonte única)"): 부분은 assets/components/에서만 편집하고 예제 복사본에서는 절대 편집하지 마십시오.

워크플로

1. 디자인 시스템 우선. design/design-system.css 및 design/design-system.md를 읽으십시오. 파일이 없으면 사용자에게 브랜드(기본 색상, 서체 느낌, 톤; 중립 팔레트를 하나의 옵션으로 제공)를 묻고 둘 다 생성하십시오. 이후 캔버스는 이를 재사용합니다. 토큰은 요청 후에만 변경하십시오.
2. 누락된 것만 물으십시오. 요청이 모호한 경우(어떤 화면, 어떤 플랫폼, 어떤 데이터) 한 번만 묻고, 명확하면 시작하십시오.
3. 캔버스를 구축하십시오. 먼저 이 스킬의 폴더에서 assets/craft.md를 읽고(형제 공예 스킬 — taste, emil-design-eng, impeccable — 을 캔버스 화면에 대한 규칙으로 융합) 모든 화면에 적용하십시오. 그런 다음 canvas.json 및 화면을 생성하십시오. 모든 화면에 대한 규칙:
   • 스타일링 정책: 유틸리티 어휘가 어휘입니다. 토큰 기반(색상, 유형, 간격, 반경)의 모든 것은 생성된 유틸리티를 통해 사용: <link rel="stylesheet" href="../design-system.css"> 및 <link rel="stylesheet" href="../utilities.css">를 연결한 다음 bg-accent, p-2, text-heading, rounded-md와 같은 클래스를 사용하십시오. 인터랙티브 화면은 또한 <link rel="stylesheet" href="../mock.css"> (모의 런타임 클래스: 토스트, 오버레이, 진입 전환)를 연결합니다. 의미론적 클래스는 구조와 레이아웃만 전달합니다. var(--…)는 적합한 유틸리티가 없는 경우에 허용되며, 인라인 <style> 블록은 허용되지만 0개의 리터럴 색상을 포함해야 합니다. 금지 검사는 <style>, style="" 및 SVG fill=/stroke=의 VALUE 위치에서 리터럴 색상을 검사합니다. 또한 화면 어디에서든 http(s)://, Tailwind 팔레트 클래스(예: bg-zinc-900) 및 임의 값(예: text-[13px])을 금지합니다.
   • 두 테마 모두에서 토큰을 통해 작업하십시오. 테마는 <html>에 data-theme으로 도착합니다(기본값은 light — 속성 포함).
   • 어떤 종류의 CDN 또는 원격 URL도 사용하지 마십시오(캔버스는 오프라인 및 샌드박스 처리됨): 인라인 SVG 아이콘, 시스템 글꼴 또는 design/ 아래의 글꼴 파일, 로컬 이미지.
   • 사용자 언어(기본값: 브라질 포르투갈어)의 실제 카피와 그럴듯한 샘플 데이터 — 로렘 입숨 사용 금지.
   • 중요할 때 빈 상태, 로딩 상태 및 오류 상태를 추가 화면으로 다루십시오.
   • 접근성 기본 사항: 입력 레이블, 가시적 포커스, 충분한 대비, 모바일에서 44px 이상의 탭 대상.
   • 레이아웃은 화면의 장치 너비에서 유지되어야 합니다.
   • 컴포넌트는 부분의 인스턴스이며, 느슨한 컴포넌트 마크업이 아닙니다 ("instância usa partial, nunca markup solto de componente"). 모든 인스턴스를 마커 쌍 <!-- component:id size=md tone=primary state=default -->…<!-- /component:id -->으로 감싸고 세 가지 필수 인수 size=, tone=, state=를 포함하고(값은 design/components/components.json의 레지스트리 열거형에 있어야 함), 슬롯을 쌍을 이루는 마커 <!-- slot:name -->…<!-- /slot:name -->로 채우십시오. 우선 순위: 마커 인수가 진실 공급원입니다(marker-args-win). 동기화는 실행할 때마다 마커에서 data-size/data-tone/data-state 및 변형 클래스를 다시 내보냅니다. 슬롯 내용과 루트의 사용자 추가 data-* 속성은 유지됩니다.
   • 포스터가 아닌 시스템 미리보기로 만드십시오. 요청이 작동하는 제품을 의미하는 경우 모의 런타임(<script src="../mock.js"></script>, 설정에서 복사)으로 화면을 연결하십시오: 양식은 유효성 검사 및 제출, 버튼은 피드백 제공, 화면은 Mock.go('03-dashboard.html')로 탐색, 가상 데이터는 캔버스의 data.json (await Mock.data('items')), 흐름 상태(로그인한 사용자, 도중에 생성된 항목)는 Mock.state (세션, 캔버스별 네임스페이스)에 저장, 시뮬레이션된 작업은 Mock.toast('…')로 확인합니다. JS가 실패해도 모든 화면은 여전히 정적 구성으로 렌더링되어야 합니다. 뷰어는 탐색한 카드에 ↺ 시작 버튼과 전체 흐름을 다시 시작하는 "흐름 재설정" 버튼을 표시합니다. 중요한 상태는 data.json의 명명된 scenarios로 다루십시오(최상위 재정의, 예: "vazio": {"items": []}) — 뷰어는 이에 대한 선택기를 얻고, 선택은 탐색 시 유지되며, 각 시나리오는 잘 구성되어야 합니다(빈 목록, 최소 미만의 모든 항목, API 실패). 시스템은 여러 캔버스에 걸쳐 있을 수 있습니다(흐름당 하나): Mock.go('../<canvas>/<screen>.html')로 교차 탐색 — 흐름 상태는 프로젝트 전체에서 공유되므로 로그인 캔버스가 사용자를 설정하고 대시보드 캔버스가 이를 읽습니다. 뷰어의 캔버스 선택기는 캔버스 간에 이동합니다(각 캔버스는 자체 시나리오, 테마 및 장치를 유지). 모달 및 확인 대화상자도 전체 캔버스 화면입니다(단일 진실 공급원): 트리거는 일반 화면 링크 <a href="03-modal.html">이며, 모의 런타임이 이를 Mock.overlay('03-modal.html')로 가로챕니다 — JS가 없으면 수정되지 않은 href는 모달 화면 자체로 이동합니다(JS 꺼짐 폴백). 지속적인 탐색(사이드바, 상단 메뉴, 탭)은 실제로 화면을 전환해야 합니다: 각 항목에 data-go="02-cadastro.html"을 넣고(같은 링크에 실제 href="02-cadastro.html"을 유지하여 JS 꺼짐 폴백 제공 — 런타임은 data-go를 Mock.go로 라우팅하여 ?scenario= 및 진입 전환 유지). 일반 링크는 오버레이 트리거(모달/세부 정보 — 일반 화면 링크는 항상 오버레이를 엽니다)용으로 유지됩니다. 동일한 탐색 블록을 캔버스의 모든 화면에 반복하고 활성 항목을 표시하십시오. 화면은 canvas.json에서 "transition": "fade"| "slide-left"| "none"을 선언할 수 있습니다: Mock.go는 대상에 진입 클래스(mock-enter-fade/mock-enter-slide-left, 300ms 이내에 자체 제거됨)를 전달합니다. 핸드오프는 대상 파일 이름과 일치하는 현재 캔버스의 canvas.json을 읽으므로 동일 캔버스 홉에 대해 작동합니다(예: Mock.go('01-overview.html') 자체 탐색은 새로고침 패턴임) — 교차 캔버스 Mock.go('../<canvas>/<screen>.html')는 진입 클래스 없이 일반 탐색입니다. 스크롤 위치는 화면당 유지됩니다(sessionStorage의 scroll.<canvas>.<file>, 화면이 반환될 때 복원되고 흐름 재설정 시 유지됨, 흐름 재설정은 mock.*만 지움).
4. 검증 및 수정. 필수 동기화 먼저: design/components/에서 부분(또는 마커 인수)을 편집한 후 아무것도 제시하기 전에 프로젝트 루트에서 node design/scripts/sync-components.mjs를 실행하십시오. 각 인스턴스를 부분에서 다시 구체화합니다(marker-args-win). --check는 드라이런 형식입니다: 발산되는 영역당 file:line diff를 출력하고 발산 시 1로 종료(0은 깨끗함), 절대 쓰지 않습니다. 그런 다음 프로젝트 루트에서 node design/validate.mjs design/<canvas>를 실행하십시오. 나열된 모든 문제를 수정하고 요약 줄만 남을 때까지 다시 실행하십시오. 문제가 있는 캔버스는 절대 제시하지 마십시오. 검증기의 인수는 디자인 루트(프로젝트 모드) 또는 단일 캔버스 폴더(캔버스 모드)입니다. 인수 없으면 기본값은 ./design입니다. 구조적 검사는 canvas.json에 나열된 화면만 다룹니다. 프로젝트 모드는 추가로 토큰/생성된 CSS 오래됨, 컴포넌트 및 댓글을 검사합니다. 컴포넌트 규칙은 canvas.json과 독립적으로 모든 비면제 .html에서 스캔되며, 코드는 component-unknown, component-variant, component-marker, component-divergence 및 slot-marker입니다. --allow-stale은 오래됨 검사만 건너뜁니다. --mark-stale은 검증기의 유일한 쓰기 작업입니다(앵커가 사라진 댓글 핀 표시). --example-inventory는 예제 계약 검사입니다(inventory.json의 정확한 파일 목록 + 모든 핀에 "_demo": true; inventory.json이 없으면 건너뛰고 0으로 종료). 4b. 흠 없는 감사. 검증 후, 형제 impeccable 스킬의 기술 감사를 캔버스에서 실행하십시오(설치된 레이아웃, win32): <skill-impeccable>/scripts/impeccable.cmd audit design/<canvas> - 경로는 설치된 스킬에서 확인됩니다.

…

[번역을 위해 잘렸습니다]