Steps

Steps.Root는 단계의 순서와 각 단계가 어디까지 왔는지를 보여 줍니다. 작업 중인 에이전트의 계획, 체크리스트, 여러 단계로 된 폼이 그 예입니다. 각 Steps.Item은 status로 done, current, pending, error 중 하나를 받습니다. 단계와 그 순서는 직접 가진 데이터이고, Todae는 상태마다 표시를 그리고 표시를 잇는 선을 그립니다.

<Steps.Root aria-label="Plan">
  {plan.map((step) => (
    <Steps.Item key={step.id} status={step.status}>
      {step.title}
    </Steps.Item>
  ))}
</Steps.Root>

파트

• Steps.Root는 role="list"가 붙은 ol이므로, Safari에서도 목록 표시 없이 목록으로 남습니다.
• Steps.Item은 표시와 그 뒤의 내용으로 된 li입니다. status가 data-status와 표시를 정합니다. done 단계는 채운 원 위에 check 글리프를 보여 줍니다. current 단계는 aria-current="step"을 받습니다. pending 단계는 빈 원을, error가 있는 단계는 critical 색으로 error 글리프를 보여 줍니다. 기본값은 pending입니다.

표시와 그 색은 steps.marker.* 토큰에서, progress 변형의 현재 단계 표시는 steps.marker.progress.*에서, 텍스트 색은 steps.fg.*에서, 선은 steps.line.*에서, 단계 사이 간격은 steps.gap에서 옵니다.

변형

Steps.Root의 variant는 단계를 어떻게 그릴지 정합니다. 기본값 plan은 에이전트의 계획처럼 실행되는 작업입니다. 현재 단계는 Loader 스피너를 보여 주고, 끝난 단계는 텍스트에 취소선을 긋습니다. progress는 Wizard의 단계처럼 사람이 폼의 어디까지 왔는지입니다. 현재 단계는 점이 든 멈춘 고리를 보여 주고, 끝난 단계는 텍스트를 그대로 둡니다. 상태, 상태 단어, aria-current는 둘 다 같습니다.

<Steps.Root variant="progress" aria-label="Sign-up steps">
  <Steps.Item status="done">Account</Steps.Item>
  <Steps.Item status="current">Workspace</Steps.Item>
  <Steps.Item>Review</Steps.Item>
</Steps.Root>

상태 단어

표시는 스크린 리더에서 숨겨집니다. 대신 각 단계는 화면에는 보이지 않는 상태 단어로 시작하므로, 스크린 리더는 "Done: Read the failing test"처럼 읽습니다. 이 단어는 StringsProvider의 stepDone, stepCurrent, stepPending, stepError 문자열에서 오며, 영어로는 "Done", "In progress", "Not started", "Failed"입니다. 직접 정한 단어를 쓰려면 항목에 statusLabel을 넘기세요. done 단계에 "Skipped"를 쓰는 식입니다.

접근성을 지키는 조합

Todae가 맡는 것: 순서 있는 목록, 각 단계 앞에서 읽히는 상태 단어, 현재 단계의 aria-current="step", 그리고 접근 가능한 이름에서 빠지는 표시를 맡습니다.

직접 제공할 것: 페이지에 목록이 둘 이상이면 aria-label이나 aria-labelledby로 목록의 이름을 붙이세요. 단계가 끝나거나 실패했을 때 목록으로 이동하지 않아도 들려야 한다면 useAnnouncer 등으로 알리세요. 기본 단어가 맞지 않으면 알맞은 상태 단어를 주세요.

주의할 점: 실패를 색으로만 보여 주지 마세요. 무엇이 잘못됐는지 단계의 텍스트로도 말하세요. 긴 단계의 세부 내용을 항목에 넣으면 plan 변형에서 done 단계의 취소선이 그 전부를 가로지릅니다.

언제 쓰나요

쓸 때: 단계가 차례로 진행되고 각 단계에 상태가 있는 계획이나 체크리스트. 여러 단계로 된 폼에서 사람이 어디까지 왔는지는 variant="progress"로 보여 줍니다.

쓰지 않을 때: 진행 중인 작업 하나 → Loader 또는 Progress. 페이지 경로 → Breadcrumbs.

Props