문서 페이지

사용 가능Product composition

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

문서 언어

긴 문서샘플 코드 줄바꿈

Example guide / 17 October 2026

Before you begin

Check the service name and environment. This example makes no service requests and creates no resources.

Confirm the service name and identifier.
Choose an environment you can currently deploy to.
Identify who will review the deployment and its build logs.

Read-only example

Check product permissions and execution conditions before operational changes.

Preview configuration

Copy the configuration or enable wrapping. Long identifiers scroll horizontally inside the code region.

const preview = {
  environment: 'sample-environment',
  mode: 'read-only',
  identifier:
    'platform-api-abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789',
}

Next steps

Continue with the form workflow for input and error handling, or review the accessibility foundation.

사용법

PageHeader, Prose, CodeBlock, InlineMessage, 네이티브 목차 링크로 문서를 만드세요.
본문은 명시적 읽기 폭을 유지합니다. 보조 목차는 넓은 화면에서 본문 옆에, 좁은 화면에서는 본문 앞에 놓입니다.
각 제목의 안정적인 ID 를 목차 href 에 맞추세요. 공유 문서 스크롤 위치로 현재 항목을 표시하세요.
언어를 바꿔도 섹션 ID 는 유지되고 article.lang, 공지, 복사 메시지가 바뀝니다.

문서 전체와 각 섹션에 카드를 중첩하지 마세요.
읽기 폭 제한을 일반 UI 설명 텍스트에 적용하지 마세요. 문서 본문의 Prose 에만 적용하세요.
가로 코드 넘침이 페이지 전체를 스크롤하게 하지 마세요. 공유 ScrollArea 에 두세요.
공지 의미를 색만으로 전달하지 마세요.
예시의 날짜와 설정을 실제 데이터로 취급하지 마세요. 고정된 로컬 콘텐츠이며, 실제 문서의 번역 상태, 서버 문서 로딩, 권한, URL 로케일, 버전 전환은 제품이 소유합니다.

구성

Language/length/wrap controls → desktop body + contents rail / mobile contents then body → article(lang) → PageHeader + date → Prose(sections, headings, lists, inline message, CodeBlock, related native links)

키보드와 접근성

목차 링크는 표준 a href=#id 링크입니다. 대상 제목은 tabIndex=-1 로 포커스를 받을 수 있습니다.
목차 스크롤 추적은 포커스를 이동시키지 않습니다. 언어나 줄 바꿈을 바꿔도 사용 중인 컨트롤에 포커스가 유지됩니다.
가로 코드 영역은 공유 ScrollArea 에서 키보드와 포인터로 스크롤됩니다.
목차는 Collapsible 의 버튼과 aria-expanded 상태로 접힙니다.
제목은 페이지 h1 → 미리보기 h2 → 문서 제목 h3 → 본문 섹션 h4 순서입니다. CodeBlock 은 복사 성공이나 실패를 알립니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { PageHeader, Prose, CodeBlock, InlineMessage } from '@surflane/ui'

<nav aria-label='In this guide'>
  <a href='#guide-setup'>Setup</a>
</nav>
<article lang='en' aria-label='Getting started'>
  <PageHeader level={3} variant='display' title='Getting started' />
  <Prose>
    <section aria-labelledby='guide-setup'>
      <h4 id='guide-setup' tabIndex={-1}>
        Setup
      </h4>
      <p>Confirm the target before continuing.</p>
      <InlineMessage.Root tone='neutral'>
        <InlineMessage.Content>Read-only example.</InlineMessage.Content>
      </InlineMessage.Root>
      <CodeBlock code={sample} language='typescript' label='Configuration' />
    </section>
  </Prose>
</article>

// Keep heading IDs stable across translations and direct fragment loads.
// Use the actual scroll viewport for current-section tracking; never focus on scroll.
// Translate content, lang, control labels and announcements together in the product.

주요 API

문서 페이지 — 공통 래퍼 props
Prop	설명	기본값
`Prose`	문서 콘텐츠의 명시적 읽기 폭, 타이포그래피, 줄 바꿈	--surf-layout-reading
`Heading IDs / TOC href`	번역 전체에서 공유하는 안정적인 시맨틱 섹션 ID	caller-owned
`Article.lang`	현지화된 문서 하위 트리의 언어	en / ko in preview
`CodeBlock.wrap`	가로 코드 탐색 또는 긴 줄 바꿈	false
`TOC state`	Collapsible 공개 상태와 현재 섹션의 aria-current=location	open / first section
`Preview content`	현지화된 제목/본문/메시지; 고정 샘플 날짜; 선택적 긴 문서	local only

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.