Post
Repo Deep Dive: Nutlope/hallmark — 디자인 스킬의 선택과 검증 절차
2026년 10월 27일 07:10 KST에 확인한 GitHub Trending 일간 전체 언어 목록에서 Nutlope/hallmark는 1위였다. 이 순위는 저장소 선정 시점의 스냅샷이며, 게시 시점 또는 이후의 실시간 순위를 뜻하지 않는다.
1. 프로젝트 소개
Hallmark는 웹사이트와 새 페이지를 만드는 코딩 에이전트에 디자인 지침과 검사 도구를 제공하는 스킬이다. 저장소의 소유자는 Nutlope이고, README는 제작 주체를 Together AI라고 소개한다. Claude Code, Codex, Cursor, OpenCode에서 쓰는 경로를 문서화했으며, 프레임워크 자체나 완성된 사이트 생성 서비스보다는 에이전트가 페이지를 설계·구현·검토할 때 읽는 작업 규칙에 가깝다. 사용자는 만들 페이지의 목적과 실제 소재를 제시하고, 에이전트가 스킬의 절차에 따라 테마를 고르고 코드를 작성한다.
README가 말하는 핵심은 모든 페이지에 똑같은 구성을 입히는 것이 아니다. 접근성·사실성·모바일 표시 같은 최소 기준은 공통으로 묶고, 그 위의 시각적 재료는 48개 테마 중에서 선택한다. 테마 파일은 색, 서체, 표면, 사진 처리, 움직임의 성격을 정의하지만 페이지의 섹션 순서를 고정하지 않는다. 실제 페이지의 내용과 행동은 방문자가 무엇을 하러 왔는지에 따라 정한다. 저장소의 테마 안내도 테마를 완성 페이지의 복제본이나 컴포넌트 묶음이 아니라 ‘재료’로 설명한다.
2. 해결하려는 문제
코딩 에이전트에게 ‘멋진 랜딩 페이지’만 요청하면 서로 다른 제품에도 비슷한 영웅 영역, 동일한 크기의 기능 카드, 끝부분의 가입 유도 영역이 반복되기 쉽다. 보기 좋은 장식이 실제 과업을 가리거나, 근거 없는 사용량·고객 평가·로고가 설득 자료처럼 들어갈 수도 있다. 반대로 스타일만 세세하게 지정해도 버튼의 키보드 포커스, 작은 화면의 가로 넘침, 모션 감소 설정, 아무 곳에도 제출되지 않는 폼처럼 기능적 결함은 남는다.
Hallmark는 이 문제를 세 층으로 다룬다. 먼저 모든 결과에 적용하는 Floor 규칙으로 대비, 포커스, 모션 대체, 만들어 낸 사실과 같은 항목을 검사한다. 자주 반복되는 시각적 습관은 Reflex로 분류해 수정하거나 페이지에 맞는 이유를 기록하도록 한다. 마감 수준의 세부 표현은 Finish 검토 대상으로 남긴다. 이 구분은 README의 구호에만 있는 것이 아니다. SKILL.md가 Floor와 작업 흐름을 정의하고, gates.md가 각 규칙의 등급·검사 방식·예외 기록 방식을 설명하며, sloplint.mjs가 기계적으로 판별할 수 있는 항목을 검사한다. 다만 심미적 완성도와 내용의 적합성까지 린터 하나가 자동 판정한다는 뜻은 아니다. 문서는 별도 검토도 요구한다.
3. 주요 기능
테마 제안과 구조 선택. theme.mjs deal은 장르와 페이지 설명을 입력받아 맞는 테마 세 가지를 제안한다. 테마의 키워드 적합도와 최근 작업 기록을 고려하므로, 입력을 줬다고 테마가 하나로 강제되는 방식은 아니다. 이어 theme.mjs draw는 페이지가 보여 줄 주된 소재와 방문자의 행동을 입력받아 영웅 영역의 자세, 내비게이션, 뒤따르는 구성의 방향을 출력한다. 사용자는 제안된 테마의 예시 이미지와 실제 소재가 어울리는지 보고 하나를 고른다. 이 단계의 출력은 디자인 결정 자료이지 완성된 HTML이 아니다.
토큰과 기본 규칙의 생성. 고른 테마로 theme.mjs scaffold를 실행하면 색·서체·간격 토큰과 공통 CSS 규칙을 담은 파일을 만든다. 테마 파일의 값이 실제 CSS 토큰으로 옮겨지며, 공통 기본 규칙에는 이미지 크기, 텍스트 줄바꿈, 반응형 간격과 모션 감소 처리 등이 포함된다. 이후 페이지 내용과 상호작용은 에이전트가 작성해야 한다. 테마의 예시 페이지를 그대로 내려받아 회사 이름만 바꾸는 생성기는 아니다.
검사와 재설계. sloplint.mjs는 HTML·CSS뿐 아니라 JSX, TSX, Vue, Svelte, Astro 파일도 읽고 정적 규칙을 검사한다. --render는 브라우저에서 여러 화면 폭으로 확인하는 단계를 추가한다. 결과는 수정해야 하는 FAIL, 이유를 남기거나 고쳐야 하는 REFLEX, 재확인이 필요한 경고 등으로 구분된다. 기존 페이지에 Hallmark를 명시적으로 적용할 때는 /hallmark audit <path>로 변경 없는 점검을, /hallmark redesign <path>로 재설계를 요청할 수 있다. 재설계 문서는 먼저 sloplint --before로 링크·입력 필드·이벤트 연결 등을 기록하고 --kept로 누락을 대조하도록 한다. 코드가 이 항목들을 비교한다는 것은 확인했지만, 이것만으로 모든 사용자 흐름이 정상이라는 보증은 아니다.
사진과 실제 제품 자료. README에는 Wikimedia Commons에서 고른 공개 라이선스 사진 755건과 페이지 내 출처 표기 절차가 설명되어 있다. theme.mjs photos는 주제에 맞는 사진 후보와 크기·크레딧을 제시한다. capture.mjs는 접근 가능한 URL이나 실행 중인 제품을 화면 크기별로 캡처하는 경로다. 따라서 제품 화면이 실제로 있을 때는 임의로 꾸민 대시보드 이미지보다 캡처한 자료를 쓰도록 작업 흐름이 구성된다. 사진별 라이선스가 같지는 않으므로 출력된 크레딧과 이용 조건을 함께 확인해야 한다.
4. 사용 방법과 동작 흐름
README의 기본 설치 명령은 다음과 같다. Node.js 18 이상이 필요하며, -g는 여러 프로젝트에서 쓰는 전역 설치 옵션이다. 현재 프로젝트에만 설치하려면 옵션을 뺀다.
npx skills add nutlope/hallmark -g
설치 후 Codex CLI에서는 $hallmark와 페이지 요구사항을 함께 전달할 수 있고, Claude Code에서는 /hallmark 명령을 쓴다. 예를 들어 ‘사용자가 상담 시간을 예약하는 페이지를 만들어 줘. 실제 예약 가능한 시간 목록은 이 데이터에서 읽어’처럼 방문자의 행동과 확인 가능한 소재를 전달하는 것이 출발점이다. 이는 실행 예시의 입력 형태이며, 예약 백엔드가 없는 상태에서도 예약이 실제로 완료된다고 약속하는 문장이 아니다.
스킬의 문서상 흐름은 기존 프로젝트의 서체·색·프레임워크와 실제 제품 자료를 먼저 확인하는 것에서 시작한다. 새 페이지라면 요청에 맞는 테마 후보를 뽑고, 예시 이미지를 보고 하나를 고른 다음, 방문자의 주된 과업에 맞는 페이지 구조를 정한다. 이어 화면 첫 부분을 구현하고 검사한 뒤 나머지를 작성한다. 사용자가 custom을 요구하면 테마 선택을 건너뛰되 공통 Floor와 검사 절차는 유지한다. 기존 디자인을 건드릴 때는 Hallmark를 명시적으로 지목한 재설계·감사 요청만 이 경로에 들어간다.
검사를 직접 호출하려면 복제한 저장소 기준으로 node skills/hallmark/scripts/sloplint.mjs ./index.html --render 형태를 쓸 수 있다. 브라우저 렌더링, 화면 캡처에는 별도로 puppeteer-core와 Chrome이 필요하다. 이 환경이 없으면 정적 검사는 가능하지만 실제 화면에서의 확인까지 끝났다고 해석하면 안 된다. 출력에서 Floor 실패와 미처리 Reflex를 구분해 처리하고, 실제 링크·폼 동작과 내용의 진실성도 검토해야 한다.
5. 활용 사례
처음 만드는 서비스 페이지. 예를 들어 공식 문서가 드는 예약 페이지는 방문자가 일정을 선택하고 예약하는 일이 핵심이다. Hallmark의 작업 흐름에서는 예쁘게 보이는 기능 카드 배열을 먼저 정하지 않고, 예약 행동이 페이지 어디에서 일어나는지와 그 행동을 뒷받침할 실제 정보를 확인한다. 테마는 색과 재질의 방향을 제공하고, 페이지의 순서와 예약 UI 자체는 과업에 맞춰 구성한다. 저장소의 테마별 완성 화면은 같은 원칙이 서로 다른 제품 유형에 적용된 예시로 볼 수 있다.
이미 운영 중인 화면을 점검하거나 바꾸는 경우. /hallmark audit ./index.html은 소스를 바꾸지 않고 문제를 보고하는 경로다. 재설계라면 기존 콘텐츠와 연결을 먼저 기록한 뒤 결과가 이를 유지했는지 비교한다. 정적 파일이 아니라 개발 서버의 페이지라면 문서가 sloplint의 --url 경로를 안내한다. 특히 링크나 폼이 사라지지 않았는지 검사하는 절차는 ‘보기 좋은 새 화면’과 ‘원래 하던 일을 계속하는 화면’을 분리해 검토할 수 있게 한다.
실제 사진이나 제품 화면을 넣는 경우. 사진을 요구하는 페이지에서는 내장 라이브러리의 후보와 각 사진의 저작자·라이선스 표기를 함께 받는다. 이미 동작 중인 웹앱이 있다면 제품 화면을 캡처해 그 자체를 시각 자료로 사용할 수 있다. 사이트의 Dusk·Cobalt 등 테마 예시는 서로 다른 서체와 표면 처리를 확인할 수 있는 자료지만, 각 예시의 브랜드와 문구를 사용자의 실제 사업 성과로 오인해서는 안 된다.
댓글