ABOUT

OHOUSE-DESIGN.md는
무엇이고, 어떻게 쓰나요?

오늘의집 디자인 시스템을 단일 마크다운 파일에 담아, AI 코딩 에이전트가 일관된 오늘의집 UI를 생성할 수 있게 만든 자족(self-contained) 명세입니다. 이 페이지는 처음 보는 분이 5분 안에 무엇이고, 어떻게 쓰며, 무엇을 못하는지 파악할 수 있도록 정리했어요.

01왜 만들었나요?

AI 코딩 도구가 빠르게 일상이 되고 있는데, 디자인 시스템 컨텍스트 없이는 generic Material / Tailwind UI를 출력합니다.

Cursor, Claude Code, Stitch, v0 같은 AI 도구가 화면을 자동 생성하지만, "오늘의집스러운 톤"을 모릅니다. 사내 디자인 시스템(apps-web ODS)·Figma는 외부 도구가 직접 접근하기 어렵고, 매번 토큰 값을 일일이 알려주는 건 비효율적이에요.

한 마크다운 파일로 추리면 어디든 드롭해서 컨텍스트로 쓸 수 있고, LLM이 마크다운을 가장 잘 읽기 때문에 결과 일관성이 훨씬 높아집니다. Google Stitch / VoltAgent의 awesome-design-md 컨셉을 오늘의집 스펙에 맞춰 구현한 결과물입니다.

02할 수 있는 것

7개 핵심 시나리오를 자족 재현 가능하도록 컬러·타이포·컴포넌트·아이콘·패턴을 전부 인라인으로 담았습니다.

03할 수 없는 것

이 파일이 만능은 아닙니다. 아래 영역은 다른 도구·자산이 필요해요.

이건 못합니다

  • ODS API 실측 — 실제 컴포넌트가 ODS에 존재하는지 검증 안 됨 → ODS MCP 사용 필요. 본 파일은 컴포넌트 spec만 알려줌
  • Figma 실측 (좌표·spacing 자동 추출) — "섹션 간격 32px" 같은 implicit 정보 자동 추출 안 됨 → Figma MCP / O!Slice 플러그인 영역. 별도 워크플로우 도구 필요
  • 트랙 고유 화면 spec — 특정 화면(공구·콘텐츠·Seller 등)의 고유 패턴은 없음 → 트랙별 화면 spec 별도 참조. 본 파일은 전사 공통만
  • 운영 코드 직접 lint·test — 실제 코드의 토큰 사용 여부 자동 검증 안 됨 → 가이드만 제공. CI / lint rule 별도 필요
  • 디자인 디테일 자동 검증 — 자동 생성 결과의 디테일 8건 누락 같은 패턴은 자동으로 잡지 못함 → 워크플로우 약점 5종(a~e) 별도 정리 + 체크리스트로 보완
  • 일러스트·로고·BI 가이드 — 본 파일에 없음 → 별도 BI 가이드 repo / Brand Asset 자산. Phase 2에 링크 추가 예정
  • iOS / Android 토큰 — 현재 Web(apps-web ODS) 기준만 → Phase 2 예정. 컴포넌트 canonical 이름은 플랫폼 독립적으로 작성 중
  • 실시간 동기화 — Figma·apps-web 변경 시 자동 갱신 X → 수동 갱신. Phase 2에 빌드 스크립트 검토

04사용법

4단계로 시작합니다. 다른 디자인 시스템 도구가 없어도 됩니다.

1

다운로드

상단 다운로드 버튼으로 OHOUSE-DESIGN.md 또는 버전 고정본 OHOUSE-DESIGN-v0.3.0.md를 받습니다.

2

프로젝트 루트에 둔다

Cursor / Claude Code 작업 디렉토리, Stitch 프로젝트, v0 컨텍스트 슬롯 등 AI 도구가 읽을 수 있는 곳에 파일을 둡니다.

3

프롬프트 시 참조

예시: "@OHOUSE-DESIGN.md를 따라서 모듈 패브릭 4인 소파 상품 상세 페이지를 만들어줘. 모바일 우선, brand-solid CTA 1개, 라이트·다크 양쪽 토큰 적용."

4

마커 확인 + 피드백

결과물에 @ods-component:BoxButton, @non-ods:topic-chip, @missing-ods:<설명> 같은 주석이 자동으로 박힙니다. 이 마커는 다음 iteration에서 재조회 비용을 줄이고, ODS 미커버 컴포넌트를 피드백 루프(#ds-feedback-loop)로 보냅니다.

05누구한테 유용한가요?

PD

AI로 빠른 화면 시안을 만들 때, 매번 "오늘의집 톤으로" 설명하지 않아도 됩니다.

개발자

디자인 시스템 토큰을 한눈에 보고 코드에 적용. 하드코드 hex 방지.

디자이너

외부 도구로 시안을 보낼 때, 사내 톤을 잃지 않고 일관되게 작업.

외주

처음 합류해도 오늘의집 톤을 30분 안에 학습. 1차 산출물 70%↑ 정합.

06현재 상태와 한계

버전v0.3.0 (alpha)
상태전사 공유 시작 단계
기준 플랫폼Web (apps-web ODS)
⛔ Critical 토큰4건 Light 마이그 대기 (red 램프 이전)
Shapes (border-radius)디자인팀 컨펌 대기 (TBD)
Grid column / gutterFigma 추출 한계 (TBD)
알려진 이슈아이콘 visual padding 차이 (245개 path 영역 다름)
동기화수동 (Phase 2 자동화 검토)

07관련 자원

bucketplace/design-assets

아이콘 245개 + DTCG 토큰 원본 (private)

Storybook 카탈로그

아이콘·컴포넌트 시각 브라우징 (사내)

오늘의집 프로젝트 (집들이)

실제 콘텐츠 톤 참고용 (시나리오 07)

awesome-design-md

본 명세의 포맷 레퍼런스 (라인님 공유)

Google design.md

YAML 호환 스펙 (lint·export 도구)

#des_pd

피드백·이슈 채널 (사내)

이제 시작해볼까요?

다운로드 후 AI 도구에 컨텍스트로 입력하면 바로 작동합니다.

v0.3.0 다운로드 시나리오 비교 보기 →
OHOUSE-DESIGN.md · 오늘의집 프로덕트 디자인팀
피드백: Slack #des_pd