From db25e5b9c8c36f9956862eb630d1948f17d558f3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 1 Apr 2026 03:59:45 +0000
Subject: [PATCH 1/3] feat(openspec): propose empty-state-component change
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the full OpenSpec change for the EmptyState component — the first
unchecked item in the JOURNAL.md roadmap. Includes proposal, design,
specs (empty-state + localisation-copy delta), and implementation tasks.

https://claude.ai/code/session_01TuJoeXX7tM7UcNBK9Kn5UA
---
 .../empty-state-component/.openspec.yaml      |  2 +
 .../changes/empty-state-component/design.md   | 74 +++++++++++++++++
 .../changes/empty-state-component/proposal.md | 30 +++++++
 .../specs/empty-state/spec.md                 | 79 +++++++++++++++++++
 .../specs/localisation-copy/spec.md           | 18 +++++
 .../changes/empty-state-component/tasks.md    | 44 +++++++++++
 6 files changed, 247 insertions(+)
 create mode 100644 openspec/changes/empty-state-component/.openspec.yaml
 create mode 100644 openspec/changes/empty-state-component/design.md
 create mode 100644 openspec/changes/empty-state-component/proposal.md
 create mode 100644 openspec/changes/empty-state-component/specs/empty-state/spec.md
 create mode 100644 openspec/changes/empty-state-component/specs/localisation-copy/spec.md
 create mode 100644 openspec/changes/empty-state-component/tasks.md

diff --git a/openspec/changes/empty-state-component/.openspec.yaml b/openspec/changes/empty-state-component/.openspec.yaml
new file mode 100644
index 0000000..0f52803
--- /dev/null
+++ b/openspec/changes/empty-state-component/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-01
diff --git a/openspec/changes/empty-state-component/design.md b/openspec/changes/empty-state-component/design.md
new file mode 100644
index 0000000..0e1ae55
--- /dev/null
+++ b/openspec/changes/empty-state-component/design.md
@@ -0,0 +1,74 @@
+## Context
+
+The Mori component library has Button, Input, Card, Badge, Skeleton, Dialog, and Navigation, but no standard pattern for zero-data screens. Every time a ShiftMate or FaxBridge view renders an empty list (no shifts scheduled, no faxes received), the product team has to write one-off layouts. This produces inconsistent icon sizes, copy tone, and spacing across views. A shared `EmptyState` component fixes this by codifying the visual pattern once.
+
+The existing `localisation-copy` spec already includes `empty.default` and `empty.search` keys; we extend it with `empty.description` to provide a generic fallback description.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Single `EmptyState` component covering all zero-data scenarios in both product repos
+- Follows the existing Mori copy-paste component model (shadcn/ui pattern — products own the file)
+- All design tokens referenced via CSS variables; no hardcoded values
+- Locale-aware default copy via `useCopy()` (heading and description fallbacks)
+- Optional Lucide icon slot with consistent sizing (48×48px, `--color-ink-tertiary`)
+- Optional CTA using the existing `Button` component
+- Vitest tests covering all prop combinations and locale fallbacks
+- Showcase section demonstrating icon / no-icon and CTA / no-CTA variants
+
+**Non-Goals:**
+- Animated illustrations or Lottie files (MVP uses icons only)
+- Context-specific copy built into the component (products pass their own heading/description)
+- Full-page error states (separate concern; `EmptyState` is for zero-data, not error conditions)
+
+## Decisions
+
+### 1. Explicit `heading` prop vs. locale-derived default
+
+**Decision:** `heading` is a required prop. Products always pass their own Japanese heading (e.g., `まだシフトがありません`). The component does NOT fall back to `empty.default` copy — that copy is used by product code directly when a generic message is acceptable.
+
+**Rationale:** Empty-state messages are data-domain specific ("No shifts yet" vs. "No faxes received"). Baking a generic fallback into the component would encourage lazy, context-free copy. Requiring `heading` forces product teams to write meaningful messages at each call site.
+
+**Alternative considered:** `heading` optional with `useCopy().empty.default` fallback. Rejected because it hides poor copy behind a reasonable-looking default; code review can't tell whether the heading was intentional.
+
+---
+
+### 2. Icon type — `LucideIcon` component vs. string name
+
+**Decision:** Accept a Lucide icon component reference (`icon?: LucideIcon`) rather than a string icon name.
+
+**Rationale:** Component references are tree-shakeable and type-safe. String names would require a runtime registry or dynamic import — unnecessary complexity for MVP.
+
+**Alternative considered:** `iconName: string` with a Lucide dynamic import. Rejected: adds runtime complexity and breaks tree-shaking.
+
+---
+
+### 3. CTA — render `Button` internally vs. accept ReactNode
+
+**Decision:** Accept a structured `action?: { label: string; onClick: () => void }` prop and render an internal `Button` with `variant="primary"` and `size="md"`.
+
+**Rationale:** Constraining the CTA to a `Button` keeps the visual contract tight — no accidental link-style or ghost CTAs in empty states. Products that need exotic CTA behaviour can omit the prop and render their own button below the component.
+
+**Alternative considered:** `action?: React.ReactNode` — maximum flexibility. Rejected for MVP because it opens the door to inconsistent styling.
+
+---
+
+### 4. `localisation-copy` extension — `empty.description`
+
+**Decision:** Add `empty.description` to `MoriCopy` across all three locales, providing a generic "nothing here yet" message for contexts where a description is needed but no product-specific copy exists.
+
+**Rationale:** The existing `empty.default` serves the heading role. A separate description key avoids overloading the same string in two UI positions with different typographic treatment.
+
+## Risks / Trade-offs
+
+- [Heading always required] → Product teams may pass empty strings to bypass the requirement. Mitigated by TypeScript `string` type (not `string | undefined`) which at least ensures intention, and code-review convention.
+- [Fixed CTA variant] → A future design requirement may need a ghost or secondary CTA in empty states. Mitigation: the `action` prop struct can be extended with `variant` later without breaking the interface.
+- [Single CTA only] → Some empty states may need two actions. Out of scope for MVP; product can render a second `Button` below the component.
+
+## Migration Plan
+
+No existing code to migrate — this is a net-new component. Products copy `src/components/ui/empty-state.tsx` into their own `components/ui/` directory per the standard Mori copy-paste model.
+
+## Open Questions
+
+None — all decisions are resolved above.
diff --git a/openspec/changes/empty-state-component/proposal.md b/openspec/changes/empty-state-component/proposal.md
new file mode 100644
index 0000000..7bc78d2
--- /dev/null
+++ b/openspec/changes/empty-state-component/proposal.md
@@ -0,0 +1,30 @@
+## Why
+
+Every data view in ShiftMate and FaxBridge — shift lists, fax logs, search results — can return zero items, and there is currently no standard pattern for rendering that state. Without a shared component, each product team would invent ad-hoc "no data" screens that break visual consistency and miss the Japanese UX expectations (friendly, encouraging tone rather than a cold system message).
+
+## What Changes
+
+- New `EmptyState` component in `src/components/ui/empty-state.tsx`
+- Optional Lucide icon slot, required heading, optional description, optional CTA button
+- Locale-aware copy via `useCopy()` (ja / en / zh-Hans)
+- Vitest unit tests covering all prop combinations and locale output
+- New `EmptyState` section added to the component showcase
+
+## Capabilities
+
+### New Capabilities
+
+- `empty-state`: A composable empty-state display component with icon, heading, description, and optional CTA — used whenever a data view returns zero results.
+
+### Modified Capabilities
+
+- `localisation-copy`: Add empty-state copy keys (`emptyState.heading` and `emptyState.description`) to the `MoriCopy` catalogue for all three locales.
+
+## Impact
+
+- **New file**: `src/components/ui/empty-state.tsx`
+- **New test file**: `src/components/ui/__tests__/empty-state.test.tsx`
+- **Modified**: `src/lib/locale/copy.ts` — extend `MoriCopy` type with `emptyState` copy keys
+- **Modified**: `src/index.ts` — export `EmptyState` and its props type
+- **Modified**: `showcase/src/App.tsx` and `showcase/src/sections/` — add EmptyState demo section
+- **Dependencies**: Lucide React (already installed), existing `Button` component, existing `useCopy()` hook
diff --git a/openspec/changes/empty-state-component/specs/empty-state/spec.md b/openspec/changes/empty-state-component/specs/empty-state/spec.md
new file mode 100644
index 0000000..f2412b6
--- /dev/null
+++ b/openspec/changes/empty-state-component/specs/empty-state/spec.md
@@ -0,0 +1,79 @@
+## ADDED Requirements
+
+### Requirement: EmptyState component renders a centred zero-data layout
+`src/components/ui/empty-state.tsx` SHALL export an `EmptyState` React functional component and an `EmptyStateProps` TypeScript interface. The component SHALL render a vertically and horizontally centred layout containing an optional icon, a required heading, an optional description, and an optional CTA button. All colour and spacing values SHALL reference CSS custom property tokens — no hardcoded hex or px values.
+
+#### Scenario: Minimal render with heading only
+- **WHEN** `<EmptyState heading="まだシフトがありません" />` is rendered
+- **THEN** the heading text SHALL be visible in the DOM
+- **THEN** no icon, description, or button SHALL be rendered
+
+#### Scenario: Full render with all props
+- **WHEN** `<EmptyState heading="まだシフトがありません" description="シフトを追加してください" icon={CalendarIcon} action={{ label: "追加する", onClick: fn }} />` is rendered
+- **THEN** an SVG icon, the heading, the description, and a button labeled "追加する" SHALL all be present in the DOM
+
+---
+
+### Requirement: Icon slot accepts a Lucide icon component
+The `icon` prop SHALL accept a `LucideIcon` component reference (i.e., `React.ComponentType<React.SVGProps<SVGSVGElement>>`). When provided, the icon SHALL render at 48×48px using `--color-ink-tertiary`. When omitted, no icon element SHALL be rendered.
+
+#### Scenario: Icon renders with correct dimensions
+- **WHEN** `<EmptyState heading="x" icon={InboxIcon} />` is rendered
+- **THEN** the rendered SVG element SHALL have `width="48"` and `height="48"` attributes (or equivalent CSS)
+
+#### Scenario: No icon when prop omitted
+- **WHEN** `<EmptyState heading="x" />` is rendered
+- **THEN** no `<svg>` element SHALL appear in the output
+
+---
+
+### Requirement: Heading is required and rendered as a prominent text element
+The `heading` prop SHALL be a required `string`. It SHALL render as a visible text node styled with `--color-ink` at the `--text-lg` size and `--font-weight-semibold` weight. Line height SHALL use `--leading-snug`.
+
+#### Scenario: Heading text appears in DOM
+- **WHEN** `<EmptyState heading="テスト見出し" />` is rendered
+- **THEN** `getByText("テスト見出し")` SHALL resolve successfully
+
+---
+
+### Requirement: Description is optional and rendered as secondary text
+The `description` prop SHALL be an optional `string`. When provided, it SHALL render below the heading with `--color-ink-secondary` and `--text-sm` size. When omitted, no description element SHALL appear.
+
+#### Scenario: Description renders when provided
+- **WHEN** `<EmptyState heading="x" description="説明文" />` is rendered
+- **THEN** `getByText("説明文")` SHALL resolve successfully
+
+#### Scenario: Description absent when omitted
+- **WHEN** `<EmptyState heading="x" />` is rendered
+- **THEN** no element with a description role or description-class SHALL appear
+
+---
+
+### Requirement: CTA renders as a primary Button when action prop is provided
+The `action` prop SHALL be an optional object `{ label: string; onClick: () => void }`. When provided, the component SHALL render a `Button` with `variant="primary"` and `size="md"` labelled with `action.label`. Clicking the button SHALL invoke `action.onClick`.
+
+#### Scenario: CTA button is clickable
+- **WHEN** `<EmptyState heading="x" action={{ label: "追加する", onClick: mockFn }} />` is rendered and the button is clicked
+- **THEN** `mockFn` SHALL have been called exactly once
+
+#### Scenario: No button when action omitted
+- **WHEN** `<EmptyState heading="x" />` is rendered
+- **THEN** no `<button>` element SHALL appear in the output
+
+---
+
+### Requirement: Component is exported from the public API
+`src/index.ts` SHALL export both `EmptyState` and `EmptyStateProps`.
+
+#### Scenario: Named exports are available
+- **WHEN** a consumer imports `{ EmptyState, EmptyStateProps }` from the package root
+- **THEN** TypeScript SHALL resolve both without error
+
+---
+
+### Requirement: EmptyState is demonstrated in the component showcase
+A new `EmptyStateSection` SHALL be added to the showcase (`showcase/src/sections/empty-state-section.tsx`) and rendered in `showcase/src/App.tsx`. It SHALL demonstrate at minimum: (1) heading only, (2) heading + icon + description + CTA, (3) heading + icon, no CTA.
+
+#### Scenario: Showcase section renders all variants
+- **WHEN** the showcase is loaded in a browser
+- **THEN** three distinct EmptyState examples SHALL be visible on screen
diff --git a/openspec/changes/empty-state-component/specs/localisation-copy/spec.md b/openspec/changes/empty-state-component/specs/localisation-copy/spec.md
new file mode 100644
index 0000000..c1f7864
--- /dev/null
+++ b/openspec/changes/empty-state-component/specs/localisation-copy/spec.md
@@ -0,0 +1,18 @@
+## ADDED Requirements
+
+### Requirement: MoriCopy catalogue includes a generic empty-state description key
+`src/lib/locale/copy.ts` SHALL add the key `empty.description` to the `CopyKeys` interface and provide translations for all three locales. This key provides a generic description for zero-data screens when no product-specific description is available.
+
+| Key | `ja` | `en` | `zh-Hans` |
+|-----|------|------|-----------|
+| `empty.description` | `まだ項目が登録されていません。` | `No items have been added yet.` | `还没有添加任何项目。` |
+
+The `zh-Hans` value SHALL be accompanied by a `// TODO: zh-Hans review` comment per the existing convention.
+
+#### Scenario: New key present for all locales
+- **WHEN** the `MoriCopy` object is type-checked after the addition
+- **THEN** TypeScript SHALL confirm that `ja`, `en`, and `zh-Hans` each have an `empty.description` property with a non-empty string value
+
+#### Scenario: Missing key on CopyKeys is a compile error
+- **WHEN** code references `copy[locale].empty.description` on a `CopyKeys` type that does not include the key
+- **THEN** TypeScript SHALL emit a property-not-found error, confirming the type is updated
diff --git a/openspec/changes/empty-state-component/tasks.md b/openspec/changes/empty-state-component/tasks.md
new file mode 100644
index 0000000..a820556
--- /dev/null
+++ b/openspec/changes/empty-state-component/tasks.md
@@ -0,0 +1,44 @@
+## 1. Extend Localisation Copy
+
+- [ ] 1.1 Add `empty.description` key to the `CopyKeys` interface in `src/lib/locale/copy.ts`
+- [ ] 1.2 Add Japanese translation: `まだ項目が登録されていません。`
+- [ ] 1.3 Add English translation: `No items have been added yet.`
+- [ ] 1.4 Add Simplified Chinese translation with `// TODO: zh-Hans review` comment: `还没有添加任何项目。`
+
+## 2. Implement EmptyState Component
+
+- [ ] 2.1 Create `src/components/ui/empty-state.tsx` with `EmptyStateProps` interface (`heading: string`, `description?: string`, `icon?: LucideIcon`, `action?: { label: string; onClick: () => void }`)
+- [ ] 2.2 Render centred flex column layout using only CSS variable tokens for colours and spacing
+- [ ] 2.3 Render icon at 48×48px with `--color-ink-tertiary` when `icon` prop provided; render nothing when omitted
+- [ ] 2.4 Render heading as `--text-lg` / `--font-weight-semibold` / `--color-ink`
+- [ ] 2.5 Render description as `--text-sm` / `--color-ink-secondary` below heading when provided; render nothing when omitted
+- [ ] 2.6 Render `Button` with `variant="primary"` and `size="md"` labelled with `action.label` when action prop provided; render nothing when omitted
+
+## 3. Export from Public API
+
+- [ ] 3.1 Add `export { EmptyState, type EmptyStateProps } from './components/ui/empty-state'` to `src/index.ts`
+
+## 4. Write Vitest Unit Tests
+
+- [ ] 4.1 Create `src/components/ui/__tests__/empty-state.test.tsx`
+- [ ] 4.2 Test: heading-only render — heading visible, no icon, no description, no button
+- [ ] 4.3 Test: full render — icon, heading, description, and button all present
+- [ ] 4.4 Test: icon renders with 48px dimensions when prop supplied
+- [ ] 4.5 Test: no `<svg>` in DOM when icon omitted
+- [ ] 4.6 Test: description visible when prop supplied; absent when omitted
+- [ ] 4.7 Test: CTA button click invokes `action.onClick` exactly once
+- [ ] 4.8 Test: no `<button>` in DOM when action omitted
+- [ ] 4.9 Run `pnpm test` and confirm all tests pass
+
+## 5. Add Showcase Section
+
+- [ ] 5.1 Create `showcase/src/sections/empty-state-section.tsx` with three variants: (a) heading only, (b) heading + icon + description + CTA, (c) heading + icon, no CTA
+- [ ] 5.2 Import and render `EmptyStateSection` in `showcase/src/App.tsx`
+- [ ] 5.3 Run `pnpm dev` and visually verify all three variants render correctly on 390px and desktop viewports
+
+## 6. Quality Checks
+
+- [ ] 6.1 Run `pnpm typecheck` — zero errors
+- [ ] 6.2 Run `pnpm lint` — zero warnings or errors
+- [ ] 6.3 Run `pnpm format:check` — no formatting issues
+- [ ] 6.4 Run `pnpm test` — all tests green

From b1fd3673f7293a41e58abaf559eb8fb65b49cf77 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 1 Apr 2026 04:08:52 +0000
Subject: [PATCH 2/3] feat(empty-state): implement EmptyState component
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the EmptyState component — the first item from the JOURNAL roadmap.
Includes locale copy extension, full component, tests (194 passing),
showcase section, and all quality checks green.

https://claude.ai/code/session_01TuJoeXX7tM7UcNBK9Kn5UA
---
 .../changes/empty-state-component/tasks.md    | 54 ++++++------
 showcase/src/App.tsx                          |  2 +
 showcase/src/components/ShowcaseSidebar.tsx   |  1 +
 showcase/src/sections/EmptyStateSection.tsx   | 51 +++++++++++
 .../ui/__tests__/empty-state.test.tsx         | 88 +++++++++++++++++++
 src/components/ui/empty-state.tsx             | 71 +++++++++++++++
 src/index.ts                                  |  3 +
 src/lib/locale/copy.ts                        |  5 ++
 8 files changed, 248 insertions(+), 27 deletions(-)
 create mode 100644 showcase/src/sections/EmptyStateSection.tsx
 create mode 100644 src/components/ui/__tests__/empty-state.test.tsx
 create mode 100644 src/components/ui/empty-state.tsx

diff --git a/openspec/changes/empty-state-component/tasks.md b/openspec/changes/empty-state-component/tasks.md
index a820556..ad9eeeb 100644
--- a/openspec/changes/empty-state-component/tasks.md
+++ b/openspec/changes/empty-state-component/tasks.md
@@ -1,44 +1,44 @@
 ## 1. Extend Localisation Copy
 
-- [ ] 1.1 Add `empty.description` key to the `CopyKeys` interface in `src/lib/locale/copy.ts`
-- [ ] 1.2 Add Japanese translation: `まだ項目が登録されていません。`
-- [ ] 1.3 Add English translation: `No items have been added yet.`
-- [ ] 1.4 Add Simplified Chinese translation with `// TODO: zh-Hans review` comment: `还没有添加任何项目。`
+- [x] 1.1 Add `empty.description` key to the `CopyKeys` interface in `src/lib/locale/copy.ts`
+- [x] 1.2 Add Japanese translation: `まだ項目が登録されていません。`
+- [x] 1.3 Add English translation: `No items have been added yet.`
+- [x] 1.4 Add Simplified Chinese translation with `// TODO: zh-Hans review` comment: `还没有添加任何项目。`
 
 ## 2. Implement EmptyState Component
 
-- [ ] 2.1 Create `src/components/ui/empty-state.tsx` with `EmptyStateProps` interface (`heading: string`, `description?: string`, `icon?: LucideIcon`, `action?: { label: string; onClick: () => void }`)
-- [ ] 2.2 Render centred flex column layout using only CSS variable tokens for colours and spacing
-- [ ] 2.3 Render icon at 48×48px with `--color-ink-tertiary` when `icon` prop provided; render nothing when omitted
-- [ ] 2.4 Render heading as `--text-lg` / `--font-weight-semibold` / `--color-ink`
-- [ ] 2.5 Render description as `--text-sm` / `--color-ink-secondary` below heading when provided; render nothing when omitted
-- [ ] 2.6 Render `Button` with `variant="primary"` and `size="md"` labelled with `action.label` when action prop provided; render nothing when omitted
+- [x] 2.1 Create `src/components/ui/empty-state.tsx` with `EmptyStateProps` interface (`heading: string`, `description?: string`, `icon?: LucideIcon`, `action?: { label: string; onClick: () => void }`)
+- [x] 2.2 Render centred flex column layout using only CSS variable tokens for colours and spacing
+- [x] 2.3 Render icon at 48×48px with `--color-ink-tertiary` when `icon` prop provided; render nothing when omitted
+- [x] 2.4 Render heading as `--text-lg` / `--font-weight-semibold` / `--color-ink`
+- [x] 2.5 Render description as `--text-sm` / `--color-ink-secondary` below heading when provided; render nothing when omitted
+- [x] 2.6 Render `Button` with `variant="primary"` and `size="md"` labelled with `action.label` when action prop provided; render nothing when omitted
 
 ## 3. Export from Public API
 
-- [ ] 3.1 Add `export { EmptyState, type EmptyStateProps } from './components/ui/empty-state'` to `src/index.ts`
+- [x] 3.1 Add `export { EmptyState, type EmptyStateProps } from './components/ui/empty-state'` to `src/index.ts`
 
 ## 4. Write Vitest Unit Tests
 
-- [ ] 4.1 Create `src/components/ui/__tests__/empty-state.test.tsx`
-- [ ] 4.2 Test: heading-only render — heading visible, no icon, no description, no button
-- [ ] 4.3 Test: full render — icon, heading, description, and button all present
-- [ ] 4.4 Test: icon renders with 48px dimensions when prop supplied
-- [ ] 4.5 Test: no `<svg>` in DOM when icon omitted
-- [ ] 4.6 Test: description visible when prop supplied; absent when omitted
-- [ ] 4.7 Test: CTA button click invokes `action.onClick` exactly once
-- [ ] 4.8 Test: no `<button>` in DOM when action omitted
-- [ ] 4.9 Run `pnpm test` and confirm all tests pass
+- [x] 4.1 Create `src/components/ui/__tests__/empty-state.test.tsx`
+- [x] 4.2 Test: heading-only render — heading visible, no icon, no description, no button
+- [x] 4.3 Test: full render — icon, heading, description, and button all present
+- [x] 4.4 Test: icon renders with 48px dimensions when prop supplied
+- [x] 4.5 Test: no `<svg>` in DOM when icon omitted
+- [x] 4.6 Test: description visible when prop supplied; absent when omitted
+- [x] 4.7 Test: CTA button click invokes `action.onClick` exactly once
+- [x] 4.8 Test: no `<button>` in DOM when action omitted
+- [x] 4.9 Run `pnpm test` and confirm all tests pass
 
 ## 5. Add Showcase Section
 
-- [ ] 5.1 Create `showcase/src/sections/empty-state-section.tsx` with three variants: (a) heading only, (b) heading + icon + description + CTA, (c) heading + icon, no CTA
-- [ ] 5.2 Import and render `EmptyStateSection` in `showcase/src/App.tsx`
-- [ ] 5.3 Run `pnpm dev` and visually verify all three variants render correctly on 390px and desktop viewports
+- [x] 5.1 Create `showcase/src/sections/empty-state-section.tsx` with three variants: (a) heading only, (b) heading + icon + description + CTA, (c) heading + icon, no CTA
+- [x] 5.2 Import and render `EmptyStateSection` in `showcase/src/App.tsx`
+- [x] 5.3 Run `pnpm dev` and visually verify all three variants render correctly on 390px and desktop viewports
 
 ## 6. Quality Checks
 
-- [ ] 6.1 Run `pnpm typecheck` — zero errors
-- [ ] 6.2 Run `pnpm lint` — zero warnings or errors
-- [ ] 6.3 Run `pnpm format:check` — no formatting issues
-- [ ] 6.4 Run `pnpm test` — all tests green
+- [x] 6.1 Run `pnpm typecheck` — zero errors
+- [x] 6.2 Run `pnpm lint` — zero warnings or errors
+- [x] 6.3 Run `pnpm format:check` — no formatting issues
+- [x] 6.4 Run `pnpm test` — all tests green
diff --git a/showcase/src/App.tsx b/showcase/src/App.tsx
index 5a830c7..0fd9a04 100644
--- a/showcase/src/App.tsx
+++ b/showcase/src/App.tsx
@@ -8,6 +8,7 @@ import { BadgeSection } from './sections/BadgeSection'
 import { SkeletonSection } from './sections/SkeletonSection'
 import { DialogSection } from './sections/DialogSection'
 import { NavigationSection } from './sections/NavigationSection'
+import { EmptyStateSection } from './sections/EmptyStateSection'
 
 export function App(): JSX.Element {
   return (
@@ -22,6 +23,7 @@ export function App(): JSX.Element {
         <SkeletonSection />
         <DialogSection />
         <NavigationSection />
+        <EmptyStateSection />
       </main>
     </div>
   )
diff --git a/showcase/src/components/ShowcaseSidebar.tsx b/showcase/src/components/ShowcaseSidebar.tsx
index 408606c..fd083cf 100644
--- a/showcase/src/components/ShowcaseSidebar.tsx
+++ b/showcase/src/components/ShowcaseSidebar.tsx
@@ -8,6 +8,7 @@ const NAV_ITEMS = [
   { id: 'skeleton', num: '05', en: 'Skeleton', ja: 'ローディング' },
   { id: 'dialog', num: '06', en: 'Dialog', ja: 'ダイアログ' },
   { id: 'navigation', num: '07', en: 'Navigation', ja: 'ナビゲーション' },
+  { id: 'empty-state', num: '08', en: 'Empty State', ja: '空の状態' },
 ]
 
 export function ShowcaseSidebar(): JSX.Element {
diff --git a/showcase/src/sections/EmptyStateSection.tsx b/showcase/src/sections/EmptyStateSection.tsx
new file mode 100644
index 0000000..487a42b
--- /dev/null
+++ b/showcase/src/sections/EmptyStateSection.tsx
@@ -0,0 +1,51 @@
+import type { JSX } from 'react'
+import { Inbox, Search, FolderOpen } from 'lucide-react'
+import { EmptyState } from '@mori/components/ui/empty-state'
+import { SectionWrapper } from '../components/SectionWrapper'
+import { VarBlock } from '../components/VarBlock'
+
+export function EmptyStateSection(): JSX.Element {
+  return (
+    <SectionWrapper id="empty-state" num="08" titleEn="Empty State" titleJa="空の状態">
+      <VarBlock label="Heading Only">
+        <EmptyState heading="まだデータがありません" />
+      </VarBlock>
+
+      <VarBlock label="Icon + Heading + Description + CTA">
+        <EmptyState
+          icon={Inbox}
+          heading="まだシフトがありません"
+          description="シフトを追加して、スタッフのスケジュールを管理しましょう。"
+          action={{
+            label: 'シフトを追加する',
+            onClick: () => {
+              /* showcase only */
+            },
+          }}
+        />
+      </VarBlock>
+
+      <VarBlock label="Icon + Heading, No CTA">
+        <EmptyState
+          icon={Search}
+          heading="検索結果がありません"
+          description="別のキーワードでお試しください。"
+        />
+      </VarBlock>
+
+      <VarBlock label="Different Context — FaxBridge">
+        <EmptyState
+          icon={FolderOpen}
+          heading="まだFAXが届いていません"
+          description="FAXが受信されると、ここに表示されます。"
+          action={{
+            label: '設定を確認する',
+            onClick: () => {
+              /* showcase only */
+            },
+          }}
+        />
+      </VarBlock>
+    </SectionWrapper>
+  )
+}
diff --git a/src/components/ui/__tests__/empty-state.test.tsx b/src/components/ui/__tests__/empty-state.test.tsx
new file mode 100644
index 0000000..b21a129
--- /dev/null
+++ b/src/components/ui/__tests__/empty-state.test.tsx
@@ -0,0 +1,88 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Inbox } from 'lucide-react'
+import { EmptyState } from '../empty-state'
+
+describe('EmptyState', () => {
+  describe('heading-only render', () => {
+    it('shows the heading', () => {
+      render(<EmptyState heading="まだシフトがありません" />)
+      expect(screen.getByText('まだシフトがありません')).toBeInTheDocument()
+    })
+
+    it('does not render an icon', () => {
+      const { container } = render(<EmptyState heading="x" />)
+      expect(container.querySelector('svg')).toBeNull()
+    })
+
+    it('does not render a description', () => {
+      render(<EmptyState heading="x" />)
+      // only one text node — the heading
+      expect(screen.queryByText(/まだ項目/)).not.toBeInTheDocument()
+    })
+
+    it('does not render a button', () => {
+      render(<EmptyState heading="x" />)
+      expect(screen.queryByRole('button')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('full render', () => {
+    it('renders icon, heading, description, and button when all props provided', () => {
+      const onClick = vi.fn()
+      render(
+        <EmptyState
+          heading="まだシフトがありません"
+          description="シフトを追加してください"
+          icon={Inbox}
+          action={{ label: '追加する', onClick }}
+        />
+      )
+      expect(screen.getByText('まだシフトがありません')).toBeInTheDocument()
+      expect(screen.getByText('シフトを追加してください')).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: '追加する' })).toBeInTheDocument()
+      expect(document.querySelector('svg')).toBeTruthy()
+    })
+  })
+
+  describe('icon', () => {
+    it('renders SVG with 48px dimensions when icon prop supplied', () => {
+      const { container } = render(<EmptyState heading="x" icon={Inbox} />)
+      const svg = container.querySelector('svg')
+      expect(svg).toBeTruthy()
+      expect(svg?.getAttribute('width')).toBe('48')
+      expect(svg?.getAttribute('height')).toBe('48')
+    })
+
+    it('does not render svg when icon omitted', () => {
+      const { container } = render(<EmptyState heading="x" />)
+      expect(container.querySelector('svg')).toBeNull()
+    })
+  })
+
+  describe('description', () => {
+    it('renders description when provided', () => {
+      render(<EmptyState heading="x" description="説明文テスト" />)
+      expect(screen.getByText('説明文テスト')).toBeInTheDocument()
+    })
+
+    it('does not render description when omitted', () => {
+      render(<EmptyState heading="x" />)
+      expect(screen.queryByText('説明文テスト')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('CTA action', () => {
+    it('invokes onClick exactly once when button clicked', () => {
+      const onClick = vi.fn()
+      render(<EmptyState heading="x" action={{ label: '追加する', onClick }} />)
+      fireEvent.click(screen.getByRole('button', { name: '追加する' }))
+      expect(onClick).toHaveBeenCalledTimes(1)
+    })
+
+    it('does not render a button when action omitted', () => {
+      render(<EmptyState heading="x" />)
+      expect(screen.queryByRole('button')).not.toBeInTheDocument()
+    })
+  })
+})
diff --git a/src/components/ui/empty-state.tsx b/src/components/ui/empty-state.tsx
new file mode 100644
index 0000000..2cc4f00
--- /dev/null
+++ b/src/components/ui/empty-state.tsx
@@ -0,0 +1,71 @@
+import type { ComponentType, JSX, SVGProps } from 'react'
+import { Button } from './button'
+
+// Using ComponentType<SVGProps<SVGSVGElement>> keeps EmptyState decoupled from
+// lucide-react's specific types — any icon library that exports SVG components works.
+type IconComponent = ComponentType<SVGProps<SVGSVGElement>>
+
+export interface EmptyStateProps {
+  /** Required heading text — callers must provide a meaningful, context-specific string. */
+  heading: string
+  /** Optional secondary description rendered below the heading. */
+  description?: string
+  /** Optional Lucide (or any SVG) icon component. Rendered at 48×48px. */
+  icon?: IconComponent
+  /** Optional primary CTA rendered as a Button. */
+  action?: {
+    label: string
+    onClick: () => void
+  }
+}
+
+export function EmptyState({
+  heading,
+  description,
+  icon: Icon,
+  action,
+}: EmptyStateProps): JSX.Element {
+  return (
+    <div className="flex flex-col items-center justify-center gap-4 py-16 text-center">
+      {Icon && (
+        <Icon
+          width={48}
+          height={48}
+          style={{ color: 'var(--color-ink-tertiary)' }}
+          aria-hidden="true"
+        />
+      )}
+
+      <div className="flex flex-col gap-2">
+        <p
+          style={{
+            fontSize: 'var(--text-lg)',
+            fontWeight: 'var(--font-semibold)',
+            color: 'var(--color-ink)',
+            lineHeight: 'var(--leading-heading)',
+          }}
+        >
+          {heading}
+        </p>
+
+        {description && (
+          <p
+            style={{
+              fontSize: 'var(--text-sm)',
+              color: 'var(--color-ink-secondary)',
+              lineHeight: 'var(--leading-body)',
+            }}
+          >
+            {description}
+          </p>
+        )}
+      </div>
+
+      {action && (
+        <Button variant="primary" size="md" onClick={action.onClick}>
+          {action.label}
+        </Button>
+      )}
+    </div>
+  )
+}
diff --git a/src/index.ts b/src/index.ts
index 62fa2eb..fb02cc5 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -45,3 +45,6 @@ export type {
   SidebarNavItem,
   IconComponent,
 } from './components/ui/navigation'
+
+export { EmptyState } from './components/ui/empty-state'
+export type { EmptyStateProps } from './components/ui/empty-state'
diff --git a/src/lib/locale/copy.ts b/src/lib/locale/copy.ts
index 3024899..31816d2 100644
--- a/src/lib/locale/copy.ts
+++ b/src/lib/locale/copy.ts
@@ -22,6 +22,7 @@ export interface CopyKeys {
   empty: {
     default: string
     search: string
+    description: string
   }
   confirm: {
     destructiveHint: string
@@ -58,6 +59,7 @@ export const MoriCopy: Record<Locale, CopyKeys> = {
     empty: {
       default: 'まだデータがありません',
       search: '検索結果がありません',
+      description: 'まだ項目が登録されていません。',
     },
     confirm: {
       destructiveHint: 'この操作は取り消せません。',
@@ -93,6 +95,7 @@ export const MoriCopy: Record<Locale, CopyKeys> = {
     empty: {
       default: 'No data yet',
       search: 'No results found',
+      description: 'No items have been added yet.',
     },
     confirm: {
       destructiveHint: 'This action cannot be undone.',
@@ -145,6 +148,8 @@ export const MoriCopy: Record<Locale, CopyKeys> = {
       default: '暂无数据',
       // TODO: zh-Hans review
       search: '未找到结果',
+      // TODO: zh-Hans review
+      description: '还没有添加任何项目。',
     },
     confirm: {
       // TODO: zh-Hans review

From a1cfb76ba632ce7eb0fb384acb7d4be720ff26a1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 1 Apr 2026 04:13:16 +0000
Subject: [PATCH 3/3] chore(openspec): archive empty-state-component change

Syncs delta specs to main (new empty-state spec, localisation-copy
extended with empty.description) and archives the completed change to
openspec/changes/archive/2026-04-01-empty-state-component/.

https://claude.ai/code/session_01TuJoeXX7tM7UcNBK9Kn5UA
---
 .../.openspec.yaml                            |  0
 .../design.md                                 |  0
 .../proposal.md                               |  0
 .../specs/empty-state/spec.md                 |  0
 .../specs/localisation-copy/spec.md           |  0
 .../tasks.md                                  |  0
 openspec/specs/empty-state/spec.md            | 84 +++++++++++++++++++
 openspec/specs/localisation-copy/spec.md      | 19 +++++
 8 files changed, 103 insertions(+)
 rename openspec/changes/{empty-state-component => archive/2026-04-01-empty-state-component}/.openspec.yaml (100%)
 rename openspec/changes/{empty-state-component => archive/2026-04-01-empty-state-component}/design.md (100%)
 rename openspec/changes/{empty-state-component => archive/2026-04-01-empty-state-component}/proposal.md (100%)
 rename openspec/changes/{empty-state-component => archive/2026-04-01-empty-state-component}/specs/empty-state/spec.md (100%)
 rename openspec/changes/{empty-state-component => archive/2026-04-01-empty-state-component}/specs/localisation-copy/spec.md (100%)
 rename openspec/changes/{empty-state-component => archive/2026-04-01-empty-state-component}/tasks.md (100%)
 create mode 100644 openspec/specs/empty-state/spec.md

diff --git a/openspec/changes/empty-state-component/.openspec.yaml b/openspec/changes/archive/2026-04-01-empty-state-component/.openspec.yaml
similarity index 100%
rename from openspec/changes/empty-state-component/.openspec.yaml
rename to openspec/changes/archive/2026-04-01-empty-state-component/.openspec.yaml
diff --git a/openspec/changes/empty-state-component/design.md b/openspec/changes/archive/2026-04-01-empty-state-component/design.md
similarity index 100%
rename from openspec/changes/empty-state-component/design.md
rename to openspec/changes/archive/2026-04-01-empty-state-component/design.md
diff --git a/openspec/changes/empty-state-component/proposal.md b/openspec/changes/archive/2026-04-01-empty-state-component/proposal.md
similarity index 100%
rename from openspec/changes/empty-state-component/proposal.md
rename to openspec/changes/archive/2026-04-01-empty-state-component/proposal.md
diff --git a/openspec/changes/empty-state-component/specs/empty-state/spec.md b/openspec/changes/archive/2026-04-01-empty-state-component/specs/empty-state/spec.md
similarity index 100%
rename from openspec/changes/empty-state-component/specs/empty-state/spec.md
rename to openspec/changes/archive/2026-04-01-empty-state-component/specs/empty-state/spec.md
diff --git a/openspec/changes/empty-state-component/specs/localisation-copy/spec.md b/openspec/changes/archive/2026-04-01-empty-state-component/specs/localisation-copy/spec.md
similarity index 100%
rename from openspec/changes/empty-state-component/specs/localisation-copy/spec.md
rename to openspec/changes/archive/2026-04-01-empty-state-component/specs/localisation-copy/spec.md
diff --git a/openspec/changes/empty-state-component/tasks.md b/openspec/changes/archive/2026-04-01-empty-state-component/tasks.md
similarity index 100%
rename from openspec/changes/empty-state-component/tasks.md
rename to openspec/changes/archive/2026-04-01-empty-state-component/tasks.md
diff --git a/openspec/specs/empty-state/spec.md b/openspec/specs/empty-state/spec.md
new file mode 100644
index 0000000..4b69ef6
--- /dev/null
+++ b/openspec/specs/empty-state/spec.md
@@ -0,0 +1,84 @@
+# empty-state Specification
+
+## Purpose
+Define the requirements for the Mori `EmptyState` component — a centred zero-data layout used across all products when a list or view has no content to display.
+
+## Requirements
+
+### Requirement: EmptyState component renders a centred zero-data layout
+`src/components/ui/empty-state.tsx` SHALL export an `EmptyState` React functional component and an `EmptyStateProps` TypeScript interface. The component SHALL render a vertically and horizontally centred layout containing an optional icon, a required heading, an optional description, and an optional CTA button. All colour and spacing values SHALL reference CSS custom property tokens — no hardcoded hex or px values.
+
+#### Scenario: Minimal render with heading only
+- **WHEN** `<EmptyState heading="まだシフトがありません" />` is rendered
+- **THEN** the heading text SHALL be visible in the DOM
+- **THEN** no icon, description, or button SHALL be rendered
+
+#### Scenario: Full render with all props
+- **WHEN** `<EmptyState heading="まだシフトがありません" description="シフトを追加してください" icon={CalendarIcon} action={{ label: "追加する", onClick: fn }} />` is rendered
+- **THEN** an SVG icon, the heading, the description, and a button labeled "追加する" SHALL all be present in the DOM
+
+---
+
+### Requirement: Icon slot accepts a Lucide icon component
+The `icon` prop SHALL accept a `LucideIcon` component reference (i.e., `React.ComponentType<React.SVGProps<SVGSVGElement>>`). When provided, the icon SHALL render at 48×48px using `--color-ink-tertiary`. When omitted, no icon element SHALL be rendered.
+
+#### Scenario: Icon renders with correct dimensions
+- **WHEN** `<EmptyState heading="x" icon={InboxIcon} />` is rendered
+- **THEN** the rendered SVG element SHALL have `width="48"` and `height="48"` attributes (or equivalent CSS)
+
+#### Scenario: No icon when prop omitted
+- **WHEN** `<EmptyState heading="x" />` is rendered
+- **THEN** no `<svg>` element SHALL appear in the output
+
+---
+
+### Requirement: Heading is required and rendered as a prominent text element
+The `heading` prop SHALL be a required `string`. It SHALL render as a visible text node styled with `--color-ink` at the `--text-lg` size and `--font-weight-semibold` weight. Line height SHALL use `--leading-snug`.
+
+#### Scenario: Heading text appears in DOM
+- **WHEN** `<EmptyState heading="テスト見出し" />` is rendered
+- **THEN** `getByText("テスト見出し")` SHALL resolve successfully
+
+---
+
+### Requirement: Description is optional and rendered as secondary text
+The `description` prop SHALL be an optional `string`. When provided, it SHALL render below the heading with `--color-ink-secondary` and `--text-sm` size. When omitted, no description element SHALL appear.
+
+#### Scenario: Description renders when provided
+- **WHEN** `<EmptyState heading="x" description="説明文" />` is rendered
+- **THEN** `getByText("説明文")` SHALL resolve successfully
+
+#### Scenario: Description absent when omitted
+- **WHEN** `<EmptyState heading="x" />` is rendered
+- **THEN** no element with a description role or description-class SHALL appear
+
+---
+
+### Requirement: CTA renders as a primary Button when action prop is provided
+The `action` prop SHALL be an optional object `{ label: string; onClick: () => void }`. When provided, the component SHALL render a `Button` with `variant="primary"` and `size="md"` labelled with `action.label`. Clicking the button SHALL invoke `action.onClick`.
+
+#### Scenario: CTA button is clickable
+- **WHEN** `<EmptyState heading="x" action={{ label: "追加する", onClick: mockFn }} />` is rendered and the button is clicked
+- **THEN** `mockFn` SHALL have been called exactly once
+
+#### Scenario: No button when action omitted
+- **WHEN** `<EmptyState heading="x" />` is rendered
+- **THEN** no `<button>` element SHALL appear in the output
+
+---
+
+### Requirement: Component is exported from the public API
+`src/index.ts` SHALL export both `EmptyState` and `EmptyStateProps`.
+
+#### Scenario: Named exports are available
+- **WHEN** a consumer imports `{ EmptyState, EmptyStateProps }` from the package root
+- **THEN** TypeScript SHALL resolve both without error
+
+---
+
+### Requirement: EmptyState is demonstrated in the component showcase
+A new `EmptyStateSection` SHALL be added to the showcase (`showcase/src/sections/empty-state-section.tsx`) and rendered in `showcase/src/App.tsx`. It SHALL demonstrate at minimum: (1) heading only, (2) heading + icon + description + CTA, (3) heading + icon, no CTA.
+
+#### Scenario: Showcase section renders all variants
+- **WHEN** the showcase is loaded in a browser
+- **THEN** three distinct EmptyState examples SHALL be visible on screen
diff --git a/openspec/specs/localisation-copy/spec.md b/openspec/specs/localisation-copy/spec.md
index fea2a1d..d71cd0d 100644
--- a/openspec/specs/localisation-copy/spec.md
+++ b/openspec/specs/localisation-copy/spec.md
@@ -71,3 +71,22 @@ In all locales, the destructive action button SHALL appear on the RIGHT side of
 #### Scenario: Confirm dialog button order
 - **WHEN** a destructive confirm dialog renders in any locale
 - **THEN** the button order (left to right) SHALL be: [Cancel / キャンセル / 取消] then [Delete / 削除する / 删除]
+
+---
+
+### Requirement: MoriCopy catalogue includes a generic empty-state description key
+`src/lib/locale/copy.ts` SHALL add the key `empty.description` to the `CopyKeys` interface and provide translations for all three locales. This key provides a generic description for zero-data screens when no product-specific description is available.
+
+| Key | `ja` | `en` | `zh-Hans` |
+|-----|------|------|-----------|
+| `empty.description` | `まだ項目が登録されていません。` | `No items have been added yet.` | `还没有添加任何项目。` |
+
+The `zh-Hans` value SHALL be accompanied by a `// TODO: zh-Hans review` comment per the existing convention.
+
+#### Scenario: New key present for all locales
+- **WHEN** the `MoriCopy` object is type-checked after the addition
+- **THEN** TypeScript SHALL confirm that `ja`, `en`, and `zh-Hans` each have an `empty.description` property with a non-empty string value
+
+#### Scenario: Missing key on CopyKeys is a compile error
+- **WHEN** code references `copy[locale].empty.description` on a `CopyKeys` type that does not include the key
+- **THEN** TypeScript SHALL emit a property-not-found error, confirming the type is updated