admin-ui-starter-kit 0.1.0

package/.agents/skills/component-library-rules/references/item-pattern.md

@@ -0,0 +1,184 @@
+# `<Item>` — the canonical row primitive
+
+Open this when you're about to render a list of "icon/avatar/image media +
+title/description text-stack + optional actions" rows. Anywhere two adjacent
+surfaces currently disagree on `py-1.5` vs `py-2.5` is the smell `Item` is
+supposed to fix.
+
+Source: [`@/components/base/item`](../../../src/components/base/item).
+Wraps: shadcn `ui/item.tsx` (do not edit per rule 1).
+
+## Compound parts
+
+| Part | Renders | Notes |
+| --- | --- | --- |
+| `<ItemGroup>` | `<div role="list">` | Default gap follows row size; nest `<ItemSeparator />` between rows for hairline dividers. |
+| `<ItemSeparator>` | thin horizontal rule | Same `Separator` primitive shadcn ships. |
+| `<Item>` | row container | `size`, `variant`, polymorphic `render`. See below. |
+| `<ItemMedia variant="icon" \| "image" \| "avatar" \| "default">` | leading slot | `icon` sizes the icon to the row, `image` and `avatar` get sized image-square / round. |
+| `<ItemContent>` | text-stack column | Hosts title + description + any inline content (progress bar, metric grid). |
+| `<ItemTitle>` | strong primary line | Internally `<Text weight="semibold">`; pass `bold={false}` for body-weight. |
+| `<ItemDescription>` | secondary line | Internally `<Text size="xs" type="secondary">`; `clamp={1\|2\|3\|4\|'none'}`, default 2. |
+| `<ItemActions>` | trailing slot | Buttons, badges, switches, chevrons. |
+| `<ItemHeader>` | full-width eyebrow above the row | Use for "vendor + status" or section labels. |
+| `<ItemFooter>` | full-width footer beneath the row | Use for "publisher · date" or last-active timestamps. |
+
+## `size` and `variant`
+
+Resolve through `<UIProvider>` via the `useItemConfig()` slice:
+
+| Slice key | Default | Effect |
+| --- | --- | --- |
+| `item.defaultSize` | `'sm'` | `xs` (dropdowns), `sm` (admin density, library default), `default` (settings rows). |
+| `item.defaultVariant` | `'default'` | `'default'` (transparent), `'outline'` (bordered card-on-card), `'muted'` (inset list). |
+
+Resolution order: `props.size ?? useItemConfig().defaultSize ?? 'sm'`. Same for
+variant. Omit the prop unless you're intentionally pinning the size against
+provider configuration.
+
+## Canonical shapes
+
+### Plain icon row
+
+```tsx
+<ItemGroup>
+  <Item>
+    <ItemMedia variant="icon"><Mail /></ItemMedia>
+    <ItemContent>
+      <ItemTitle>kira@example.com</ItemTitle>
+      <ItemDescription clamp={1}>Primary contact</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Button buttonStyle="ghost" variant="secondary">Copy</Button>
+    </ItemActions>
+  </Item>
+</ItemGroup>
+```
+
+### Avatar row with badge action
+
+```tsx
+<Item>
+  <ItemMedia variant="avatar">
+    <Avatar>
+      <AvatarImage src={user.avatarUrl} alt={user.name} />
+      <AvatarFallback>{initials}</AvatarFallback>
+    </Avatar>
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>{user.name}</ItemTitle>
+    <ItemDescription clamp={1}>{user.role}</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Badge variant="secondary">{user.dept}</Badge>
+  </ItemActions>
+</Item>
+```
+
+### Body-weight title (contact details, line items)
+
+```tsx
+<Item size="xs" className="px-0">
+  <ItemMedia variant="icon" className="text-muted-foreground"><Phone /></ItemMedia>
+  <ItemContent>
+    <ItemTitle bold={false}>{phone}</ItemTitle>
+  </ItemContent>
+</Item>
+```
+
+### Header + footer slots
+
+```tsx
+<Item variant="outline" size="default">
+  <ItemHeader>
+    <ItemTitle>Acme Workspace</ItemTitle>
+    <Badge variant="success">Active</Badge>
+  </ItemHeader>
+  <ItemMedia variant="image">
+    <img src={hero} alt="" />
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>Production environment</ItemTitle>
+    <ItemDescription>
+      Customer-facing storefront. Read-write for admins, read-only for analysts.
+    </ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Button buttonStyle="ghost" variant="secondary">Manage</Button>
+  </ItemActions>
+  <ItemFooter>
+    <span className="text-muted-foreground text-xs">Last deploy 12 minutes ago</span>
+    <span className="text-muted-foreground text-xs">3 collaborators</span>
+  </ItemFooter>
+</Item>
+```
+
+### Render as link (no extra `<a>` wrapper, focus styling preserved)
+
+```tsx
+<Item render={<a href="/dashboard" />}>
+  <ItemMedia variant="icon"><Home /></ItemMedia>
+  <ItemContent>
+    <ItemTitle>Dashboard</ItemTitle>
+    <ItemDescription>Overview of your workspace</ItemDescription>
+  </ItemContent>
+</Item>
+```
+
+## When to reach for it
+
+- Admin rows (`team-member`, `conversation-row`, `settings-toggle`).
+- Card detail rows (`contact-card` email/phone/location).
+- Settings menus, navigation rows (`category-nav`), dropdown rows.
+- Card *headers* with avatar + title + verified badge (`vendor-profile`,
+  `feature-announcement`, `inventory-level`, `giftcard-{dark,minimal}`
+  headers).
+- Citation source rows (`ai-citation`).
+- Two adjacent components disagreeing on `py-1.5` vs `py-2.5` density.
+
+## When NOT to reach for it
+
+- **Form inputs** — that's `FormField` / `ControlledFormField`. See
+  [`form-field-pattern.md`](form-field-pattern.md).
+- **Cards with header + body + footer that aren't list rows** — `SmartCard`.
+- **Hero/dashboard surfaces** with one big number + chart — `Metric`,
+  `GradientCard`, `MetricGradient`.
+- **Step ribbons / horizontal connector lines** —
+  `OrderStatusCard`, `ShipmentTrackingCard`, `BreadcrumbProgress` keep
+  their bespoke layout.
+- **Marker-rail timelines** — `ActivityRow`, `Timeline` from
+  `composed/timelines/shared`, `StepsCard`.
+- **Inline pills / chips** — `Badge`, `IconBadge`, `MetricTrendChip`.
+- **Filter popover headers** — `features/filters` has its own bespoke
+  back-button + clear-button structure inside the popover.
+
+## Migrating an existing row
+
+1. Find the icon → text-stack → trailing-content flex block.
+2. Replace the wrapping `<div className="flex items-center gap-3 px-3 py-2.5">`
+   with `<Item>` and the children with `ItemMedia`, `ItemContent`,
+   `ItemActions`.
+3. Strip the bespoke `<Text weight="semibold">` and
+   `<Text size="xs" type="secondary">` — `ItemTitle` / `ItemDescription`
+   handle those.
+4. Drop manual padding overrides; the size token (`xs` / `sm` / `default`)
+   provides density.
+5. If multiple rows render in a list, wrap them in `<ItemGroup>` so the
+   group gap follows size.
+6. Verify in the matching preview page (`/composed/<group>`) — zero
+   console warnings, item visually identical or denser by one notch
+   (often the goal).
+
+## Common pitfalls
+
+- **Wrapping the row in `<button>`/`<a>` yourself** — use `render={<a />}`
+  or `onClick` on `<Item>` directly. Wrapping breaks the focus ring.
+- **Putting the title's badge/icon in `ItemActions`** — if it's part of the
+  identity (verified checkmark next to a name), put it inline inside
+  `ItemTitle`. `ItemActions` is for trailing affordances, not title
+  decoration.
+- **Setting `size` per-row** — let the provider drive density. Pin only
+  for genuinely-different rows (e.g. `size="default"` for a hero settings
+  row inside an `xs`-default app).
+- **Adding `bg-muted` and `border` manually** — that's `variant="muted"`
+  and `variant="outline"`.

package/.agents/skills/component-library-rules/references/layout.md

@@ -0,0 +1,120 @@
+# Working in the `layout/` layer
+
+The `layout/` layer ships **page shells** — structural chrome that wraps a
+consumer's app: containers, page headers, topbars, sidebars, navigation
+rows, account menus, notifications. It is a peer of `composed/`, sits
+above `base/` + `typography/`, and **never imports `composed/` or
+`features/`**. (Layer order, rule 2.)
+
+A more detailed living-document of the layer's conventions is the
+package-local README at
+[`src/components/layout/README.md`](../../../src/components/layout/README.md).
+Read it first when working in this layer; this guide complements it with
+the rule-skill perspective.
+
+## Folder shape
+
+```
+src/components/layout/
+├── containers/         — Container, ScrollContainer
+├── header/             — Header, HeaderSearch, HeaderUserMenu, HeaderBreadcrumbs
+│   └── partials/
+├── page/               — Page, PageHeader, PageActions
+├── sidebar/            — AppSidebar, Sidebar primitives, SidebarNavigation
+│   ├── components/
+│   └── sidebar.context.tsx
+├── hooks/              — layout-only hooks (e.g. mobile breakpoint glue)
+├── index.ts            — public surface
+├── layout.types.tsx    — shared types
+└── README.md           — package-local conventions (admin density, navigation contract)
+```
+
+## Hard constraints
+
+1. **No imports from `composed/` or `features/`.** Layout chrome is the
+   surface a feature mounts *into*, not the other way around.
+2. **No framework integration imports.** Same rule as everywhere else —
+   no `@inertiajs/*`, `next/*`, `react-router*`, `@tanstack/react-router`,
+   `@tanstack/react-query`, `vite-bundled-i18n/*`, `ziggy-js`. The
+   consumer wires routing via `renderLink`/`onSelect` (see below).
+3. **Reach into `ui/` only via the matching `base/` wrapper.** The
+   sidebar/sheet primitives are wrapped in `base/sidebar/` and
+   `base/sheet/`; layout imports those, not the raw shadcn files.
+4. **Admin-density typography.** `Badge size="xs"`, `Button size="sm"`,
+   icon-only header controls use `icon-sm`. Primary labels and row text
+   default to `Text size="sm"`; descriptions and helper copy use
+   `Text size="xs"`. Don't push beyond `Text size="base"` in layout —
+   page hierarchy belongs in `PageHeader`.
+
+## Navigation contract — `renderLink`
+
+The library can't hardcode a router. Every layout component that renders
+a link accepts a `renderLink` render-prop:
+
+```tsx
+type RenderLink = (link: {
+    href: string;
+    children: ReactNode;
+    isActive?: boolean;
+    icon?: LucideIcon;
+    badge?: ReactNode;
+}) => ReactElement;
+```
+
+Default behaviour: render a plain `<a href>` if `renderLink` is absent.
+Consumers wire it once at the root:
+
+```tsx
+<AppSidebar renderLink={(l) => <Link to={l.href}>{l.children}</Link>}>
+```
+
+For a framework router:
+
+```tsx
+<AppSidebar renderLink={(l) => <AppLink href={l.href}>{l.children}</AppLink>}>
+```
+
+If a layout component needs to *select* a target without rendering a
+link (e.g. a workspace switcher dropdown), it accepts `onSelect(value)`
+and the consumer dispatches `router.visit(...)` themselves.
+
+## Sidebar specifics
+
+- `AppSidebar` is the canonical shell. It wraps `base/sidebar/`'s
+  compound parts (`SidebarProvider`, `SidebarContent`, …).
+- A sidebar's mobile mode uses `base/sheet/` under the hood — already
+  wired inside `base/sidebar/`.
+- Pass nav data declaratively as props (`sections`, `items`,
+  `footerItems`) — never reach for a routing context.
+- For workspace / org switcher: the `<SidebarWorkspaceDropdown>` accepts
+  a `workspaces` array + `onSelect(workspaceId)` callback. The library
+  doesn't fetch.
+
+## Page header
+
+`<PageHeader>` is `Heading h2 + optional badge + optional description +
+trailing actions`. Don't hand-roll alternative page chrome — extend
+`<PageHeader>` with a slot if a specific surface needs more.
+
+## Strings
+
+Layout components with user-facing copy follow rule 8: each component
+exports a `*Strings` interface and `default*Strings`, deep-merged via
+`useStrings(defaults, override)`. A consumer maps their i18n once at the
+mount site:
+
+```tsx
+<HeaderUserMenu strings={{ signOut: t('auth.sign_out') }} … />
+```
+
+## What does NOT belong here
+
+- Domain widgets (analytics cards, comment threads, AI surfaces) — those
+  are `composed/` or `features/`.
+- App state stores — `<UIProvider>` is the only library provider.
+  Anything else is the consumer's job.
+- "Utility" hooks that aren't layout-specific — those go in
+  `src/hooks/`.
+
+When in doubt, mirror the closest existing example
+(`AppSidebar`, `Header`, `PageHeader`) and let layer order decide.

package/.agents/skills/component-library-rules/references/new-feature.md

@@ -0,0 +1,109 @@
+# Adding a new feature folder
+
+Open this when creating `src/components/features/$feature/` from scratch.
+
+## Folder shape (rule 11)
+
+```
+features/$feature/
+├── index.ts                # public exports only — the package surface
+├── $feature.types.ts       # shared types
+├── $feature.strings.ts     # `<Feature>Strings` interface + `default<Feature>Strings`
+├── $feature.tsx            # main entry component
+├── partials/               # internal pieces, exported via index.ts when reusable
+│   └── index.ts            # barrel
+└── hooks/                  # feature-specific hooks
+    └── index.ts            # barrel
+```
+
+`hooks/` and `partials/` are optional when the feature is a single component with no internal state machine. They are mandatory the moment you have a second renderable piece or a non-trivial state hook.
+
+There is **no** `adapters/` folder. Framework wiring happens at the consumer's call site — the library never imports `@inertiajs/*`, `@tanstack/react-router`, `next/*`, `react-router*`, `vite-bundled-i18n/*`, `ziggy-js`, or any backend SDK.
+
+## Acceptance criteria
+
+When you're done, all four MUST be true:
+
+1. `import { Feature, useFeature } from '@/components/features/$feature'` works inside this repo, and `import { Feature } from 'admin-ui-starter-kit/features/$feature'` works from a fresh consumer with only this feature's required peers installed.
+2. Every internal partial is either re-exported from `index.ts` OR overridable via a render-prop / slot on the main component.
+3. Every user-facing string is overridable via `<Feature strings={{ … }} />` deep-merged over `default<Feature>Strings`.
+4. The feature accepts callbacks (`onSubmit`, `onDelete`, `onSelect`, `fetcher`, `onResultSelect`, …) — never imports a router, query lib, or i18n hook.
+
+## Reference implementations
+
+| Pattern | Look at |
+| --- | --- |
+| Folder shape, slots, headless hook | `features/global-search/` |
+| Provider + exported partials + headless config | `features/filters/` |
+| Strings file, accessors, editor slot | `features/comments/` |
+| Multi-interface strings file | `features/mentions/` |
+| Two implementation modes sharing one strings file | `features/rich-text-editor/` (Tiptap + Fallback) |
+
+If your folder doesn't structurally resemble at least one of these, stop and re-read [`../SKILL.md`](../SKILL.md) rule 11.
+
+## Boilerplate
+
+```ts
+// $feature.strings.ts
+export interface FeatureStrings {
+    title: string;
+    emptyState: string;
+}
+
+export const defaultFeatureStrings: FeatureStrings = {
+    title: 'Feature',
+    emptyState: 'Nothing here yet',
+};
+```
+
+```ts
+// $feature.types.ts
+import type { StringsProp } from '@/lib/strings';
+import type { FeatureStrings } from './$feature.strings';
+
+export interface FeatureProps {
+    items: ReadonlyArray<{ id: string; label: string }>;
+    onSelect?: (id: string) => void;
+    strings?: StringsProp<FeatureStrings>;
+    className?: string;
+}
+```
+
+```tsx
+// $feature.tsx
+import { useStrings } from '@/lib/strings';
+import { defaultFeatureStrings } from './$feature.strings';
+import type { FeatureProps } from './$feature.types';
+
+export function Feature({ items, onSelect, strings: stringsProp, className }: FeatureProps) {
+    const strings = useStrings(defaultFeatureStrings, stringsProp);
+    if (items.length === 0) return <div>{strings.emptyState}</div>;
+    return /* … */;
+}
+```
+
+```ts
+// index.ts
+export { Feature } from './$feature';
+export {
+    defaultFeatureStrings,
+    type FeatureStrings,
+} from './$feature.strings';
+export type { FeatureProps } from './$feature.types';
+```
+
+## Don'ts
+
+- ❌ Drop user-facing strings inline as JSX literals.
+- ❌ Import from any framework integration package — even "just for now".
+- ❌ Use `{ ...DEFAULT, ...override }` shallow merge instead of `useStrings(defaults, override)`.
+- ❌ Create an `adapters/` subfolder.
+- ❌ Add a feature without a strings file just because you "don't have any user-facing strings yet" — you will, and adding the file later means re-touching every importer.
+
+## After landing
+
+Add a showcase docs pair under `src/preview/pages/features/`:
+`$feature.examples.tsx` for named live examples and `$feature.mdx` for
+`DocsPage` / `Section` / `Example` / `PropsTable` documentation. Register the
+MDX page in `src/preview/registry.tsx`, then run `npm run docs:generate-props`
+and `npm run docs:sync-skill` (see [`preview-pages.md`](preview-pages.md)).

package/.agents/skills/component-library-rules/references/preview-pages.md

@@ -0,0 +1,153 @@
+# Preview pages and the showcase registry
+
+Open this when adding, moving, or refactoring a showcase page.
+
+## The contract
+
+Every MDX page under `src/preview/pages/**/*.mdx` MUST appear in
+`src/preview/registry.tsx`. Pages on disk that are not registered are dead —
+they exist but never appear in the showcase, so they silently rot.
+
+Each page normally has a sibling examples file:
+
+```
+src/preview/pages/<section>/<slug>.mdx
+src/preview/pages/<section>/<slug>.examples.tsx
+```
+
+The MDX file owns prose, sections, live example wrappers, and API tables. The
+examples file owns named React examples that import the real library components.
+
+## Adding a new preview page
+
+1. **Create** `src/preview/pages/<section>/<slug>.examples.tsx`. Sections:
+   `ui`, `base`, `common`, `composed`, `features`, `layout`.
+2. **Compose with the real components.** Import from
+   `@/components/base/...`, `@/components/composed/...`,
+   `@/components/features/...`, `@/components/layout/...`. Use real props and
+   realistic data, not a custom visual mock.
+3. **Create** `src/preview/pages/<section>/<slug>.mdx`. Import
+   `DocsPage`, `Section`, `Example`, and `PropsTable` from `@/preview/_docs`,
+   then render each named example through `<Example>`.
+4. **Register** in `src/preview/registry.tsx`:
+    ```ts
+    {
+        id: '<section>/<slug>',
+        label: 'Friendly name',
+        section: 'Composed',          // capitalized — PreviewEntry['section']
+        family: 'Cards',              // groups in the sidebar
+        component: lazy(() => import('./pages/composed/contact-card.mdx')),
+        status: 'ready',              // 'ready' | 'wip' | 'broken'
+    },
+    ```
+5. **Regenerate docs surfaces**:
+   `npm run docs:generate-props` and `npm run docs:sync-skill`.
+6. **Verify** in the running showcase — open the section tab and confirm the
+   entry appears under the right family.
+
+## Page anatomy
+
+```mdx
+import { DocsPage, Section, Example, PropsTable } from '@/preview/_docs';
+import * as Examples from './feature.examples';
+import examplesSource from './feature.examples?raw';
+
+<DocsPage
+    title="Features · Feature"
+    description="One-line description of what this surface does."
+    layer="features"
+    status="ready"
+    sourcePath="src/components/features/feature"
+>
+
+<Section title="Examples" id="examples">
+
+<Example name="Default" source={examplesSource}>
+    <Examples.Default />
+</Example>
+
+<Example name="StringsOverride" source={examplesSource}>
+    <Examples.StringsOverride />
+</Example>
+
+</Section>
+
+<Section title="API" id="api">
+
+#### Feature
+<PropsTable component="Feature" />
+
+</Section>
+
+</DocsPage>
+```
+
+```tsx
+// feature.examples.tsx
+import { useState } from 'react';
+import { Feature } from '@/components/features/feature';
+
+export function Default() {
+    const [value, setValue] = useState('');
+    return <Feature value={value} onChange={setValue} />;
+}
+
+export function StringsOverride() {
+    const [value, setValue] = useState('');
+    return (
+        <Feature
+            value={value}
+            onChange={setValue}
+            strings={{ title: 'Custom title' }}
+        />
+    );
+}
+```
+
+## Example rules
+
+Examples are public documentation and informal API tests. Keep them thin:
+
+- Import the actual shipped component or exported partial.
+- Keep reusable demo data in the examples file, not the MDX file.
+- Use `Row` / `Col` from `src/preview/PreviewLayout.tsx` only for simple demo
+  arrangement. Page chrome belongs to `DocsPage`, `Section`, and `Example`.
+- Avoid `// @ts-nocheck` on new examples. Existing converted examples may still
+  have it, but new work should be typed.
+
+## Forbidden — re-implementing the component
+
+A preview example that defines a "private" version of the component inline is a
+smell:
+
+```tsx
+// ❌ This is the rule-10 violation — a static visual mock with no
+//    `import { RichTextEditor } from '@/components/features/rich-text-editor'`.
+const TOOLBAR_BUTTONS = [{ icon: Bold, label: 'Bold' }, /* … */];
+export function Default() {
+    return /* … hand-rolled toolbar + body */;
+}
+```
+
+If the preview cannot drive the real component, the underlying feature is
+missing a slot, render-prop, exported partial, or fallback path. Fix the
+feature, then make the preview a thin demo.
+
+The one acceptable exception: when a feature genuinely cannot render in the
+showcase context because an optional peer is absent. In that case the feature
+itself ships a fallback, and the preview imports the real component which
+decides at runtime which path to take.
+
+## Status meanings
+
+- `'ready'` — production-grade, no known issues.
+- `'wip'` — under active development; some examples may not be stable yet.
+- `'broken'` — known to fail; surfaces a red dot so contributors notice.
+
+`status` defaults to `'ready'` if omitted.
+
+## When restructuring a feature folder
+
+If you move a partial from the feature root into `partials/`, double-check the
+examples that demo it. Update imports through the index barrel rather than
+direct paths so future moves do not break the showcase.

package/.agents/skills/component-library-rules/references/strings-pattern.md

@@ -0,0 +1,123 @@
+# Strings pattern — defaults + overrides via `useStrings`
+
+Open this when adding or refactoring a `*.strings.ts` file.
+
+## The shape
+
+One `*.strings.ts` per feature/composed surface, at the surface root. Contains:
+
+1. One or more `<Name>Strings` interfaces.
+2. A `default<Name>Strings` const for each interface.
+3. Nothing else (no helpers, no formatters, no JSX).
+
+```ts
+// features/feature-x/feature-x.strings.ts
+export interface FeatureXStrings {
+    title: string;
+    emptyState: string;
+    confidenceLevels: { low: string; medium: string; high: string };
+    // Templates take args so locales can re-order substitutions:
+    formatRowTitle: (count: number) => string;
+}
+
+export const defaultFeatureXStrings: FeatureXStrings = {
+    title: 'Feature X',
+    emptyState: 'Nothing here yet',
+    confidenceLevels: { low: 'Low', medium: 'Medium', high: 'High' },
+    formatRowTitle: (count) => `${count} items`,
+};
+```
+
+## Consuming in the component
+
+```tsx
+import { useStrings, type StringsProp } from '@/lib/strings';
+import { defaultFeatureXStrings, type FeatureXStrings } from './feature-x.strings';
+
+export interface FeatureXProps {
+    /* … other props … */
+    strings?: StringsProp<FeatureXStrings>;
+}
+
+export function FeatureX({ strings: stringsProp, ...rest }: FeatureXProps) {
+    const strings = useStrings(defaultFeatureXStrings, stringsProp);
+    return <h2>{strings.title}</h2>;
+}
+```
+
+`useStrings` deep-merges `stringsProp` over the defaults and memoises by override identity. Stable references avoid downstream re-renders. Inline literals work fine — the merge is trivial.
+
+## Multiple interfaces in one file
+
+When several partials in the same surface have related strings, keep them in **one** `*.strings.ts` file and export multiple interfaces:
+
+```ts
+// features/mentions/mentions.strings.ts
+export interface MentionPickerStrings { /* … */ }
+export const defaultMentionPickerStrings: MentionPickerStrings = { /* … */ };
+
+export interface MentionInlineSuggestionsStrings { /* … */ }
+export const defaultMentionInlineSuggestionsStrings: MentionInlineSuggestionsStrings = { /* … */ };
+```
+
+Each partial imports only its own slice from the shared file. Re-export the type from the partial if you want the existing public API to stay stable: `export type { MentionPickerStrings }`.
+
+## Multiple implementation modes sharing one strings interface
+
+`features/rich-text-editor/` has two implementations (Tiptap + Fallback). They share **one** strings file because the user-facing copy is identical regardless of which path runs. Each implementation independently calls `useStrings(defaultRichTextEditorStrings, stringsProp)`.
+
+## Re-exporting from the feature index
+
+```ts
+// features/feature-x/index.ts
+export { FeatureX } from './feature-x';
+export type { FeatureXProps } from './feature-x.types';
+
+// Strings — make defaults importable so consumers can build on them
+export {
+    defaultFeatureXStrings,
+    type FeatureXStrings,
+} from './feature-x.strings';
+```
+
+## Templates over interpolated strings
+
+Prefer functions over `{0}`-style templates when arguments need to move:
+
+```ts
+// ✅ Locales can rearrange
+formatGreeting: (name: string, count: number) => `Hello ${name}, you have ${count} messages.`
+
+// ❌ Hard for translators
+greeting: 'Hello {name}, you have {count} messages.'
+```
+
+The library has no concept of locales or translators — consumers map their backend i18n into the strings prop at the call site:
+
+```tsx
+<FeatureX
+    strings={{
+        title: t('feature_x.title'),
+        formatRowTitle: (n) => t('feature_x.row_title', { count: n }),
+    }}
+/>
+```
+
+## Migration checklist (refactoring inline strings)
+
+1. Identify every hardcoded user-facing literal in the component(s) — JSX text, `aria-label`, `placeholder`, `title`, error/empty messages.
+2. Create `<surface>.strings.ts` with one or more `<Name>Strings` interfaces + `default<Name>Strings` constants.
+3. Replace each literal with `strings.<key>`.
+4. Add `strings?: StringsProp<TStrings>` to the props interface.
+5. Call `useStrings(defaults, stringsProp)` once per component.
+6. Re-export from `index.ts`.
+7. Run `tsc -p tsconfig.app.json --noEmit --ignoreDeprecations 6.0`.
+
+## Don'ts
+
+- ❌ `const STRINGS = { … }` defined inline at module scope of a partial. Move to the strings file.
+- ❌ `{ ...DEFAULT, ...override }` shallow merge. Use `useStrings`.
+- ❌ Strings duplicated across partials in the same feature. Consolidate.
+- ❌ Strings shared across unrelated features. Each feature owns its own — no global strings file.
+- ❌ Calling `t()` / `useI18n()` inside the library. Backend i18n maps INTO the prop at the call site.
+- ❌ Skipping `useStrings` because "the override prop is empty most of the time". The hook is cheap; consistency matters more.