ToshqulovLaziz/naqsh

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

v0.6. <skill>은 이 스킬의 기본 디렉터리를 의미합니다. 스크립트는 Node ≥ 22와 로컬 Chrome/Edge가 필요하며, 설치할 것은 없습니다.

1. 라우팅

다른 모든 작업 전에 표면과 모드를 한 줄로 표시하세요.

표면	신호	읽을 파일
page	랜딩, 포트폴리오, 마케팅, 제품, 원페이지	references/page.md
app	ERP, 관리자, 대시보드, 테이블, 폼, 설정, CRUD	references/app.md

모드	코드 수정?	출력
build	예, 새 UI	UI + DESIGN.md
redesign	예, 동작/데이터/카피 유지	UI + DESIGN.md
audit	아니오	파일:라인 순위가 매겨진 발견 사항 및 수정 방법

검사를 실행하기 전에 항상 references/rules.md를 읽으세요. 누구도 질문에 답할 수 없으면 결정하고 그 이유를 기록하세요.

2. 컨텍스트

• 스택, 스타일링, 기존 토큰, 폰트 및 로딩 방식, 테마 전환(+ localStorage 키), i18n(+ 로케일 키), 라우트, 빌드 명령어.
• 변경될 수 있는 것과 절대 변경되어서는 안 되는 것(다른 페이지, 공유 컴포넌트, 비즈니스 로직).
• 로케일: 키릴 문자를 사용하는 로케일이 있다면 선택된 모든 서체가 이를 지원해야 합니다.

3. 기준선(Baseline)

현재 상태에서 두 검사를 모두 실행하고 출력을 유지하세요. 이는 보고서의 "이전" 상태이며, 종종 실제 버그(폰트 로딩 안 됨, 대비, 오버플로)를 드러냅니다.

node <skill>/scripts/lint.mjs <projectRoot>
node <skill>/scripts/inspect.mjs http://localhost:PORT --surface <surface> --routes ... --locales ... --themes ...

audit 모드: 여기서부터 references/audit.md를 따르고 중단하세요. 프로젝트 파일을 편집하지 마세요.

4. 인벤토리

• 주제(Subject): 이 제품이나 사람만이 가진 8~12가지 것(이름, 장소, 실제 숫자, 실제 작업).
• 자료(Material): 각 시각적 슬롯에 대해 real(실제), picture(정직하게 출처 확보 가능) 또는 absent(부재)로 표시하세요. 가짜 로고, 사용 후기, 지표 또는 스크린샷을 절대 만들어내지 마세요.
• 대상 및 작업(Audience and job): 누가 보는지, 그들이 무엇을 하거나 먼저 배워야 하는지.

5. 방향 설정 (딜, 취향 기반)

node <skill>/scripts/deal.mjs --surface <page|app> --options 3 --project <projectRoot>

스크립트는 사용자의 취향 프로필(~/.naqsh/taste.json, 프로젝트별로 <project>/.naqsh/taste.json에서 재정의 가능)과 최근 선택 사항에 대해 라이브러리를 평가하고, 서로 다른 패밀리에서 3가지 방향을 딜합니다.

• 사용자가 있으면 세 가지(아이디어, 서체, 팔레트, 히어로)를 보여주고 선택하게 하세요. 그렇지 않으면 콘텐츠에 가장 잘 맞는 것을 선택하고 이유를 설명하세요.
• deal.mjs --pick <id>는 전체 시트(섹션, 모션, 폰트 임포트, 라이트/다크 토큰)를 출력하고 선택을 기록합니다. 시트를 기준으로 빌드하세요: 시트의 서체, 팔레트, 히어로가 계약입니다. 크기와 섹션을 실제 콘텐츠에 맞게 조정하고, 서면 이유(예: 자료 부족) 없이 벗어나지 마세요.
• page: references/page.md도 읽으세요. app: references/app.md도 읽으세요; 시트의 system 블록이 셸, 밀도, KPI, 테이블, 상태 및 차트 스타일을 결정합니다.

브리핑과 취향. 브리핑의 형용사("차분한", "미니멀", "전문적인")는 작업을 설명하는 것이지 외형을 설명하는 것이 아닙니다. 취향 프로필이 피하는 방향을 선택하지 말고, 명확성, 밀도 및 모션 절제를 통해 이를 충족시키세요. 브리핑의 형용사보다 대담하다는 이유만으로 방향을 포기하지 마세요. 브리핑과 취향이 실제로 충돌하면 취향을 선택하고 DESIGN.md에 기록하세요.

취향 피드백. 사용자가 결과에 대해 좋아하거나 싫어하는 점을 말하면 ~/.naqsh/taste.json(boldness 1–5, temperature warm|cool|neutral|any, typeStyles, likes, avoid, notes)을 업데이트하고 알려주세요. 하나의 표면에만 해당되는 선호도는 page 또는 app 블록에 들어가며, 이는 일반 키를 재정의합니다.

6. 바닥 규칙 (절대 완화 불가; 스크립트가 대부분 검사)

• 모든 로케일의 i18n에서 보이는 텍스트; 지어낸 카피 없음.
• 폰트가 로딩되고 모든 로케일 스크립트를 지원; 가장 긴 로케일이 375px에 맞아야 함.
• 폰트 @import는 @import "tailwindcss" 위에 있어야 함; 요소 스타일은 @layer base 내부에.
• 가로 페이지 스크롤 없음; overflow-x: clip, 절대 hidden/100vw 사용 금지.
• 모든 테마에서 대비 ≥ 4.5:1(큰 텍스트는 3:1); 포커스 가시성 확보; 타겟 ≥ 24px(44px 권장).
• prefers-reduced-motion 존중; transition: all 사용 금지; transform/opacity 애니메이션 사용.
• 새로운 토큰은 건드리지 않은 페이지가 변경되지 않도록 범위 지정.

7. 생성형 UI 특유의 징후 (반사: 딜된 시트가 허용할 때만 예외)

기본 Tailwind 인디고/바이올렛; 광택, 유리, 오로라 블롭, 궤도를 도는 아이콘, 샤이머 버튼, 그라데이션 텍스트; 모든 제목 위에 대문자 눈썹 텍스트; 동일한 둥근 모서리+그림자 카드 그리드; 둥근 지표로 구성된 히어로 밴드; 한 화면에 같은 이름이나 제목 반복. 굵은 스케일, 강한 색상 및 세리프/산세리프 대비는 징후가 아닙니다 — 소심함도 실패입니다: 결과가 템플릿처럼 보일 수 있다면 시트의 아이디어를 더 강하게 밀어붙이세요.

8. 빌드 루프

1. 토큰(범위 지정) → 메인 화면 / 히어로 → 나머지.
2. 각 단계 후: lint. 메인 화면 후: 빌드, 미리보기, 해당 라우트에 대해서만 inspect 실행(가장 넓은 + 가장 좁은 너비, 첫 번째 로케일, 두 테마). 마지막에: 전체 매트릭스 실행. 스크린샷을 열고 매번 확인하세요. 수정, 반복 — 첫 번째 전체 패스 후 최대 3회. 변경한 파일만 읽고, 턴을 짧게 유지하세요.
3. 디테일 패스: references/components.md 읽기; 모든 컨트롤이 이 기준으로 빌드되었는지 확인(native-control 미완화 금지), 시그니처 순간이 존재하는지 확인. inspect ... --details 실행하고 <out>/details/에서 모든 크롭을 열어보고, 각각이 2배율에서 의도적으로 보일 때까지 수정하세요.
4. 디테일 패스가 완료되고 빌드가 0개의 바닥 규칙 FAIL을 가지면 DESIGN.md(초안)를 작성하고, 새로운 컨텍스트에서 리뷰어를 생성하세요 — Agent 도구, subagent_type: "naqsh:naqsh-reviewer"와 함께: 프로젝트 루트, 표면, 모드, 방향 ID, <skill> 경로, 스크린샷 폴더(details/ 포함), 미리보기 URL 및 inspect 플래그를 전달하세요. 리뷰어의 floor, idea 및 fidelity 수정 사항을 적용하고(다른 것은 판단에 따라), 검사를 다시 실행하세요. 한 번의 리뷰 라운드; 두 번째는 평결이 rework였을 때만. Agent 도구를 사용할 수 없으면 agents/naqsh-reviewer.md에서 스크린샷을 다시 읽은 후 직접 리뷰를 수행하세요.
5. 0개의 바닥 규칙 FAIL, 모든 징후가 수정 또는 완화되고, 프로젝트 빌드가 통과된 상태로 마무리하세요. 미리보기 서버를 중지하세요.

9. 보고서

프로젝트 루트(또는 사용자가 지정한 위치)에 DESIGN.md를 작성하세요: 딜된 옵션과 선택, 아이디어 문장, 토큰, 서체, 주요 결정 사항, 시그니처 순간, 전후 검사 카운트, 이유와 함께 완화 사항, 판단된 검사, 열린 항목. 마지막에 사용자가 좋아하는 것과 싫어하는 것을 물어보세요. 그래야 취향 프로필이 개선됩니다.