# Patterns

Composition and responsive rules for LafLabs Web Design 2026.10.3.

## Collection row (`collection-row`)

A full-width row separated by space and one-pixel rules. / 여백과 1px 선으로 반복 항목을 나누는 전체 폭 행입니다.

- Keep rules and spacing between items instead of wrapping each item in a card. / 카드로 감싸지 않고 항목 사이의 선과 간격을 유지합니다.
- Align name, description, and status or action to shared columns. / 이름, 설명, 상태나 동작의 열을 같은 기준선에 맞춥니다.
- Do not animate padding on hover. / hover에서 padding을 움직이지 않습니다.
- Related components: `button`, `separator`, `status-label`, `text-link`

## Contrast band (`contrast-band`)

A restrained Ink surface divides the flow of the light public theme. / 밝은 공개 화면 안에서 Ink 면을 제한적으로 사용해 흐름을 나눕니다.

- Use a dark band only for a clear content shift, such as the company statement. / 어두운 구간은 회사 소개처럼 분명한 내용 전환에만 씁니다.
- Use white for primary text and Blue Light for short highlights. / 기본 텍스트는 흰색, 짧은 강조는 Blue Light를 사용합니다.
- Do not restore legacy Page Navy as the default surface for new public pages. / legacy인 Page Navy를 새 공개 화면의 기본 배경으로 되살리지 않습니다.
- Related components: `logo`, `button-link`, `text-link`

## Document surface (`document-surface`)

A shared shell and reading rhythm connect document indices and detail pages. / 목록과 읽기 화면은 같은 shell과 본문 리듬을 유지합니다.

- Keep body measure, heading levels, dates, and metadata placement consistent. / 본문 폭, 제목 단계, 날짜와 메타데이터 위치를 문서마다 바꾸지 않습니다.
- Use Code Block for multiline code and distinguish it from inline identifiers. / 코드는 Code Block으로 표시하고 inline 식별자와 구분합니다.
- Use direct links between document indices and reading surfaces. / 목록과 본문 사이의 이동은 직접적인 링크로 제공합니다.
- Related components: `field`, `code-block`, `panel`, `separator`, `text-link`

## Editorial heading (`editorial-heading`)

A short heading and only the necessary copy establish a section's purpose. / 짧은 제목과 필요한 설명만으로 구간의 목적을 밝힙니다.

- Do not stack an eyebrow, number, and subtitle by default. / 보조 라벨, 번호, 부제를 습관처럼 겹치지 않습니다.
- Constrain heading and description measures separately to clarify hierarchy. / 제목과 설명의 폭을 따로 제한해 위계를 분명히 합니다.
- Add a Text Link only when the section needs an onward destination. / 다음 목적지가 필요할 때만 Text Link를 붙입니다.
- Related components: `text-link`

## Responsive collapse (`responsive-collapse`)

Desktop relationships become a one-column reading order on small screens. / 넓은 화면의 관계를 작은 화면에서 한 열의 읽기 순서로 바꿉니다.

- Stack complex grids at 1080px and simplify navigation and actions at 720px. / 1080px에서 복잡한 grid를 쌓고 720px에서 탐색과 동작을 정리합니다.
- Reorder the same content for reading instead of shrinking a desktop diagram. / 데스크톱 도식을 축소하지 말고 같은 내용을 읽기 순서로 다시 배치합니다.
- Keep a 44px target area on small screens. / 작은 화면의 동작 영역은 44px를 유지합니다.
- Related components: `button`, `button-group`, `field`, `segmented-control`

## Selected work (`selected-work`)

An editorial module pairing a real image with verified project copy. / 실제 이미지와 확인된 설명을 한 편집 모듈에 묶습니다.

- Use real images from public and never fabricate a product screen. / public에 있는 실제 이미지만 사용하며 가짜 화면은 만들지 않습니다.
- Show product status and destinations only when current data provides them. / 제품 상태와 목적지는 현재 데이터에 있을 때만 표시합니다.
- Provide previous and next actions as named, keyboard-operable buttons. / 이전과 다음 동작은 이름 있는 button으로 만들고 키보드 조작을 지원합니다.
- Related components: `button`, `segmented-control`, `text-link`

## Site chrome (`site-chrome`)

The existing Site Header and Footer frame every public surface. / 기존 Site Header와 Footer가 모든 공개 화면을 감쌉니다.

- Do not add a second fixed navbar inside a page. / 페이지 안에 두 번째 고정 내비게이션을 만들지 않습니다.
- Keep logo, locale, search, and document navigation in their established chrome positions. / 로고, 언어 선택, 검색, 문서 이동은 기존 공통 영역에 둡니다.
- Place page-local navigation inside the content shell. / 현재 페이지의 로컬 탐색은 콘텐츠 shell 안에 둡니다.
- Related components: `logo`, `segmented-control`, `button`, `text-link`

## System states (`system-states`)

Loading, empty, and error states share one visual and verbal grammar. / loading, empty, error 상태를 같은 화면 문법으로 설명합니다.

- Name the state and the next available action in short copy. / 상태와 다음 동작을 짧은 문장으로 알립니다.
- Provide a retry action for errors when recovery is available. / error에는 가능한 경우 retry 동작을 제공합니다.
- Do not fill empty states with invented example data. / empty 상태를 임의의 예시 데이터로 채우지 않습니다.
- Related components: `alert`, `button`, `empty-state`, `panel`, `skeleton`, `status-label`, `text-link`

# Recipes

Use a published Recipe before assembling a recurring documented task. Preserve the declared component semantics, state behavior, and task order instead of inventing a replacement abstraction.

## Collection state surface (`collection-state-surface`)

Explains loading, results, empty, and error states consistently in one collection surface. / 하나의 목록 영역에서 loading, 결과, empty, error 상태를 일관되게 설명합니다.

- Category: **system-state**
- Components: `panel`, `table`, `item`, `pagination`, `skeleton`, `empty-state`, `alert`, `status-label`, `button`
- Related Patterns: `collection-row`, `system-states`, `responsive-collapse`
- Use: Use when a table or list waits for asynchronous data and has multiple outcomes. / 표나 목록이 비동기 데이터를 기다리고 여러 결과 상태를 가질 때 사용합니다.
- Avoid: Do not use for immediate static content or one form-submission result. / 즉시 표시되는 정적 콘텐츠나 단일 폼 제출 결과에는 사용하지 않습니다.
- Accessibility: Name the state and next action in text without announcing loading or errors twice. / 상태 제목과 다음 동작을 텍스트로 제공하고 loading과 error를 중복 발표하지 않습니다.
- Anatomy:
  1. Collection name and scope / 컬렉션 이름과 범위
  2. Current state body / 현재 상태의 본문
  3. State-specific next action / 상태별 다음 동작
  4. Pagination when results exist / 결과가 있을 때의 페이지 이동
- States and inspection:
  - `loading` [fixture]: Reserve space with a Skeleton matching the final collection structure. / 최종 목록 구조와 같은 Skeleton으로 공간을 유지합니다.
  - `populated` [fixture]: Shows comparable columns, explicit status, and pagination. / 실제 비교 가능한 열과 상태, 페이지 이동을 표시합니다.
  - `empty` [fixture]: Explains why the collection is empty and the first available action without fake results. / 빈 이유와 가능한 첫 행동을 설명하고 가짜 결과를 만들지 않습니다.
  - `error` [fixture]: Keeps the error and recoverable retry action inside the collection context. / 오류와 복구 가능한 재시도 동작을 목록 맥락 안에 둡니다.
- Responsive behavior:
  - On small screens, keep essential comparisons and reflow the rest into Item rows. / 작은 화면에서는 비교에 필요한 열만 유지하고 나머지는 Item 행으로 재배치합니다.
  - Never hide the state title or retry action behind horizontal overflow. / 상태 제목과 재시도 동작은 가로 overflow 밖으로 숨기지 않습니다.
- Source paths: `components/design-system/recipes/collection-state-surface-demo.tsx`

### Usage shape

```tsx
import {
  Item,
  ItemActions,
  ItemContent,
  ItemTitle,
} from "@/components/ui/item"
import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
} from "@/components/ui/pagination"
import { Panel, PanelContent, PanelHeader, PanelTitle } from "@/components/ui/panel"
import { StatusLabel } from "@/components/ui/status-label"
import { Table, TableBody, TableCell, TableRow } from "@/components/ui/table"

<Panel aria-label="populated document collection">
  <PanelHeader>
    <PanelTitle>Documents</PanelTitle>
  </PanelHeader>
  <PanelContent>
    <Table>
      <TableBody>
        <TableRow>
          <TableCell>Operations policy</TableCell>
          <TableCell>
            <StatusLabel tone="success">Published</StatusLabel>
          </TableCell>
        </TableRow>
      </TableBody>
    </Table>
    <Item>
      <ItemContent>
        <ItemTitle>Operations policy</ItemTitle>
      </ItemContent>
      <ItemActions>
        <StatusLabel tone="success">Published</StatusLabel>
      </ItemActions>
    </Item>
    <Pagination aria-label="Document pages">
      <PaginationContent>
        <PaginationItem>
          <PaginationLink href="#" isCurrent>1</PaginationLink>
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  </PanelContent>
</Panel>
```

## Document publishing toolbar (`document-publishing-toolbar`)

Combines document status, saving, and publishing into one predictable workflow. / 문서 상태와 저장·발행 동작을 하나의 예측 가능한 작업 흐름으로 묶습니다.

- Category: **action**
- Components: `button-group`, `button`, `dropdown-menu`, `status-label`
- Related Patterns: `document-surface`, `responsive-collapse`
- Use: Use for document work with a clear order and priority, such as saving and publishing. / 초안 저장과 발행처럼 순서와 우선순위가 분명한 문서 작업에 사용합니다.
- Avoid: Do not use for unrelated actions or a form with one simple submit action. / 서로 관계없는 동작이나 한 개의 단순 제출 버튼에는 사용하지 않습니다.
- Accessibility: Expose status in text and preserve keyboard order across save, publish, and more options. / 상태는 텍스트로 표시하고 저장, 발행, 추가 옵션의 키보드 순서를 유지합니다.
- Anatomy:
  1. Current document status / 현재 문서 상태
  2. Secondary save action / 보조 저장 동작
  3. Primary publish action / 주요 발행 동작
  4. Additional publishing options / 추가 발행 옵션
- States and inspection:
  - `draft` [fixture]: Shows draft status with available save and publish actions. / 초안 상태와 사용할 수 있는 저장·발행 동작을 함께 보여줍니다.
  - `publish-options` [interactive]: Additional publishing options open without leaving the toolbar context. / 추가 발행 옵션은 현재 도구 모음의 맥락을 유지한 채 열립니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `publishing` [fixture]: Publishing prevents duplicate activation and communicates progress in text. / 발행 중에는 중복 실행을 막고 진행 상태를 텍스트로 알립니다.
- Responsive behavior:
  - On small screens, place status above a full-width action group. / 작은 화면에서는 상태를 동작 위에 두고 버튼 그룹을 전체 폭으로 배치합니다.
  - Keep save, publish, and more-options order at every viewport size. / 저장, 발행, 추가 옵션의 순서는 화면 크기와 관계없이 유지합니다.
- Source paths: `components/design-system/recipes/document-publishing-toolbar-demo.tsx`

### Usage shape

```tsx
import { Button } from "@/components/ui/button"
import { ButtonGroup, ButtonGroupSeparator } from "@/components/ui/button-group"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { StatusLabel } from "@/components/ui/status-label"

<div>
  <StatusLabel tone="neutral">Draft</StatusLabel>
  <DropdownMenu>
    <ButtonGroup label="Document publishing">
      <Button variant="secondary">Save draft</Button>
      <Button>Publish document</Button>
      <ButtonGroupSeparator />
      <DropdownMenuTrigger asChild>
        <Button aria-label="Open publishing options" size="icon">...</Button>
      </DropdownMenuTrigger>
    </ButtonGroup>
    <DropdownMenuContent align="end">
      <DropdownMenuItem>Schedule publication</DropdownMenuItem>
      <DropdownMenuItem>Copy preview link</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</div>
```

## Document settings form (`document-settings-form`)

Connects document metadata and publishing settings in one meaningful form structure. / 문서 메타데이터와 공개 설정을 하나의 의미 있는 폼 구조로 연결합니다.

- Category: **form**
- Components: `field`, `input`, `native-select`, `checkbox`, `switch`, `alert`
- Related Patterns: `document-surface`, `responsive-collapse`
- Use: Use when editing related fields and immediately applied settings as one task. / 여러 관련 필드와 즉시 적용 설정을 한 작업으로 편집할 때 사용합니다.
- Avoid: Do not group unrelated settings or use it as a read-only summary. / 서로 관계없는 설정을 한 Panel에 모으거나 읽기 전용 요약을 표시할 때는 사용하지 않습니다.
- Accessibility: Name the task with fieldset and legend, and connect all guidance and errors to their fields. / fieldset과 legend로 작업을 이름 붙이고 모든 안내와 오류를 해당 필드에 연결합니다.
- Anatomy:
  1. Settings group legend / 설정 그룹 legend
  2. Document identity fields / 문서 식별 정보
  3. Publishing and pinning settings / 공개와 고정 설정
  4. Save-state feedback / 저장 상태 피드백
- States and inspection:
  - `default` [fixture]: Editable default document settings. / 편집 가능한 기본 문서 설정입니다.
  - `invalid` [fixture]: Only the affected field shows an invalid state and specific guidance. / 문제가 있는 필드만 오류 상태와 구체적인 안내를 표시합니다.
  - `disabled` [fixture]: Clearly disables settings unavailable because of permission or document state. / 권한이나 문서 상태로 편집할 수 없는 설정을 명확히 비활성화합니다.
  - `saving` [fixture]: Saving prevents duplicate submission and communicates current progress. / 저장 중에는 중복 제출을 막고 현재 진행 상태를 알립니다.
- Responsive behavior:
  - On small screens, collapse horizontal fields into one label-then-input column. / 작은 화면에서는 가로 필드를 label 다음 입력 순서의 한 열로 바꿉니다.
  - Keep descriptions and errors immediately below their related input. / 설명과 오류는 관련 입력 바로 아래에 남깁니다.
- Source paths: `components/design-system/recipes/document-settings-form-demo.tsx`

### Usage shape

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import {
  Field,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { NativeSelect } from "@/components/ui/native-select"
import { Switch } from "@/components/ui/switch"

<FieldSet>
  <FieldLegend>Document settings</FieldLegend>
  <FieldGroup>
    <Field>
      <FieldLabel>Title</FieldLabel>
      <Input />
    </Field>
    <Field>
      <FieldLabel>Category</FieldLabel>
      <NativeSelect defaultValue="notice">
        <option value="notice">Notice</option>
        <option value="disclosure">Disclosure</option>
      </NativeSelect>
    </Field>
    <Checkbox label="Pin document" />
    <Switch label="Publish immediately" />
  </FieldGroup>
</FieldSet>
```

## Search and filter field (`search-filter-field`)

Combines a query and structured filters into one named discovery task. / 검색어 입력과 구조화된 필터를 하나의 이름 있는 탐색 작업으로 구성합니다.

- Category: **form**
- Components: `field`, `input-group`, `combobox`, `alert`, `button`
- Related Patterns: `collection-row`, `responsive-collapse`
- Use: Use to search a document or record collection and narrow it with a small filter set. / 문서나 레코드 목록을 검색하고 제한된 필터로 범위를 좁힐 때 사용합니다.
- Avoid: Do not use for a form field that selects one fixed value without search. / 검색 없이 하나의 고정 값을 고르는 폼 필드에는 사용하지 않습니다.
- Accessibility: Connect label, description, and error to the query while preserving popup keyboard navigation. / 검색 label, 설명, 오류를 입력과 연결하고 필터 popup의 키보드 탐색을 유지합니다.
- Anatomy:
  1. Search field label / 검색 필드 label
  2. Query input / 검색어 입력
  3. Filter selection / 필터 선택
  4. Clear action and field feedback / 지우기 동작과 필드 피드백
- States and inspection:
  - `default` [fixture]: The default discovery state with an empty query and filters. / 검색과 필터가 비어 있는 기본 탐색 상태입니다.
  - `filters-open` [interactive]: Open the filter popup directly to inspect search and keyboard movement. / 필터 popup을 직접 열어 검색과 키보드 이동을 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `empty` [fixture]: When no result matches, retain the query and explain the next action. / 일치하는 결과가 없을 때 검색 조건을 유지하고 다음 행동을 안내합니다.
  - `invalid` [fixture]: Explain an unsupported query through an error connected to the input. / 지원하지 않는 검색 값은 입력과 연결된 오류로 설명합니다.
- Responsive behavior:
  - On small screens, move filters below the query as a full-width row. / 작은 화면에서는 필터를 검색 입력 아래의 전체 폭 행으로 옮깁니다.
  - Keep the label and error associated with the same input after reflow. / label과 오류는 재배치 뒤에도 같은 입력을 설명합니다.
- Source paths: `components/design-system/recipes/search-filter-field-demo.tsx`

### Usage shape

```tsx
import { Alert, AlertAction } from "@/components/ui/alert"
import { Button } from "@/components/ui/button"
import { Combobox } from "@/components/ui/combobox"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { InputGroup, InputGroupInput } from "@/components/ui/input-group"

const statusOptions = [
  { value: "all", label: "All statuses" },
  { value: "draft", label: "Draft" },
  { value: "published", label: "Published" },
]

<div>
  <Field>
    <FieldLabel>Search documents</FieldLabel>
    <FieldDescription>Search titles and content.</FieldDescription>
    <InputGroup><InputGroupInput type="search" /></InputGroup>
  </Field>
  <Field>
    <FieldLabel>Filter by document status</FieldLabel>
    <Combobox
      defaultValue="all"
      emptyText="No matching status."
      options={statusOptions}
    />
  </Field>
  <Alert title="No documents match this search.">
    Clear the query or adjust the status filter.
      <AlertAction>
        <Button variant="secondary">Clear search</Button>
      </AlertAction>
    </Alert>
  </div>
```