@tailor-platform/app-shell 1.14.0 → 1.16.0

package/skills/app-shell-patterns/SKILL.md

@@ -9,15 +9,20 @@ description: "Best-practice UI patterns and correct component usage for building
 
 Select and implement the correct UI pattern using @tailor-platform/app-shell components.
 
-## Fundamental References
+## Concepts
 
-These are the foundational rules that underpin all patterns. All patterns build on top of these references.
+Cross-cutting guides that underpin every screen — styling & theming and the token system, GraphQL data access, building custom components, plus auth and routing. Patterns and components build on these.
 
-| File                                                        | Description             |
-| ----------------------------------------------------------- | ----------------------- |
-| [components.md](references/fundamental/components.md)       | components reference    |
-| [design-system.md](references/fundamental/design-system.md) | design-system reference |
-| [graphql.md](references/fundamental/graphql.md)             | graphql reference       |
+| Name                                                                  | Description                                                                                                                              |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| [Authentication](references/concepts/authentication.md)               | Set up OAuth2/OIDC authentication with Tailor Platform's Auth service using the AuthProvider component                                   |
+| [Custom Components](references/concepts/custom-components.md)         | When AppShell lacks a component — compose first, and if you must build one, conform to the token system                                  |
+| [File-Based Routing](references/concepts/file-based-routing.md)       | Define pages via directory structure using the Vite plugin instead of explicit module configuration                                      |
+| [GraphQL Conventions](references/concepts/graphql.md)                 | Conventions for data access in AppShell apps — urql setup, fragment collocation, the connection pattern, and mutation cache invalidation |
+| [Modules and Resources](references/concepts/modules-and-resources.md) | Learn how to structure your AppShell application using modules and resources for automatic routing, navigation, and breadcrumbs          |
+| [Routing and Navigation](references/concepts/routing-navigation.md)   | Learn how to navigate between pages using React Router hooks and components re-exported from AppShell                                    |
+| [Sidebar Navigation](references/concepts/sidebar-navigation.md)       | Learn how to customize sidebar navigation with auto-generation or composition mode                                                       |
+| [Styling and Theming](references/concepts/styling-theming.md)         | The AppShell design system — Tailwind CSS v4 setup, theming and palettes, the token catalog, typography, and the styling boundary        |
 
 ## Migrations
 
@@ -25,20 +30,98 @@ These are the foundational rules that underpin all patterns. All patterns build
 
 Read it when upgrading `@tailor-platform/app-shell`, and whenever styling, theming, or dark mode looks wrong after a version bump. These breakages are silent: the build succeeds and nothing warns, so the cause is not discoverable from the error output. The package ships no CHANGELOG, so this file is the only migration record available locally.
 
-## Available Pages
+## Available Components
+
+Every AppShell component, its API surface, and usage guidance. Read the entry for the exact props, variants, and examples.
+
+| Name                                                                    | Description                                                                                                                                        |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [ActionPanel](references/components/action-panel.md)                    | Display a title and a vertical list of actions with per-row loading and disabled states                                                            |
+| [ActivityCard](references/components/activity-card.md)                  | Timeline of recent document activities with avatars and overflow dialog                                                                            |
+| [AIChat](references/components/ai-chat.md)                              | Building blocks for an LLM assistant UI — a streaming conversation view over a composer, plus reasoning, tool-call, and citation parts             |
+| [Alert](references/components/alert.md)                                 | Contextual status messages with automatic variant icons                                                                                            |
+| [AppShell](references/components/app-shell.md)                          | The root component that provides routing, navigation, and theming for your application                                                             |
+| [AppearanceSwitcher](references/components/appearance-switcher.md)      | Pre-built dropdown for toggling the application color theme                                                                                        |
+| [Attachment](references/components/attachment.md)                       | Attachment list with upload, previews, and per-item actions; compose with Card for titles and surface styling                                      |
+| [Autocomplete](references/components/autocomplete.md)                   | Text input with a suggestion list — value is the raw input string, not a discrete item selection                                                   |
+| [Avatar](references/components/avatar.md)                               | User avatar with image and fallback (Base UI)                                                                                                      |
+| [Badge](references/components/badge.md)                                 | Display status, labels, and tags with customizable variants                                                                                        |
+| [Button](references/components/button.md)                               | Styled button with multiple variants and sizes                                                                                                     |
+| [Card](references/components/card.md)                                   | General-purpose container with consistent styling using a compound component API                                                                   |
+| [Checkbox](references/components/checkbox.md)                           | Styled checkbox for boolean form fields, with indeterminate state and automatic Field / React Hook Form integration                                |
+| [Combobox](references/components/combobox.md)                           | Searchable combobox with single/multi selection, built-in filtering, async data fetching, and user-creatable items                                 |
+| [CommandPalette](references/components/command-palette.md)              | Keyboard-driven quick navigation with fuzzy search for all routes in your application                                                              |
+| [CsvImporter](references/components/csv-importer.md)                    | Guided multi-step CSV import flow with drag-and-drop upload, column mapping, validation, and inline error correction                               |
+| [DataTable](references/components/data-table.md)                        | Compound data table component with sortable columns, filter chips, cursor-based pagination, row actions, and multi-row selection                   |
+| [DatePicker](references/components/date-picker.md)                      | Accessible date input components (@internationalized/date + Base UI)                                                                               |
+| [DefaultHeader](references/components/default-header.md)                | The built-in SidebarLayout top bar, extensible via an actions slot                                                                                 |
+| [DefaultSidebar](references/components/default-sidebar.md)              | Built-in sidebar component for auto-generated or composed navigation, with optional search suppression and icon-rail mode                          |
+| [DescriptionCard](references/components/description-card.md)            | Display structured key-value information in a responsive grid layout with automatic field rendering                                                |
+| [Dialog](references/components/dialog.md)                               | Modal dialog with a compound component API                                                                                                         |
+| [DocumentProgressCard](references/components/document-progress-card.md) | Generic card visualising a document's lifecycle state — optional percentage, stacked progress bar, and status legend                               |
+| [Form, Field, and Fieldset](references/components/form.md)              | Components for building validated forms with automatic accessibility wiring, validation state management, and optional React Hook Form integration |
+| [GlobalHeaderLayout](references/components/global-header-layout.md)     | Opinionated layout with an app-wide header above the whole shell and a sidebar that collapses to a persistent icon rail                            |
+| [Grid](references/components/grid.md)                                   | Generic CSS-Grid layout primitive for equal or custom-width columns with responsive reflow, auto-fit, and spanning                                 |
+| [Input](references/components/input.md)                                 | Styled text input with consistent theming                                                                                                          |
+| [Layout](references/components/layout.md)                               | Responsive column layout component for organizing page content in 1, 2, or 3 columns                                                               |
+| [Menu](references/components/menu.md)                                   | Dropdown menu with a compound component API, supporting checkbox/radio items, groups, separators, and nested sub-menus                             |
+| [MetricCard](references/components/metric-card.md)                      | Compact card for dashboard KPI summaries with title, value, optional trend and description                                                         |
+| [Select](references/components/select.md)                               | Single or multi-select dropdown with optional async data fetching                                                                                  |
+| [Sheet](references/components/sheet.md)                                 | Slide-in panel backed by a Drawer with native swipe-to-dismiss support                                                                             |
+| [SidebarGroup](references/components/sidebar-group.md)                  | Collapsible group component for organizing sidebar navigation items with icons and nested structure                                                |
+| [SidebarItem](references/components/sidebar-item.md)                    | Individual navigation item for customizing sidebar with icons, active states, and external links                                                   |
+| [SidebarLayout](references/components/sidebar-layout.md)                | Default AppShell layout with a built-in sidebar, content header, optional app-wide top bar, and an escape-hatch body slot                          |
+| [Spinner](references/components/spinner.md)                             | Lightweight loading indicator component with accessible defaults and preset sizes                                                                  |
+| [Table](references/components/table.md)                                 | Semantic HTML table with pre-styled sub-components                                                                                                 |
+| [Tabs](references/components/tabs.md)                                   | Tab navigation with a compound component API                                                                                                       |
+| [Textarea](references/components/textarea.md)                           | Styled multi-line text input sized by rows, with automatic Field / React Hook Form integration                                                     |
+| [Timeline](references/components/timeline.md)                           | Composable primitives for building time-based layouts with axis guides, row backgrounds, intervals, and dependency links                           |
+| [Toolbar](references/components/toolbar.md)                             | Full-width action bars with composable rows, grouped controls, and keyboard navigation                                                             |
+| [Tooltip](references/components/tooltip.md)                             | Hover/focus tooltip with configurable placement and shared delay via Tooltip.Provider                                                              |
+| [WithGuard](references/components/with-guard.md)                        | Conditionally render UI elements based on guard evaluation with support for async permissions checks                                               |
+
+## Available Hooks & Functions
+
+Hooks, factory functions, guards, and router utilities exported by AppShell.
+
+| Name                                                                                       | Description                                                                   |
+| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| [createAIGatewayClient](references/api/create-ai-gateway-client.md)                        | Create a low-level AI Gateway client that reuses AppShell authentication      |
+| [createTypedPaths](references/api/create-typed-paths.md)                                   | Generate type-safe route paths from file-based routing                        |
+| [defineI18nLabels](references/api/define-i18n-labels.md)                                   | Define internationalized labels for multi-language support                    |
+| [defineModule](references/api/define-module.md)                                            | Define a top-level module that appears in the main navigation                 |
+| [defineResource](references/api/define-resource.md)                                        | Define a nested resource (page) within a module                               |
+| [hidden](references/api/guards/hidden.md)                                                  | Guard function that denies access and returns 404 Not Found                   |
+| [Guards Overview](references/api/guards/overview.md)                                       | Access control system for routes and components using guard functions         |
+| [pass](references/api/guards/pass.md)                                                      | Guard function that allows access and continues to the next guard             |
+| [redirectTo](references/api/guards/redirect-to.md)                                         | Guard function that redirects to another page                                 |
+| [useLocation](references/api/router/use-location.md)                                       | Hook to access current location object with pathname, search, and state       |
+| [useNavigate](references/api/router/use-navigate.md)                                       | Hook for programmatic navigation between routes                               |
+| [useParams](references/api/router/use-params.md)                                           | Hook to access dynamic route parameters                                       |
+| [useAIChat](references/api/use-ai-chat.md)                                                 | Simple text-only chat hook for AI Gateway                                     |
+| [useAppShell](references/api/use-app-shell.md)                                             | Hook to access AppShell context data and configuration                        |
+| [useAppShellConfig](references/api/use-app-shell-config.md)                                | Hook to access AppShell configuration data                                    |
+| [useAppShellData](references/api/use-app-shell-data.md)                                    | Hook to access custom context data passed to AppShell                         |
+| [useAuth](references/api/use-auth.md)                                                      | Hook for accessing authentication state and methods                           |
+| [useOverrideBreadcrumb](references/api/use-override-breadcrumb.md)                         | Hook for dynamically overriding breadcrumb titles from within page components |
+| [usePageMeta](references/api/use-page-meta.md)                                             | Hook to resolve page metadata from route path                                 |
+| [useRegisterCommandPaletteActions](references/api/use-register-command-palette-actions.md) | Hook for registering contextual page actions into the CommandPalette          |
+| [useResolvedLocale](references/api/use-resolved-locale.md)                                 | Hook to access the full BCP-47 locale and language code from AppShell context |
+| [useRouteError](references/api/use-route-error.md)                                         | Hook to access error details in custom error boundaries                       |
+| [useTheme](references/api/use-theme.md)                                                    | Hook for accessing and controlling theme (light/dark mode)                    |
+| [useTimeZone](references/api/use-time-zone.md)                                             | Hook to access the configured IANA timezone from AppShell context             |
+| [useToast](references/api/use-toast.md)                                                    | Hook for displaying toast notifications                                       |
 
-A page is the shape of a whole screen — the outer choice, made before picking patterns for the parts inside it. Where a pattern is one recipe, a page compares the layouts a screen could take and says when each applies. Match the screen first, then use the patterns the entry cites for the pieces within it.
+## Available Pages
 
+A page is the shape of a whole screen — the outer choice, made before picking patterns for the parts inside it. Where a pattern is one recipe, a page fixes the layout of a whole screen and says what belongs in each part of it. Match the screen first, then use the patterns the entry cites for the pieces within it.
 
+| Slug                                                     | Name                 | Description                                                                                                        |
+| -------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [`document-detail`](references/pages/document-detail.md) | Document Detail Page | The screen for a single record — its summary, its contents, the records around it, and the actions available on it |
 
 ## Available Patterns
 
-### detail
-
-| Slug                                                                          | Name                     | Description                                                           |
-| ----------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------- |
-| [`detail/hero-with-actions`](references/patterns/detail-hero-with-actions.md) | Hero With Actions Detail | Single-record detail view with workflow actions and activity timeline |
-
 ### form
 
 | Slug                                                          | Name             | Description                                                                                                              |
@@ -66,22 +149,23 @@ A page is the shape of a whole screen — the outer choice, made before picking
 ## How to Use
 
 1. Identify the user's intent (list, detail, form, interaction, screen composition, recipe)
-2. Match constraints to an entry slug from the tables above
-3. Read the entry's detailed spec: `references/<category>/<slug>.md` (relative to this file)
-4. Read fundamental references for component APIs, design tokens, and GraphQL conventions: `references/fundamental/`
-5. Implement using ONLY the imports listed in the entry's `requiredImports`
+2. Building a whole screen? Match it to a **page** entry first and read that. A page fixes the screen's shape — its layout, what goes where, and in what order — before any of the parts inside it are chosen.
+3. Match each part you are building to a **pattern** entry slug from the tables above. A one-off recipe rather than a screen skips straight to this step.
+4. Read the entry's detailed spec: `references/<category>/<slug>.md` (relative to this file)
+5. Read the concept references for styling, design tokens, GraphQL, and custom components: `references/concepts/`; component and hook APIs live in `references/components/` and `references/api/`
+6. Implement using ONLY the imports listed in the entry's `requiredImports` — for a page, the `requiredImports` of the pattern it sent you to
 
 ## Rules
 
 - ALWAYS cite the entry slug in a comment at the top of the file:
-  `/* pattern: list/dense-scan */`
-- NEVER mix patterns in a single page component
+  `/* pattern: list/dense-scan */`. Cite the pattern you implemented, even when a page entry sent you to it.
+- NEVER mix two patterns that solve the same problem in one component — one part, one recipe. Composing patterns for _different_ parts of a screen is expected, and the screen's page entry says which.
 - ALWAYS use AppShell components — do NOT use raw HTML or third-party UI libraries
-- If no entry matches, compose directly from fundamental references
+- If no entry matches, compose directly from the concept references and component docs
 
 ### Cross-cutting UX rules (apply to every screen)
 
-Full rationale in [`design-system.md`](references/fundamental/design-system.md) → Composition & emphasis rules.
+Full rationale in [`styling-theming`](references/concepts/styling-theming.md) → Composition & emphasis rules.
 
 - **One primary action per view:** at most one primary/filled `Button`; everything else is `outline`/`secondary`/`ghost`.
 - **Status badges by semantic color:** a **filled** semantic variant for the record's primary/lifecycle status, **`outline-*`** for secondary statuses, **`subtle-*`** for tags; reserve brand `default` for non-status emphasis.
@@ -89,5 +173,5 @@ Full rationale in [`design-system.md`](references/fundamental/design-system.md)
 - **Action placement:** primary CTA + status in `Layout.Header`; workflow actions in `ActionPanel`; back/navigation in the breadcrumb — never in `ActionPanel`.
 - **Metric tiles always go in a `Grid`** (`columns={{ initial: 1, md: 2, xl: 4 }}`) — never one-per-row.
 - **Forms default to `form/modal`** — only build a routed full-page form when the design explicitly calls for one.
-- **Forms use AppShell `Form` + `Field`**, submitting via `onFormSubmit` — never a bare `<form onSubmit>` with `FormData`. `onFormSubmit` reads registered `Field.Root`s, so every control (dropdowns included) just needs a wrapping `Field.Root name="…"` — no `name` on the control, no `useState`. React Hook Form is optional, consumer-installed, and only warranted for cross-field validation, field arrays, or a Zod resolver. Details in [`components.md`](references/fundamental/components.md) → Forms.
+- **Forms use AppShell `Form` + `Field`**, submitting via `onFormSubmit` — never a bare `<form onSubmit>` with `FormData`. `onFormSubmit` reads registered `Field.Root`s, so every control (dropdowns included) just needs a wrapping `Field.Root name="…"` — no `name` on the control, no `useState`. React Hook Form is optional, consumer-installed, and only warranted for cross-field validation, field arrays, or a Zod resolver. Details in [`Form`](references/components/form.md) and the `form/*` patterns.
 - **Handle every state:** loading (skeleton), empty (labelled empty state), and error (inline + retry) — never ship only the happy path.

package/skills/app-shell-patterns/references/api/create-ai-gateway-client.md

@@ -0,0 +1,115 @@
+---
+title: createAIGatewayClient
+description: Create a low-level AI Gateway client that reuses AppShell authentication
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/create-ai-gateway-client.docs.outline.md — do not edit by hand. -->
+
+# createAIGatewayClient
+
+Creates a small AI Gateway transport client for text-only chat completions.
+
+## Signature
+
+```typescript
+function createAIGatewayClient(config: {
+  gatewayUri: string;
+  authClient: AuthClient;
+}): AIGatewayClient;
+```
+
+## Parameters
+
+### `gatewayUri`
+
+- **Type:** `string`
+- **Required:** Yes
+- **Description:** Base URL of the AI Gateway
+
+### `authClient`
+
+- **Type:** `AuthClient`
+- **Required:** Yes
+- **Description:** Auth client used for authenticated requests via `authClient.fetch(...)`
+
+## Return Value
+
+```typescript
+interface AIGatewayClient {
+  streamChatCompletion(request: AIGatewayChatRequest): AsyncIterable<AIChatCompletionEvent>;
+}
+```
+
+The iterable yields completion events:
+
+- `text-delta` — append `event.text` to build the assistant response
+- `done` — terminal event with an optional `finishReason`
+
+## Related Types
+
+```typescript
+type AIGatewayChatMessage =
+  | {
+      role: "system" | "user";
+      content: string;
+    }
+  | {
+      role: "assistant";
+      content?: string;
+    };
+
+interface AIGatewayChatRequest {
+  model: string;
+  messages: AIGatewayChatMessage[];
+  signal?: AbortSignal;
+}
+
+type AIChatCompletionEvent =
+  | {
+      type: "text-delta";
+      text: string;
+    }
+  | {
+      type: "done";
+      finishReason?: string;
+    };
+```
+
+## Usage
+
+```typescript
+import { createAuthClient, createAIGatewayClient } from "@tailor-platform/app-shell";
+
+const authClient = createAuthClient({
+  clientId: "your-client-id",
+  appUri: "https://xyz.erp.dev",
+});
+
+const aiClient = createAIGatewayClient({
+  gatewayUri: "https://your-ai-gateway.example.com",
+  authClient,
+});
+
+let text = "";
+for await (const event of aiClient.streamChatCompletion({
+  model: "gpt-5-mini",
+  messages: [{ role: "user", content: "Hello" }],
+})) {
+  if (event.type === "text-delta") {
+    text += event.text;
+  }
+}
+
+console.log(text);
+```
+
+## Notes
+
+- AppShell chooses the appropriate AI Gateway transport automatically
+- The low-level API is intentionally narrow: text deltas plus completion metadata
+- `request.signal` is passed through so callers can abort in-flight work
+
+## Related
+
+- [Authentication Concept](../concepts/authentication.md)
+- [useAIChat](./use-ai-chat.md)

package/skills/app-shell-patterns/references/api/create-typed-paths.md

@@ -0,0 +1,117 @@
+---
+title: createTypedPaths
+description: Generate type-safe route paths from file-based routing
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/create-typed-paths.docs.outline.md — do not edit by hand. -->
+
+# createTypedPaths
+
+Generates type-safe route path helpers from file-based routing structure. Only available when using the Vite plugin.
+
+## Signature
+
+```typescript
+function createTypedPaths<T extends Record<string, PageEntry>>(pages: T): TypedPaths<T>;
+```
+
+## Parameters
+
+### `pages`
+
+- **Type:** `Record<string, PageEntry>`
+- **Required:** Yes
+- **Description:** Pages object from virtual module (auto-generated by Vite plugin)
+
+## Return Value
+
+Type-safe path builder functions for each route.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createTypedPaths } from "@tailor-platform/app-shell";
+import pages from "virtual:app-shell-pages";
+
+const paths = createTypedPaths(pages);
+
+// Type-safe navigation
+navigate(paths.products.detail({ id: "123" }));
+// Result: "/products/123"
+```
+
+### With useNavigate
+
+```typescript
+import { useNavigate } from "@tailor-platform/app-shell";
+
+function ProductCard({ product }: { product: Product }) {
+  const navigate = useNavigate();
+  const paths = createTypedPaths(pages);
+
+  const handleClick = () => {
+    navigate(paths.products.detail({ id: product.id }));
+  };
+
+  return <button onClick={handleClick}>View Details</button>;
+}
+```
+
+### With Link Component
+
+```typescript
+import { Link } from "@tailor-platform/app-shell";
+
+function ProductLink({ id }: { id: string }) {
+  const paths = createTypedPaths(pages);
+
+  return (
+    <Link to={paths.products.detail({ id })}>
+      View Product
+    </Link>
+  );
+}
+```
+
+### Nested Routes
+
+```typescript
+// File structure:
+// pages/
+//   orders/
+//     page.tsx
+//     [id]/
+//       page.tsx
+//       edit/
+//         page.tsx
+
+paths.orders.index(); // "/orders"
+paths.orders.detail({ id: "1" }); // "/orders/1"
+paths.orders.edit({ id: "1" }); // "/orders/1/edit"
+```
+
+## TypeScript Benefits
+
+```typescript
+// ✅ Type-safe parameters
+paths.products.detail({ id: "123" }); // Valid
+
+// ❌ Type error - missing required param
+paths.products.detail(); // Error: Argument required
+
+// ❌ Type error - wrong param name
+paths.products.detail({ productId: "123" }); // Error: Unknown key
+```
+
+## File-Based Routing Only
+
+This function is only available when using the Vite plugin with file-based routing.
+
+See [File-Based Routing](../concepts/file-based-routing.md) for setup.
+
+## Related
+
+- [File-Based Routing](../concepts/file-based-routing.md) - Setup guide
+- [useNavigate](./router/use-navigate.md) - Programmatic navigation

package/skills/app-shell-patterns/references/api/define-i18n-labels.md

@@ -0,0 +1,143 @@
+---
+title: defineI18nLabels
+description: Define internationalized labels for multi-language support
+---
+
+<!-- GENERATED by docs-kit from docs-src/hooks/define-i18n-labels.docs.outline.md — do not edit by hand. -->
+
+# defineI18nLabels
+
+Creates internationalized labels that automatically resolve based on the current locale.
+
+## Signature
+
+```typescript
+function defineI18nLabels<T extends Record<string, Record<string, string>>>(
+  labels: T,
+): I18nLabels<T>;
+```
+
+## Parameters
+
+### `labels`
+
+- **Type:** `Record<string, Record<string, string>>`
+- **Required:** Yes
+- **Description:** Object mapping label keys to locale-specific strings
+
+## Return Value
+
+```typescript
+{
+  t: (key: keyof T) => LocalizedString;
+}
+```
+
+## Usage
+
+### Basic Labels
+
+```typescript
+import { defineI18nLabels } from "@tailor-platform/app-shell";
+
+const labels = defineI18nLabels({
+  dashboard: {
+    en: "Dashboard",
+    ja: "ダッシュボード",
+  },
+  products: {
+    en: "Products",
+    ja: "商品",
+  },
+  settings: {
+    en: "Settings",
+    ja: "設定",
+  },
+});
+
+// Use in modules
+const dashboardModule = defineModule({
+  path: "dashboard",
+  meta: {
+    title: labels.t("dashboard"),
+  },
+  component: DashboardPage,
+});
+```
+
+### Multiple Locales
+
+```typescript
+const labels = defineI18nLabels({
+  welcome: {
+    en: "Welcome",
+    ja: "ようこそ",
+    es: "Bienvenido",
+    fr: "Bienvenue",
+  },
+});
+```
+
+### In Components
+
+```typescript
+function WelcomeMessage() {
+  const labels = defineI18nLabels({
+    greeting: {
+      en: "Hello",
+      ja: "こんにちは",
+    },
+  });
+
+  return <h1>{labels.t("greeting")}</h1>;
+}
+```
+
+### With SidebarGroup
+
+```typescript
+import { SidebarGroup } from "@tailor-platform/app-shell";
+
+const labels = defineI18nLabels({
+  admin: {
+    en: "Administration",
+    ja: "管理",
+  },
+});
+
+<SidebarGroup title={labels.t("admin")}>
+  <SidebarItem to="/admin/users" />
+</SidebarGroup>
+```
+
+## Setting Locale
+
+The active locale is controlled by the `locale` prop on `AppShell`:
+
+```typescript
+<AppShell locale="ja" modules={modules}>
+  <SidebarLayout />
+</AppShell>
+```
+
+Supported locales: `en`, `ja`
+
+If not specified, auto-detects from browser settings.
+
+## TypeScript
+
+Full type safety:
+
+```typescript
+const labels = defineI18nLabels({
+  dashboard: { en: "Dashboard", ja: "ダッシュボード" },
+  products: { en: "Products", ja: "商品" },
+});
+
+labels.t("dashboard"); // ✅ Valid
+labels.t("invalid"); // ❌ Type error
+```
+
+## Related
+
+- [defineModule](./define-module.md) - Use labels in modules