settle

settle은(는) 무엇을 하나요?

"클릭감이 정말 좋은 스위치" 또는 "내 투두 앱을 보여주는 짧은 루핑 애니메이션" 같은 요청을 물리적 사물처럼 안정감 있게 움직이는 실제 조각으로 변환합니다. 모든 조각에 동일한 모션 크래프트가 적용되며, 외형은 요청마다 새롭게 생성되거나 기존 프로젝트의 디자인을 상속받습니다.

아래 경로는 이 파일의 폴더를 기준으로 합니다. 모든 스크립트는 작업 폴더(프로젝트 루트 또는 조각이 위치할 폴더)에서 전체 경로로 실행하세요(node <this folder>/scripts/deal.mjs …). 스크립트는 실행된 위치에 파일을 씁니다.

요청 실행 방법

1. 컨텍스트를 읽습니다. 프로젝트 내에 있는지 확인합니다. package.json에 프레임워크가 명시되어 있거나 HTML 페이지 폴더가 있는지 확인하세요. 프로젝트의 경우 스타일 작성 방식, 토큰이나 테마가 설정하는 외형, 이미 사용 중인 모션 라이브러리를 기록합니다. 그런 다음 요청을 읽습니다. references/kinds/의 어떤 구조 유형인지, 쇼케이스인지 제품의 일부인지, 초보자의 표현이 무엇을 요구하는지(이는 references/words.md에서 해석) 확인합니다.
2. 외형을 생성하거나 상속합니다.
   • 자체 외형을 가진 프로젝트는 그 외형을 유지합니다. 시트의 변수에 해당 외형을 매핑하고, 부족한 것만 --keep palette,type 플래그로 생성합니다.
   • 그렇지 않은 경우 생성합니다: node scripts/deal.mjs --brief "<요청을 한 줄로>" --kind <control, data-view, composite or flow>, 요청의 단어에 대해 references/words.md가 제공하는 플래그와 함께 사용하고, 프로젝트 내에 있는 경우 --project 플래그를 추가합니다. 이후 조각이 그 외형을 상속받도록 합니다. 외형 1(생성된 외형)을 빌드합니다: --pick 1. 외형 1이 주제와 충돌하는 경우에만 외형 2 또는 3을 선택하고, 충돌 이유를 명명합니다: --pick 2 --because "아침 메뉴판을 위한 어두운 배경". references/tokens.md에 규칙이 있습니다.
   • 생성된 외형에는 방향(direction)이 있으며, 이는 조각을 꾸밉니다. 요청이 형식을 결정합니다. references/directions.md에서 해당 섹션을 읽으세요. 각 방향의 맨 위에 있는 모든 방향(브리프 전)을 읽으세요.
3. 브리프 또는 스토리보드를 작성합니다.
   • 컨트롤, 데이터 뷰 또는 컴포지트의 경우 브리프를 두 줄로 기술하고 바로 빌드합니다: 무엇인지, 방향이 이 주제에 대해 어떻게 적용되는지, 외형, 시그니처 순간, 선택한 기본값. "스터디 사이트를 위한 포모도로 타이머. 도구: 타이머는 주방 타이머의 얼굴, 분 눈금이 베젤 주위에 있음; 외형 1, 퍼티와 검정; 시그니처: 시작 버튼이 막대처럼 줄어듦; 25분, 5분 휴식."
   • 시간 경과에 따른 플로우 또는 두 가지 매우 다른 의미를 가질 수 있는 요청의 경우 스토리보드를 보여주고(references/kinds/flow.md에 형식이 있음) 승인을 기다립니다.
   • 빌드하기 전에 유사한 요청이 받을 내용을 상상합니다. 해당 그림과 일치하는 브리프의 각 부분을 변경합니다.
4. 조각이 위치할 곳에 빌드합니다.
   • 프로젝트 없음: assets/page.html 또는 릴의 경우 assets/reel.html을 기반으로 한 하나의 HTML 파일입니다. 시트, 방향의 페이지 규칙, 커널(assets/kernel.js)을 head의 모듈 스크립트에 전체 붙여넣기, 그리고 조각에 필요한 레시피(references/motion.md에서)를 포함합니다.
   • 프로젝트: 프로젝트의 프레임워크와 스타일링을 사용한 컴포넌트, 커널을 한 번 모듈로 복사, 시트를 프로젝트의 글로벌 스타일시트에 포함합니다. references/stacks/에 스택별 노트가 있습니다.
   • 이미 존재하는 조각에 모션 추가: 마크업과 외형을 유지하고, 각 변경 사항에 게이트를 통해 문법이 명명한 움직임을 부여합니다(references/craft.md, 섹션 3).
   • 각 부분의 변경 종류에 따라 references/kinds/의 구조 파일이 어떤 레시피로 시작할지 알려줍니다.
5. 확인합니다. 파일을 린트하고 references/review.md에 설명된 대로 snap.mjs로 프레임을 촬영합니다(파일 또는 프로젝트의 개발 서버에서). 접촉 시트에서 잘못 읽히는 부분을 수정하고 다시 촬영합니다(최대 3회). 드래그 스냅이 안착되지 않거나 서버가 시작되지 않는 등 오작동하는 확인은 두 번 시도한 후, 확인되지 않은 상태로 명명하여 넘깁니다.
6. 핸드오버 (아래 참조).

읽을 자료

파일	읽어야 할 때
references/craft.md	모든 빌드: 모든 움직임이 따라야 하는 규칙, 금지 목록 및 주의사항
references/tokens.md	모든 빌드: 외형이 생성되거나 상속되는 방식 및 사용 방식
references/directions.md	프로젝트 없이 모든 빌드: 생성된 방향의 섹션
references/motion.md	모든 빌드: 시트, 기본 페이지 및 모션별 레시피
references/kinds/control.md, data-view.md, composite.md, flow.md	조각의 구조: 해부학 및 시작할 레시피
references/stacks/html.md, react-next.md, vue.md, svelte.md, astro.md	조각이 위치할 곳: 독립 실행 파일의 경우 html.md, 그 외는 프로젝트 스택
references/words.md	요청이 "더 돋보이게" 같은 느낌을 설명할 때
references/review.md	확인 단계

엄격한 규칙

• 조각은 작업자가 작업하는 곳에 위치합니다. 프로젝트 내: 프로젝트의 프레임워크와 스타일링, 새 패키지 없음, 프로젝트에 자체 모션 라이브러리가 있으면 그것을 사용하며, settle의 타이밍을 유지합니다. 프로젝트 없음: 커널이 붙여넣기된 하나의 자체 포함 HTML 파일로, 외부 요청은 외형의 폰트 링크 하나뿐이며, 시스템 폰트에서도 작동해야 합니다. 요청 시 가져온 사진은 그 옆에 위치합니다.
• 요청이 형식을 결정합니다. 컨트롤은 실제 크기로 유지, 위젯은 하나의 카드나 패널로 유지, 전체 화면은 요청이 화면을 요청할 때만 사용합니다. 전체 랜딩 페이지나 웹사이트 요청은 슬라이드쇼 같은 페이지에 드롭인할 수 있는 움직이는 조각만 생성하며, 핸드오버 시 페이지 디자인 스킬로 넘깁니다. 조각 주변 배경은 평범하게 유지됩니다.
• 외형은 시트와 방향에서 비롯됩니다. 모든 시각적 값은 시트의 변수 또는 그 색조에서 비롯되며, 하나의 배경, 하나의 잉크, 하나 또는 두 개의 강조색을 사용합니다. 생성된 방향이 조각을 꾸미며, 어두운 배경은 어둠 속에서 일어나는 주제에 사용합니다.
• 모션은 커널에서 비롯됩니다. 사람의 동작에 응답하는 모든 움직임과 모든 상태 변경은 settle.track, settle.stretch 또는 settle.move를 사용하며, 외형 레지스터의 프리셋인 settle.register()를 따릅니다.
• 시간은 settle.now()에서 비롯됩니다. 핸들러는 목표를 설정합니다. 하나의 requestAnimationFrame 루프가 현재 시간으로부터 모든 움직이는 스타일을 그립니다. snap.mjs는 프레임을 확인하기 위해 이 클록을 중지합니다.
• 형태는 이월됩니다. 각 새 상태는 이미 화면에 있는 형태로부터 만들어지며, 변경된 텍스트는 짧은 블러를 통과하고, 새 컨테이너는 그대로 있는 것 뒤에서 열립니다.
• 손이 이끕니다. 드래그된 값은 포인터 바로 아래에 위치하고, 한계를 넘으면 고무 밴드처럼 따라가며, 놓으면 손의 속도를 유지합니다.
• 실제 콘텐츠. 그럴듯한 구체성을 가지며, 액션은 플로우를 통해 이름을 유지합니다. 사진은 작업자로부터 오거나, 작업자가 실제 사진을 요청하고 없는 경우 scripts/photo.mjs에서 가져와 조각에 크레딧을 표시합니다. 그 외에는 코드만으로 선명하게 그릴 수 있는 것만 코드로 그리며, 절대 풍경은 그리지 않습니다(references/directions.md, 그림 항목 참조).
• 하나의 시그니처 순간, 그 주변은 모두 조용하게.
• 요청이 명시하지 않는 한 금지: references/craft.md의 금지 목록에 있는 모든 것(린트로 확인).
• 모든 사용자를 위해. 포인터, 터치, 키보드로 작동하며, 시각적 포커스와 44px 대상이 보장됩니다. 360px 화면에 맞으며, 텍스트는 11px 미만이 없습니다. 리듀스 모션(reduced motion)에서는 스프링이 즉시 안착됩니다.
• 비용을 고려합니다. 모든 도구 호출은 사용자의 사용량을 소모합니다. 한 번 빌드하고, 최대 3회 확인하며, 오작동하는 확인은 두 번 시도하고, 확인되지 않은 부분을 핸드오버에 명시합니다. 스크립트 자체는 디버깅하지 않습니다.

쇼케이스 또는 제품

쇼케이스(예: 랜딩 페이지용 릴)는 전체 모션을 받습니다. 실제 제품 내부의 컨트롤은 사용자가 더 자주 볼수록 덜 움직입니다. 하루에 수백 번 사용되는 것은 모션 없음, 수십 번 사용되는 것은 빠르고 미묘함. references/craft.md에 표(Emil Kowalski의 빈도 규칙)가 있습니다.

파일 위치

프로젝트가 없는 경우, 작업 폴더에 주제에서 짧은 이름(예: tea-timer.html)으로 작성합니다(작업자가 경로를 지정하지 않은 경우). 프로젝트 내에서는 스택 노트가 지정하는 위치에, 프로젝트 자체 스타일의 이름으로 배치하고, 작업자가 열 수 있는 위치(페이지 또는 라우트, 요청이 지정하지 않은 경우 자체 페이지나 라우트)에 표시합니다. 조각의 조정 가능한 숫자(데이터, 레지스터가 설정하지 않은 타이밍)는 스크립트 상단에 함께 유지합니다.

핸드오버

다음과 같이 응답합니다:

• 조각의 위치, 여는 방법(파일 또는 라우트 및 개발 서버 시작 명령), 조각이 무엇인지와 시그니처 순간에 대한 한 줄 설명.
• 시도해볼 두세 가지 사항: "노브를 끝까지 드래그", "Tab 키를 누른 다음 화살표 키 사용".
• 조정할 두 개의 노브(스크립트 상단에 나타난 이름).
• 드로잉이 사진을 대체하는 경우, 사진이 위치할 요소: 작업자의 <img>로 교체할 요소.
• 확인되지 않은 사항(예: 실제 휴대폰의 Safari).
• 외형의 한 부분을 재생성(node scripts/deal.mjs --redeal palette)하거나, 모호한 요청의 경우 스위처 뒤에 세 가지 변형을 제공하겠다는 제안.

릴의 경우 비디오 내보내기 제안: node scripts/export.mjs reel.html --out reel.mp4 (또는 --gif)는 ffmpeg로 렌더링하며, 모션 블러를 위해 프레임당 4개의 서브 프레임을 평균냅니다.

스크립트

스크립트	기능
scripts/deal.mjs --brief "…" [--tone …] [--register …] [--dark] [--project]	세 가지 외형을 생성합니다. --pick <n>은 선택한 시트를 출력합니다(--project와 함께 사용 시 프로젝트의 외형으로 유지). --redeal <part>는 한 부분을 다시 생성합니다. --check는 라이브러리를 확인합니다.
scripts/lint.mjs <file>	독립 실행 파일의 정적 검사. FAIL 시 exit 1.
scripts/snap.mjs <file or url> --out <dir> --sheet [--size WxH] [--times …] [--do "…"] [--calm]	정지된 클록에서 실제 입력과 접촉 시트로 프레임을 촬영한 후, 헤더에 나열된 고정 페이지의 검사를 수행합니다.
scripts/export.mjs <reel> [--out reel.mp4] [--gif]	릴을 4-서브프레임 모션 블러와 함께 MP4 또는 GIF로 내보냅니다.
scripts/photo.mjs "<내용 설명>" [--out photo.jpg]	공개 라이선스(CC0, 퍼블릭 도메인 또는 CC BY) 사진 하나를 실행 위치에 저장하고, 조각에 크레딧 라인을 추가합니다. 작업자가 실제 사진을 요청한 경우에만 사용합니다.

필요 조건: Node 22 이상 및 Chromium 브라우저. snap.mjs는 일반적인 위치에서 Chrome, Chromium, Edge 또는 Brave를 찾고, CHROME 환경 변수를 통해 다른 브라우저도 찾습니다. 찾을 수 없으면 한 줄로 알리고, references/review.md에 따라 코드를 검토하며, 프레임을 확인되지 않은 상태로 명명합니다. 내보내기에는 ffmpeg가, photo.mjs에는 네트워크가 필요합니다. 설치할 것은 없습니다.

셸이 없는 경우

셸이 없는 채팅 등에서 스크립트를 실행할 수 없는 경우: library/directions.json, library/palettes.json, library/type.json을 읽고, 요청에 맞는 종류와 톤의 항목을 유지합니다. 각 목록을 기준으로 요청의 문자 길이에 해당하는 위치의 항목을 가져와, 다른 요청이 다른 외형에 도달하도록 합니다. 동일한 파일로 빌드하고, references/review.md의 루브릭에 따라 코드를 검토하며, 핸드오버에서 프레임이 확인되지 않았다고 말합니다.

크레딧

• Emil Kowalski's skills — 동기, 구조 및 빈도 규칙.
• 7GUIs — 벤치마크 작업.
• Rauno Freiberg — 동기.
• Håkon Wium Lie — CSS 및 웹 표준.
• Apple Human Interface Guidelines — 모션 원칙.
• Material Design Motion — 모션 원칙.
• OpenAI — AI 에이전트 플랫폼 연결.
• Anthropic — Claude Code 및 지속적인 학습.
• 모든 오픈 소스 라이브러리 기여자.

라이선스

이 스킬은 MIT 라이선스에 따라 제공됩니다.

연락처

문제나 제안 사항이 있으면 GitHub 리포지토리에서 이슈를 열어주세요.