saltjsx/build-design-system

디자인 시스템 구축

용어는 references/glossary.md에, 금지 사항 및 너비 기본값은 references/taste.md에 있습니다. 앱 자체의 모양이 출처입니다. 사용자가 디자인 출처를 선택하고 샘플을 확인하지 않는 한, 앱에 이미 없는 색상, 글꼴, 그림자, 그라데이션 또는 모션 값을 새로 만들지 마십시오.

스크립트는 이 스킬의 scripts/ 디렉토리에 있습니다. 저장소 루트에서 node로 실행하고, 먼저 --help를 읽으십시오. scripts/capture.mjs는 스크린샷을 찍고, scripts/capture-guard.mjs는 모든 쓰기를 차단하며, scripts/pixdiff.mjs는 이를 비교합니다. 캡처 및 pixdiff에는 Playwright와 Chromium이 필요하며, scripts/find-chromium.mjs가 이를 찾거나 설치 방법을 설명합니다.

단계

1. 프레임. AGENTS.md 또는 CLAUDE.md, 매니페스트 및 라우트 트리를 읽으십시오. 사용자의 말로 불만 사항, 이에 응답하는 첫 번째 가시적 변경 사항, 그리고 파일럿 흐름(불만 사항이 명명한 흐름, 그렇지 않으면 가장 많은 컴포넌트 패밀리와 오류 상태가 있는 양식을 가진 흐름)을 작성하십시오. .design-system/을 .git/info/exclude에 추가하여 노트, 캡처 또는 스크래치 파일이 커밋되지 않도록 하십시오. 사용자가 명명한 실행 브랜치를 사용하거나, 새 브랜치를 만들고 시작했던 브랜치를 .design-system/start-branch에 기록하십시오. land.mjs는 이를 거부합니다. references/taste.md를 금지 사항이 선택 해제된 상태로 한 번 제공하고, 수락된 사본을 .design-system/taste.md에 저장하십시오. 다른 것은 묻지 마십시오. 기본값을 선택하고, default (unanswered)로 기록한 후 계속 진행하십시오. 불만 사항, 파일럿, 브랜치 및 수락된 취향 파일이 기록되면 완료됩니다.

2. 인벤토리 및 베이스라인. 모든 표면, 해당 상태 및 데이터를 쓰는지 여부를 나열하십시오. scripts/check-system.mjs --no-allowlist --no-self-test --json을 사용하여 raw 값의 발생 횟수(#fff, text-gray-500, p-[13px])를 세고, 컴포넌트를 패밀리로 그룹화하십시오. 편집 전에 지원되는 최소 및 최대 너비(기본값 390 및 1280)에서 모든 상태의 모든 표면을 캡처하십시오. 각 너비당 한 번의 새 탐색으로 진행하십시오. 앱이 실행 중인 상태에서(여기서는 포트 3000), 각 표면을 .design-system/surfaces.tsv에 surface<TAB>route<TAB>states 행으로 나열하고, 앱이 보내는 모든 쓰기를 네트워크 로그에서 복사하여 .design-system/writes.txt에 METHOD URL로 기록한 후, node <this skill>/scripts/capture.mjs --base http://localhost:3000 --kind before --out .design-system/captures --surfaces .design-system/surfaces.tsv --writes .design-system/writes.txt를 실행하십시오. --writes(또는 쓰기를 보내지 않는 앱의 경우 --no-backend) 없이 시작을 거부하며, 브라우저를 열기 전에 각 쓰기가 차단되었음을 증명하고, 각 캡처의 접근성 트리를 저장하며, 놓친 캡처가 있으면 exit 1로 종료합니다. 아무도 사용하지 않는 것은 자체 커밋에서 삭제하십시오. 각 표면에 베이스라인 또는 명시된 not captured 이유가 있으면 완료됩니다.

3. 토큰. raw 값을 역할별로 클러스터링하고, 목적별로 이름을 지정하며, 각 표면을 전경색과 연결하십시오(references/tokens.md). 모든 raw 값이 역할, 병합 또는 나열된 예외에 매핑될 때까지 token-mapping을 실행하십시오. 허용 오차 내의 병합은 결정입니다. 허용 오차를 벗어나면, 기본값이 병합인 클러스터당 하나의 게이트를 여십시오. 모든 라우트에서 동일한 값으로 교체를 수행하십시오. token-mapping이 예외 목록 외부에 제로 갭을 보고하고, pixdiff.mjs가 허용 오차 0에서 교체가 영향을 미친 모든 표면에 대해 0%를 보고하면 완료됩니다.

4. 컴포넌트. 가장 많이 사용되는 패밀리를 처음부터 끝까지 먼저 구축하십시오(references/components.md). 텍스트 프리미티브와 작은 텍스트 프리미티브는 Button과 함께 1차 웨이브에 제공됩니다. 각각을 component-docs로 문서화하십시오. 화면이 시스템을 소비한 후 발견된 핵심 버그는 정리 작업이 필요하므로(비활성화된 필드가 여전히 빨간색으로 그려짐, Combobox가 Input보다 2px 더 큼, 패널 액션이 줄바꿈되지 않음, 파일 드롭이 조용히 실패함), 확장 전에 패밀리를 사용자에게 보여주십시오. 모든 정식 컴포넌트에 레지스트리 행과 문서가 있고, 비활성화, 필수, 오류 및 긴 텍스트 상태가 쇼케이스에서 캡처되어 사용자에게 표시되면 완료됩니다.

5. 검사. scripts/check-system.mjs 및 scripts/oklch.mjs를 저장소의 scripts/에 복사하고, --init을 실행한 다음, --init-allowlist를 한 번 실행하십시오. 규칙은 실패하는 것이 확인된 후에만 계산됩니다. 스캔된 폴더에 하나의 위반을 심고, --files <plant> --no-allowlist를 실행하고, 규칙을 명명하는 exit 1을 확인한 후, 심은 파일을 삭제하십시오. allowlist와 ratchet은 축소만 가능합니다. 금지 사항은 동일한 변경에서 검사 규칙과 함께 제공됩니다. 복사 규칙은 문자 그대로 유지해야 하는 텍스트(인용문, 용어, 버전 문자열)와 기계나 사람이 다른 곳에 붙여넣는 페이로드 문자열(프롬프트, API 예제, 클립보드 값)에 대해 예외와 함께 요소 범위로 제공됩니다. 이를 다시 쓰면 다른 사람이 받는 내용이 변경되기 때문입니다. 깨끗한 클론에서 검사가 exit 0으로 종료되고, --self-test가 "all as expected"로 끝나며, 실행에 추가된 모든 규칙이 이 세션에서 심은 파일에서 실패하는 것이 확인되면 완료됩니다.

6. 파일럿. 코드 모드를 사용하여 파일럿 흐름을 훅 단위로 읽으면서 이동하십시오. 베이스라인과 동일한 명령, 너비, 테마 및 데이터를 사용하여 --kind after만 변경한 후 캡처하고, 두 폴더에 대해 pixdiff.mjs를 실행하십시오. 설명되지 않은 차이는 결함입니다. 키보드로 흐름을 탐색하고, 오류 및 로딩 상태를 강제로 실행한 후, after 캡처에 대해 ui-review를 실행하십시오. 캡처의 모든 차이가 결정 또는 게이트로 추적되면 완료됩니다. 캡처가 없는 렌더링 변경은 checks-only로 보고됩니다.

7. 준비 상태. 마이그레이션이 확산되기 전에, 아래의 다섯 가지 감사가 유지되거나 기록된 예외가 있어야 합니다.

8. 인계. 개수를 다시 계산하십시오. 시스템이 다루는 내용을 숫자로, 먼저 응답되지 않은 기본값을, 그다음에 발견되었지만 수정되지 않은 내용을 순위별로 보고하십시오. 마이그레이션을 크기와 함께 제공하십시오. 시작하지 마십시오. 보고서의 모든 숫자가 이를 생성한 명령을 명명하면 완료됩니다.

준비 상태 감사

화면이 시스템을 소비한 후 발견된 갭은 정리 작업이 필요합니다. 전에 발견된 갭은 행 하나면 됩니다. 5단계가 끝날 때와 첫 번째 웨이브 전에 이를 실행하십시오. 각 결과를 평결 단어와 함께 .design-system/readiness.md에 기록하십시오.

1. 슬롯 및 속성 패리티. 호출 사이트가 있는 각 레거시 프리미티브의 모든 속성에 대해 새 프리미티브에 일치하는 속성이 있거나 갭 행이 있어야 합니다.
2. 동작 계약. 대화형 프리미티브당 "무엇이 발사되는지" 테이블, 각 행은 테스트입니다(references/components.md).
3. 톤 패리티. 모든 누를 수 있는 프리미티브와 행 프리미티브를 모든 상태 톤 및 음소거와 교차시킵니다. 각 빈 셀은 갭 행이거나 지원되지 않음으로 명시됩니다.
4. 고정 문자열. 역할 이름 또는 텍스트별 모든 레거시 테스트 쿼리에 대해 새 프리미티브에 기본 이름과 레이블 재정의가 있어야 합니다.
5. 가장 어려운 화면. 패밀리당 하나의 가장 어려운 호출 사이트가 쇼케이스에서 렌더링되고 스크린샷이 있어야 합니다.

준비되지 않은 패밀리는 마이그레이션되지 않습니다. 해당 화면은 레거시에 남아 있습니다.

절대 금지

• 사용자가 이 세션에서 요청하지 않는 한, 푸시, 게시 또는 배포하지 마십시오.
• 실행이 시작된 브랜치에 커밋하지 마십시오. 먼저 실행 브랜치를 만드십시오.
• 더티 체크아웃에서 스태시하거나 브랜치를 전환하지 마십시오. 더티 체크아웃은 자체 워크트리에서 실행 브랜치를 가져옵니다(git worktree add).
• 다른 패키지나 공개 API가 내보내는 것을 삭제하지 마십시오. 중단하고, 가져오는 사람과 함께 게이트로 나열하십시오.
• 단계를 조용히 건너뛰지 마십시오. 앱이 빌드 또는 실행되지 않으면 보고서는 code-complete, not runtime-verified라고 말하고 실행되지 않은 것을 명명합니다.
• 자신의 작업을 verified라고 부르지 마십시오. 다른 에이전트를 시작할 수 없는 호스트에서는 순서대로 단계를 실행하고, diff 및 캡처를 새로 읽어 각각을 확인하고, 해당 평결을 self-verified로 표시하십시오.

규칙

• Raw 값 냄새는 #fff, rgb(, text-gray-500, p-[13px] 및 style={{ padding: 12 }}입니다. 각각은 의미론적 토큰 또는 나열된 예외에 매핑됩니다.
• 누락된 프리미티브는 표면 내의 해결 방법이 아닌 갭 행입니다.
• Delta E OK 2 이내의 색상 병합과 2px 이내의 간격 병합은 결정입니다. 테두리 두께, 두께 및 이징은 허용 오차가 없습니다.
• 의미론(이름, 역할, aria-current)만 추가하는 변경은 결정입니다. 의미론을 제거하거나 재구성하는 것은 게이트입니다.
• 잘못된 예: {saving ? "Saving..." : "Save"}. 올바른 예: 유휴 레이블은 유지되고, 동일한 상자 안에 스피너가 있으며, aria-busy가 설정됩니다.
• 두 번 반복되는 수정은 다른 문장이 아닌 검사 규칙 또는 스크립트가 됩니다.
• 베이스라인은 diff를 통과시키기 위해 편집되지 않습니다. 올바른 코드를 플래그하는 검사는 코드를 구부리는 것이 아니라, 수정을 증명하는 심은 사례와 함께 검사에서 수정됩니다.
• 스크립트가 생성하지 않은 개수 또는 실패하는 것이 확인되지 않은 검사는 보고되지 않습니다.

완료 조건

깨끗한 클론에서 모든 규칙이 실패하는 것이 확인되고, 모든 라우트가 프로덕션 빌드에서 200을 응답하며(capture.mjs --status), 파일럿이 나열된 의도된 변경 사항을 제외하고 베이스라인과 일치하고, 모든 인계 개수가 스크립트에서 나오면 검사가 exit 0으로 종료됩니다.

references/traps.md에는 ID별 동작 트랩이 나열됩니다. references/tokens.md에는 레이어, 이름, 허용 오차 및 모션 프리셋이 있습니다.