# OSH Family Design

버전 1.0 · 2026-09-19 · 기준 화면: OSH AI Hub (`osh.ai.kr`)

**다른 앱도 색상·폰트·버튼·박스·여백을 공유하여 OSH 제품군처럼 보이게 만드는 공통 시각 디자인이다.** 데이터 검색, 문서 변환, 건강검진 등 앱의 목적과 작업 순서는 각각에 맞게 구성한다.

공개 소개: https://osh.ai.kr/datasets/family-design

## 1. 다른 앱/AI에게 전달할 것

이 문서, `osh-family.css`, `preview.html`, `fonts/`를 함께 전달한다. 저장소에는 CSS·예시·내보내기 코드만 두고, 배포 묶음을 만들 때 Hub에서 쓰는 한글 폰트와 라이선스를 포함한다. React·Next.js뿐 아니라 일반 HTML·Django·FastAPI 템플릿에서도 같은 CSS를 사용할 수 있다.

저장소 루트에서 실행:

```bash
python3 design/osh-family/export.py --output local_asset/osh-family-kit-v1
```

실행 결과는 **동일한 이름의 폴더와 ZIP**이다. 원본 저장소에는 이미 설치된 `@fontsource-variable/noto-sans-kr`가 필요하다. 새 환경에서는 프로젝트의 정해진 의존성을 먼저 설치한다. 내보내기는 네트워크에 접속하지 않으며 대상 폴더/ZIP이 이미 있으면 덮어쓰지 않는다.

ZIP을 다른 서버에 풀고 `preview.html`을 브라우저로 열거나 정적 파일 서버로 제공하면 실제 폰트·색상·컴포넌트를 비교할 수 있다. 저장소의 preview.html만 복사하면 fonts/가 없으므로 폰트까지 들어 있는 내보내기 묶음을 권장한다.

## 2. 반드시 같은 것으로 맞추기

| 요소 | OSH 공통 규칙 |
|---|---|
| 주요 색상 | 짙은 파랑 `#003876`. 주요 실행·활성 항목·링크에 사용 |
| 보조 배경 | 옅은 파랑 `#E6EFFB`, 페이지 배경 `#F5F8FD` |
| 카드 | 흰색 `#FFFFFF`, 테두리 `#D6E0ED` 1px, 모서리 12px |
| 글자 | 본문 `#14243D`, 보조 `#52627A` |
| 폰트 | **Noto Sans KR Variable**. 폰트를 실제로 로드해야 동일하게 보임 |
| 버튼 | 모서리 7px, 최소 높이 44px, 주요 버튼은 파랑 바탕·흰 글자 |
| 보조 버튼 | 흰 바탕·파란 글자·테두리. 회색 비활성 버튼과 구별 |
| 입력창 | 흰색, 모서리 7px, 최소 높이 44px, 입력 글자 16px |
| 입력 경계 | `#7B8AA0`. 옅은 카드 테두리보다 진하게 구분 |
| 포커스 | `#0E4A9F` 3px 외곽선, 바깥 간격 4px |
| 배지 | 모서리 4px. DEMO는 `#FFF2D6` 바탕·`#785209` 글자 |
| 아이콘 | 단순한 선형 아이콘. Hub는 Lucide 사용; 일반 18–24px |
| 효과 | 얇은 경계와 여백 중심. 작업 카드에 강한 그림자·다색 그라데이션 사용하지 않음 |

`#1769C2`, `#63A5EF`는 기존 브랜드 마크의 보조 파랑이다. 주요 버튼 색을 앱마다 임의의 보라/초록/주황으로 바꾸지 않는다. 성공·오류 색은 작은 상태 안내에서만 사용하고 문구를 함께 표시한다.

이 CSS는 기존 Hub의 색상과 형태를 가져오고 신규 앱의 가독성을 위해 본문 16px·설명 14px·터치 높이 44px를 적용한 **새 공통 기준**이다. 현재 Hub의 모든 화면이 이미 같은 글자 크기라는 뜻은 아니다. 이번 키트를 만들면서 기존 서비스 화면을 일괄 변경하지 않았다.

## 3. 글꼴과 여백

| 용도 | 크기·굵기 |
|---|---|
| 페이지 제목 | PC 36px / 모바일 28px, 750 |
| 작업 영역 제목 | PC 24px / 모바일 22px, 700 |
| 카드 제목 | 20px, 650 |
| 본문·입력 | 16px, 400, 줄높이 1.7 |
| 버튼 | 16px, 600 |
| 도움말·표·배지 | 14px, 도움말 줄높이 1.7 |

간격은 4·8·12·16·24·32·48·64px 계열을 사용한다. 카드 안쪽은 PC 24px / 모바일 20px, 카드 사이 24px, 주요 화면 구역 사이 40px를 이 키트의 기본값으로 한다. 제목/설명은 한국어 줄바꿈을 자연스럽게 하고 긴 파일명·URL은 컨테이너 안에서 줄바꿈한다.

콘텐츠 폭은 최대 1240px, 좌우 여백은 PC 40px·1150px 이하 24px·640px 이하 18px다. 850px 이하에서는 기본 작업 2열과 카드 3열을 한 열로 바꾼다. 표처럼 넓어야 하는 부분만 내부 스크롤을 허용한다.

## 4. 공통으로 보이는 기본 화면

```text
흰색 상단: OSH 계열 표시 + 앱 이름                  도움말/계정
옅은 페이지 배경
  제목 + 한 문장 설명
  ┌ 흰색 입력 카드 ─────┐  ┌ 흰색 결과 카드 ─────┐
  │ 레이블·입력창        │  │ 상태·내용·근거       │
  │ 파란색 주요 버튼     │  │ 보조 행동            │
  └────────────────────┘  └────────────────────┘
  자료 처리 안내·출처
```

이 배치는 예시다. 모든 앱을 똑같은 대시보드로 만들지는 않는다.

| 유지할 것 | 앱에 맞춰 바꿀 것 |
|---|---|
| 색상·폰트·카드·버튼·입력창·여백 규칙 | 앱 이름, 메뉴, 필드, 작업 단계 |
| 원문/AI/DEMO를 구분하는 표현 | 검색 목록/파일 변환/단계별 동의 등의 레이아웃 |
| 동일한 포커스·오류·도움말 스타일 | 넓은 표, 문서 뷰어, 결과 패널 크기 |
| OSH 제품군임을 알리는 작은 브랜드 표시 | 기능에 필요한 시각화·차트 종류 |

상단에 각 앱의 이름을 분명히 표시한다. Hub의 전체 메뉴나 대형 소개 배너를 작업 앱마다 반복하지 않는다. OSH 앱에 한해 제공된 마크를 사용하고 비율·세 막대의 색을 임의로 바꾸지 않는다. 색을 맞춘 것만으로 앱 간 로그인/계정이 연동된다고 표시하지 않는다.

## 5. CSS 적용법

전체 페이지를 이 스타일로 만들 때:

```html
<link rel="stylesheet" href="/static/osh-family/fonts/font.css">
<link rel="stylesheet" href="/static/osh-family/osh-family.css">
<body class="osh-app">
  <main class="osh-container osh-main">
    <h1 class="osh-title">우리 앱 이름</h1>
    <section class="osh-card">
      <h2 class="osh-heading">자료 입력</h2>
      <p class="osh-copy">앱이 처리하는 자료와 다음 단계를 설명합니다.</p>
    </section>
  </main>
</body>
```

경로는 앱의 정적 파일 위치에 맞춘다. 기존 화면 일부에만 적용하려면 그 영역을 `<div class="osh-app">`으로 감싼다. CSS 변수와 스타일은 `.osh-app` 범위에 있으며 `osh-` 접두어로 기존 클래스와 충돌을 줄였다. **각 앱의 기존 CSS와 충돌 검증은 별도로 필요**하다.

React/Next에서는 CSS와 폰트를 앱의 전역 진입점에서 로드하고 `class`를 `className`으로 바꾼다. 이미 `@fontsource-variable/noto-sans-kr`를 로드한다면 같은 폰트를 중복 로드하지 않는다. Django/FastAPI에서는 정적 파일로 제공한다. Streamlit 등 프레임워크가 만든 DOM에 부분 적용하는 경우 버튼·표까지 실제로 스타일이 반영됐는지 확인한다.

| 공통 클래스 | 용도 |
|---|---|
| `.osh-header`, `.osh-header-inner`, `.osh-brand` | 상단·앱 이름 |
| `.osh-container`, `.osh-main`, `.osh-section` | 콘텐츠 폭·페이지·구역 여백 |
| `.osh-card`, `.osh-panel` | 흰 작업 카드·옅은 안내 패널 |
| `.osh-workspace`, `.osh-grid`, `.osh-stack` | 2열 작업·3열 카드·세로 간격 |
| `.osh-title`, `.osh-heading`, `.osh-card-title` | 제목 단계 |
| `.osh-button`, `.osh-button--secondary` | 주요·보조 행동 |
| `.osh-field`, `.osh-label`, `.osh-input`, `.osh-help` | 레이블·입력·도움말 |
| `.osh-note`, `.osh-note--success`, `.osh-note--error` | 안내·성공·오류 |
| `.osh-badge`, `.osh-badge--demo` | 분류·DEMO 표시 |
| `.osh-table-scroll`, `.osh-table` | 표와 내부 스크롤 |

버튼은 실제 동작을 연결하고 이동은 링크로 구현한다. `aria-invalid`, `aria-describedby`, `role=status/alert`는 실제 화면 상태에 맞게 지정한다. CSS는 인증·파일 전송·검증 기능을 제공하지 않는다.

## 6. 다른 AI에게 줄 지시문

> 이 앱에 첨부한 OSH Family Design을 적용해 줘. osh-family.css와 Noto Sans KR Variable 폰트를 사용해서 osh.ai.kr와 같은 색상·카드·버튼·입력창·여백으로 맞춰 줘. 기능과 작업 순서는 이 앱의 목적에 맞게 구성하고, 새 브랜드 색이나 별도 폰트를 임의로 만들지 마. preview.html을 시각 기준으로 삼고 360px 모바일·키보드·오류 상태까지 확인해 줘. 기존 인증·데이터·배포 설정은 작업 범위에 맞게 보존하고, 실제 기능이 없는 예시는 DEMO로 표시해 줘.

새 화면의 목적·입력·결과·권한·검증 범위는 함께 제공되는 DESIGN-BRIEF-TEMPLATE.md에 적는다. DESIGN-GUIDELINES.md는 상세 UX·접근성·DEMO 표현 기준이다. Family Design은 **앱 간 시각적 통일**의 기준이며 두 문서를 함께 따른다.

## 7. 적용 완료 확인

- [ ] 로컬 한글 폰트가 실제 로드되고 대체 폰트로 보이지 않는다.
- [ ] 주요 색·카드 배경/테두리·모서리·버튼 높이가 키트와 같다.
- [ ] 360px·PC·200% 확대에서 주요 행동이 잘리지 않는다.
- [ ] 본문·도움말 대비, 입력 경계, 키보드 포커스, 레이블을 확인했다.
- [ ] 정상/빈 결과/오류/로딩/비활성 상태가 실제 동작과 일치한다.
- [ ] 디자인을 맞추면서 기존 로그인·다운로드·API 권한을 바꾸지 않았다.
- [ ] 코드 변경에는 해당 앱의 lint·typecheck·tests·build를 실행했다.

이 키트는 특정 앱들의 전체 화면을 이미 변경했다는 뜻이 아니다. 적용 앱·키트 버전·예외와 이유를 각 앱의 디자인 브리프에 기록한다. 공통 색·형태를 바꾸려면 버전을 올리고 적용 앱별 반영 여부를 기록한다.