# @tissue-ui/layout — Design System Catalog

> 기계가독 디자인 시스템 카탈로그. @tissue-ui/layout 은 매니페스트 기반 화면 아키타입 + React 프리미티브 라이브러리다. 이 문서는 LAYOUT_MANIFEST(schema 0.11.0, package 0.7.7)에서 자동 생성되며, 에이전트가 아키타입·슬롯·컴포넌트 props·상태를 그대로 소비하도록 만들어졌다. 사람이 보는 문서는 https://ui.tissue.works 참고.

## Install

.npmrc 에 스코프 레지스트리를 매핑한다:

    @tissue-ui:registry=https://forge.tissue.works/npm/
    //forge.tissue.works/npm/:_authToken=${TISSUE_NPM_TOKEN}

그다음 설치:

    npm install @tissue-ui/layout-core @tissue-ui/layout-react @tissue-ui/layout-themes

- `@tissue-ui/layout-core` — LAYOUT_MANIFEST + 조회 헬퍼(getArchetype/getElement/getSlot/isElementAllowed). framework-agnostic.
- `@tissue-ui/layout-react` — 아키타입 컴포넌트 + 프리미티브 (peer react>=17).
- `@tissue-ui/layout-themes` — CSS 변수 브리지(base.css) + 스킨(tissue.css/assetly.css/krds.css) + Tailwind preset.

## Theming

layout 은 CSS 변수 브리지 방식이다. 앱에서 base.css 를 먼저 import 하고 스킨 css 를 겹친 뒤, `--tissue-layout-*` 상위 변수만 덮어써 리스킨한다:

    import "@tissue-ui/layout-themes/base.css";
    import "@tissue-ui/layout-themes/tissue.css";

## Archetypes (6) — 화면 레이아웃

각 아키타입은 슬롯을 가지며, 슬롯의 `allows` 는 그 자리에 넣을 수 있는 element key 목록이다.

### list — List page  [ListPage · import from @tissue-ui/layout-react]
A collection screen: header with title/actions, an optional filter toolbar, a list body (grid or cards), and an optional pagination footer.
 slots:
  - header (required, multiple, layout=space-between): allows: tabs, button-primary, notice-bar
  - toolbar.left (optional, multiple, layout=row): allows: search, filter-dropdown, tabs
  - toolbar.right (optional, multiple, layout=row): allows: button-primary, filter-dropdown
  - body (required, single): allows: grid, card-grid, empty-state
  - footer (optional, single): allows: pagination

### detail — Detail page  [DetailPage · import from @tissue-ui/layout-react]
A single-record screen: header with title/status/actions, an optional meta (property) list, a main body of content cards, an optional aside for related panels, and an optional action footer.
 slots:
  - header (required, multiple, layout=space-between): allows: page-header, badge, button, tabs, breadcrumb
  - meta (optional, multiple, layout=row): allows: field, badge
  - body (required, multiple, layout=column): allows: card, field, empty-state
  - aside (optional, multiple, layout=column): allows: card, field, badge
  - footer (optional, multiple, layout=row): allows: button

### dashboard — Dashboard page  [DashboardPage · import from @tissue-ui/layout-react]
An overview screen: header, a metrics row of KPI tiles, a main body of summary/content cards, and an optional aside for a secondary panel.
 slots:
  - header (required, multiple, layout=space-between): allows: page-header, button, tabs
  - metrics (optional, multiple, layout=grid): allows: metric-card
  - body (required, multiple, layout=column): allows: card, metric-card, empty-state
  - aside (optional, multiple, layout=column): allows: card

### form — Form page  [FormPage · import from @tissue-ui/layout-react]
An edit screen: header with title, a body of labeled form fields (optionally grouped into cards), and a footer of submit/cancel actions.
 slots:
  - header (required, multiple, layout=space-between): allows: page-header, button
  - body (required, multiple, layout=column): allows: form-field, field, card, file-attachment, accordion
  - footer (optional, multiple, layout=row): allows: button

### centered — Centered page  [CenteredPage · import from @tissue-ui/layout-react]
A narrow centered column for auth/onboarding: optional brand/title header, a body (usually a form), and an optional footer of links.
 slots:
  - header (optional, multiple, layout=space-between): allows: page-header, badge
  - body (required, multiple, layout=column): allows: card, form-field, button
  - footer (optional, multiple, layout=row): allows: button

### split — Split page  [SplitPage · import from @tissue-ui/layout-react]
A master-detail screen: optional header, a sidebar list rail (master), and a body detail pane that reflects the selection.
 slots:
  - header (optional, multiple, layout=space-between): allows: page-header, button, tabs
  - sidebar (required, multiple, layout=column): allows: card, empty-state
  - body (required, multiple, layout=column): allows: card, field, empty-state

## Primitives (14) — @tissue-ui/layout-react

### button — Button  [primitive · stable · import from @tissue-ui/layout-react]
Action button. Variants cover primary CTA, secondary, ghost, and destructive.
 props:
  - variant: enum(primary|secondary|ghost|danger) — Visual emphasis / intent (default `secondary`).
  - size: enum(sm|md|lg) — Control height (default `md`).
  - loading: boolean — Show a spinner and make the button non-interactive.
 states: default, hover, focus, active, disabled, loading
 state attributes: data-disabled, data-loading

### badge — Badge  [primitive · stable · import from @tissue-ui/layout-react]
Small status / label pill, typically next to a title.
 props:
  - tone: enum(neutral|blue|green|amber|red|violet) — Semantic color (default `neutral`).
 states: default

### card — Card  [primitive · stable · import from @tissue-ui/layout-react]
Bordered surface that groups related content, with an optional title.
 props:
  - title: string — Optional card heading.
  - actions: node — Optional header-right actions.
 states: default

### field — Field  [primitive · stable · import from @tissue-ui/layout-react]
A labeled read-only value — one row of a property / metadata list.
 props:
  - label: string — Field name.
  - children: node — Field value.
 states: default

### metric-card — Metric card  [primitive · stable · import from @tissue-ui/layout-react]
A KPI tile: an uppercase label, a prominent value, and an optional hint — for dashboard stat rows.
 props:
  - label: string — Metric name (rendered uppercase).
  - value: string — The metric value (string or number).
  - hint: string — Optional secondary line under the value.
 states: default

### input — Text input  [primitive · stable · import from @tissue-ui/layout-react]
Single-line text/password/number input.
 props:
  - type: string — HTML input type (default `text`).
  - placeholder: string — Placeholder text.
  - disabled: boolean — Disable the control.
  - error: boolean — Mark the control invalid (aria-invalid + danger border).
 states: default, hover, focus, disabled, error
 state attributes: data-disabled, data-error

### select — Select  [primitive · stable · import from @tissue-ui/layout-react]
Dropdown select; children are <option> elements.
 props:
  - disabled: boolean — Disable the control.
  - error: boolean — Mark the control invalid (aria-invalid + danger border).
 states: default, hover, focus, disabled, error
 state attributes: data-disabled, data-error

### textarea — Textarea  [primitive · stable · import from @tissue-ui/layout-react]
Multi-line text input.
 props:
  - placeholder: string — Placeholder text.
  - rows: string — Visible rows.
  - error: boolean — Mark the control invalid (aria-invalid + danger border).
 states: default, hover, focus, disabled, error
 state attributes: data-disabled, data-error

### switch — Switch  [primitive · stable · import from @tissue-ui/layout-react]
An on/off toggle backed by a checkbox, with an optional inline label.
 props:
  - label: node — Optional text next to the toggle.
  - size: enum(sm|md) — Track size (default `md`).
  - disabled: boolean — Disable the control.
 states: default, hover, focus, active, disabled
 state attributes: data-state, data-disabled

### empty-state — Empty state  [primitive · stable · import from @tissue-ui/layout-react]
Placeholder shown when a collection or section has no rows.
 props:
  - title: string — Headline of the empty state.
  - description: string — Optional secondary line.
  - action: node — Optional CTA (e.g. a primary Button).
 states: default

### notice-bar — 공지 배너  [primitive · experimental · import from @tissue-ui/layout-react]
공지·알림·오류·성공 메시지를 전달하는 배너. tone에 따라 WCAG role="alert" 또는 role="status" 자동 분기.
 props:
  - tone: enum(info|warning|danger|success) — 의미 톤. danger→role="alert"(assertive), 나머지→role="status"(polite).
  - children: node — 배너 본문.
  - closeable: boolean — 닫기 버튼 표시.
  - onClose: node — 닫기 핸들러.
 states: default

### checkbox — 체크박스  [primitive · experimental · import from @tissue-ui/layout-react]
단일 체크박스. indeterminate(불확정) 상태 지원. KWCAG 2.1 준수.
 props:
  - label: string — 체크박스 레이블.
  - checked: boolean — 체크 상태.
  - onChange: node — 변경 핸들러.
  - indeterminate: boolean — 불확정(반선택) 상태.
  - disabled: boolean — 비활성화.
  - error: boolean — 오류 상태(danger 테두리).
 states: default, disabled, error
 state attributes: data-state, data-disabled, data-error

### date-picker — 날짜 선택기  [primitive · experimental · import from @tissue-ui/layout-react]
전자정부 표준 날짜 입력(YYYY.MM.DD). 네이티브 <input type="date"> 기반이라 의존성이 없다. KWCAG 준수.
 props:
  - value: string — 날짜 값 (YYYY-MM-DD).
  - onChange: node — 변경 핸들러. 값은 YYYY-MM-DD.
  - label: string — 레이블 (독립 사용 시).
  - error: string — 오류 메시지.
  - disabled: boolean — 비활성화.
 states: default, hover, focus, disabled, error
 state attributes: data-disabled, data-error

### time-picker — 시간 선택기  [primitive · experimental · import from @tissue-ui/layout-react]
시·분(12시간일 때 오전·오후) 셀렉트로 시간을 고른다. 값은 24시간 "HH:MM", format 으로 24h/12h 전환. 셀렉트 기반이라 접근성이 기본 확보된다.
 props:
  - value: string — 시간 값 ("HH:MM" 24시간).
  - onChange: node — 변경 핸들러. 값은 "HH:MM".
  - format: enum(24h|12h) — 표시 형식 (기본 24h).
  - minuteStep: string — 분 간격 (기본 5).
  - label: string — 레이블 (독립 사용 시).
  - error: string — 오류 메시지.
  - disabled: boolean — 비활성화.
 states: default, focus, disabled, error
 state attributes: data-disabled, data-error

## Composites (9) — @tissue-ui/layout-react

### page-header — Page header  [composite · stable · import from @tissue-ui/layout-react]
Screen title block: title, optional badges next to it, description, and right-aligned actions.
 props:
  - title: string — Screen title.
  - titleSuffix: node — Inline node after the title (usually a Badge).
  - description: string — Optional sub-title line.
  - actions: node — Right-aligned actions (usually Buttons).
 states: default

### form-field — Form field  [composite · stable · import from @tissue-ui/layout-react]
A labeled form control row: label, the control (input/select/textarea) as children, and an optional hint.
 props:
  - label: string — Field label.
  - hint: string — Helper text under the control.
  - required: boolean — Append a `*` marker after the label.
  - error: string — Validation error message; wires aria-invalid/aria-describedby on the control.
  - children: node — The control element.
 states: default, error
 state attributes: data-required, data-error

### modal — Modal  [composite · stable · import from @tissue-ui/layout-react]
Overlay dialog with a header (title/description + close) and a scrollable body. Client-only.
 props:
  - open: boolean — Whether the dialog is shown.
  - onClose: node — Close handler.
  - title: node — Dialog title.
  - description: string — Optional sub-title.
  - size: enum(sm|md|lg|fullscreen) — Width preset (default `md`).
  - children: node — Body content.
 states: default, loading
 state attributes: data-state, data-busy

### step-indicator — 단계 표시기  [composite · experimental · import from @tissue-ui/layout-react]
민원 신청·다단계 폼의 진행 단계 표시. 완료·현재·미완료 상태를 번호+레이블로 표현. KWCAG 2.1 준수.
 props:
  - steps: node — StepItem[] 배열: `{ key: string; label: string }`.
  - current: string — 현재 활성 단계의 key (1-based index 아닌 key 기반).
 states: default

### file-attachment — 파일 첨부  [composite · experimental · import from @tissue-ui/layout-react]
전자정부 표준 파일 첨부 컴포넌트. drag-drop + 버튼, 업로드 파일 목록, 확장자·용량 제한 표시. KWCAG 2.1 준수.
 props:
  - accept: string — 허용 파일 확장자 (예: `.pdf,.hwp`).
  - maxSize: string — 파일당 최대 크기 (예: `10MB`).
  - multiple: boolean — 다중 파일 선택 허용 (기본 `false`).
  - value: node — File[] 또는 `{ name: string; size: number }[]`.
  - onChange: node — 파일 목록 변경 핸들러.
  - disabled: boolean — 비활성화.
  - error: string — 오류 메시지.
 states: default, error, disabled
 state attributes: data-error, data-disabled

### data-table — 데이터 테이블  [composite · experimental · import from @tissue-ui/layout-react]
전자정부 게시판형 `<table>` 컴포넌트. 번호·정렬·체크박스 선택 지원. aria-sort, caption 포함. 고성능 대용량은 grid 엘리먼트를 사용.
 props:
  - columns: node — ColumnDef[] 배열: `{ key; label; sortable? }`.
  - rows: node — 행 데이터 배열.
  - selectable: boolean — 체크박스 다중 선택 활성화.
  - onSort: node — 정렬 핸들러 `(key, dir) => void`.
  - caption: string — 테이블 캡션(웹접근성 필수).
 states: default

### accordion — 아코디언  [composite · experimental · import from @tissue-ui/layout-react]
FAQ·공지·내용 펼치기. `<details>`/`<summary>` 기반, CSS 트랜지션, single/multiple 모드.
 props:
  - items: node — AccordionItem[] 배열: `{ key; title; children }`.
  - multiple: boolean — 동시에 여러 항목 열기 허용 (기본 `false`).
  - defaultOpen: string — 기본으로 열려있을 항목 key.
 states: default

### radio — 라디오 버튼  [composite · experimental · import from @tissue-ui/layout-react]
라디오 버튼 그룹. role="radiogroup", aria-labelledby 배선. KWCAG 2.1 준수.
 props:
  - name: string — input name 속성.
  - options: node — RadioOption[] 배열: `{ value; label; disabled? }`.
  - value: string — 선택된 값.
  - onChange: node — 변경 핸들러.
  - layout: enum(row|column) — 항목 배열 방향 (기본 `column`).
 states: default, disabled, error
 state attributes: data-disabled, data-error

### tooltip — 툴팁  [composite · experimental · import from @tissue-ui/layout-react]
hover·focus 트리거 툴팁. role="tooltip", aria-describedby 배선. 키보드 접근성 포함.
 props:
  - content: string — 툴팁 내용.
  - position: enum(top|bottom|left|right) — 표시 위치 (기본 `top`).
  - children: node — 툴팁을 트리거하는 요소.
  - delay: string — 표시 지연 ms (기본 200).
 states: default

## Abstract elements (8)

슬롯 allows 가 참조하는 개념적 요소. 실제 컴포넌트는 소비처가 구현하거나 다른 패키지(예: grid → @tissue-ui/grid-react)에서 온다.

- search — Search input: Free-text search box that filters the list body.
- filter-dropdown — Filter dropdown: Dropdown / select that narrows the list by a facet (status, type, …).
- button-primary — Primary button: Primary call-to-action, e.g. "New", "Create".
- tabs — Tabs: Segmented navigation between sibling views of the same collection.
- grid — Data grid: Canvas-based high-performance data grid for tabular collections.
- card-grid — Card grid: Responsive grid of cards for visual/collection-style listings.
- pagination — Pagination: Page navigation for a paged collection.
- breadcrumb — 브레드크럼: 현재 위치 경로 표시(홈 > 상위 > 현재). KWCAG 2.1 SC 2.4.8 준수.