bergside/awesome-design-skills 딥다이브
— "코드 한 줄 없는" AI 디자인 스킬 레지스트리

1한 줄 정체

awesome-design-skills는 "디자인 시스템을 코드로 만드는 도구"가 아니라 "AI 에이전트가 읽을 지침서 모음"이다. 저장소를 열어 보면 놀랍도록 단순하다 — README.md, LICENSE, 이미지 폴더 하나, 그리고 skills/ 폴더 안에 67개의 하위 폴더. 각 하위 폴더 안에는 딱 두 개의 마크다운 파일(SKILL.md, DESIGN.md)만 들어 있다. package.json도, 빌드 스크립트도, 테스트 코드도 없다.

67개 폴더는 각각 하나의 "디자인 미학"을 표현한다. 유리질감의 glassmorphism, 거친 콘크리트 느낌의 brutalism, 8비트 게임을 흉내 낸 pacman·tetris, 리서치 저널풍의 claude까지 — 취향의 스펙트럼이 넓다. 각 폴더의 SKILL.md는 "이 미학대로 UI 코드를 짜라"는 지침을 AI 에이전트에게 주는 파일이고, DESIGN.md는 같은 내용을 사람이 읽기 좋게 풀어놓은 짝꿍 파일이다.

2왜 지금 뜨는가

2025년 이후 Claude·Cursor·Codex 같은 AI 코딩 에이전트가 널리 쓰이면서, 에이전트에게 "이렇게 행동하라"고 미리 심어주는 스킬(skill)·규칙(rules) 파일이라는 새로운 파일 장르가 생겼다. awesome-design-skills는 이 트렌드 중에서도 "디자인"이라는 좁고 구체적인 영역에 특화해 자리를 잡았다.

① "그냥 예쁘게 해줘"의 함정 — AI 슬롭(slop) 회색 UI

에이전트에게 지침 없이 "UI를 예쁘게 만들어줘"라고만 하면, 대부분 비슷비슷한 무채색 Tailwind 기본값(둥근 카드, 옅은 회색 배경, 파스텔 배지)으로 수렴하는 현상이 흔하다. 색상 토큰·폰트·톤이 미리 정의된 SKILL.md 한 장을 읽히면, 에이전트가 적어도 "이 프로젝트만의 일관된 방향"은 지키게 만들 수 있다.

② 미리 다 골라놓은 67가지 선택지 — "취향 쇼핑"의 편리함

글래스모피즘부터 브루탈리즘, 레트로 아케이드(pacman·tetris), 브랜드 오마주(claude·codex·shadcn·roku·sega)까지 폭넓게 큐레이션돼 있어, "어떤 스타일부터 시작할지" 고민하는 시간을 npx typeui.sh pull <slug> 한 줄로 줄여준다.

③ 배포 파이프라인과의 조합 — CLI 하나로 여러 프로바이더에

SKILL.md는 에이전트마다 규칙 파일을 두는 위치가 다르다는 현실적 문제(.cursor/skills/, .claude/ 등)를 typeui.sh CLI가 -p cursor,claude 같은 옵션으로 흡수한다. 저장소 자체는 "콘텐츠"만 책임지고, "배포"는 CLI가 맡는 역할 분리가 여러 에디터·에이전트를 오가는 개발자에게 매력적이다.

3무엇을 해결하나

README의 표현을 빌리면 이 저장소는 "AI 에이전트가 코드를 생성할 때 참고할 디자인 시스템 지침 파일의 큐레이션 레지스트리"다. 구체적으로 세 가지 반복되는 실무 문제를 겨냥한다.

문제 1 — 매 프로젝트마다 색상·폰트·톤을 처음부터 정의하는 노동

새 프로젝트를 시작할 때마다 "우리 브랜드 컬러가 뭐였지, 폰트는, 여백 스케일은?"을 다시 정리하는 대신, skills/<slug>/SKILL.md 프런트매터에 이미 colors·typography·rounded·spacing 토큰이 정의돼 있다. 예를 들어 skills/glassmorphism/SKILL.md는 primary=#1856FF, success=#07CA6B, warning=#E89558, danger=#EA2143 같은 값을 이미 갖고 있다.

문제 2 — 에이전트마다 규칙 파일이 사는 위치가 다른 파편화

Cursor는 .cursor/, Claude Code류는 .claude/ 아래에 규칙·스킬 파일을 기대하는 식으로 도구마다 관례가 다르다. 저장소 자체는 이 문제를 직접 풀지 않지만, README의 "Specify providers" 절이 안내하는 npx typeui.sh pull glassmorphism -p cursor,claude 명령이 이 파편화를 CLI 레벨에서 흡수하도록 설계돼 있다 — 저장소는 "재료"만 대고, "여러 곳에 나눠 담는 일"은 짝꿍 CLI의 몫으로 분업한다.

문제 3 — "그냥 예쁘게"의 모호함을 검증 가능한 체크리스트로 바꾸기

SKILL.md의 Quality Gates 절은 "모호한 형용사에만 의존하는 규칙 금지", "모든 접근성 문장은 구현에서 테스트 가능해야 함" 같은 검증 기준을 명시한다. 또 Component Rule Expectations 절은 default·hover·focus-visible·active·disabled·loading·error 같은 상태값을 빠짐없이 정의하라고 요구한다. 즉 "예쁘게"라는 취향 판단을, 최소한 "이 상태들을 빠뜨리지 않았는가"라는 점검 가능한 목록으로 바꿔주는 것이 실질적 기여다.

4전체 구조

저장소 루트는 단출하다. 실행할 것도, 설정할 것도 없다. 무게중심은 오직 skills/ 폴더에 실린 67개 서브폴더다.

이 트리에서 눈여겨볼 점 두 가지. 첫째, 이 저장소에는 실행 진입점이 없다 — package.json도 .github/workflows/도 존재하지 않는다(직접 클론해 확인). 둘째, skills/.DS_Store처럼 macOS Finder가 남긴 시스템 파일이 .gitignore 없이 그대로 커밋돼 있다 — 사소하지만 "저장소 위생"이 완벽하지 않다는 신호다.

5핵심 내용 · 분류 체계

이 저장소의 진짜 콘텐츠는 skills/index.json + 67벌의 SKILL.md/DESIGN.md 쌍이다. 하나씩 실제 파일 내용을 기준으로 뜯어본다.

① skills/index.json — slug 기반 조회 테이블

67개 키를 가진 JSON 객체로, 각 키(slug)마다 slug·name·skillPath·designPath 네 필드를 담는다. 예를 들어 실제 파일의 항목은 이렇다.

"glassmorphism": {
  "slug": "glassmorphism",
  "name": "Glassmorphism",
  "skillPath": "skills/glassmorphism/SKILL.md",
  "designPath": "skills/glassmorphism/DESIGN.md"
}

67개 키의 등장 순서는 알파벳순이 아니다("agentic, artistic, bold, brutalism, cafe, claymorphism, clean, colorful, contemporary, corporate, cosmic, creative, dithered, doodle, dramatic, editorial" 다음 갑자기 "square, pulse, stitch"가 끼어드는 식) — 즉 스킬이 추가된 시간 순서를 그대로 반영한 배열로 보인다. CLI는 이 파일 하나만 내려받아 slug로 조회한 뒤 skillPath를 따라가 실제 SKILL.md를 가져가는 구조다.

② SKILL.md — AI 에이전트가 읽는 지침 (12개 섹션)

YAML 프런트매터(name·description·license·metadata.author)로 시작해, 본문은 <!-- TYPEUI_SH_MANAGED_START -->와 <!-- TYPEUI_SH_MANAGED_END -->라는 HTML 주석 마커 사이에 담긴다. 이 마커는 "이 구간은 typeui.sh 도구가 관리(재생성)한다"는 신호로 읽힌다 — 즉 사람이 직접 이 구간을 손으로 고쳐도, CLI가 다시 밀어넣을 때 덮어써질 수 있다는 뜻이다. 마커 안쪽 구조는 12개 섹션으로 고정돼 있다.

③ DESIGN.md — 사람용 짝꿍 문서, 그러나 실제로는…

YAML 프런트매터에 colors·typography·rounded·spacing 토큰을 좀 더 구조화된 형태(중첩 객체)로 다시 담고, 본문은 Overview·Style Foundations·Colors 세 섹션뿐이다. 그런데 Colors 섹션을 열어보면 skills/glassmorphism/DESIGN.md와 skills/brutalism/DESIGN.md 모두 색상 설명이 토씨 하나 안 틀리고 이렇다.

- **Primary (#1856FF):** Token from style foundations.
- **Secondary (#3A344E):** Token from style foundations.
- **Success (#07CA6B):** Token from style foundations.

README는 DESIGN.md를 "디자인 개요·근거(rationale)·유지보수 노트를 담는 사람용 문서"라고 소개하지만, 실측 결과 색상 하나하나의 "근거"는 전부 "Token from style foundations."(스타일 파운데이션에서 온 토큰)이라는 동일 문장으로 채워져 있다 — 왜 이 색을 골랐는지에 대한 실제 서술은 없다.

④ 분류 체계 — 명시적 카테고리 필드는 없다, 이름 자체가 분류다

index.json과 SKILL.md 프런트매터 어디에도 category나 tag 필드는 없다. 67개는 평평한(flat) 단일 네임스페이스로만 존재하며, 분류는 오직 슬러그 이름이 속하는 "느낌"으로만 짐작할 수 있다. 실제 슬러그를 훑어 정리하면 대략 이런 결이 보인다.

같은 표 안에서도 실제 토큰 값은 확실히 다르다 — pacman은 primary=Press Start 2P 픽셀 폰트를, tetris는 primary=Bangers 만화체 폰트를, matrix는 primary=Space Mono, secondary=#0B0C14(짙은 검정)를 쓴다. 토큰 값의 다양성은 진짜지만, 그 값을 감싸는 12개 섹션 중 6개는 완전히 동일한 틀이라는 점이 이 저장소의 핵심 성격이다.

6기술 스택 · 자동화

스택 지도를 그리려면 먼저 밝혀야 할 게 있다. 이 저장소 자체에는 실행되는 코드가 0줄이다. find . -type f로 전수 조사한 결과 파일 확장자는 .md·.json·.png, 그리고 macOS가 흘린 .DS_Store뿐이었다. package.json·CI 워크플로(.github/)·테스트 코드는 전혀 없다.

SKILL.md 본문의 Guideline Authoring Workflow·Required Output Structure 절이 "긴 지시문 템플릿을 채워 넣는" 형식을 취하고, README의 generate 명령이 "대화형 프롬프트로 커스텀 스킬 생성"을 약속하는 것을 함께 보면 — 이 67개 SKILL.md 자체가 그 generate 파이프라인의 산출물일 가능성이 높다. 5번 섹션에서 확인한 "6개 섹션이 완전히 동일하다"는 사실이 이 추정을 뒷받침한다. 다만 이는 소스 구조로부터의 합리적 추정이며, 생성 스크립트 자체는 이 저장소에 없어 직접 확인하지는 못했다.

7설치 / 사용 요구사항

이 딥다이브를 위해서는 얕은 클론(git clone --depth 1)으로 소스를 직접 확인했지만, 일반 사용자는 이 저장소를 클론할 필요가 없다. README가 안내하는 실사용 경로는 전부 npx 한 줄이다.

8실제 사용 흐름

9함정 · 오해 방지

오해 1 — "67개 모두 똑같이 공들여 손으로 만들어졌다"

README는 각 SKILL.md를 "브랜드 철학·타이포 스케일·컴포넌트 규칙·접근성 규칙까지 담은" 문서로 소개한다. 실제로 열어보면 반은 맞고 반은 다르다. skills/claude/SKILL.md의 Brand 절은 "연구 저널풍의 미학이 따뜻한 돌 위에 인쇄된 듯한 인상. Anthropic Sans로 UI 크롬을, Anthropic Serif로 대형 타이포를... 1차 CTA 버튼에만 비대칭적인 위 평평·아래 둥근 모서리를 준다"는 식으로 구체적이고 공들인 서술을 담은 반면, skills/tetris/SKILL.md의 Brand 절은 통째로 "the most iconic game of history(역사상 가장 상징적인 게임)" 한 문장뿐이다. 67개의 완성도는 균일하지 않다 — 일부만 깊게 다듬어졌고, 다수는 자동 생성된 뼈대에 가깝다.

오해 2 — 마케팅 이미지 개수(77장) = 스킬 개수라는 착각

registry-examples/ 폴더의 PNG는 77장이지만 skills/ 폴더와 index.json의 스킬은 67개뿐이다. 두 목록을 직접 대조해 보면 anime·candy·dark·forest·machine·mars·matcha·minimax·nostalgia·pragmatic 이렇게 10개의 -marketing.png 파일은 대응하는 스킬 폴더가 더 이상 존재하지 않는 "유령 이미지"다. 과거에 있다가 이름이 바뀌었거나 삭제된 스킬의 흔적으로 보이며, 정리(clean-up)가 완벽하지 않다는 증거다.

오해 3 — 이 저장소를 클론해서 "실행"하거나 "빌드"할 수 있다는 오해

git clone 자체는 되지만, 클론한 폴더 안에서 돌릴 스크립트가 없다. package.json도 없고 CI도 없다. 이 저장소는 "읽고 필요한 파일만 복사해 가는" 대상이지, "실행하는" 대상이 아니다. 실습·학습 목적이라면 클론보다 npx typeui.sh list --dry-run류로 CLI를 직접 만져보는 편이 이 프로젝트의 실제 사용 방식에 더 가깝다.

오해 4 — bergside/design-md-chrome과 같은 프로젝트라는 혼동

같은 소유자(Bergside) 계정에는 design-md-chrome이라는 별개 저장소도 있다(추정컨대 DESIGN.md 계열 파일을 브라우저에서 보기 좋게 렌더링하는 크롬 확장 프로그램류로 보인다). 이번 딥다이브의 대상은 오직 awesome-design-skills이며, 두 저장소는 코드·목적이 다른 별개 프로젝트다. 이름이 비슷한 자매 저장소와 혼동하지 않도록 주의한다.

10대안 비교

11정리 · 누가 쓰면 좋은가

bergside/awesome-design-skills는 67개의 SKILL.md/DESIGN.md 쌍을 담은, 코드가 전혀 없는 콘텐츠 레지스트리다. 실제 배포·설치 로직은 별도 저장소인 bergside/typeui.sh CLI가 담당하고, 이 저장소는 그 CLI가 읽어갈 "재료"만 index.json과 폴더 구조로 정리해둔다. 67개 스킬은 슬러그 이름 자체가 유일한 분류 기준이며, 각 SKILL.md의 12개 섹션 중 6개(Guideline Authoring Workflow·Required Output Structure·Component Rule Expectations·Quality Gates 등)는 완전히 동일한 공용 템플릿이고, 나머지(토큰 값·Brand 문단)만 스킬마다 다르다 — 그리고 그 "다른 부분"조차 스킬별로 공들인 정도가 크게 갈린다.