Skip to content

Shortlink UI Design

wcorn edited this page Oct 16, 2026 · 3 revisions

화면 설계: 단축 URL (링크)

확정 명세 · 유스케이스 · 아키텍처 · API · 디자인 시스템

출처: 디자인 핸드오프 design_handoff_shortlink (2026-08-23, hifi). 색·타이포·간격·상태가 확정값이다. 이 문서가 그 번들을 흡수한 정본이며, 아래 §0의 정정 사항이 원본보다 우선한다.

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를 옮기지 않는다.

1. 화면 목록

# 화면 경로 비고
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 서버 렌더 · 비로그인

2. 워크스페이스 선택 /select (수정)

레이아웃은 기존 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

3. 링크 목록 /links

셸: AppLayout(헤더 + 사이드바 + main.min-w-0.flex-1.p-4.md:p-6). 본문 래퍼 mx-auto flex max-w-[720px] flex-col gap-5.

3.1 사이드바 (링크 워크스페이스)

  • 전환 그룹 3분할: 컨테이너 bg-muted flex gap-0.5 rounded-lg p-1, 버튼 h-7 flex-1 rounded-md text-[13px] font-medium, 아이콘 size-3.5, 아이콘-라벨 gap gap-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] + Tag size-3.5 opacity-70 + 우측 개수
  • 판정: isLinkWorkspace = pathname === "/links" || pathname.startsWith("/links/")

일상 사이드바는 손대지 않는다(명세 §9). 여행 사이드바도 그대로다. 바뀌는 것은 최상단 전환 그룹이 2칸에서 3칸이 되는 것뿐이다.

3.2 본문 (위 → 아래)

  1. PageHeader — title 링크(text-display font-semibold), description s.orino.dev · 자동 발급 5자, 최종 17자, actions <Button><Plus className="size-4"/>새 링크</Button>
  2. 빠른 발급 바 (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 + Link2 size-4. 가운데 border 없는 input(placeholder URL 붙여넣고 Enter — 짧은 주소가 바로 만들어지고 클립보드에 복사돼요). 우측 <Button variant="secondary" size="sm">만들기</Button>
  3. 필터 행 — 검색 input h-8 rounded-lg border + Search size-3.5 absolute left-2.5 top-2.5, placeholder 제목·슬러그·목적지·설명 검색. 상태 칩 3개(전체 34 활성 = bg-secondary text-secondary-foreground, 나머지 border 톤, 각 h-8 rounded-lg px-3 text-[13px])
  4. 즐겨찾기 섹션 헤더(text-caption text-muted-foreground font-semibold) → 카드 행
  5. 최근 발급 섹션 → 카드 행

3.3 링크 카드 행

기존 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"> + Copy size-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, 없으면 줄 생략)
  • 우측 메타 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자는 모든 행에서 같다.

4. 새 링크 모달 + 발급 직후

모달(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, prefix text-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 + Check size-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로 이어지는 안내

5. 링크 상세 /links/{slug}

본문 래퍼 mx-auto max-w-[820px] flex-col gap-5. 맨 위 뒤로가기 ← 링크 목록(text-[13px] text-muted-foreground).

  1. 헤더 카드 (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>
  2. 통계 카드 — 지표 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개(시작일 / 중간 / 오늘)
  3. 유입 경로(SL-016) — 라벨 + 값(tabular) + 진행바(h-1.5 rounded-full bg-muted 위 bg-primary). 도메인 수준까지만
  4. 기기 · 국가 — Smartphone/Monitor + 퍼센트, 마지막 줄 국가만 봅니다. IP는 저장하지 않아요.
    • 국가 줄은 그리지 않는다(2026-08-24, D-9 뒤집힘). countries가 항상 빈 배열이라 화면은 그 줄을 자동으로 접는다 — 빈 칸에 —를 넣지 않는다. 기기 판정은 User-Agent로 그대로 남았다
  5. 목적지 교체 이력(SL-008) — History + URL + 날짜 — 사유. 과거 항목 opacity-70 + line-through(현재 목적지 제외)

6. 모바일 /links (390×844)

  • 헤더: 메뉴 버튼(md:hidden) + 로고 size={20} + 테마 토글. 본문 p-4
  • 제목 text-[28px](text-display 36 대신) + 34개 · 이번 주 방문 128
  • 빠른 발급 바를 제목 바로 아래 상주시킨다 — 모바일 발급 빈도가 이 모듈의 성패다(명세 §5.4). placeholder는 URL 붙여넣기로 짧게, 버튼은 default 변형
  • 필터 칩 가로 스크롤(overflow-x-auto)
  • 카드 행 2줄(주소 / 목적지)로 축약, 우측은 복사 버튼 하나만(variant="secondary" size="icon-sm", 28px — 터치 타깃은 행 전체가 44px 이상)

7. 실패 화면 s.orino.dev/{slug} (비로그인)

유일한 공개 표면. 기준은 「정보를 주지 않는 것」이다(명세 §7).

  • 중앙 정렬 한 덩어리: BrandMark size={28} + 이 링크는 사용할 수 없습니다(text-[15px] text-foreground) — 그 이상 아무것도 없다
  • 없음 · 꺼짐 · 만료 · 삭제 구분 없음. 문구 하나, HTTP 404 하나(410 금지)
  • 목적지·메모·생성 시각·계정 정보 노출 금지, 로그인 유도 금지, 재시도·검색 UI 금지
  • 다크/라이트 모두 대응하되 prefers-color-scheme만 쓴다. 모바일 우선
  • BE 서버 렌더 정적 HTML. DS 컴포넌트를 쓸 수 없어 색·타이포 값을 손으로 옮기는 유일한 지점이고, 그래서 요소를 둘로 줄여 뒀다(아키텍처 §2.3)

8. 비밀번호 확인 화면 (비로그인)

같은 서버 렌더 틀. BrandMark + 비밀번호를 입력해 주세요 + 입력칸 + 버튼 하나.

  • 실패 시 같은 화면 + 비밀번호가 맞지 않아요. 왜 틀렸는지 나누지 않는다
  • 통과해도 쿠키를 만들지 않는다 — 다음 방문에 다시 입력(명세 §10)
  • 이 화면이 뜨는 것 자체가 "슬러그가 존재한다"를 알리는 §7의 예외다. 알고 켠다

9. 인터랙션

트리거 동작
빠른 발급 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".

10. 상태 · 데이터

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로 묶는다.

11. 디자인 토큰

새 토큰을 만들지 않는다. 값은 전부 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.

12. 아이콘 · 에셋

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 → 다운로드. 링크 라우트 청크에만 들어간다. 이미지 에셋 없음.

Clone this wiki locally