@dextinity/agent-features 10.0.1-canary-20260814073232 → 10.0.1

package/skills/dev-pm/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: dev-pm
+description: Run, restart, stop, and inspect logs/status of long-running development processes via dev-pm (dev-process-manager). Use when starting/stopping/restarting services, tailing logs of those processes, or checking which services are running. Do not use for one-off scripts (`npm run X` is fine for those) — dev-pm is for processes that stay alive.
+---
+
+# dev-pm Skill
+
+`dev-pm` (`dev-process-manager`) supervises long-running dev processes (servers, watchers, codegen, storybook, docker, …). Available scripts and groups are defined in `dev-pm.config.ts` at the repo root — read it to discover what can be started.
+
+## Critical rules
+
+1. **Always invoke through the package manager:** `npm exec -- dev-pm <command>`. Never call `dev-pm` directly. If `pnpm` is the active package manager for the project (e.g. a `pnpm-lock.yaml` is present), use `pnpm exec -- dev-pm <command>` instead.
+2. **Never use streaming flags from a tool call — they hang.** `logs` requires `-n` / `--lines <N>`; `status` must not get `--interval`; `start` / `restart` must not get `--follow`.
+3. **Services may already be running.** dev-pm runs as a daemon across sessions — check `status` before starting things again. Same applies to build watchers ("the build watcher is running" means dev-pm is supervising a `build:watch` script); if absent, build the affected package manually.
+4. **dev-pm owns _all_ long-running tasks — including docker.** If a project uses dev-pm, assume every long-lived process (servers, watchers, codegen, **and** `docker compose up`) is wired into `dev-pm.config.ts`. Don't reach for `docker compose up` / `docker compose down` directly — start/stop the corresponding dev-pm script (commonly named `docker`). Exceptions exist; only treat something as outside scope after confirming it's not in `dev-pm.config.ts`.
+
+## Commands
+
+Script/group names below are placeholders; the authoritative list is `dev-pm.config.ts`.
+
+### `start [patterns...]`
+
+```bash
+npm exec -- dev-pm start <script>      # one script
+npm exec -- dev-pm start @<group>      # a group
+npm exec -- dev-pm start <a> <b>       # multiple patterns
+```
+
+- `@`-prefix → group name (from `group: [...]` in the config). Bare → script `name`. Globs (minimatch) work too, e.g. `api-*`.
+- Already-running scripts are a no-op — safe to call again. To force a restart, use `restart`.
+
+### `status` / `list`
+
+```bash
+npm exec -- dev-pm status              # all scripts
+npm exec -- dev-pm status <pattern>    # filter
+```
+
+First stop when troubleshooting "is X running?".
+
+**Reading the output:**
+
+- **Status:**
+    - `Running` — script is up.
+    - `Waiting` — `waitOn` condition unmet (e.g. api waiting for the database, site waiting for the api). Will start when the dependency is ready; if it stays here, the dependency failed — check its logs.
+    - `Backoff` — process crashed; dev-pm is sleeping before respawn. Wait grows as `min(1.3 ^ restartCount, 10)` seconds, capped at 10s. Flapping `Backoff` means broken — read logs and fix the cause; restarting won't help.
+    - `Stopped` — not running (never started or manually stopped).
+- **Restarts:** healthy scripts sit at `0`. Anything `> 0` means dev-pm respawned a crash — pull logs (`logs --lines 300 <name>`).
+
+### `logs` / `log`
+
+```bash
+npm exec -- dev-pm logs --lines 200 <script>
+npm exec -- dev-pm log -n 500 <pattern>
+```
+
+Pick a line count for the question — 100–200 for a quick check, 500+ for startup/error history.
+
+### `restart [patterns...]`
+
+```bash
+npm exec -- dev-pm restart <script>
+npm exec -- dev-pm restart @<group>
+```
+
+Use after rebuilding a package whose consumers cache the old build, or after editing config the running process loaded at startup.
+
+### `stop [patterns...]`
+
+```bash
+npm exec -- dev-pm stop <script>
+npm exec -- dev-pm stop @<group>
+```
+
+Stops the matched scripts; the daemon stays alive.
+
+### `shutdown` / `halt`
+
+```bash
+npm exec -- dev-pm shutdown
+```
+
+Stops everything and shuts down the daemon. Only when the user explicitly asks to "stop everything" / "kill dev-pm". Don't use as a "reset state" hammer — prefer `restart <pattern>`.
+
+## Discovering scripts and groups
+
+`dev-pm.config.ts` exports a `scripts` array. Each entry has:
+
+- `name` — identifier for start/stop/logs.
+- `group` — group names usable with the `@` prefix.
+- `script` — underlying shell command (informational; don't run directly).
+- `waitOn` — files / TCP ports the script waits for (explains startup ordering).
+
+When the user names a service vaguely ("the api"), grep `dev-pm.config.ts` for the matching `name` rather than guessing.
+
+## Common workflows
+
+- **"Why isn't service X responding?"** → `status` → `logs --lines 200 <name>` → `restart <name>` after fixing the cause.
+- **"Edited a package, running service isn't picking it up"** → confirm the package's build watcher is in `status`; if not, build the package or start its watcher; then `restart` the consumer.
+- **"Verify service X still boots"** → `start <name>`, poll `logs --lines N` until the ready line or an error appears.

package/skills/dextinity-admin-ui/SKILL.md

@@ -0,0 +1,544 @@
+---
+name: dextinity-admin-ui
+description: Building or editing admin UI in a project that uses @dextinity/admin and its sibling packages — pages, dashboards, dialogs, widgets, layouts, or component styling. Use even for small UI changes, to build with Dextinity's theme, components, and helpers instead of custom sx/styled CSS, hard-coded values, or Box layouts.
+---
+
+# Building admin UIs with @dextinity/admin
+
+`@dextinity/admin` and its sibling packages ship a design system: a theme (spacing,
+colors, shadows, typography, breakpoints) and a library of ready-made components. For
+internationalization, Dextinity recommends `react-intl` (the default) to translate text, numbers, and
+dates. The components and types are available in the consuming project through the installed
+packages — import them directly (e.g. `import { Button, MainContent } from "@dextinity/admin"`).
+
+Build admin UI by composing what the design system already provides. Add custom styling only
+after the system genuinely can't express what you need.
+
+## Core principle
+
+**Prefer Dextinity's theme values, components, and helpers over custom styling.** Three reasons:
+
+1. **Reviewability.** When styling lives in the theme and in components, the markup stays
+   declarative and diffs stay small. A component that mixes `sx`, inline `style`, and `styled()`
+   is hard to read and hard to review — the layout, the styling, and the logic blur together.
+2. **Automatic upgrades.** A project's visual design is often built against a _future_ version of
+   the design system, so it won't fully match what the currently installed components and theme
+   produce. That gap is expected — it is not a reason to add custom styling to force the match.
+   Use the current Dextinity components and tokens as they are; a later library upgrade closes the gap
+   on its own, with no hand-written CSS to find and rework.
+3. **Consistency.** Every screen built from the same components and tokens looks and behaves the
+   same way.
+
+This holds **even when a project's design deliberately differs** from the current library defaults —
+a permanent design decision, not a gap a later library upgrade will close. Prefer the Dextinity component
+or token, and apply that project-specific difference by configuring the theme — not by re-styling
+individual components. Add custom styling only when explicitly instructed, or when no component, prop,
+or token can produce the result.
+
+## Decision framework
+
+Before writing any styling or markup, work down this list and stop at the first step that applies:
+
+1. **Is there a component for this?** Use it rather than assembling the same thing from
+   `Box` + CSS (page structure, cards, toolbars, dialogs, alerts, buttons, …).
+2. **Is there a prop for this?** Props apply the correct theme values with no CSS — e.g.
+   `elevation` / `square` on `Paper` and `Card`, `variant` on `Button` and `Typography`,
+   `spacing` on `Stack` and `Grid`.
+3. **Is there a theme value for this?** Read spacing, colors, and shadows from the theme
+   (`theme.spacing(n)`, `theme.palette.*`, `theme.shadows[n]`) instead of hard-coding pixels,
+   hex colors, or shadow strings.
+4. **Is there a helper for this?** User-facing text, numbers, and dates go through the i18n
+   helpers (`FormattedMessage`, `FormattedNumber`, `FormattedDate`), never hard-coded.
+5. **Only then, custom-style** — using `styled()` (not `sx` or inline `style`) and reading
+   values from the theme.
+
+## Styling and theme
+
+### Custom styling: `styled()`, not `sx` or inline `style`
+
+When you do need custom styling, write it with `styled()` from `@mui/material/styles` and give the
+result a name that says what it is. Styling in `sx` props or inline `style` mixes the look into the
+markup, so layout, styling, and logic blur together and the diff is harder to follow. A named
+styled component keeps the markup declarative and the styling in one place.
+
+```tsx
+// Avoid — sx and inline style mixed into the markup
+<Box sx={{ padding: 2, backgroundColor: "#fff", borderRadius: 1 }} style={{ marginTop: 16 }}>
+    {children}
+</Box>;
+
+// Prefer — a named styled component, styling separated from markup
+const Panel = styled("div")`
+    padding: ${({ theme }) => theme.spacing(2)};
+    background-color: ${({ theme }) => theme.palette.background.paper};
+`;
+
+<Panel>{children}</Panel>;
+```
+
+### Spacing and color: theme tokens, not hard-coded values
+
+Read spacing and color from the theme instead of typing pixels and hex codes. The theme is the
+single place those values are defined, so reading from it keeps every screen consistent and lets a
+theme change reach all of them at once. Dextinity's spacing base is `5px` — `theme.spacing(1)` is `5px`,
+`theme.spacing(2)` is `10px` — and it takes up to four arguments for top, right, bottom, and left.
+
+```tsx
+// Avoid — hard-coded pixels and colors
+const Header = styled("header")`
+    padding: 16px 24px;
+    color: #1a1a1a;
+    border-bottom: 1px solid #e0e0e0;
+`;
+
+// Prefer — spacing and palette tokens from the theme
+const Header = styled("header")`
+    padding: ${({ theme }) => theme.spacing(2, 3)};
+    color: ${({ theme }) => theme.palette.text.primary};
+    border-bottom: 1px solid ${({ theme }) => theme.palette.divider};
+`;
+```
+
+Use the palette tokens — `primary`, `secondary`, `error`, `warning`, `info`, `success`,
+`grey[50…900]`, `divider`, `text`, `background`, `action` — rather than naming raw colors.
+
+### Elevation and shape: `elevation` and `square`, not manual CSS
+
+Shadows and corner radius come from props on `Paper` and `Card`, not hand-written CSS. Dextinity defines
+four shadow elevations (1–4); higher values are `none`. The `elevation` prop selects one, and the
+`square` prop toggles the rounded corner. Read `theme.shadows[n]` directly only inside a `styled()`
+component that cannot be a `Paper` or `Card`.
+
+```tsx
+// Avoid — manual shadow and radius on a plain element
+<div style={{ boxShadow: "0 0 8px rgba(0,0,0,0.1)", borderRadius: 4 }}>{children}</div>
+
+// Prefer — a Paper carrying the theme's elevation and shape
+<Paper elevation={2}>{children}</Paper>
+```
+
+### Typography: `<Typography variant>`, not manual font CSS
+
+Render text through `<Typography>` with a variant rather than setting font size, weight, and line
+height by hand. The variant carries the type scale and its responsive steps, so headings and body
+text stay in proportion across breakpoints. Available variants: `h1`–`h6`, `body1`, `body2`,
+`subtitle1`, `subtitle2`, `caption`, `overline`, `list`, `listItem`, `button`.
+
+```tsx
+// Avoid — font properties set by hand
+const Title = styled("h2")`
+    font-size: 20px;
+    font-weight: 600;
+    line-height: 26px;
+`;
+
+// Prefer — a Typography variant from the type scale
+<Typography variant="h4">{title}</Typography>;
+```
+
+## Organizing styled components
+
+By default, define a component's styled parts at the bottom of its own file, below the component
+that uses them:
+
+```
+imports → types → component → styled components
+```
+
+When a file grows hard to read, refactor the component itself first — split it into smaller
+components and compose them, each keeping its own styled parts at the bottom. Move styles to a
+separate `*.sc.ts` sibling only when you are asked to, or when the styles grow but the component
+cannot be split logically. A `*.sc.ts` file is private to its equally-named component
+(`FooButton.sc.ts` belongs to `FooButton.tsx`). Don't import one component's `*.sc.ts` from another:
+that couples them through styling neither owns. When styling is shared, give it a single owner — a
+reusable component (below).
+
+When the same styled component is used by several components, it is no longer a styled part of any
+one of them. Promote it to its own reusable component: one export per file, named exactly as that
+export so it is easy to find, e.g. `SpecialButton.ts` exporting
+`export const SpecialButton = styled(Button)`. Group several small related ones into a single
+generically-named file only when explicitly instructed.
+
+## Internationalization
+
+Dextinity recommends `react-intl` (the default). When a project uses it, its user-facing text,
+numbers, and dates go through the `react-intl` helpers instead of being hard-coded.
+
+### Text: `<FormattedMessage>` and `useIntl`, not literals
+
+Use `<FormattedMessage>` wherever a ReactNode fits. String attributes (`alt`, `placeholder`,
+`title`, `aria-*`) take a string, not a ReactNode, so translate those with
+`useIntl().formatMessage()`.
+
+```tsx
+// Avoid — hard-coded user-facing text
+<Button>Save</Button>;
+<img src={src} alt="Preview" />;
+
+// Prefer — translate through react-intl (formatMessage for string attributes)
+import { FormattedMessage, useIntl } from "react-intl";
+
+<Button>
+    <FormattedMessage id="product.save" defaultMessage="Save" />
+</Button>;
+
+const intl = useIntl();
+<img src={src} alt={intl.formatMessage({ id: "product.previewAlt", defaultMessage: "Preview" })} />;
+```
+
+Interpolate runtime values with `values` rather than concatenating strings, and pluralize with ICU
+syntax rather than by hand:
+
+```tsx
+<FormattedMessage id="product.greeting" defaultMessage="Welcome, {name}" values={{ name }} />;
+
+// # is the formatted count
+<FormattedMessage id="product.cartCount" defaultMessage="{count, plural, one {# item in cart} other {# items in cart}}" values={{ count }} />;
+```
+
+### Numbers: `<FormattedNumber>` / `intl.formatNumber()`
+
+Format plain numbers, currency, and percentages through react-intl so grouping, decimals, and
+symbols follow the active locale rather than a hand-written format.
+
+```tsx
+// Avoid — raw or hand-formatted numbers (no locale grouping, decimals, or symbol)
+<span>{count}</span>;
+<span>{`${price.toFixed(2)} €`}</span>;
+<span>{`${Math.round(ratio * 100)}%`}</span>;
+
+// Prefer — locale-aware grouping and decimals, currency, and percent
+<FormattedNumber value={count} />;
+<FormattedNumber value={price} style="currency" currency="EUR" />;
+<FormattedNumber value={ratio} style="percent" />;
+```
+
+### Dates and times: `<FormattedDate>` / `<FormattedTime>`
+
+Render dates and times through react-intl so they follow the active locale rather than a
+hand-built format.
+
+```tsx
+// Avoid — hand-built date and time strings
+<span>{date.toLocaleDateString("en-US")}</span>;
+<span>{date.toLocaleTimeString("en-US")}</span>;
+
+// Prefer — locale-aware formatting
+<FormattedDate value={date} year="numeric" month="long" day="numeric" />;
+<FormattedTime value={date} />;
+```
+
+## Layout
+
+### Arranging elements: `Stack` and `Grid`, not `Box` with margins
+
+To arrange children and the space between them, use MUI's `Stack` (one-dimensional flow with a
+`spacing` prop) and `Grid` (responsive columns with `spacing` and `size`), imported from
+`@mui/material`. Both apply spacing from the theme through props, so you never hand-write the
+gaps. Use `Box` with manual `margin` only when neither fits.
+
+Pure layout — arranging children and the gaps between them — is fine inline through these props
+and needs no `styled()`. Anything beyond that (padding inside an element, background, borders,
+and other visual styling) goes through the theme and `styled()`, as in the styling section
+above.
+
+```tsx
+// Avoid — Box with hand-written margins between children
+<Box>
+    <Widget />
+    <Box sx={{ marginTop: 16 }}>
+        <Widget />
+    </Box>
+    <Box sx={{ marginTop: 16 }}>
+        <Widget />
+    </Box>
+</Box>;
+
+// Prefer — Stack with spacing from the theme
+<Stack spacing={4}>
+    <Widget />
+    <Widget />
+    <Widget />
+</Stack>;
+```
+
+```tsx
+// Avoid — manual flex and width math for a responsive two-column layout
+<Box sx={{ display: "flex", flexWrap: "wrap" }}>
+    <Box sx={{ width: "50%" }}>
+        <Widget />
+    </Box>
+    <Box sx={{ width: "50%" }}>
+        <Widget />
+    </Box>
+</Box>;
+
+// Prefer — Grid with responsive size and spacing from the theme
+<Grid container spacing={4}>
+    <Grid size={{ xs: 12, md: 6 }}>
+        <Widget />
+    </Grid>
+    <Grid size={{ xs: 12, md: 6 }}>
+        <Widget />
+    </Grid>
+</Grid>;
+```
+
+For responsive behaviour, pass a per-breakpoint object to these props (`size` on `Grid`,
+`direction` on `Stack`); inside a `styled()` component, use `theme.breakpoints` for media
+queries.
+
+Don't use `Grid` or `Stack` to lay out form fields: Dextinity stacks them vertically at full width,
+grouped with `FieldSet` or `FormSection`.
+
+`sx` is fine for an occasional layout property that no `Stack` or `Grid` prop covers, such as
+`flexGrow`. On your own markup, it is not for visual styling — that goes through `styled()`.
+
+### Page structure: `MainContent`, `Toolbar`, and their parts
+
+Wrap a page's body in `MainContent` rather than a hand-padded `Box` — it applies the standard
+page padding and can fill the height with `fullHeight`. Build the action bar from `Toolbar` and
+its parts instead of assembling one from a flex row:
+
+- `ToolbarTitleItem` holds the page title, `ToolbarActions` the action buttons; `ToolbarItem` is
+  the generic slot for anything else.
+- `FillSpace` is a flexbox spacer that fills the free space, moving the elements after it to the
+  end.
+
+```tsx
+// Avoid — hand-built toolbar and padded container
+<Box sx={{ display: "flex", padding: 16 }}>
+    <Typography variant="h4">{title}</Typography>
+    <Box sx={{ marginLeft: "auto" }}>
+        <Button>{addLabel}</Button>
+    </Box>
+</Box>;
+
+// Prefer — Toolbar parts and MainContent
+<Toolbar>
+    <ToolbarTitleItem>{title}</ToolbarTitleItem>
+    <FillSpace />
+    <ToolbarActions>
+        <Button>{addLabel}</Button>
+    </ToolbarActions>
+</Toolbar>;
+<MainContent>{children}</MainContent>;
+```
+
+When a page is rendered inside a Dextinity navigation `Stack` (nested master–detail views), use the
+`StackMainContent` and `StackToolbar` variants instead: they render only for the active stack
+level, so nested pages don't show duplicate toolbars.
+
+### Full-height content: `fullHeight` and `FullHeightContent`
+
+Content that should fill the viewport and scroll inside itself — most often a `DataGrid` — needs
+a height-bounded parent, or it grows the whole page instead of scrolling. Set that height through
+the page structure, not a hand-written `height` that has to track the header and toolbar offset:
+
+- When the grid is the page's direct content, add `fullHeight` to `MainContent` or
+  `StackMainContent`.
+- When the grid is nested inside `RouterTabs` or other content rather than placed directly in
+  `MainContent`, wrap it in `FullHeightContent`, which bounds the height at that level.
+- When the grid holds few rows, give the `DataGrid` the `autoHeight` prop instead and skip
+  `fullHeight`.
+
+```tsx
+// Avoid — a hand-set height that has to track the header and toolbar offset
+<MainContent>
+    <Box sx={{ height: "calc(100vh - 200px)" }}>
+        <DataGrid />
+    </Box>
+</MainContent>;
+
+// Prefer — fullHeight for a grid that is the page's direct content
+<StackMainContent fullHeight>
+    <DataGrid />
+</StackMainContent>;
+
+// Prefer — FullHeightContent for a grid nested inside tabs
+<MainContent>
+    <RouterTabs>
+        <RouterTab path="" label={label}>
+            <FullHeightContent>
+                <DataGrid />
+            </FullHeightContent>
+        </RouterTab>
+    </RouterTabs>
+</MainContent>;
+```
+
+## Components
+
+### Containers and widgets: `FieldSet`, `FormSection`, and themed `Card`, not `Box`
+
+To group related content, use a container component instead of a `Box` with hand-set padding,
+borders, and a title. `FieldSet` (from `@dextinity/admin`) is a collapsible titled panel — wrap a page
+form's fields in it. Inside a dialog or sidebar, group fields with `FormSection` instead, a lighter
+titled section with a divider. For a dashboard widget, if the project uses `@dextinity/cms-admin` (most
+do), use its ready-made `DashboardWidgetRoot` rather than building one by hand; when you compose a
+container yourself, build it from MUI's `Card` (with `CardHeader` and `CardContent`) or `Paper`, with
+`Typography` for text and `Grid` for layout — Dextinity themes `Card`, `Paper`, and `Typography`, so they
+carry the right elevation, radius, and type scale without custom CSS, while `Grid` takes its spacing
+from the theme. `Card`, `CardHeader`, `CardContent`, `Paper`, `Typography`, and `Grid` come from
+`@mui/material`; `FieldSet` and `FormSection` from `@dextinity/admin`.
+
+```tsx
+// Avoid — a Box hand-styled into a titled, bordered panel
+<Box sx={{ border: "1px solid #e0e0e0", borderRadius: 1, padding: 2 }}>
+    <Typography variant="h4">{title}</Typography>
+    {children}
+</Box>;
+
+// Prefer — FieldSet groups content under a title (collapsible by default)
+<FieldSet title={title} supportText={supportText}>
+    {children}
+</FieldSet>;
+
+// Prefer — a dashboard widget from @dextinity/cms-admin's ready-made container
+<DashboardWidgetRoot header={title}>{children}</DashboardWidgetRoot>;
+```
+
+### Buttons: `Button` variants and action buttons, not hand-styled buttons
+
+Give `Button` a `variant` rather than styling a button by hand or setting MUI's `color` directly.
+The variants are `primary`, `secondary`, `outlined`, `destructive`, `success`, `textLight`, and
+`textDark`. For common actions, prefer the specialized buttons: `SaveButton`, `CancelButton`,
+`DeleteButton`, and `OkayButton` each carry a suitable variant, an icon, and a translated label.
+`SaveButton` also has built-in loading, success, and error feedback (it is a `FeedbackButton`), so
+you don't hand-build that; use `FeedbackButton` for other async actions, and `CopyToClipboardButton`
+to copy text with a confirmation.
+
+```tsx
+// Avoid — a hand-styled button, and a Save button rebuilt from a plain Button
+<button style={{ background: "#c00", color: "#fff" }} onClick={onDelete}>
+    Delete
+</button>;
+<Button variant="primary" startIcon={<Save />}>
+    Save
+</Button>;
+
+// Prefer — specialized buttons carry variant, icon, and label (SaveButton adds save feedback)
+<DeleteButton onClick={onDelete} />;
+<SaveButton onClick={onSave} />;
+```
+
+### Date and time: pickers from `@dextinity/admin`, not raw inputs
+
+Enter dates and times through the picker components rather than a plain text input or an MUI picker
+configured by hand. `@dextinity/admin` exports `DatePicker`, `DateTimePicker`, and `TimePicker` (with
+`DateRangePicker` and `DateTimeRangePicker` for ranges), plus `DatePickerField` and siblings for use
+as Final Form fields. Each picker
+manages its own value format — `DatePicker`, for example, reads and writes an ISO `YYYY-MM-DD`
+string — so you don't parse or format dates by hand. The pickers need MUI X's `LocalizationProvider`
+at the app root, set up once with `AdapterDateFns`; pass `adapterLocale` to localize.
+
+```tsx
+// Avoid — a plain text input used as a date field
+<input type="text" value={value} onChange={(event) => onChange(event.target.value)} />;
+
+// Prefer — a DatePicker working with ISO date strings
+<DatePicker value={value} onChange={onChange} />;
+
+// The pickers need a LocalizationProvider at the app root, set up once
+import { LocalizationProvider } from "@mui/x-date-pickers";
+import { AdapterDateFns } from "@mui/x-date-pickers/AdapterDateFns";
+
+<LocalizationProvider dateAdapter={AdapterDateFns} adapterLocale={locale}>
+    {children}
+</LocalizationProvider>;
+```
+
+### Feedback and overlays: `Alert`, `Loading`, `Dialog`, `Tooltip`, not hand-built ones
+
+Show status, loading, dialogs, and tooltips through the components rather than assembling them from
+`div`s and state. `Alert` takes a `severity` (`info`, `warning`, `error`, `success`), a `title`, an
+`action`, and an `onClose`. `Loading` renders the standard spinner; its `behavior` prop (`auto`,
+`fillParent`, `fillParentAbsolute`, `fillPageHeight`) sets whether it renders inline, fills its
+parent, or fills the page. Use `Dialog` and `Tooltip` from `@dextinity/admin` — Dextinity's own wrappers, not
+MUI's directly. For a transient confirmation, call `showSnackbar()` from `useSnackbarApi()` with a
+snackbar element — Dextinity's `UndoSnackbar`, or a MUI `Snackbar` wrapping an `Alert` — and mount
+`SnackbarProvider` near the app root.
+
+```tsx
+// Avoid — a hand-built alert box and a hand-built spinner
+<div style={{ background: "#fdecea", padding: 12 }}>{errorMessage}</div>;
+{
+    loading && <div className="spinner" />;
+}
+
+// Prefer — Alert shows severity; Loading renders the standard spinner
+<Alert severity="error">{errorMessage}</Alert>;
+{
+    loading && <Loading />;
+}
+```
+
+### Icons: `@dextinity/admin-icons`, not ad-hoc SVGs
+
+Take icons from `@dextinity/admin-icons` rather than importing SVG files or an arbitrary
+icon from another set, so they match the design system and stay consistent. Each icon is a named
+export built on MUI's `SvgIcon`, so size it with the `fontSize` prop (`small`, `medium`, `large`) and
+color it with the `color` prop — the icons use `currentColor`.
+
+```tsx
+// Avoid — an imported SVG file, or an arbitrary icon from another set
+import deleteIcon from "./delete.svg";
+
+<img src={deleteIcon} width={16} alt="" />;
+
+// Prefer — a named icon from the Dextinity set, sized and colored through props
+import { Delete } from "@dextinity/admin-icons";
+
+<Delete fontSize="small" color="error" />;
+```
+
+## Customizing an existing Dextinity Admin component
+
+When a Dextinity Admin component needs to look or behave differently than its defaults, customize it
+through the mechanisms it already supports: the component's own props, a per-slot `slotProps` prop,
+and theme-level `styleOverrides` and `defaultProps`. A _slot_ is a named inner element of a component;
+only `root` is universal — a component lists its own slot names on its props type. Which mechanism you
+pick depends on whether you're changing behavior or appearance.
+
+### Behavior
+
+Start with the component's own props. To reach an inner element, use `slotProps`: it forwards props
+to a named slot, letting you override that slot's props. This configures the component rather than
+restyling it.
+
+```tsx
+// Override an inner slot's props — here, disable the button behind the content
+<ContentOverflow slotProps={{ clickableContent: { disabled: true } }}>{children}</ContentOverflow>
+```
+
+### Appearance
+
+To change how a Dextinity component looks, configure the theme rather than the component itself — the core
+principle's rule for a project-specific design difference. `createDextinityTheme`'s `components` map takes
+a `DextinityAdmin*` key (MUI components use their `Mui*` key); `styleOverrides` restyles a component's
+slots and `defaultProps` sets default prop values, such as swapping an icon through `iconMapping`.
+Both apply to every instance, so the deviation stays consistent and is defined in one reviewable place.
+
+Styling a single instance directly is the rare exception — for a change genuinely specific to that
+instance, or when you're explicitly told to. Which tool you use is then the same as anywhere else:
+`sx` (or `slotProps.<slot>.sx` for a slot) for small layout, `styled()` for other custom styling, per
+the styling section above. Use this only for a true single-instance change; a difference that recurs
+belongs in the theme, not repeated on each instance.
+
+```tsx
+// Avoid — a styled() wrapper for a design difference that belongs in the theme
+const HighlightedContentOverflow = styled(ContentOverflow)`
+    background-color: ${({ theme }) => theme.palette.grey[50]};
+`;
+
+// Prefer — configure the theme, applied to every instance
+const theme = createDextinityTheme({
+    components: {
+        DextinityAdminContentOverflow: {
+            styleOverrides: {
+                root: ({ theme }) => ({ backgroundColor: theme.palette.grey[50] }),
+            },
+        },
+    },
+});
+```