refactor(home): streamline archive browsing

Author: 박은우

blog/ui/components/CategoryFilter.test.tsx

@@ -79,28 +79,30 @@ describe('CategoryFilter', () => {
     expect(onCategoryChange).toHaveBeenCalledWith('Life');
   });
 
-  it('renders active style classes', () => {
+  it('renders the active category as an underlined text control', () => {
     render(
       <CategoryFilter
         {...baseProps}
         activeCategory="Life"
         onCategoryChange={vi.fn()}
+        variant="links"
       />
     );
 
     const lifeButton = screen
       .getAllByRole('button')
-      .find((button) => button.textContent === 'Life2');
+      .find((button) => button.textContent === 'Life(2)');
 
     expect(lifeButton).toBeDefined();
 
     if (!lifeButton) {
       throw new Error('Life category button not found');
     }
 
-    expect(lifeButton).toHaveClass('bg-[var(--color-toss-blue)]');
-    expect(lifeButton).toHaveClass('rounded-[var(--radius-selection)]');
-    expect(lifeButton).not.toHaveClass('shadow-sm');
-    expect(lifeButton).not.toHaveClass('active:translate-y-px');
+    expect(lifeButton).toHaveClass('border-b-2');
+    expect(lifeButton).toHaveClass('border-[var(--color-toss-blue)]');
+    expect(lifeButton).toHaveClass('text-[var(--color-toss-blue)]');
+    expect(lifeButton).not.toHaveClass('rounded-[var(--radius-selection)]');
+    expect(lifeButton).not.toHaveClass('bg-[var(--color-toss-blue)]');
   });
 });

blog/ui/components/CategoryFilter/CategoryFilter.tsx

@@ -3,6 +3,7 @@
 import { clsx } from 'clsx';
 
 type Category = 'All' | 'Tech' | 'Life';
+type CategoryFilterVariant = 'links' | 'pills';
 
 const CATEGORY_LABELS: Record<Category, string> = {
   All: 'All',
@@ -15,44 +16,70 @@ interface CategoryFilterProps {
   activeCategory: Category;
   onCategoryChange: (category: Category) => void;
   categoryCounts: Record<Category, number>;
+  variant?: CategoryFilterVariant;
 }
 
 export default function CategoryFilter({
   categories,
   activeCategory,
   onCategoryChange,
   categoryCounts,
+  variant = 'pills',
 }: CategoryFilterProps) {
+  const isLinkVariant = variant === 'links';
+
   return (
-    <div className="flex gap-2 flex-wrap">
-      {categories.map((category) => (
-        <button
-          key={category}
-          onClick={() => onCategoryChange(category)}
-          className={clsx(
-            'inline-flex min-h-11 items-center gap-2 rounded-[var(--radius-selection)] border px-4 py-2 text-sm transition-colors duration-[var(--duration-200)] ease-[var(--ease-default)]',
-            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-toss-blue)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-bg-primary)]',
-            activeCategory === category
-              ? 'border-[var(--color-toss-blue)] bg-[var(--color-toss-blue)] text-white'
-              : 'border-[var(--color-border)] bg-[var(--color-bg-primary)] text-[var(--color-grey-600)] hover:border-[var(--color-border-hover)] hover:bg-[var(--color-grey-50)]'
-          )}
-          aria-pressed={activeCategory === category}
-        >
-          <span className="font-medium">{CATEGORY_LABELS[category]}</span>
-          <span
+    <nav aria-label="글 분류">
+      <div
+        className={clsx(
+          'flex flex-wrap items-center',
+          isLinkVariant ? 'gap-x-5 gap-y-1' : 'gap-2'
+        )}
+      >
+        {categories.map((category) => (
+          <button
+            key={category}
+            onClick={() => onCategoryChange(category)}
             className={clsx(
-              'rounded-[var(--radius-selection)] px-1.5 py-0.5 text-[10px] font-semibold',
-              activeCategory === category
-                ? 'bg-white/20 text-white'
-                : 'bg-[var(--color-grey-100)] text-[var(--color-text-tertiary)]'
+              'inline-flex min-h-11 items-center text-sm transition-colors duration-[var(--duration-200)] ease-[var(--ease-default)]',
+              isLinkVariant
+                ? 'border-b-2 px-0 py-2 font-medium'
+                : 'gap-2 rounded-[var(--radius-selection)] border px-4 py-2',
+              'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-toss-blue)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-bg-primary)]',
+              isLinkVariant
+                ? activeCategory === category
+                  ? 'border-[var(--color-toss-blue)] text-[var(--color-toss-blue)]'
+                  : 'border-transparent text-[var(--color-text-secondary)] hover:border-[var(--color-grey-300)] hover:text-[var(--color-text-primary)]'
+                : activeCategory === category
+                  ? 'border-[var(--color-toss-blue)] bg-[var(--color-toss-blue)] text-[var(--color-accent-foreground)]'
+                  : 'border-[var(--color-border)] bg-[var(--color-bg-primary)] text-[var(--color-grey-600)] hover:border-[var(--color-border-hover)] hover:bg-[var(--color-grey-50)]'
             )}
+            aria-pressed={activeCategory === category}
           >
-            {categoryCounts[category]}
-          </span>
-        </button>
-      ))}
-    </div>
+            <span className={clsx(!isLinkVariant && 'font-medium')}>
+              {CATEGORY_LABELS[category]}
+            </span>
+            {isLinkVariant ? (
+              <span className="ml-1 text-meta font-normal text-[var(--color-text-tertiary)]">
+                ({categoryCounts[category]})
+              </span>
+            ) : (
+              <span
+                className={clsx(
+                  'rounded-[var(--radius-selection)] px-1.5 py-0.5 text-[10px] font-semibold',
+                  activeCategory === category
+                    ? 'bg-[var(--color-grey-700)] text-[var(--color-accent-foreground)]'
+                    : 'bg-[var(--color-grey-100)] text-[var(--color-text-tertiary)]'
+                )}
+              >
+                {categoryCounts[category]}
+              </span>
+            )}
+          </button>
+        ))}
+      </div>
+    </nav>
   );
 }
 
-export type { CategoryFilterProps, Category };
+export type { CategoryFilterProps, Category, CategoryFilterVariant };

blog/ui/components/PostCard.test.tsx

@@ -65,6 +65,37 @@ describe('PostCard', () => {
     expect(screen.queryByRole('presentation')).not.toBeInTheDocument();
   });
 
+  it('renders date and title only in archive variant', () => {
+    const detailedPost: FeedData = {
+      ...basePost,
+      readingTime: 12,
+      series: {
+        id: 'redis',
+        title: 'Redis 완전정복',
+        order: 1,
+      },
+      tags: ['redis', 'cache'],
+    };
+
+    render(<PostCard post={detailedPost} variant="archive" />);
+
+    const link = screen.getByRole('link', {
+      name: /2026\.02\.10 테스트 글/,
+    });
+
+    expect(link).toHaveAttribute('href', '/blog/test-post');
+    expect(link).toHaveClass('min-h-11');
+    expect(link).not.toHaveClass('border');
+    expect(screen.getByText('2026.02.10')).toHaveAttribute(
+      'dateTime',
+      '2026-02-10T00:00:00.000Z'
+    );
+    expect(screen.queryByText('Tech')).not.toBeInTheDocument();
+    expect(screen.queryByText('테스트 설명')).not.toBeInTheDocument();
+    expect(screen.queryByText('#redis')).not.toBeInTheDocument();
+    expect(screen.queryByText('약 12분')).not.toBeInTheDocument();
+  });
+
   it('uses a static content surface for the list variant', () => {
     render(<PostCard post={basePost} variant="list" />);
 

blog/ui/components/PostCard/PostCard.tsx

@@ -5,7 +5,17 @@ import { CategoryIcon } from '@/ui/icons/AppSectionIcon';
 
 interface PostCardProps {
   post: FeedData;
-  variant?: 'default' | 'list';
+  variant?: 'archive' | 'default' | 'list';
+}
+
+function formatArchiveDate(date: string): string {
+  const matchedDate = /^(\d{4})-(\d{2})-(\d{2})/.exec(date);
+
+  if (!matchedDate) {
+    return date;
+  }
+
+  return `${matchedDate[1]}.${matchedDate[2]}.${matchedDate[3]}`;
 }
 
 export default function PostCard({ post, variant = 'default' }: PostCardProps) {
@@ -17,6 +27,29 @@ export default function PostCard({ post, variant = 'default' }: PostCardProps) {
   const readingTimeLabel = post.readingTime ? `약 ${post.readingTime}분` : null;
   const visibleTags = post.tags?.slice(0, 3) ?? [];
 
+  if (variant === 'archive') {
+    return (
+      <Link
+        href={`/blog/${post.slug}`}
+        className={clsx(
+          'group flex min-h-11 items-baseline gap-3 rounded-[var(--radius-action)] py-2',
+          'transition-colors duration-[var(--duration-200)] ease-[var(--ease-default)]',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-toss-blue)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--color-bg-primary)]'
+        )}
+      >
+        <time
+          dateTime={post.date}
+          className="shrink-0 text-meta font-medium tabular-nums text-[var(--color-text-tertiary)]"
+        >
+          {formatArchiveDate(post.date)}
+        </time>
+        <h3 className="min-w-0 text-base font-semibold leading-snug tracking-tight text-[var(--color-text-primary)] transition-colors duration-[var(--duration-200)] ease-[var(--ease-default)] group-hover:text-[var(--color-toss-blue)] group-focus-visible:text-[var(--color-toss-blue)]">
+          {post.title}
+        </h3>
+      </Link>
+    );
+  }
+
   if (variant === 'list') {
     return (
       <Link

blog/ui/components/PostList.test.tsx

@@ -34,7 +34,9 @@ describe('PostList', () => {
   it('shows empty state when no posts exist', () => {
     render(<PostList posts={[]} />);
 
-    expect(screen.getByRole('status')).toHaveTextContent('아직 작성된 글이 없어요');
+    expect(screen.getByRole('status')).toHaveTextContent(
+      '아직 작성된 글이 없어요'
+    );
   });
 
   it('renders a list of posts', () => {
@@ -59,4 +61,14 @@ describe('PostList', () => {
     expect(links[0]).toHaveAttribute('href', '/blog/one');
     expect(screen.getByText('첫 번째 글')).toBeInTheDocument();
   });
+
+  it('renders archive layout when requested', () => {
+    render(<PostList posts={samplePosts} layout="archive" />);
+
+    expect(screen.getByRole('list')).toBeInTheDocument();
+    expect(screen.getAllByRole('listitem')).toHaveLength(2);
+    expect(
+      screen.getByRole('link', { name: /2026\.02\.01 첫 번째 글/ })
+    ).toHaveAttribute('href', '/blog/one');
+  });
 });

blog/ui/components/PostList/PostList.tsx

@@ -12,7 +12,7 @@ import {
 
 interface PostListProps {
   posts: FeedData[];
-  layout?: 'grid' | 'list';
+  layout?: 'archive' | 'grid' | 'list';
 }
 
 function getContainerVariants(
@@ -49,6 +49,7 @@ function getItemVariants(effectiveMotionMode: EffectiveMotionMode): Variants {
 }
 
 const layoutClassNames = {
+  archive: 'space-y-1',
   grid: 'grid gap-6 md:grid-cols-2',
   list: 'space-y-4',
 } satisfies Record<NonNullable<PostListProps['layout']>, string>;
@@ -68,12 +69,25 @@ export default function PostList({ posts, layout = 'grid' }: PostListProps) {
 
   if (effectiveMotionMode === 'off') {
     return (
-      <div className={layoutClassNames[layout]}>
+      <div
+        className={layoutClassNames[layout]}
+        role={layout === 'archive' ? 'list' : undefined}
+      >
         {posts.map((post) => (
-          <div key={post.slug} className={layout === 'grid' ? 'h-full' : ''}>
+          <div
+            key={post.slug}
+            className={layout === 'grid' ? 'h-full' : ''}
+            role={layout === 'archive' ? 'listitem' : undefined}
+          >
             <PostCard
               post={post}
-              variant={layout === 'list' ? 'list' : 'default'}
+              variant={
+                layout === 'archive'
+                  ? 'archive'
+                  : layout === 'list'
+                    ? 'list'
+                    : 'default'
+              }
             />
           </div>
         ))}
@@ -84,17 +98,25 @@ export default function PostList({ posts, layout = 'grid' }: PostListProps) {
   const containerVariants = getContainerVariants(effectiveMotionMode);
   const itemVariants = getItemVariants(effectiveMotionMode);
 
-  if (layout === 'list') {
+  if (layout === 'list' || layout === 'archive') {
     return (
       <motion.div
         variants={containerVariants}
         initial="hidden"
         animate="visible"
-        className={layoutClassNames.list}
+        className={layoutClassNames[layout]}
+        role={layout === 'archive' ? 'list' : undefined}
       >
         {posts.map((post) => (
-          <motion.div key={post.slug} variants={itemVariants}>
-            <PostCard post={post} variant="list" />
+          <motion.div
+            key={post.slug}
+            variants={itemVariants}
+            role={layout === 'archive' ? 'listitem' : undefined}
+          >
+            <PostCard
+              post={post}
+              variant={layout === 'archive' ? 'archive' : 'list'}
+            />
           </motion.div>
         ))}
       </motion.div>

docs/adr/0029-use-link-like-controls-for-home-category-filtering.md

@@ -0,0 +1,47 @@
+# 0029. 홈 카테고리 필터를 링크형 상태 컨트롤로 표현한다
+
+Date: 2026-07-19
+Status: Accepted
+
+## 배경
+
+홈은 최신 글을 훑는 아카이브다. 기존 카테고리 필터는 테두리 컨테이너 안에
+채워진 pill 버튼과 카운트 배지로 배치되어, 글 탐색보다 독립된 설정 화면처럼
+보였다. 홈 피드는 선택해야 할 복잡한 옵션이 아니라 글의 범위를 빠르게
+좁히는 짧은 상태 전환만 제공한다.
+
+필터 상태는 현재 클라이언트에서 즉시 전환되며 URL이나 route를 변경하지
+않는다. 시각적으로 링크처럼 보여도 실제 anchor를 사용하면 브라우저 탐색
+의미와 동작이 맞지 않는다.
+
+## 결정
+
+- 홈 카테고리 필터는 별도 테두리 컨테이너 없이 제목 아래에 직접 배치한다.
+- 각 항목은 `button`의 semantic을 유지하되, 텍스트 링크처럼 보이게 한다.
+- 활성 항목은 Toss blue와 하단선으로만 구분하고, 비활성 항목은 중립 텍스트와
+  hover 하단선으로 처리한다.
+- 카운트는 배지 대신 항목 이름 뒤 괄호 표기로 표시한다.
+- `aria-pressed`와 keyboard focus ring을 유지해 현재 선택 상태와 조작 가능성을
+  명시한다.
+
+## 결과
+
+- 아카이브의 시각적 계층이 제목과 글 목록에 집중된다.
+- 필터는 상태 전환이라는 실제 동작에 맞는 semantic을 유지한다.
+- 이후 URL 기반 카테고리 archive를 도입할 때에는 이 컨트롤을 anchor와 route
+  상태로 별도 전환해야 한다.
+
+## 검토한 대안
+
+- 채워진 pill 버튼과 독립 컨테이너를 유지한다: 선택 상태는 강하지만, 홈
+  아카이브에는 과한 표면과 시각적 무게를 만든다.
+- 실제 anchor 링크로 바꾼다: 링크 모양과 의미는 일치하지만 현재의 in-place
+  filtering 및 URL 유지 동작과는 맞지 않는다.
+- 카운트 배지를 유지한다: 수치 구분은 쉽지만, 작은 인터페이스 표면을 더해
+  링크형 톤을 흐린다.
+
+## Related History
+
+- [ADR 0018](0018-use-semantic-surface-tokens-for-content-discovery.md): 콘텐츠
+  탐색 화면의 surface 선택 원칙
+- [ADR 0024](0024-use-latest-only-home-feed.md): 홈의 최신순 단일 피드 결정