HTML 프로토타입 빌드
모든 프로토타입은 이 스킬 디렉토리의 assets/template.html을 기반으로 빌드합니다. 하나의 자체 포함 HTML 파일입니다. 템플릿에는 이미 전체 셸(헤더, 브라우저 프레임, 상태 전환기, 노트 패널, 화면 맵, 검토자 댓글, k-* 컴포넌트가 포함된 Koobiq 토큰 및 런타임)이 포함되어 있습니다. 셸 UI는 OS/브라우저 언어에 따라 영어 또는 러시아어로 표시되며, 프로토타입 자체의 사본은 사용자가 작성하는 언어 그대로입니다. PROTOTYPE 블록(JS)과 섹션 5. PROTOTYPE STYLES(CSS)만 작성하십시오. 템플릿을 손상시키지 마십시오. 셸을 다시 빌드하거나, 스타일을 재정의하거나, 설명하지 마십시오.
코드 작성 전 설계
프로토타입은 화면 갤러리가 아니라 단일 의사 결정을 위한 도구입니다. prototype.js를 작성하기 전에 다음 단계를 수행하십시오.
-
맥락 파악. 사용자의 역할(직무, 전문성), 수행 중인 작업, 트리거 및 '완료' 상태가 무엇인지 파악합니다. 제품이 존재하는 경우(저장소, 스크린샷, Figma, 문서, 이전 프로토타입) 해당 제품의 탐색, 용어, 엔티티 및 데이터를 가져와 변경 사항만 설계합니다. 기능을 중심으로 제품을 발명하지 마십시오.
-
질문 명명. 검토자가 결정해야 하는 사항 또는 UI에서 가장 의심스러운 점(사용자가 X를 찾을 수 있는지, Y를 이해하는지, Z가 실제 데이터에서 유지되는지)을 한 문장(대규모 프로토타입의 경우 여러 문장)으로 작성합니다. 각 질문에 대해 검토자가 답변을 위해 봐야 하는 내용과 설계를 무너뜨릴 수 있는 상태 또는 데이터를 기록합니다. 요청에 질문이 명시되지 않은 경우, 가장 위험한 결정을 하나의 질문으로 간주하고 4단계에서 작성자에게 제시합니다. 3.사용자의 관점에서 시나리오 작성 (트리거부터 결과까지): "분석가가 스파이크를 봄 → 규칙 열기 → 임계값 낮추기 → 발생할 인시던트 수 확인". 그런 다음 질문에 필요한 분기만 추가합니다: 취소, 유효성 검사 오류, 빈 상태 또는 첫 사용, 그리고 아무도 예상하지 못한 요구 사항이 표면화되는 어려운 경우: 권한 없음, 다른 객체와의 충돌, 제한, 대량의 데이터, 객체의 현재 상태가 금지하는 작업. 단계는
STEPS가 되고, 분기는 상태가 되며, 교차 조건(역할, 기능 플래그, 데이터 볼륨)은SWITCHES가 됩니다. -
빌드 전에 작성자와 합의. 하나의 짧은 메시지로 다음을 보냅니다:
- 질문
- 계획한 분기 및 어려운 경우를 포함한 시나리오
- 요청 또는 제품에서 가져온 것이 아니라 추측한 모든 내용을 번호가 매겨진 목록(항목당 하나의 진술)으로 작성하여 작성자가 번호로 답변할 수 있도록 합니다: "2 — 아니요, 관리자의 승인이 필요합니다."
답변을 기다리십시오. 기존 프로토타입을 약간 수정하는 경우 이 단계를 건너뜁니다. 작성자가 질문하지 말라고 요청한 경우, 추측을 바탕으로 빌드하고 답변에 나열합니다.
-
각 단계 × 상태 셀의 깊이 설정:
- 전체(full) = 질문 경로: 클릭 가능, 모든 상태, 스트레스 데이터
- 그럴듯함(plausible) = 컨텍스트: 정적이지만 현실적
- 제외(out) = 답변에서 다루지 않는 것으로 명명됨
질문에 필요한 상태만 사용하십시오: 이상적, 비어 있거나 첫 사용, 부분, 오류, 권한 없음, 단계당 최대 약 6개. 특정 항목(긴 작업, 진행률, 부분 결과)을 보여줄 때만 로딩 상태를 추가합니다. 실패한 로드는 거의 상태를 가질 가치가 없지만, "이 객체의 상태에서 허용되지 않음"은 일반적으로 그렇습니다. 설계되지 않은 결과를 절대 가짜로 만들지 마십시오.
-
먼저 각 화면을 글로 설계: 한 구절로 된 목적, 하나의 기본 작업, 사용자가 여기서 결정하기 위해 봐야 하는 내용(중요도 순). 그런 다음 표준 Koobiq 패턴(테이블, 양식, 사이드 패널, 모달, 빈 상태)으로 구축합니다. 질문이 있는 곳에만 새로움을 두고, 나머지는 제품의 일반 화면처럼 보이게 합니다.
- 모든 작업에는 눈에 보이는 결과(무슨 일이 발생했는지, 객체가 현재 어디에 있는지)가 있습니다.
- 파괴적인 작업은 객체와 그 결과의 이름을 지정합니다. 버튼은 일반적으로 동사를 표시합니다.
- 오류 메시지는 수정 방법을 알려주고 입력을 유지합니다.
- 화면, 브레드크럼, 토스트 및 URL에서 하나의 사물에 대해 하나의 이름을 사용합니다. UI 사본은 사용자의 언어로 작성되며,
ux-write가 설치된 경우 이를 따릅니다.
-
뷰보다 먼저 데이터를 작성합니다. 레이아웃에 부담을 주는 현실적인 도메인 데이터를 사용하십시오: 긴 이름 하나, 0/1/많음 개수, 희귀 상태. 고정 날짜와 값(
Date.now()/Math.random()없음)을 사용하고 로렘 입숨을 사용하지 마십시오.
변형(Variants), 질문이 "어떤 솔루션"인 경우에만 사용합니다. 검토자를 위해 선택하는 대신 VARIANTS에 2-3개(최대 5개)를 빌드합니다.
- 구조(레이아웃, 계층 구조, 기본 작업)가 다르며 색상이나 사본이 다르지 않습니다. 두 초안이 비슷해 보이면 명시적인 금지("카드 그리드 없음")와 함께 하나를 다시 작성합니다.
- 변형은 데이터를 공유할 수 있지만 레이아웃은 절대 공유하지 않습니다.
- 각각
title과 한 줄 아이디어를text로 제공합니다. - 가장 좋은 피드백은 "B의 헤더, C의 목록"입니다.
완료 조건
회신하기 전에 각 항목에 대해 프로토타입을 확인하십시오:
- 표시된 모든 경로가 처음부터 끝까지 실행됩니다. 사용자가 트리거를 만나는 지점에서 시작하며 로그인 또는 대시보드에서 시작하지 않습니다. 표시된 모든 분기는 경로로 돌아오거나 결과에서 끝납니다. 다른 제품 또는 시스템으로의 핸드오프는 눈에 보이는 결과(토스트 또는 "Jira에 작업 생성됨"과 같은 상태)가 있는 스텁으로, 다른 UI의 사본이 아닙니다. 보조 컨트롤은 아무 작업도 수행하지 않을 수 있습니다(메뉴 항목이
close만 할 수 있음). 단, 해당 컨트롤에서 시나리오가 시작되지 않는 경우에 한합니다. - 논쟁의 여지가 있는 부분은 표시됩니다. 변경되었거나 논쟁의 여지가 있는 모든 요소에는 노트가 있습니다. 어느 솔루션을 선택할지가 질문인 경우 구조가 다른 2-3개의 변형이 있습니다.
- 불필요한 것은 없습니다. 모든 상태, 스위치 및 노트는 질문에 답하는 데 도움이 되거나 요구 사항에 대한 추측을 테스트합니다. 나머지는 제거하십시오.
빌드
-
편집 가능한 부분을 가져옵니다.
SKILL_DIR= 이 스킬의 디렉토리,A=$SKILL_DIR/scripts/assemble.mjs(node로 실행, 종속성 없음), 작업 디렉토리 예:/tmp/proto-<name>/:- 새 프로토타입:
node $A --split $SKILL_DIR/assets/template.html /tmp/proto-<name> - 기존 프로토타입 변경:
node $A --split <file>.html /tmp/proto-<name>. 재조립하면 셸도 업그레이드됩니다.
이렇게 하면
prototype.js(데모 PROTOTYPE 블록)와prototype.css(섹션 5)가 제공됩니다. - 새 프로토타입:
-
prototype.js를 다시 작성하여 모든 데모 콘텐츠(PROTO,STEPS,SWITCHES,S,NOTES,LINKS(보통[]), 데이터,VIEWS,ACTIONS)를 대체합니다. 사용자 정의 CSS는prototype.css에 넣습니다. 패스별로 작업합니다:- 기본 경로, 이상적인 상태에서 처음부터 끝까지 클릭 가능
- 기타 상태 및 분기
- 노트
- 확인 및 완료 조건
경로가 작동하기 전에 화면을 다듬지 마십시오.
-
조립:
node $A <target>.html /tmp/proto-<name>/prototype.js /tmp/proto-<name>/prototype.css. 구문과 필수 선언을 확인합니다. HTML만 전달합니다. -
뷰: 단계당 하나의
VIEWS[step](S). HTML 문자열을 반환하고S.state/S.sw에 따라 분기합니다.k-*클래스로 빌드하며,references/koobiq-cheatsheet.md를 참조하십시오.- 모든 상태는 직접 열렸을 때 완전히 렌더링됩니다. 직접 열기(팝오버, 해시 링크, 맵 썸네일, 노트, ←/→,
protoCheck)는 초기S에 상태의seed를 더하여 시작합니다(예:{ id: 'confirm', title: 'Confirmation', seed: { name: 'Brute force: RDP' } }). 흐름 내goto()는 사용자가 입력한 내용을 유지합니다. VIEWS는S와 상수 데이터만 읽습니다. - 오버레이. 모달 또는 사이드 패널은 동일한 뷰 내에서 덮는 화면 위에 그려집니다. 일회성 오버레이(확인)는 해당 단계의 상태입니다(
form/confirm). 자체 하위 흐름(양식 → 오류 → 확인)이 있는 오버레이는 그 아래에 덮인 화면을 그리는 자체 단계가 될 수 있습니다. 패널 위의 모달의 경우 패널 뒤에 모달을 렌더링합니다. 마지막.k-overlay가 최상위이며 해당 마커만 표시됩니다. - 스크롤. 브라우저 프레임보다 긴 화면은 페이지처럼 내부에서 스크롤됩니다. 새 단계는 맨 위에서 시작합니다. 동일한 단계의 새 상태 또는 변형은 스크롤을 유지하므로 검토자가 동일한 지점에서 비교할 수 있습니다. 앱 셸(
.app-body+.app-content)은 이전과 같이.app-content내에서 스크롤됩니다. data-act→ACTIONS로 클릭을 연결합니다.goto(step, state)/data-goto를 통해서만 화면을 변경합니다. 상태 버튼, URL 표시줄 및 해시가 동기화 상태를 유지합니다.
- 모든 상태는 직접 열렸을 때 완전히 렌더링됩니다. 직접 열기(팝오버, 해시 링크, 맵 썸네일, 노트, ←/→,
-
노트(3-7개) 는 질문의 대상이 되는 요소(변경되었거나 논쟁의 여지가 있는 요소)에만 넣습니다.
- 요소에
class="changed" data-anchor="note-N"을 넣고 그 안에${marker(N)}을 넣습니다. void 또는 비활성화된 요소는<span class="k-anchor changed" data-anchor="note-N">로 감쌉니다. - 노트
text는 1-2문장으로 변경된 내용과 이유를 설명합니다. 가설인 경우 "확인: …"으로 끝냅니다. try는 확인을 위해 클릭할 항목을 알려줍니다.
- 요소에
-
화면 맵은 상태 및 전환에서 자동으로 빌드됩니다. 전환은 각 상태의 마크업(
data-goto, 활성화된 컨트롤, 메뉴 항목 및 최상위 오버레이가 호출하는ACTIONS의 리터럴goto()/openState()호출)에서 가져옵니다(비활성화된 컨트롤은 화살표를 제공하지 않음). 동일한 액션에서 계산된 상태는 가능한 ID가 문자열로 나타나는 경우 작동합니다:goto('list', S.q ? 'empty' : 'data'). 도우미 함수, 타이머 또는 사용자가 클릭하지 않는 이벤트 뒤의 전환은LINKS로 이동합니다:{ from: 'report/building', to: 'report/ready', label: 'Report ready' }. -
확인(확인 섹션 참조).
protoCheck()가 깨끗해질 때까지 수정 및 재조립한 다음 완료 조건에 대해 프로토타입을 확인합니다. -
회신은 파일 경로, 단계 × 상태 표, 의도적으로 다루지 않은 내용 및 합의 후에 이루어진 모든 추측과 함께 제공합니다. 셸을 설명하지 마십시오.
검토자 댓글
사용자는 "모두 복사"에서 마크다운을 붙여넣을 수 있습니다. 파일: 줄에 파일 이름이 있습니다. 각 ##는 해시(#step/state?switches)가 있는 화면입니다. 변형이 있는 경우 변형 B · 카드 →로 시작하고 해시에 variant=<id>가 있습니다. 셸은 검토자의 UI 언어로 작성하므로 러시아어일 수 있습니다: Файл:, Вариант B. 각 ###는 #view 내의 선택기, data-* 속성 및 연결된 노트 번호가 있는 요소이며, 그 뒤에 댓글이 인용문으로 표시됩니다.
적용하려면 해당 파일(해당 변형의) VIEWS[step] / ACTIONS에서 요소를 찾은 다음 --split을 통해 편집하고 동일한 파일로 재조립합니다. 댓글은 파일 경로 아래 브라우저의 localStorage에 저장됩니다.
셸 규칙
- 헤더 = 짧은 제목만. 프레임 위에 부제목, 캡션, 범례 또는 "… 흐름의 프로토타입" 텍스트가 없어야 합니다.
- 하나의 상태 컨트롤: "단계 · 상태" 팝오버. 이전/다음 스테퍼, 화면별 세그먼트 컨트롤, 프레임 위의 탭 또는 사용자 정의 단축키(←/→, Esc 및 1-9 변형 선택기는 내장됨)가 없습니다.
- 노트는
aside#notes(.browser외부)에만 있습니다..app내부에는 번호가 매겨진 마커만 있습니다.::after툴팁, 오버레이 또는 앱 내부의 "검토 모드" 열에 노트 텍스트를 절대 넣지 마십시오. - 런타임을 편집하지 말고, 데크, 스테이지, 브라우저, 노트, 댓글 또는 화면 맵을 이동하거나 스타일을 재정의하지 마십시오. 동작은
ACTIONS에 넣습니다. - 기본값은 Koobiq:
k-*클래스 및--kbq-*토큰. 16진수/rgb 색상, 발명된 팔레트(--bg, 보라색 악센트) 및 밝은 모드 전용 스타일링을 사용하지 마십시오. 테마 전환이 작동해야 하기 때문입니다. 다른 디자인 시스템의 경우 셸을 유지하고 앱만 스타일을 재정의합니다. - 하나의 파일, 외부 JS 없음.
PROTOTYPE API
| 항목 | 방법 |
|---|---|
| 제목 / URL 표시줄 | PROTO.title, PROTO.url(S) |
| 팝오버 그리드 | STEPS[{id,title,states[{id,title,seed?}]}], SWITCHES[{id,title,options}] |
| 상태 | S.step, S.state, S.sw[id], S.menu (열린 메뉴 ID), 그리고 사용자 정의 필드 |
| 탐색 | 흐름 내 goto(step, state, patch?) (S 유지); 마크업 data-act="goto" data-goto="form/errors". openState(step, state) = 직접 열기(초기 S + seed) |
| 액션 | data-act="name" → ACTIONS.name(el, e); false를 반환하지 않으면 다시 렌더링 |
| 내장 액션 | goto; close (S.menu = null); menu + data-menu="id" (토글); set + data-field + data-value (S에 쓰기, 메뉴 닫기). 메뉴는 Esc, 외부 클릭 및 다른 모든 액션에서도 닫힘 |
| 입력 | data-model="field"는 S.field를 씁니다. data-live는 입력 시 다시 렌더링합니다(포커스와 캐럿 유지). data-live="act"는 먼저 ACTIONS.act를 호출합니다. data-scroll="key"는 스크롤 유지 |
| 포커스 | goto('form', 'errors', { focus: 'name' })는 [data-model="name"]을 한 번 포커스합니다 |
| 도우미 | icon('search'), marker(n, '--x:100%;--y:50%'), tip(html, text, 'k-float--right'), matches(S.q, ...fields), toast(title, {kind, text}), esc(str) |
| 노트 | NOTES[{id, step, state, title, text(html), try}]: step/state는 앵커가 있는 위치를 나타냅니다 |
| 화면 맵 | 자동으로 빌드됩니다. LINKS[{from: 'step/state', to: 'step/state', label}]는 스캔이 볼 수 없는 전환을 추가합니다 |
| 변형 | VARIANTS[{id, title, text, STEPS?, NOTES?, VIEWS?, ACTIONS?, LINKS?, S?, url?}]. 전역 선언은 변형 A입니다. 변형은 다른 부분만 재정의합니다(S는 전역 S에 병합됨). 각 변형은 자체 화면 맵, 노트 및 댓글을 가집니다. SWITCHES와 뒤로/앞으로는 공유됩니다. 헤더의 선택기, 키 1-9 |
확인
폴더를 백그라운드에서 제공합니다(file://는 종종 차단됨) 그리고 브라우저 도구에서 인쇄된 URL + <file>.html을 엽니다. 재조립 후 다시 로드합니다. 해시만 변경된 경우 파일을 다시 로드하지 않기 때문입니다.
cd <dir> && node -e "const fs=require('fs'),T={'.html':'text/html; charset=utf-8','.js':'text/javascript','.css':'text/css','.svg':'image/svg+xml'};require('http').createServer((q,r)=>{const p='.'+decodeURIComponent(new URL(q.url,'http://x').pathname);fs.readFile(p,(e,d)=>{r.writeHead(e?404:200,{'Content-Type':T[require('path').extname(p)]||'application/octet-stream'});r.end(e?'Not found':d)})}).listen(0,'127.0.0.1',function(){console.log('http://127.0.0.1:'+this.address().port+'/')})"
protoCheck()실행 페이지에서 (콘솔 또는 브라우저 도구의 평가 사용) 창 너비 1440 이상에서 실행합니다.ok: true를 반환해야 합니다. 두 테마에서 모든 단계 × 상태 × 스위치 조합을 열고 렌더링 오류, 빈 화면, 오버플로, 깨진 마커 또는 노트, 알 수 없는data-act/data-goto/goto()/LINKS대상, 하드코딩된 색상 및 템플릿 잔재를 보고합니다. 각 경고(동일한 상태, 효과 없는 스위치, 비결정적 데이터, 3-7 범위를 벗어난 노트, 다른 단계에 연결되지 않은 단계)를 수정하거나 회신에서 설명하십시오.- 보기에 …