디자인 스킬hallmark는 "AI 코딩 에이전트가 만드는 UI가 'AI스럽지 않게' 보이도록 강제하는 디자인 스킬"이다. 여기서 'hallmark(홀마크)'는 은·금 세공품에 찍는 순도·진품 보증 각인을 뜻한다. 실제로 이 스킬은 완성한 페이지의 CSS 맨 위에 /* Hallmark · macrostructure: … · tone: … */ 같은 "각인(stamp)"을 찍는다 — "이 화면은 (58개 검사를 통과한) 의도적으로 지어진 물건"이라는 도장이다.
배포 방식이 특이하다. npm 패키지처럼 npx skills add nutlope/hallmark 한 줄로 설치하는데, 설치되는 건 실행 코드가 아니라 마크다운 규칙 파일 뭉치다. 이 뭉치가 Claude Code·Cursor·Codex의 "스킬" 폴더에 들어가, 에이전트가 UI를 만들 때마다 참조하는 디자인 헌법이 된다.
요즘 AI 코딩 도구는 손은 엄청나게 빠른데 취향이 밋밋한 신입 같다. 시키면 화면을 뚝딱 만들지만, 늘 비슷하게 생겼다 — 보라색 그라데이션 히어로, Inter 폰트, 가운데 정렬, 3열 카드. 학습 데이터의 "평균값"으로 수렴하기 때문이다.
hallmark은 이 신입 옆에 깐깐한 아트 디렉터를 붙인다. "이 브리프면 페이지 골격부터 다시 골라. 그 폰트 금지. 그 그라데이션 금지. 상호작용 상태 8개 다 만들었어? 지어낸 숫자 넣지 마." — 이런 규칙 58개를 통과해야만 결과를 내놓게 한다. 그래서 "빠른 손"에 "안 뻔한 취향"이 더해진다.
skills/hallmark/SKILL.md(558줄)를 진입점으로, 100개가 넘는 references/ 규칙 파일을 필요할 때만 불러 읽는 큰 스킬이다. Claude Code·Cursor·Codex 세 harness를 모두 지원한다.2026년 현재 개발자 사이에서 가장 피부에 와닿는 불만 중 하나가 "AI한테 시키면 화면은 나오는데, 죄다 똑같이 생겼고 어딘가 싸구려 티가 난다"는 것이다. hallmark은 이 정확한 통증을 겨냥해, "취향을 규칙으로 코드화"한다는 명쾌한 컨셉으로 등장했다. (TrendShift의 굵은 숫자는 별 수가 아니라 사회적 언급 모멘텀이다.)
대부분의 "예쁘게 만들기" 프롬프트는 색·폰트만 바꾼다. hallmark의 핵심 통찰은 진짜 지루함은 '페이지 골격(macrostructure)'이 늘 똑같은 데서 온다는 것이다. 그래서 색을 고르기 전에 21종 골격(벤토 그리드·긴 문서·마퀴 히어로·통계 주도·선언문…) 중 하나를 먼저 정하고, "직전에 쓴 골격과 다른 걸 써라"는 다양화 규칙까지 건다. "색만 다른 같은 템플릿"을 구조적으로 차단한다.
제작자 Hassan El Mghari(@nutlope)는 roomGPT·llama-coder 등 여러 화제의 오픈소스 AI 앱을 만든 유명 개발자이고, 후원은 오픈소스 추론 플랫폼 Together AI다. 저자가 AI Engineer World's Fair 2026에서 한 강연 "Stop letting your agents ship ugly UIs(에이전트가 못생긴 UI를 내보내게 두지 마라)"가 저장소 docs/talk-slides.md에 실려 있어, 프로젝트 자체가 하나의 "선언"으로 읽힌다.
강연의 큰 명제는 "Design taste is a layer in the agent stack" — 모델·툴·메모리·RAG·평가(evals)·오케스트레이션과 나란히 취향(TASTE)도 하나의 레이어라는 것이다. hallmark은 이 레이어를 실제로 구현한 오픈소스 예시로 제시된다. "AI 에이전트를 잘 쓰는 법"에 관심 있는 사람들에게 개념적으로 신선하다.
특정 도구에 묶이지 않는다. npx skills add nutlope/hallmark 한 줄이면 Claude Code(~/.claude/skills/)·Cursor(.cursor/rules/)·Codex(.codex/skills/)에 바로 꽂힌다. "당장 오늘 내 에이전트에 붙여볼 수 있다"는 진입 장벽의 낮음이 확산을 도왔다. 라이선스도 MIT라 부담이 없다.
hallmark의 스택을 이해하는 열쇠는 "이건 앱이 아니라 지식(규칙)이다"라는 점이다. 저장소 전체를 세어보면 마크다운 128개(약 11,500줄)가 본체이고, 나머지 HTML/CSS/JS는 전부 "규칙을 실제로 보여주는 전시장(site/)"이다. 빌드 단계도 없다. 스택을 3개 계층으로 나눠 보자.
| 구성 | 역할 |
|---|---|
| skills/hallmark/SKILL.md | 진입점(558줄). 4개 동사(verb)·6대 공통 규율·9단계 디자인 흐름·게으른 로딩 규칙을 정의. 에이전트가 가장 먼저 통째로 읽는 헌법. |
| references/ (100+ 파일) | 주제별 상세 규칙(약 9,591줄). 타이포그래피·색·레이아웃·모션·카피·안티패턴·거시구조 21종·컴포넌트 50종·테마·장르… 필요할 때만 골라 읽는다(§4 게으른 로딩). |
| references/slop-test.md | 58개 관문의 체크리스트 + 6축 자기비평. 빌드 맨 마지막에만 로드해 "출고 검사"로 돌린다. |
| docs/ | 사람이 읽는 문서: recipes.md(9개 브리프→조합 예시), study-examples.md(3개 분석 워크스루), talk-slides.md(저자 강연 전문). |
스킬이 지시하는 웹 기술들이다. hallmark을 공부하면 이 현대 CSS 스택을 배우게 된다.
| 기술 | hallmark에서의 쓰임 |
|---|---|
| OKLCH 색 공간 | 모든 색을 OKLCH로 정의(hex/HSL 금지). 밝기·채도를 사람 눈에 맞게 다뤄 "탁한 회색·형광 사고"를 피한다. 순수 #000/#fff 금지. |
디자인 토큰 + Tailwind v4 @theme | 색·간격·폰트를 이름 있는 토큰으로 잠그고, 렌더 도중 인라인 색 즉흥 삽입 금지. tokens.css를 항상 함께 출력. |
| DTCG tokens.json · shadcn 변수 | 토큰을 4개 표준 포맷(tokens.css·Tailwind @theme·DTCG tokens.json·shadcn/ui CSS 변수)으로 내보내기(export-formats.md). |
@property · 스크롤 구동 애니메이션 · View Transitions API | 선언적 모션의 최신 CSS 기법. transform/opacity만 애니메이트, 이징 3종만 명명해 사용. |
| 접근성 원칙 | :focus-visible, prefers-reduced-motion, APCA/WCAG 대비, 44px 터치 타깃, 요소당 상호작용 상태 8개. |
규칙을 "말"로만 두지 않고 스스로 규칙을 지켜 만든 데모 사이트로 증명한다(도그푸딩). 빌드 도구·프레임워크가 전혀 없다 — 순수 HTML/CSS/JS다.
| 정적 서빙 | 프레임워크 없음(vercel.json: framework=null, build=null). python3 -m http.server로 site/를 그대로 서빙. |
| site/js/main.js (1,126줄) | 랜딩의 인터랙션. 테마 맵, T키로 테마 순환, document.startViewTransition(View Transitions API)로 테마 전환, 호버 재생 비디오. |
| site/_tests/ · examples/ | 서로 다른 브리프로 만든 30여 개 예시 페이지(각각 자기완결 HTML+CSS). 일부엔 스킬이 쓴 .hallmark/log.json(프로젝트 메모리)도 남아 있다. |
README 산문에는 "twenty themes(20개 테마)"·"fifty-seven slop-test gates(57개 관문)"로 적혀 있지만, 실제 SKILL.md와 slop-test.md는 58개 관문(57 + 게이트 38a 등 추가분)을 정의한다. recipes.md는 또 "21 거시구조 × 16 테마 × 8 강화 = 2,688 지문"이라고 계산해 테마 수(16)가 본문의 20과 다르다. 규칙집이 빠르게 진화하며 생긴 사소한 표기 불일치이니, 정확한 수는 항상 소스 파일 기준으로 볼 것.
hallmark의 "아키텍처"는 서버 구조가 아니라 에이전트가 UI 하나를 만들 때 밟는 사고 절차다. 기본 동사(그냥 "이런 페이지 만들어줘")가 실행되면 다음 흐름을 탄다.
references 파일이 100개가 넘는데 이걸 다 읽으면 에이전트의 컨텍스트가 폭발한다. 그래서 SKILL.md는 "항상 로드 / 목록만 보고 하나 골라 로드 / 빌드마다 로드 / 조건부 로드 / 맨 끝에만 로드"로 파일마다 로딩 시점을 규정한다. 예컨대 거시구조는 슬림 색인(목록)만 먼저 읽고 고른 1개 파일만 펼친다. 슬롭 테스트(58관문)는 7단계에서야 로드한다. 큰 지식베이스를 필요한 순간에만 펼치는 이 기법이 스킬 설계의 정수다.
같은 사람이 hallmark을 여러 번 쓰면 결과가 비슷해지기 쉽다. 이를 막으려고 빌드할 때마다 선택(거시구조·테마·앵커 색)을 .hallmark/log.json(JSON 배열, 최신순)에 기록하고, 다음 빌드에서 이걸 읽어 "지난 N번과 겹치는 골격·테마는 피하라"는 다양화 규칙을 적용한다. 상태를 파일에 남겨 실행 간 다양성을 보장하는 영리한 장치다.
결과를 내놓기 전에 두 겹의 검문을 통과해야 한다. 하나는 slop-test.md의 58개 예/아니오 관문(보라 그라데이션 히어로? 어디나 Inter? 3열 카드? 지어낸 통계? 이탤릭 제목? …모든 답이 "no"여야 함). 다른 하나는 6축 자기비평(철학·위계·완성도·구체성·절제·다양성을 1~5점으로 채점, 3점 미만이면 수정). 비결정적 AI에 결정적 품질 게이트를 씌운다.
hallmark은 "새로 만들기" 외에 3개 동사를 더 가진다. 같은 규칙집을 용도별로 재사용하는 구조다.
| 동사 | 하는 일 |
|---|---|
| (기본) | 새 UI 빌드. 위 9단계 흐름 전체를 밟는다. |
| audit | 기존 코드를 안티패턴 대비 점수만 매김(수정 안 함). "지적 목록" 리포트. |
| redesign | 구조는 버리고 카피·정보구조·브랜드는 유지한 채 다른 지문으로 재구축. 다중 페이지면 design.md를 먼저 만든다. |
| study | 감탄한 디자인(스크린샷/URL)에서 구조적 DNA를 추출(픽셀 복제·유료 템플릿은 거부). 원격 URL은 신뢰 불가 데이터로 취급하는 안전 규칙 포함. |
study는 외부 URL을 읽어 디자인을 분석하는데, 여기엔 보안 감각이 배어 있다. https만 허용하고, IP 리터럴·사설 IP 대역을 거부하며(SSRF 방지), 가져온 HTML/CSS는 "신뢰할 수 없는 비활성 데이터"로만 취급한다(그 안의 지시를 실행하지 않음). "남의 사이트를 참고하되 그 사이트에 조종당하지 않는다" — 에이전트가 웹을 다룰 때 필요한 자세를 규칙으로 보여준다.
구조가 곧 메시지다. 실행 코드(site/js)는 곁가지이고, 저장소의 무게중심은 skills/hallmark/references/의 마크다운 규칙 100여 개에 있다. 이 프로젝트는 "소프트웨어"라기보다 잘 조직된 디자인 지식베이스이며, site/examples/는 그 지식이 실제로 다른 결과를 낳는다는 증거 전시장이다. "말한 대로 만들어 보여준다"는 도그푸딩이 신뢰를 만든다.
이 저장소의 진짜 교육 가치는 두 갈래다 — (A) 프롬프트/스킬 엔지니어링(AI에게 판단을 위임하는 법)과 (B) 현대 웹 디자인 원칙(뻔하지 않은 UI를 만드는 구체 규칙). 기술별로 정리하면:
100개가 넘는 규칙 파일을 "언제 무엇을 읽을지"로 계층화한 로딩 전략은, 컨텍스트 한계 안에서 방대한 지식을 다루는 에이전트 설계의 정석이다. 항상 로드 / 색인 후 선택 / 조건부 / 맨 끝 로드 — 이 progressive disclosure는 자기 프로젝트용 스킬을 쓸 때 그대로 응용할 수 있다.
58개 예/아니오 관문 + 6축 자기채점은 "AI가 알아서 잘하겠지"에 기대지 않고 출고 검사(QA)를 규칙으로 명문화한다. 통과 기준을 이진(모든 답이 "no")으로 못박는 설계는, 평가(eval)·가드레일을 만들 때의 좋은 본보기다.
.hallmark/log.json에 과거 선택을 남겨 "지난번과 겹치지 마"를 강제하는 패턴은, 상태를 파일에 외재화해 실행 간 행동을 제어하는 기법이다. 에이전트에게 "기억"을 주는 가장 단순하고 견고한 방법을 보여준다.
색을 OKLCH로만 다루고, 모든 값을 이름 있는 토큰으로 잠그고, 이를 tokens.css·Tailwind @theme·DTCG tokens.json·shadcn 변수 4종으로 내보내는 흐름은 디자인 시스템 실무의 축소판이다. "색을 손으로 즉흥 삽입하지 않는다"는 규율만 익혀도 UI 완성도가 올라간다.
anti-patterns.md(418줄)는 "왜 AI가 만든 화면은 티가 나는가"를 명명된 목록으로 해부한다: 보라 그라데이션 히어로, 어디나 Inter, 3열 아이콘 그리드, 카드 속 카드, 그라데이션 제목, 화면 꽉 채운 가운데 히어로, 이탤릭 제목, 지어낸 지표… 이 목록 자체가 디자인 감식안을 기르는 체크리스트다. hallmark 없이도 이 파일만 읽어도 배운다.
study가 외부 URL을 https만 허용·사설IP 거부·가져온 내용을 비활성 데이터로 취급하는 규칙은, SSRF·프롬프트 인젝션을 규칙 레벨에서 막는 실전 예다. "에이전트가 인터넷에 나갈 때 무엇을 조심해야 하나"를 구체적으로 보여준다.
| 목적 | 필요한 것 |
|---|---|
| 스킬 설치 | Node.js/npx 환경 + npx skills add nutlope/hallmark. 또는 SKILL.md+references/를 폴더에 수동 복사. |
| 실제 사용 | 지원 harness 셋 중 하나 — Claude Code(~/.claude/skills/hallmark/) · Cursor(.cursor/rules/hallmark.mdc, frontmatter 제외) · Codex(~/.codex/skills/hallmark/ 또는 프로젝트 .codex/skills/). |
| 데모 사이트 로컬 실행 | Python만 있으면 됨: npm run serve(내부적으로 python3 -m http.server --directory site 4173). 빌드·설치 과정 없음. |
| 산출물 열람 | 브라우저. 생성되는 페이지는 외부 의존성 없는 자기완결 HTML+CSS라 그대로 열린다. |
| GPU/메모리 | 전혀 불필요. 무거운 건 에이전트가 호출하는 LLM 쪽이고, hallmark 자체는 텍스트 규칙일 뿐이다. |
정리하면 "AI 코딩 도구를 이미 쓰고 있다면 추가 준비물은 사실상 없다". 그게 이 스킬의 진입 장벽이 낮은 이유다. 학습 목적이라면 저장소를 클론해 skills/hallmark/ 마크다운을 읽고, site/examples/를 브라우저로 여는 것만으로 충분하다.
npx skills add nutlope/hallmark로 설치한 뒤, 똑같은 브리프("가계부 SaaS 랜딩 만들어줘")를 두 번 시켜보자. .hallmark/log.json이 쌓이며 두 번째가 다른 거시구조·테마로 나오는지 확인 — 프로젝트 메모리의 다양화가 체감된다.
예전에 AI로 만든 화면에 hallmark audit을 걸어보자. 보라 그라데이션·Inter·3열 카드 같은 "티" 목록이 몇 개나 잡히는지 세어보면, anti-patterns.md가 지적하는 슬롭이 내 코드에 얼마나 있었는지 정면으로 마주하게 된다.
hallmark의 안티패턴 몇 개(순수 #000/#fff, font-family: Inter, 100vh 가운데 히어로, 3열 그리드)를 정규식/CSS 파서로 검출하는 작은 린터를 짜보자. "취향을 코드로 강제"하는 경험 — hallmark의 슬롭 테스트를 축소 재현하는 셈이다.
좁은 주제(예: "이메일 HTML 작성 규칙")로 SKILL.md + references/ 몇 개를 만들고, "색인만 먼저 읽고 필요한 파일만 펼치는" progressive disclosure 구조를 흉내 내보자. hallmark의 로딩 규칙 섹션이 좋은 골격 참고서다.
감탄한 사이트 스크린샷에 hallmark study를 걸어 거시구조·타입 페어링 역할·앵커 색 진단을 받고, 그 DNA로 내 브리프를 빌드해보자. "픽셀 복제가 아니라 구조 추출"이 무엇인지, 그리고 유료 템플릿·서명적 작업을 왜 거부하는지 몸으로 익힌다.
| 주차 | 주제 | 핵심 질문 · 자료 |
|---|---|---|
| 1주차 | 스킬/프롬프트 엔지니어링 | 에이전트에게 절차를 어떻게 글로 못박나. 게으른 로딩·동사 분기·가드레일. → SKILL.md 정독 + references 로딩 규칙. |
| 2주차 | 안티슬롭 디자인 원칙 | "AI스러움"의 정체와 반례. 거시구조·타이포·색·모션의 구체 규칙. → anti-patterns.md·typography.md·color.md·macrostructures.md. |
| 3주차 | 현대 CSS · 디자인 토큰 | OKLCH, 4pt 간격, 상태 8개, @property·스크롤 애니메이션·View Transitions, 토큰 4종 내보내기. → export-formats.md·interaction-and-states.md·site/ 코드. |
| 4주차 | 평가·메모리·에이전트 안전 | 슬롭 테스트(eval), 프로젝트 메모리, study의 원격 URL 안전. → slop-test.md·study.md·.hallmark/log.json. |
먼저 anti-patterns.md와 slop-test.md부터 읽어라 — "무엇이 슬롭인가"를 알아야 나머지 규칙이 왜 있는지 이해된다. 그다음 site/examples/의 서로 다른 페이지들을 나란히 열어 "골격이 다르면 얼마나 달라 보이는지"를 눈으로 확인하라. 마지막으로 작은 나만의 스킬을 써보면, "취향을 규칙으로 옮기는" 이 프로젝트의 핵심 역량이 손에 남는다. 디자인 감각이 없어도 좋다 — 이 레포는 "센스"가 아니라 "센스를 절차로 바꾸는 법"을 가르친다.
hallmark은 "AI 스킬" 물결의 한 갈래다. emilkowalski/skills·mattpocock/skills는 각각 UI·엔지니어링 노하우를 스킬로 옮긴 사촌이고, github/spec-kit은 같은 발상을 "명세 주도 개발"에 적용했다. 디자인 쪽 무기로는 컴포넌트 라이브러리 shadcn/ui(저자 강연이 "먼저 이걸 쓰라"고 권함)와 Tailwind v4(@theme 토큰)가 hallmark이 전제하는 토대다. 이들을 나란히 보면 "AI에게 무엇을, 어떤 형태로 가르칠 것인가"의 서로 다른 답이 보인다.
SKILL.md + 상세 references/로 구성. Claude Code·Cursor·Codex가 지원.@themetokens.css·Tailwind @theme·DTCG tokens.json·shadcn 변수 4종으로 내보낸다.site/는 hallmark 규칙을 지켜 만든 데모라, "말한 대로 결과가 달라진다"를 눈으로 보여준다.| 구분 | 링크 / 위치 |
|---|---|
| GitHub 저장소 | github.com/Nutlope/hallmark |
| TrendShift | trendshift.io/repositories/33587 |
| 라이브 데모 | usehallmark.com (테마 순환: T키) |
| 설치 | npx skills add nutlope/hallmark |
| 핵심 파일 | skills/hallmark/SKILL.md (진입점 558줄) |
| 핵심 파일 | skills/hallmark/references/slop-test.md (58개 관문) |
| 핵심 파일 | skills/hallmark/references/anti-patterns.md ("AI스러움" 해부 418줄) |
| 핵심 파일 | skills/hallmark/references/macrostructures.md (21종 골격) |
| 읽을거리 | docs/talk-slides.md (저자 강연 "Stop letting your agents ship ugly UIs") |
| 이웃 프로젝트 | emilkowalski/skills · mattpocock/skills · github/spec-kit · shadcn/ui · Tailwind v4 |
| 연관 개념 | AI 슬롭 · 스킬/프롬프트 엔지니어링 · progressive disclosure · OKLCH · 디자인 토큰 · View Transitions API |