Repository navigation
Shortlink UI Design
확정 명세 · 유스케이스 · 아키텍처 · API · 디자인 시스템
출처: 디자인 핸드오프
design_handoff_shortlink(2026-08-23, hifi). 색·타이포·간격·상태가 확정값이다. 이 문서가 그 번들을 흡수한 정본이며, 아래 §0의 정정 사항이 원본보다 우선한다.
| 항목 | 핸드오프 | 확정 |
|---|---|---|
| 상세 라우트 |
/links/:id (본문) / /links/9dwqr (아트보드) |
/links/{slug} — 슬러그가 불변 키다(결정 기록 D-5) |
| 짧은 주소 문자열 | FE가 s.orino.dev/ + slug 조립 |
서버가 shortUrl로 내려준다. FE에 도메인을 하드코딩하지 않는다 |
| 실패 화면 | "SPA 라우터가 아니라 리다이렉트 서비스 쪽에서 서빙" | 그대로. BE 서버 렌더 정적 HTML이며 FE 라우트가 아니다(아키텍처 §2.3) |
| 목적지 이력 표기 | 과거 항목 opacity-70 + line-through
|
그대로. 단 현재 목적지에는 취소선을 넣지 않는다(첫 줄) |
목업의 files.orino.dev · minio.orino.dev
|
— | 목업 데이터일 뿐. 실제 공개 호스트는 img.orino.dev
|
구현 원칙(핸드오프 그대로): 레이아웃 글루는 Tailwind 유틸리티 + 시맨틱 토큰. 버튼·배지·입력·모달은 반드시 @/components/ui/*. 아이콘은 lucide-react import(HTML의 인라인 <svg> 복사 금지). 로고는 @/components/brand/Logo. 하드코딩된 hex/px를 옮기지 않는다.
| # | 화면 | 경로 | 비고 |
|---|---|---|---|
| 1a | 워크스페이스 선택 | /select |
기존 화면 수정 (2카드 → 3카드) |
| 1b | 링크 목록 | /links |
신규 |
| 1c | 새 링크 모달 + 발급 직후 | (모달) | 신규 |
| 1d | 링크 상세 | /links/{slug} |
신규 |
| 1e | 실패 화면 | s.orino.dev/{slug} |
BE 서버 렌더 · 비로그인 |
| 1f | 모바일 목록 |
/links (390×844) |
1b의 반응형 |
| 1g | 비밀번호 확인 | s.orino.dev/{slug} |
BE 서버 렌더 · 비로그인 |
레이아웃은 기존 WorkspaceSelectPage.tsx 그대로 — min-h-svh flex-col + AppHeader(메뉴 버튼 없음) + main.grid.flex-1.place-items-center.px-4.pt-8.pb-16, 안쪽 w-full max-w-[680px] flex-col gap-6. 제목 text-title font-semibold 어디로 갈까요, 설명 text-muted-foreground mt-1 text-sm 사이드바 맨 위에서 언제든 바꿀 수 있어요.
변경점: 카드 행 flex flex-wrap gap-4에 세 번째 카드. basis-[260px] → basis-[200px] (3장 + gap 32 = 632px로 680 안에 한 줄. 그 아래 폭에서는 기존처럼 wrap).
링크 카드(기존 WorkspaceCard 재사용):
- 아이콘
Link2, 아이콘 박스size-10 rounded-lg bg-muted— 일상과 같은 중립 톤.bg-accent는 여행 전용이다 - 제목
링크/ 설명짧은 주소 발급, QR, 방문 통계 - 배지 없음(기본)
- 메타:
ChartColumn+링크 34개 · 이번 주 방문 128←GET /api/shortlinks/summary - 데이터가 없거나 요청이 실패하면 메타 줄 자체를 그리지 않는다(기존 원칙)
- 클릭 →
navigate("/links") - hover:
ring-foreground/10→ring-primary+hover:-translate-y-px,duration-150
셸: AppLayout(헤더 + 사이드바 + main.min-w-0.flex-1.p-4.md:p-6). 본문 래퍼 mx-auto flex max-w-[720px] flex-col gap-5.
- 전환 그룹 3분할: 컨테이너
bg-muted flex gap-0.5 rounded-lg p-1, 버튼h-7 flex-1 rounded-md text-[13px] font-medium, 아이콘size-3.5, 아이콘-라벨 gapgap-1.5→gap-[5px](224px 사이드바에서 3칸이 눌리지 않게). 활성bg-background text-foreground shadow-sm, 비활성text-muted-foreground - 메뉴:
링크 목록(Link2, 우측 총 개수text-xs tabular-nums opacity-70) ·즐겨찾기(Star, 개수) - 섹션 헤더
태그—text-caption text-muted-foreground font-semibold,mx-3 mt-3 mb-1.5 - 태그 행
h-8 px-3 text-[13px]+ Tagsize-3.5 opacity-70+ 우측 개수 - 판정:
isLinkWorkspace = pathname === "/links" || pathname.startsWith("/links/")
일상 사이드바는 손대지 않는다(명세 §9). 여행 사이드바도 그대로다. 바뀌는 것은 최상단 전환 그룹이 2칸에서 3칸이 되는 것뿐이다.
-
PageHeader — title
링크(text-display font-semibold), descriptions.orino.dev · 자동 발급 5자, 최종 17자, actions<Button><Plus className="size-4"/>새 링크</Button> -
빠른 발급 바 (SL-002 · 상주) —
bg-card ring-1 ring-foreground/10 rounded-xl p-3 flex items-center gap-2. 좌측size-8 rounded-lg bg-accent text-accent-foreground grid place-items-center+ Link2size-4. 가운데 border 없는 input(placeholderURL 붙여넣고 Enter — 짧은 주소가 바로 만들어지고 클립보드에 복사돼요). 우측<Button variant="secondary" size="sm">만들기</Button> -
필터 행 — 검색 input
h-8 rounded-lg border+ Searchsize-3.5absoluteleft-2.5 top-2.5, placeholder제목·슬러그·목적지·설명 검색. 상태 칩 3개(전체 34활성 =bg-secondary text-secondary-foreground, 나머지border톤, 각h-8 rounded-lg px-3 text-[13px]) -
즐겨찾기 섹션 헤더(
text-caption text-muted-foreground font-semibold) → 카드 행 - 최근 발급 섹션 → 카드 행
기존 TripRow 패턴 계승 — bg-card ring-foreground/10 hover:ring-primary rounded-xl ring-1 transition-all, 패딩 p-[14px_16px], flex items-center gap-3.
- 좌측
min-w-0 flex-1 flex-col gap-[3px]- 1행: (즐겨찾기면) Star
size-3.5 fill-current text-primary→ 짧은 주소text-[15px] tracking-[-0.01em]—s.orino.dev/는text-muted-foreground, 슬러그만font-semibold text-foreground→ (커스텀이면)<Badge variant="secondary">커스텀</Badge>→ 복사<Button variant="ghost" size="icon-xs">+ Copysize-3 - 2행: 목적지 URL
text-[13px] text-muted-foreground truncate -
제목이 있으면(#1424): 1행의 짧은 주소 자리에 제목
text-[15px] font-semibold truncate, 짧은 주소는 2행 앞으로 내려와s.orino.dev/slug · 목적지가 된다. 복사 버튼이 복사하는 것은 여전히 짧은 주소다. 제목이 없으면 위 그대로 - 3행: 설명(memo) +
<Badge variant="outline">태그</Badge>(text-xs, 없으면 줄 생략)
- 1행: (즐겨찾기면) Star
- 우측 메타
w-24 flex-none items-end: 방문 수text-[15px] font-semibold tabular-nums, 마지막 방문text-xs text-muted-foreground - 우측 액션: QR
<Button variant="ghost" size="icon-sm">, 더보기Ellipsis→ Menu(편집 · 목적지 수정 · 활성/비활성 · 삭제) -
비활성·만료 행:
opacity-[.62]+<Badge variant="secondary">꺼짐</Badge>(만료는만료). QR 버튼 없음
슬러그만 진하게 두는 것은 장식이 아니다. 목록에서 사람이 실제로 구분해 읽는 부분이 슬러그 5자뿐이고, 도메인 11자는 모든 행에서 같다.
모달(DS Modal, size="md" ≈ 560px), title 새 링크, description 붙여넣고 만들기. 나머지는 나중에 고쳐도 됩니다.
-
목적지 URL — 라벨 우측 실시간 길이 미리보기:
s.orino.dev/+ab3k9(예정 슬러그,font-semibold) +17자칩(bg-muted rounded-full px-1.5 py-0.5 text-xs tabular-nums). 명세 §3의 17자를 화면이 계속 보여주는 장치다 -
OG 프리뷰(SL-005) —
bg-muted rounded-lg p-2 flex gap-2.5: 썸네일size-9 rounded-md bg-card, 제목text-[13px] font-medium truncate, 보조text-xs text-muted-foreground=프리뷰는 확인용이에요. 못 읽어도 발급은 막지 않습니다.— 비동기로 뒤따라 채우고, 실패·지연이 제출을 막지 않는다 -
제목(선택, 100자) — placeholder
목록에서 알아볼 이름 — 비우면 짧은 주소(#1424) -
설명(선택, 255자) — Textarea 2줄. 저장 필드는
memo다. 제목 바로 아래에 둔다 — 둘 다 링크를 알아보는 정보다 -
커스텀 슬러그(선택) — prefix
s.orino.dev/가 인풋 안에(flex h-8 items-center rounded-lg border px-2.5, prefixtext-muted-foreground mr-1), placeholder비우면 5자 자동 -
만료(선택) —
예: 2026-12-31 -
태그 칩(선택
secondary/ 후보outline/ 마지막+ 태그 추가) -
비밀번호 보호 —
bg-muted rounded-lg px-3 py-2.5안에 Lock +비밀번호 보호 — 켜면 확인 화면을 한 번 거칩니다+Switch, 기본 꺼짐 - footer:
취소(outline) /만들기(default)
발급 직후(같은 모달을 성공 화면으로 교체, 폭 380px 중앙):
- 성공 칩
bg-success/14 text-success rounded-full px-2.5 py-1 text-xs font-semibold+ Checksize-3.5+클립보드에 복사했어요 - 짧은 주소
text-2xl tracking-[-0.02em](도메인 muted / 슬러그font-bold) - QR 168×168
rounded-xl bg-white ring-1 ring-border— 실제 QR 렌더링 - 버튼 2개
flex-1:QR 저장(outline, Download) /완료(default) - 보조 문구
목적지는 나중에 바꿔도 이 주소는 그대로예요.← UC-01로 이어지는 안내
본문 래퍼 mx-auto max-w-[820px] flex-col gap-5. 맨 위 뒤로가기 ← 링크 목록(text-[13px] text-muted-foreground).
-
헤더 카드 (
bg-card ring-1 ring-foreground/10 rounded-xl p-5,flex gap-5)- 좌:
<Badge variant="success">활성</Badge>+2026.08.03 발급 · 가족(text-xs muted) + 우측<Button variant="ghost" size="sm">제목·설명 수정</Button>(#1424) / (제목이 있으면) 제목h1 text-title font-semibold— 이때 짧은 주소는text-lg로 한 단계 내려온다 / 짧은 주소text-[28px] tracking-[-0.02em]+<Button variant="secondary" size="sm">복사</Button>/ 목적지 블록bg-muted rounded-lg p-3: Globe + URL truncate +<Button variant="outline" size="sm">목적지 수정</Button>, 아래주소는 그대로 두고 목적지만 갈아끼웁니다. 이미 뿌린 링크가 전부 살아납니다.(text-xs muted) / 설명(memo) -
제목·설명 수정 모달(#1424): 제목 Input + 설명 Textarea, footer
저장. 지금 값에서 시작하고, 비우고 저장하면 지운다(빈 문자열 전송). 빠른 발급 바로 만든 링크에 나중에 이름을 붙이는 자리다. 목적지 수정과 모달을 나누는 이유: 목적지 교체는 사유·이력이 따르는 일이고, 이름 고치기는 내 목록의 표기만 바꾼다 - 우: QR 140×140 +
<Button variant="outline" size="sm">PNG 저장</Button>
- 좌:
-
통계 카드 — 지표 3개(
총 방문/최근 7일/마지막 방문, 숫자text-[28px] font-semibold tabular-nums, 라벨text-xs muted), 우측 Bot 아이콘 +봇·프리뷰 18건은 따로 셉니다 — 통계는 참고치. 아래 최근 30일 일별 막대: 높이 120px,flex items-end gap-[3px], 막대flex-1 rounded-t-[2px], 값 있는 날bg-primary/ 없는 날bg-muted. 축 라벨 3개(시작일 / 중간 / 오늘) -
유입 경로(SL-016) — 라벨 + 값(tabular) + 진행바(
h-1.5 rounded-full bg-muted위bg-primary). 도메인 수준까지만 -
기기 ·
국가— Smartphone/Monitor + 퍼센트, 마지막 줄국가만 봅니다. IP는 저장하지 않아요.-
국가 줄은 그리지 않는다(2026-08-24, D-9 뒤집힘).
countries가 항상 빈 배열이라 화면은 그 줄을 자동으로 접는다 — 빈 칸에—를 넣지 않는다. 기기 판정은 User-Agent로 그대로 남았다
-
국가 줄은 그리지 않는다(2026-08-24, D-9 뒤집힘).
-
목적지 교체 이력(SL-008) — History + URL +
날짜 — 사유. 과거 항목opacity-70+line-through(현재 목적지 제외)
- 헤더: 메뉴 버튼(
md:hidden) + 로고size={20}+ 테마 토글. 본문p-4 - 제목
text-[28px](text-display36 대신) +34개 · 이번 주 방문 128 -
빠른 발급 바를 제목 바로 아래 상주시킨다 — 모바일 발급 빈도가 이 모듈의 성패다(명세 §5.4). placeholder는
URL 붙여넣기로 짧게, 버튼은default변형 - 필터 칩 가로 스크롤(
overflow-x-auto) - 카드 행 2줄(주소 / 목적지)로 축약, 우측은 복사 버튼 하나만(
variant="secondary" size="icon-sm", 28px — 터치 타깃은 행 전체가 44px 이상)
유일한 공개 표면. 기준은 「정보를 주지 않는 것」이다(명세 §7).
- 중앙 정렬 한 덩어리:
BrandMark size={28}+이 링크는 사용할 수 없습니다(text-[15px] text-foreground) — 그 이상 아무것도 없다 - 없음 · 꺼짐 · 만료 · 삭제 구분 없음. 문구 하나, HTTP 404 하나(410 금지)
- 목적지·메모·생성 시각·계정 정보 노출 금지, 로그인 유도 금지, 재시도·검색 UI 금지
- 다크/라이트 모두 대응하되
prefers-color-scheme만 쓴다. 모바일 우선 - BE 서버 렌더 정적 HTML. DS 컴포넌트를 쓸 수 없어 색·타이포 값을 손으로 옮기는 유일한 지점이고, 그래서 요소를 둘로 줄여 뒀다(아키텍처 §2.3)
같은 서버 렌더 틀. BrandMark + 비밀번호를 입력해 주세요 + 입력칸 + 버튼 하나.
- 실패 시 같은 화면 +
비밀번호가 맞지 않아요. 왜 틀렸는지 나누지 않는다 - 통과해도 쿠키를 만들지 않는다 — 다음 방문에 다시 입력(명세 §10)
- 이 화면이 뜨는 것 자체가 "슬러그가 존재한다"를 알리는 §7의 예외다. 알고 켠다
| 트리거 | 동작 |
|---|---|
빠른 발급 Enter / 만들기
|
낙관적 발급 → 목록 맨 위 삽입 → 서버 응답의 슬러그로 클립보드 복사 → 토스트 복사했어요
|
| 카드 행 클릭 | /links/{slug} |
| 복사 버튼 | 복사 + 토스트. 행 이동 없음(stopPropagation) |
| QR 버튼 | QR 팝오버/모달 + PNG 저장
|
| 더보기 | Menu: 편집 · 목적지 수정 · 활성/비활성 · 삭제(ConfirmDialog, destructive) |
| 커스텀 슬러그 입력 | 디바운스 중복 검사 → FieldError 이미 사용 중이에요
|
| 목적지 입력 | 스킴 검증(http/https/mailto/tel) · 목적지가 s.orino.dev면 거부 |
| 카드 hover |
ring-foreground/10 → ring-primary (transition-all) |
로딩 목록 LoadingText, 발급 버튼 pending. 빈 상태 EmptyState + 아직 만든 링크가 없어요. + 새 링크. 에러 인라인 Alert variant="destructive".
useShortlinkSummary() GET /api/shortlinks/summary
useLinks({ query, tag, status }) GET /api/shortlinks
useLink(slug) GET /api/shortlinks/{slug}
useLinkStats(slug, range=30d) GET /api/shortlinks/{slug}/stats
createLink() POST /api/shortlinks
updateLink(slug) PATCH /api/shortlinks/{slug}
toggleLink / favoriteLink / deleteLink
ogPreview(url) GET /api/shortlinks/og-preview
로컬 상태: 검색어 · 선택 태그 · 상태 필터 · 모달 open/step(form | created) · 방금 발급된 링크. React Query 키는 기존 travelKeys 패턴대로 shortlinkKeys로 묶는다.
새 토큰을 만들지 않는다. 값은 전부 fe/src/index.css에 있다.
| 용도 | 토큰 |
|---|---|
| 페이지 배경 / 카드 |
bg-background / bg-card
|
| 본문 / 보조 텍스트 |
text-foreground / text-muted-foreground
|
| 옅은 면 | bg-muted |
| 브랜드 |
bg-primary text-primary
|
| 브랜드 톤 면 |
bg-accent text-accent-foreground (여행 카드와 빠른 발급 아이콘 박스) |
| 테두리 |
border-border / ring-foreground/10
|
| 활성 배지 | success |
반경 --radius: 0.5rem → rounded-lg 8px · rounded-xl 11.2px(카드·행 공통).
타이포 text-display 36/1.15 · text-title 24/1.2 · text-heading 18/1.3 · text-body 15/1.6 · text-label 14/1.4 · text-caption 12/1.5. Pretendard Variable.
숫자는 전부 tabular-nums. 짧은 주소는 tracking-[-0.01em].
간격 페이지 p-4 md:p-6 · 섹션 gap-5 · 카드 안 gap-3.5 · 행 사이 gap-2.
lucide-react — Link2, Star, Copy, QrCode, Ellipsis, Plus, Search, Tag, ChartColumn, Download, Globe, Smartphone, Monitor, History, Lock, Bot, Check, ArrowLeft, SquarePen, Plane, LayoutGrid
로고 @/components/brand/Logo(Logo / BrandMark / Wordmark).
QR은 FE 라이브러리로 canvas 렌더 → toBlob → 다운로드. 링크 라우트 청크에만 들어간다. 이미지 에셋 없음.