jovd83/프로토타입-스케치-스킬

프로토타입 스케치 스킬

동작하는 웹 앱이 손으로 그린 것처럼 보이게 만들어 클라이언트가 완성된 제품이 아닌 프로토타입임을 인지하도록 합니다. 이는 외형 스킨만 변경합니다. 추가만 하면 되며 완전히 되돌릴 수 있습니다.

범위 가드레일 (먼저 읽고, 절대 위반하지 마세요)

1. 스타일링 진입점과 index.html만 수정합니다. 스타일시트를 추가하고, 하나의 SVG 블록을 붙여넣고, 두 개의 속성을 설정합니다. 그 외에는 아무것도 하지 않습니다.
2. 컴포넌트, 템플릿, .ts/.tsx/.jsx/.vue 로직, 라우팅, 상태, 서비스, 테스트는 절대 수정하지 않습니다.
3. 스케치 컴포넌트 라이브러리(예: wired-elements)로 컴포넌트를 교체하지 않습니다. 이는 마크업을 다시 작성하는 행위로, 금지됩니다.
4. 로고, 사진, 차트, 아이콘 등 선명하게 유지해야 하는 요소는 색상을 변경하거나 왜곡하지 않습니다. 옵트아웃 클래스를 사용하세요.
5. 되돌리기는 항상 간단해야 합니다. <html>의 두 속성을 제거하면 전체 스킨이 꺼집니다.

작동 방식 (하나의 개념 모델)

• 하나의 스타일시트 assets/sketch-skin.css가 5가지 스타일과 스케치 정도를 모두 정의합니다.
• 하나의 SVG 블록 assets/sketch-filters.html이 흔들림 필터(#sketch-25 … #sketch-100)를 정의합니다.
• 활성화는 <html>에 두 개의 속성을 추가하는 것입니다: data-sketch="<스타일>" 및 data-sketch-level="<0|25|50|75|100>".
• 외형은 손글씨 글꼴 변경 + 손으로 그린 상자(불규칙한 border-radius, 평평한 채움) + 스케치 정도에 따라 강도가 달라지는 SVG 변위 필터로 구성됩니다. 글꼴은 텍스트를 처리하고 필터는 상자 장식만 흔들며 텍스트를 흐리게 하지 않습니다.

빠른 시작 (이 순서대로 수행)

1. 요청이 스킨 전용인지 확인합니다. 사용자가 동작/레이아웃 변경을 원한다면 중단하세요. 이는 범위를 벗어납니다.
2. 프레임워크를 감지하고 전역 스타일시트와 index.html을 찾습니다(레시피 표 참조).
3. 스타일('스타일' 표 참조)과 레벨(0, 25, 50, 75, 또는 100)을 선택합니다.
4. 스킨 CSS를 프로젝트의 전역 스타일에 추가합니다:
   • assets/sketch-skin.css를 프로젝트(예: src/styles.scss)에 복사하거나 **@import**합니다. 글꼴 @import는 해당 파일 내에 이미 포함되어 있습니다(온라인 사용).
5. assets/sketch-filters.html의 SVG 필터를 index.html의 여는 <body> 태그 바로 뒤에 붙여넣습니다. (filter: url(#sketch-…)는 이러한 defs가 DOM에 있어야만 해석되므로 필수입니다.)
6. index.html의 <html> 태그를 편집하여 활성화합니다:

   <html lang="ko" data-sketch="balsamiq" data-sketch-level="50">
   

7. 브라우저에서 확인합니다. 되돌리려면 두 data-sketch* 속성을 삭제하면 됩니다(추가된 CSS/SVG는 속성이 없으면 아무 작업도 수행하지 않으므로 비활성 상태로 남아 있을 수 있습니다).

스타일

data-sketch	외형	글꼴	용도
balsamiq	깔끔한 회색조 와이어프레임, 평평한 상자	Balsamiq Sans	기본 "이것은 목업입니다"
sharpie	굵은 검정 마커, 진한 선	Permanent Marker	화이트보드 / 워크샵 스케치
pencil	연한 흑연, 부드러운 선	Gaegu	부드러운 "종이에 연필" 초안
doodle	장난기 넘치는 밝은 색상 악센트	Short Stack	친근하고 비공식적인 컨셉
blueprint	파란 종이에 흰색 잉크	Patrick Hand	기술적인 "드로잉 보드" 느낌

스케치 정도

data-sketch-level은 선이 얼마나 흔들리는지를 제어합니다. 다른 SVG 변위 필터를 선택합니다:

레벨	효과
0	손으로 그린 상자 + 글꼴이지만 직선, 안정적인 선(가장 깔끔)
25	미묘한 흔들림
50	명확하게 손으로 그린 느낌 (권장 기본값)
75	자유롭고 에너지 넘치는 스케치
100	매우 거친, 최대 "낙서"

data-sketch가 설정되었지만 data-sketch-level이 생략되면 스킨은 기본적으로 레벨 50을 사용합니다.

대각선 워터마크 (선택 사항)

전체 화면을 초안으로 표시하려면 표시할 텍스트와 함께 세 번째 <html> 속성을 추가하세요:

<html data-sketch="balsamiq" data-sketch-level="50" data-sketch-watermark="DRAFT">

data-sketch-watermark는 뷰포트를 가로질러 대각선으로 희미한 손글씨 단어 하나를 그립니다. 고정된 비대화형 레이어(pointer-events: none)이므로 클릭을 차단하지 않으며 레이아웃을 변경하지 않고 페이지 및 경로 변경 전반에 걸쳐 제자리에 유지됩니다. 모든 텍스트가 작동합니다(DRAFT, PROTOTYPE, CONFIDENTIAL, 클라이언트 이름 등). 속성을 제거하면 꺼집니다. 오버레이를 사용하는 경우 워터마크 텍스트 필드가 실시간으로 설정합니다.

모달, 팝업 및 SPA 탐색

스킨은 <html>의 속성으로 활성화되고 전역 [data-sketch] … 선택자로 스타일이 지정되므로 활성화 후 나타나는 모든 것은 자동으로 스타일을 상속합니다. 대화상자, 팝오버, 드롭다운 메뉴, 툴팁, 토스트(포탈 마운트된 것 포함), 단일 페이지 앱에서 탐색하는 모든 화면이 포함됩니다. 컴포넌트나 경로별로 연결할 것이 없습니다.

두 가지 사항이 일관성을 유지합니다:

• 선택자 목록에는 이미 dialog, [popover], [role="dialog"], [aria-modal="true"], .modal, .popover, 메뉴, 툴팁, 토스트 및 기본 ::backdrop이 포함됩니다.
• 오버레이 스크립트는 <body>를 감시하고 프레임워크가 경로 변경 시 본문을 교체하는 경우 SVG 필터를 다시 주입하여 흔들림이 조용히 사라지지 않도록 합니다. (정적 속성 모델을 사용하는 경우 sketch-filters.html을 <body> 뒤에 한 번 붙여넣습니다. SPA 프레임워크는 하위 루트에 마운트되어 그대로 둡니다.)

프레임워크별 적용 레시피

스킨은 프레임워크에 구애받지 않습니다. 다음은 정확한 대상입니다. 자세한 내용은 references/implementation.md에 있습니다.

스택	CSS 추가 위치	SVG 붙여넣기 위치	속성 설정 위치
Angular	src/styles.scss (또는 styles.css)	src/index.html의 <body> 뒤	src/index.html의 <html>
React / Vite	src/index.css (main.tsx에서 임포트)	index.html의 <body> 뒤	index.html의 <html>
Vue	src/assets/main.css (main.ts에서 임포트)	index.html의 <body> 뒤	index.html의 <html>
정적 HTML	<head>에서 sketch-skin.css 링크	index.html의 <body> 뒤	index.html의 <html>

특정 에셋을 선명하게 유지 (옵트아웃)

스킨은 마크업을 편집하지 않지만, 사용자가 특정 요소(로고, 차트)를 보호하도록 명시적으로 요청하는 경우 허용되는 유일한 마크업 변경은 해당 단일 요소에 옵트아웃 후크를 추가하는 것입니다:

<img src="logo.svg" class="no-sketch" alt="로고">

.no-sketch(또는 data-no-sketch)는 해당 요소에서 흔들림 필터와 색상 재정의를 제거합니다. 드물게 요청된 경우에만 사용하세요.

대화형 미리보기 오버레이 (선택 사항)

사용자가 스타일을 실시간으로 전환하기를 원할 때(예: 클라이언트에게 스위치를 보여주는 경우) 정적 속성 대신 오버레이를 사용하세요:

1. assets/sketch-skin.css를 전역 스타일에 추가합니다(빠른 시작과 동일).
2. </body> 전에 하나의 스크립트 태그를 추가합니다:

   <script src="sketch-toggle.js" defer></script>
   

3. 완료되었습니다. 스크립트는 OFF + 테마별 라디오 버튼 하나, 0–100% 스케치 슬라이더, 워터마크 텍스트 필드가 있는 떠 있는 패널을 렌더링하고, <html> 속성을 실시간으로 전환하며, 선택 사항을 localStorage에 기억합니다. SVG 필터를 자동으로 주입하고(SPA가 본문을 교체하는 경우 다시 주입) 빠른 시작의 5단계(sketch-filters.html 붙여넣기)가 필요하지 않습니다.

이것도 여전히 스킨 전용이며 비파괴적입니다. 스크립트는 속성만 설정합니다. 태그를 제거하여 비활성화하세요. 요청이 "저/클라이언트가 스타일을 전환할 수 있게 해주세요"인 경우 이 모델을 선택하고, 고정된 스크린샷 안정적인 외형을 위해 정적 속성을 사용하세요.

스크린샷 갤러리

README.md는 demo/screenshots/의 PNG를 사용하여 모든 스타일과 0→100% 계단을 보여줍니다. 해당 이미지는 미리 렌더링된 것입니다. 이를 생성하는 대화형 데모 앱과 Playwright 캡처 스크립트는 프로젝트의 개발 소스에 있으며 설치된 스킬과 함께 번들로 제공되지 않습니다. 스킬 자체는 assets/ + references/일 뿐입니다. 빌드 단계나 종속성이 없습니다.

예시

예시 1 — Balsamiq 스타일의 Angular 데모, 중간 스케치

• 입력: "이 Angular 앱을 내일 데모를 위해 Balsamiq 와이어프레임처럼 보이게 해주세요."
• 작업: sketch-skin.css를 src/styles.scss에 추가합니다. src/index.html에 필터를 붙여넣습니다. <html data-sketch="balsamiq" data-sketch-level="50">로 설정합니다.
• 결과: 앱은 동일하게 실행되고 회색조 와이어프레임으로 렌더링됩니다.

예시 2 — React, 최대 sharpie

• 입력: "React 앱, 완전한 화이트보드 마커 느낌, 매우 거칠게."
• 작업: main.tsx에서 sketch-skin.css를 임포트합니다. index.html에 필터를 붙여넣습니다. data-sketch="sharpie" data-sketch-level="100"으로 설정합니다.

예시 3 — 끄기

• 입력: "실제 UI로 다시 전환해주세요."
• 작업: <html>에서 data-sketch와 data-sketch-level을 삭제합니다. 완료되었습니다. 다른 변경은 필요하지 않습니다.

문제 해결

증상	원인	해결책
상자는 손으로 그린 것처럼 보이지만 선이 완벽하게 직선임	SVG 필터가 DOM에 없거나 레벨이 0	sketch-filters.html이 <body> 뒤에 붙여넣어졌는지 확인하고 레벨을 ≥ 25로 설정
전혀 변경되지 않음	속성이 없거나 CSS가 로드되지 않음	<html data-sketch="…">가 있는지 확인하고 sketch-skin.css가 전역 스타일에 있는지 확인
텍스트가 흐릿하게 보임	필터가 텍스트/전체 <body>에 적용됨	filter:를 body나 텍스트에 추가하지 마세요. 스킨은 상자 장식만 필터링합니다. 수정되지 않은 sketch-skin.css를 다시 복사하세요.
글꼴이 손글씨가 아님	오프라인 / 차단된 Google 글꼴	글꼴을 자체 호스팅하세요. assets/fonts/README.md 참조
큰 테이블/그리드에서 페이지가 느려짐	큰 DOM에서 feDisplacementMap 비용	레벨을 낮추거나 흔들림 선택자 범위를 조정하세요(references/implementation.md 참조)
로고가 채도/흔들림이 사라짐	해당 에셋에 옵트아웃이 없음	해당 단일 요소에 class="no-sketch" 추가
아이콘 글꼴 / SVG 아이콘이 사라짐	공격적인 평탄화	아이콘 컨테이너에 no-sketch를 추가하거나 references/implementation.md의 아이콘 노트 참조

참조 파일 (필요할 때만 읽기)

• references/styles.md — 5가지 스타일 각각의 정확한 글꼴/팔레트/선 사양 및 새 스타일 추가 방법.
• references/implementation.md — SVG 필터 수학, 프레임워크별 단계별 가이드, 선택자 조정, 오프라인 글꼴, 성능, 되돌리기 세부 사항.