feat: 디자인 시스템 기반 — 유틸 헬퍼 + CI rule + 첫 6개 프리미티브

UX/UI 개편 Phase A-3 / A-4 / A-5. 후속 phase가 곧바로 소비할 수 있도록
디자인 시스템의 코어 자산을 한꺼번에 도입한다.

A-3 — 유틸 헬퍼 (lib/utils/)
- pLimit.ts: 동시 실행 N개 제한 (5대 원칙 #4 — 일괄 PATCH/DELETE에서
  GPU 서버/SSE 부하 방지). 외부 의존성 없음.
- mergeDoc.ts: PATCH/SSE 응답을 로컬 cache에 머지할 때 updated_at으로
  stale 갱신 차단 (5대 원칙 #6 — optimistic update conflict resolution).
  dropDoc 헬퍼 포함.

A-4 — CI 토큰 차단 (5대 원칙 #1)
- scripts/check-tokens.sh: bg-[var(--*)] 등 임의값 토큰 우회 grep 차단.
- npm run lint:tokens 등록.
- 현재 baseline 421건 — A-8 토큰 swap에서 0으로 떨어진 후 pre-commit 강제화.

A-5 — 첫 6개 프리미티브 (lib/components/ui/)
- Button.svelte: variant(primary/secondary/ghost/danger) × size(sm/md),
  loading/disabled, icon 슬롯, href 자동 a 변환, focus-visible ring.
- IconButton.svelte: 정사각형, aria-label 필수, Button과 동일 variant 체계.
- Card.svelte: bg-surface + rounded-card + border-default 패턴 1군데화.
  padded/interactive 옵션, interactive면 button 시맨틱.
- Badge.svelte: 의미적 tone(neutral/success/warning/error/accent) 표시.
  TagPill과 별개 (TagPill은 도메인 prefix 코드 전용).
- Skeleton.svelte: ad-hoc animate-pulse div 통합. w/h/rounded prop.
- EmptyState.svelte: icon + title + description + action slot.

모든 프리미티브는 Svelte 5 runes mode strict (\$props/\$derived/\$bindable),
@theme 토큰만 사용 (bg-surface, text-dim, border-default 등 — bg-[var(--*)] 미사용),
focus-visible ring 통일, slot은 {@render children?.()}로 작성.

svelte-check: 0 errors, 8 warnings (모두 기존 latent 이슈, 새 코드 무관).
build: 1.95s 무경고.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

frontend/package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "vite dev",
     "build": "vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "lint:tokens": "bash ./scripts/check-tokens.sh"
   },
   "devDependencies": {
     "@sveltejs/adapter-node": "^5.0.0",

frontend/scripts/check-tokens.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Tailwind 임의값 토큰 우회 차단 — plan 5대 원칙 #1.
+#
+# 새 코드에서 bg-[var(--*)] / text-[var(--*)] / border-[var(--*)] 등을 grep으로 차단.
+# @theme 토큰을 우회해 임의값을 작성하면 이 스크립트가 fail.
+#
+# 예외:
+# - frontend/src/lib/components/ui/  (프리미티브 정의 자체는 토큰 매핑이 필요할 수 있음)
+# - frontend/src/app.css              (@theme/:root 선언이므로 grep 대상 아님)
+#
+# 사용:
+#   npm run -C frontend lint:tokens
+#
+# 향후 pre-commit hook에 포함:
+#   .git/hooks/pre-commit → npm run -C frontend lint:tokens
+
+set -e
+
+# 스크립트 위치 기준으로 frontend 루트로 이동
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FRONTEND_DIR="$(dirname "$SCRIPT_DIR")"
+cd "$FRONTEND_DIR"
+
+PATTERNS=(
+  'bg-\[var\(--'
+  'text-\[var\(--'
+  'border-\[var\(--'
+  'ring-\[var\(--'
+  'fill-\[var\(--'
+  'stroke-\[var\(--'
+)
+
+EXIT=0
+TOTAL=0
+
+for p in "${PATTERNS[@]}"; do
+  HITS=$(grep -rEn \
+    --include='*.svelte' \
+    --include='*.ts' \
+    --include='*.js' \
+    --exclude-dir=node_modules \
+    --exclude-dir=.svelte-kit \
+    --exclude-dir=ui \
+    "$p" src 2>/dev/null || true)
+  if [ -n "$HITS" ]; then
+    COUNT=$(echo "$HITS" | wc -l | tr -d ' ')
+    TOTAL=$((TOTAL + COUNT))
+    echo ""
+    echo "❌ 금지 패턴 발견: $p  ($COUNT 건)"
+    echo "$HITS" | head -20
+    if [ "$COUNT" -gt 20 ]; then
+      echo "... (이하 $((COUNT - 20)) 건 생략)"
+    fi
+    EXIT=1
+  fi
+done
+
+if [ $EXIT -eq 0 ]; then
+  echo "✅ 토큰 우회 패턴 없음."
+else
+  echo ""
+  echo "총 $TOTAL 건의 토큰 우회 패턴이 발견되었습니다."
+  echo "→ @theme 유틸리티 (bg-surface, text-dim, border-default 등)로 교체하세요."
+fi
+
+exit $EXIT

frontend/src/lib/components/ui/Badge.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+  // 공용 status pill (TagPill과 별개 — TagPill은 도메인 prefix 코드,
+  // Badge는 의미적 tone 표시).
+  import type { Snippet } from 'svelte';
+
+  type Tone = 'neutral' | 'success' | 'warning' | 'error' | 'accent';
+  type Size = 'sm' | 'md';
+
+  interface Props {
+    tone?: Tone;
+    size?: Size;
+    children?: Snippet;
+    class?: string;
+  }
+
+  let {
+    tone = 'neutral',
+    size = 'md',
+    children,
+    class: className = '',
+    ...rest
+  }: Props = $props();
+
+  const toneClass: Record<Tone, string> = {
+    neutral: 'bg-surface text-dim border border-default',
+    success: 'bg-success/15 text-success border border-success/30',
+    warning: 'bg-warning/15 text-warning border border-warning/30',
+    error: 'bg-error/15 text-error border border-error/30',
+    accent: 'bg-accent/15 text-accent border border-accent/30',
+  };
+
+  const sizeClass: Record<Size, string> = {
+    sm: 'text-[10px] px-1.5 py-0.5',
+    md: 'text-xs px-2 py-0.5',
+  };
+
+  let baseClass = $derived(
+    [
+      'inline-flex items-center gap-1 rounded font-medium',
+      sizeClass[size],
+      toneClass[tone],
+      className,
+    ].join(' ')
+  );
+</script>
+
+<span class={baseClass} {...rest}>
+  {@render children?.()}
+</span>

frontend/src/lib/components/ui/Button.svelte

@@ -0,0 +1,113 @@
+<script lang="ts">
+  // 공용 Button 프리미티브.
+  // - variant: 시각적 강도 (primary/secondary/ghost/danger)
+  // - size: sm/md
+  // - href가 있으면 <a>로, 없으면 <button>으로 렌더
+  // - icon은 lucide 컴포넌트 참조 (예: import { Trash2 } 후 icon={Trash2})
+  // - loading이면 disabled + 회전 아이콘
+  import { Loader2 } from 'lucide-svelte';
+  import type { Snippet } from 'svelte';
+  import type { Component } from 'svelte';
+
+  type Variant = 'primary' | 'secondary' | 'ghost' | 'danger';
+  type Size = 'sm' | 'md';
+
+  interface Props {
+    variant?: Variant;
+    size?: Size;
+    loading?: boolean;
+    disabled?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+    icon?: Component;
+    iconPosition?: 'left' | 'right';
+    href?: string;
+    target?: string;
+    onclick?: (e: MouseEvent) => void;
+    children?: Snippet;
+    class?: string;
+  }
+
+  let {
+    variant = 'primary',
+    size = 'md',
+    loading = false,
+    disabled = false,
+    type = 'button',
+    icon: Icon,
+    iconPosition = 'left',
+    href,
+    target,
+    onclick,
+    children,
+    class: className = '',
+    ...rest
+  }: Props = $props();
+
+  const variantClass: Record<Variant, string> = {
+    primary: 'bg-accent text-white hover:bg-accent-hover',
+    secondary: 'bg-surface border border-default text-text hover:bg-surface-hover',
+    ghost: 'text-dim hover:bg-surface hover:text-text',
+    danger: 'bg-error/10 text-error border border-error/30 hover:bg-error/20',
+  };
+
+  const sizeClass: Record<Size, string> = {
+    sm: 'h-7 px-2.5 text-xs gap-1.5',
+    md: 'h-9 px-3.5 text-sm gap-2',
+  };
+
+  let iconSize = $derived(size === 'sm' ? 14 : 16);
+
+  let baseClass = $derived(
+    [
+      'inline-flex items-center justify-center rounded-md font-medium',
+      'transition-colors',
+      'focus-visible:ring-2 focus-visible:ring-accent-ring focus-visible:outline-none',
+      'disabled:opacity-50 disabled:cursor-not-allowed',
+      sizeClass[size],
+      variantClass[variant],
+      className,
+    ].join(' ')
+  );
+
+  let isDisabled = $derived(disabled || loading);
+</script>
+
+{#if href}
+  <a
+    {href}
+    {target}
+    class={baseClass}
+    aria-disabled={isDisabled || undefined}
+    tabindex={isDisabled ? -1 : undefined}
+    {...rest}
+  >
+    {#if loading}
+      <Loader2 size={iconSize} class="animate-spin" />
+    {:else if Icon && iconPosition === 'left'}
+      <Icon size={iconSize} />
+    {/if}
+    {@render children?.()}
+    {#if !loading && Icon && iconPosition === 'right'}
+      <Icon size={iconSize} />
+    {/if}
+  </a>
+{:else}
+  <button
+    {type}
+    class={baseClass}
+    disabled={isDisabled}
+    aria-busy={loading || undefined}
+    {onclick}
+    {...rest}
+  >
+    {#if loading}
+      <Loader2 size={iconSize} class="animate-spin" />
+    {:else if Icon && iconPosition === 'left'}
+      <Icon size={iconSize} />
+    {/if}
+    {@render children?.()}
+    {#if !loading && Icon && iconPosition === 'right'}
+      <Icon size={iconSize} />
+    {/if}
+  </button>
+{/if}

frontend/src/lib/components/ui/Card.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">
+  // 공용 Card 컨테이너.
+  // 기존 코드의 `bg-surface rounded-card border border-default` 패턴 1군데화.
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    padded?: boolean;
+    interactive?: boolean;
+    onclick?: (e: MouseEvent) => void;
+    children?: Snippet;
+    class?: string;
+  }
+
+  let {
+    padded = true,
+    interactive = false,
+    onclick,
+    children,
+    class: className = '',
+    ...rest
+  }: Props = $props();
+
+  let baseClass = $derived(
+    [
+      'bg-surface border border-default rounded-card',
+      padded ? 'p-5' : '',
+      interactive
+        ? 'cursor-pointer hover:bg-surface-hover transition-colors focus-visible:ring-2 focus-visible:ring-accent-ring focus-visible:outline-none'
+        : '',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ')
+  );
+</script>
+
+{#if interactive}
+  <button type="button" class={baseClass} {onclick} {...rest}>
+    {@render children?.()}
+  </button>
+{:else}
+  <div class={baseClass} {...rest}>
+    {@render children?.()}
+  </div>
+{/if}

frontend/src/lib/components/ui/EmptyState.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+  // 빈 상태/추후 지원/검색 결과 없음 등에 사용.
+  // children은 액션 슬롯 (Button 등).
+  import type { Snippet } from 'svelte';
+  import type { Component } from 'svelte';
+
+  interface Props {
+    icon?: Component;
+    title: string;
+    description?: string;
+    children?: Snippet;
+    class?: string;
+  }
+
+  let { icon: Icon, title, description, children, class: className = '', ...rest }: Props = $props();
+</script>
+
+<div
+  class={'flex flex-col items-center justify-center text-center py-12 px-4 ' + className}
+  {...rest}
+>
+  {#if Icon}
+    <div class="text-faint mb-3">
+      <Icon size={40} strokeWidth={1.5} />
+    </div>
+  {/if}
+  <p class="text-sm font-medium text-text">{title}</p>
+  {#if description}
+    <p class="text-xs text-dim mt-1 max-w-sm">{description}</p>
+  {/if}
+  {#if children}
+    <div class="mt-4">
+      {@render children()}
+    </div>
+  {/if}
+</div>

frontend/src/lib/components/ui/IconButton.svelte

@@ -0,0 +1,100 @@
+<script lang="ts">
+  // 정사각형 아이콘 전용 버튼. nav/toolbar에서 사용.
+  // aria-label 필수 (스크린 리더 라벨링).
+  import { Loader2 } from 'lucide-svelte';
+  import type { Component } from 'svelte';
+
+  type Variant = 'primary' | 'secondary' | 'ghost' | 'danger';
+  type Size = 'sm' | 'md';
+
+  interface Props {
+    icon: Component;
+    'aria-label': string;
+    variant?: Variant;
+    size?: Size;
+    loading?: boolean;
+    disabled?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+    href?: string;
+    target?: string;
+    onclick?: (e: MouseEvent) => void;
+    class?: string;
+  }
+
+  let {
+    icon: Icon,
+    'aria-label': ariaLabel,
+    variant = 'ghost',
+    size = 'md',
+    loading = false,
+    disabled = false,
+    type = 'button',
+    href,
+    target,
+    onclick,
+    class: className = '',
+    ...rest
+  }: Props = $props();
+
+  const variantClass: Record<Variant, string> = {
+    primary: 'bg-accent text-white hover:bg-accent-hover',
+    secondary: 'bg-surface border border-default text-text hover:bg-surface-hover',
+    ghost: 'text-dim hover:bg-surface hover:text-text',
+    danger: 'text-error hover:bg-error/10',
+  };
+
+  const sizeClass: Record<Size, string> = {
+    sm: 'h-7 w-7',
+    md: 'h-9 w-9',
+  };
+
+  let iconSize = $derived(size === 'sm' ? 14 : 16);
+
+  let baseClass = $derived(
+    [
+      'inline-flex items-center justify-center rounded-md',
+      'transition-colors',
+      'focus-visible:ring-2 focus-visible:ring-accent-ring focus-visible:outline-none',
+      'disabled:opacity-50 disabled:cursor-not-allowed',
+      sizeClass[size],
+      variantClass[variant],
+      className,
+    ].join(' ')
+  );
+
+  let isDisabled = $derived(disabled || loading);
+</script>
+
+{#if href}
+  <a
+    {href}
+    {target}
+    class={baseClass}
+    aria-label={ariaLabel}
+    aria-disabled={isDisabled || undefined}
+    tabindex={isDisabled ? -1 : undefined}
+    {...rest}
+  >
+    {#if loading}
+      <Loader2 size={iconSize} class="animate-spin" />
+    {:else}
+      <Icon size={iconSize} />
+    {/if}
+  </a>
+{:else}
+  <button
+    {type}
+    class={baseClass}
+    disabled={isDisabled}
+    aria-label={ariaLabel}
+    aria-busy={loading || undefined}
+    {onclick}
+    {...rest}
+  >
+    {#if loading}
+      <Loader2 size={iconSize} class="animate-spin" />
+    {:else}
+      <Icon size={iconSize} />
+    {/if}
+  </button>
+{/if}

frontend/src/lib/components/ui/Skeleton.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+  // 로딩 placeholder. 기존의 ad-hoc `animate-pulse h-N` div 패턴 통합.
+  type Rounded = 'sm' | 'md' | 'lg' | 'card' | 'full';
+
+  interface Props {
+    /** Tailwind width 클래스 (예: 'w-full', 'w-32') 또는 임의값 */
+    w?: string;
+    /** Tailwind height 클래스 (예: 'h-4', 'h-28') */
+    h?: string;
+    rounded?: Rounded;
+    class?: string;
+  }
+
+  let { w = 'w-full', h = 'h-4', rounded = 'md', class: className = '', ...rest }: Props = $props();
+
+  const roundedClass: Record<Rounded, string> = {
+    sm: 'rounded-sm',
+    md: 'rounded-md',
+    lg: 'rounded-lg',
+    card: 'rounded-card',
+    full: 'rounded-full',
+  };
+
+  let baseClass = $derived(
+    ['animate-pulse bg-surface', w, h, roundedClass[rounded], className].join(' ')
+  );
+</script>
+
+<div class={baseClass} {...rest}></div>

frontend/src/lib/utils/mergeDoc.ts

@@ -0,0 +1,35 @@
+// PATCH 응답 또는 (향후 도입 시) SSE 푸시로 들어온 doc을 로컬 cache의 doc과
+// 합칠 때 사용. updated_at 비교로 stale 갱신을 무시 → optimistic update가
+// 더 fresh한 데이터 위에 덮어쓰는 race를 차단. plan 5대 원칙 #6.
+//
+// 더 강력한 보호는 backend ETag/If-Match 도입이 필요(plan 부록 #8).
+// 이 헬퍼는 그 사이의 가장 흔한 race(stale PATCH가 fresh push 위에 덮어쓰기)를 막는다.
+//
+// 사용 예:
+//   documents = mergeDoc(documents, response);  // PATCH 응답
+//   documents = dropDoc(documents, id);          // 삭제 / Inbox 승인 후 제거
+
+export interface DocLike {
+  id: number;
+  updated_at: string;
+}
+
+export function mergeDoc<T extends DocLike>(list: T[], incoming: T): T[] {
+  const idx = list.findIndex((d) => d.id === incoming.id);
+  if (idx === -1) {
+    // 새 doc — 맨 앞에 삽입
+    return [incoming, ...list];
+  }
+  const current = list[idx];
+  if (new Date(incoming.updated_at) < new Date(current.updated_at)) {
+    // stale — 무시
+    return list;
+  }
+  const next = [...list];
+  next[idx] = incoming;
+  return next;
+}
+
+export function dropDoc<T extends { id: number }>(list: T[], id: number): T[] {
+  return list.filter((d) => d.id !== id);
+}

frontend/src/lib/utils/pLimit.ts

@@ -0,0 +1,33 @@
+// 동시 실행 N개로 제한하는 작은 헬퍼 (외부 의존성 추가 없음).
+// 일괄 PATCH/DELETE 같은 batch 작업에서 GPU 서버 / API / SSE에 부하 폭탄을
+// 던지지 않도록 사용. plan 5대 원칙 #4.
+//
+// 사용 예:
+//   const limit = pLimit(5);
+//   const results = await Promise.allSettled(
+//     ids.map((id) => limit(() => api(`/documents/${id}`, { method: 'PATCH', body })))
+//   );
+
+export function pLimit(concurrency: number) {
+  let active = 0;
+  const queue: Array<() => void> = [];
+
+  const next = () => {
+    active--;
+    if (queue.length > 0) {
+      queue.shift()!();
+    }
+  };
+
+  return async function run<T>(fn: () => Promise<T>): Promise<T> {
+    if (active >= concurrency) {
+      await new Promise<void>((resolve) => queue.push(resolve));
+    }
+    active++;
+    try {
+      return await fn();
+    } finally {
+      next();
+    }
+  };
+}