@skunkworksai/ui-kit 0.1.18

package/rules/command.md

@@ -0,0 +1,73 @@
+# AppCommand
+
+> Docs: https://ui-kit.vercel.app/docs/components/command
+
+```tsx
+import {
+  AppCommand,
+  AppCommandDialog,
+  AppCommandInput,
+  AppCommandList,
+  AppCommandEmpty,
+  AppCommandGroup,
+  AppCommandItem,
+  AppCommandShortcut,
+  AppCommandSeparator,
+} from "@/components/primitives/AppCommand"
+```
+
+## AppCommand
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `label` | `string` | - | Accessible label for the command menu. |
+| `shouldFilter` | `boolean` | `true` | Whether to filter items based on the search input. |
+
+## AppCommandInput
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `placeholder` | `string` | - | Placeholder text for the search input. |
+
+## AppCommandItem
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `onSelect` | `(value: string) => void` | - | Event handler called when the item is selected. |
+| `disabled` | `boolean` | - | Whether the item is disabled. |
+| `value` | `string` | - | Optional value for the item. Defaults to text content. |
+
+## Usage
+
+### Default Command Menu
+```tsx
+<AppCommand className="rounded-lg border shadow-md">
+  <AppCommandInput placeholder="Type a command or search..." />
+  <AppCommandList>
+    <AppCommandEmpty>No results found.</AppCommandEmpty>
+    <AppCommandGroup heading="Suggestions">
+      <AppCommandItem>Calendar</AppCommandItem>
+      <AppCommandItem>Search Emoji</AppCommandItem>
+      <AppCommandItem>Calculator</AppCommandItem>
+    </AppCommandGroup>
+    <AppCommandSeparator />
+    <AppCommandGroup heading="Settings">
+      <AppCommandItem>
+        <span>Profile</span>
+        <AppCommandShortcut>⌘P</AppCommandShortcut>
+      </AppCommandItem>
+      <AppCommandItem>
+        <span>Settings</span>
+        <AppCommandShortcut>⌘S</AppCommandShortcut>
+      </AppCommandItem>
+    </AppCommandGroup>
+  </AppCommandList>
+</AppCommand>
+```
+
+## Rules
+
+- **Do** use `AppCommand` for searchable lists and command palettes.
+- **Do** use `AppCommandDialog` for full-screen or modal command interfaces.
+- **Don't** forget to handle `onSelect` for interactive items.
+- If a prop you need is missing, stop and inform the design team.

package/rules/context-menu.md

@@ -0,0 +1,65 @@
+# AppContextMenu
+
+> Docs: https://ui-kit.vercel.app/docs/components/context-menu
+
+```tsx
+import {
+  AppContextMenu,
+  AppContextMenuTrigger,
+  AppContextMenuContent,
+  AppContextMenuItem,
+  AppContextMenuCheckboxItem,
+  AppContextMenuRadioItem,
+  AppContextMenuLabel,
+  AppContextMenuSeparator,
+  AppContextMenuShortcut,
+  AppContextMenuGroup,
+  AppContextMenuSub,
+  AppContextMenuSubContent,
+  AppContextMenuSubTrigger,
+  AppContextMenuRadioGroup,
+} from "@/components/primitives/AppContextMenu"
+```
+
+## AppContextMenuContent
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `loop` | `boolean` | `false` | Whether keyboard navigation should loop from last to first item. |
+
+## AppContextMenuItem
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `onSelect` | `(event: Event) => void` | - | Event handler called when the item is selected. |
+| `disabled` | `boolean` | - | Whether the item is disabled. |
+
+## Usage
+
+### Basic Context Menu
+```tsx
+<AppContextMenu>
+  <AppContextMenuTrigger className="flex h-32 w-64 items-center justify-center border border-dashed">
+    Right click here
+  </AppContextMenuTrigger>
+  <AppContextMenuContent className="w-56">
+    <AppContextMenuItem>
+      <span>Copy</span>
+      <AppContextMenuShortcut>⌘C</AppContextMenuShortcut>
+    </AppContextMenuItem>
+    <AppContextMenuItem>
+      <span>Paste</span>
+      <AppContextMenuShortcut>⌘V</AppContextMenuShortcut>
+    </AppContextMenuItem>
+    <AppContextMenuSeparator />
+    <AppContextMenuItem>Settings</AppContextMenuItem>
+  </AppContextMenuContent>
+</AppContextMenu>
+```
+
+## Rules
+
+- **Do** use `AppContextMenu` for secondary actions associated with a specific UI element.
+- **Do** include shortcuts using `AppContextMenuShortcut` where appropriate.
+- **Don't** overpopulate the context menu; keep it concise.
+- If a prop you need is missing, stop and inform the design team.

package/rules/dashboard.md

@@ -0,0 +1,368 @@
+# AppDashboard
+
+> **Single entry point** — Use this for every page. Do not compose the scaffold manually.
+
+## Import
+
+```tsx
+import { AppDashboard } from '@skunkworksai/ui-kit'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `nav` | `AppDashboardNavSection[]` | built-in default nav | Sidebar navigation sections. Omit to use the built-in UI Kit default. |
+| `header` | `Omit<AppHeaderProps, "className">` | `{}` | Props forwarded to `AppHeader`. Use to customize searchbar, actions, avatar, etc. |
+| `sidebarWidth` | `string` | `"14rem"` | Overrides the `--sidebar-width` CSS variable. |
+| `headerHeight` | `string` | `"3.5rem"` | Overrides the `--header-height` CSS variable. |
+| `mainClassName` | `string` | `"p-6"` | Extra classes on the main content area. |
+| `backgroundTheme` | `"dark" \| "light"` | `"dark"` | Locks sidebar, header, and background to a fixed mode regardless of page theme toggle. |
+| `animated` | `"auto" \| "on" \| "off"` | `"auto"` | Controls the canvas animation. `"auto"` honors `prefers-reduced-motion`; `"off"` renders gradient only — use for perf-constrained consumers. |
+| `background` | `ReactNode` | `<AppDashboardBackgroundWave />` | Background preset or custom component. Must render gradient. See Background presets section. |
+| `pageTitle` | `AppPageTitleProps \| false` | omitted | Page title bar below the header. Pass `false` to hide entirely. |
+| `brand` | `Omit<AppSidebarBrandProps, "className">` | `WhiteLogo` / `WhiteSymbol` | Props forwarded to `AppSidebarBrand`. Use to set a custom logo for expanded and collapsed sidebar states. |
+| `children` | `ReactNode` | required | Page content. |
+
+## Customising the header
+
+`AppDashboard` renders `AppHeader` internally. Pass the `header` prop to forward any `AppHeaderProps` to it:
+
+```tsx
+// Remove searchbar
+<AppDashboard header={{ searchbar: null }}>...</AppDashboard>
+
+// Remove avatar
+<AppDashboard header={{ avatar: null }}>...</AppDashboard>
+
+// Remove network select
+<AppDashboard header={{ networkSelect: null }}>...</AppDashboard>
+
+// No theme toggle or bento
+<AppDashboard header={{ showThemeToggle: false, showBento: false }}>...</AppDashboard>
+
+// Custom right-side actions (replaces entire actions slot)
+<AppDashboard header={{ actions: <AppButton>Save</AppButton> }}>...</AppDashboard>
+
+// Custom searchbar
+<AppDashboard header={{ searchbar: <AppInput placeholder="Find sites..." /> }}>...</AppDashboard>
+```
+
+See `rules/header.md` for the full `AppHeaderProps` reference.
+
+## Customising the brand
+
+`AppDashboard` renders `AppSidebarBrand` internally. Pass the `brand` prop to forward any `AppSidebarBrandProps` to it:
+
+```tsx
+// Custom SVG logo components (import from your own src/assets/logos)
+import { MyLogo, MySymbol } from './assets/logos'
+
+<AppDashboard
+  brand={{
+    logo: <MyLogo width={90} height={28} />,
+    collapsedLogo: <MySymbol width={24} height={24} />,
+  }}
+>
+  ...
+</AppDashboard>
+
+// With a brand switcher dropdown
+<AppDashboard
+  brand={{
+    logo: <MyLogo />,
+    collapsedLogo: <MySymbol />,
+    dropdown: [
+      { label: "Workspace A", onClick: () => switchWorkspace("a") },
+      { label: "Workspace B", onClick: () => switchWorkspace("b") },
+      { separator: true },
+      { label: "Create new", onClick: openCreateDialog },
+    ],
+  }}
+>
+  ...
+</AppDashboard>
+
+// Hide the dropdown chevron
+<AppDashboard brand={{ logo: <MyLogo />, showChevron: false }}>...</AppDashboard>
+```
+
+Logo rules:
+- Import logos from `./assets/logos` — never from the package root
+- Use `WhiteLogo` / `WhiteSymbol` variants on dark backgrounds (default `backgroundTheme="dark"`)
+- Use `PrimaryLogo` / `PrimarySymbol` on light backgrounds (`backgroundTheme="light"`)
+- Pass SVG React components — not `<img>` tags or PNG paths
+
+## Background theme
+
+The `backgroundTheme` prop locks sidebar, header, and background to a fixed mode. The main content area still responds to the page theme toggle independently.
+
+```tsx
+// Dark background (default)
+<AppDashboard backgroundTheme="dark">
+  <PageContent />
+</AppDashboard>
+
+// Light background
+<AppDashboard backgroundTheme="light">
+  <PageContent />
+</AppDashboard>
+```
+
+Set once in the root layout — do not change per page.
+
+## Background presets
+
+`AppDashboard` accepts a `background` prop for swapping the background visual. Omit it for the default Wave.
+
+```tsx
+import { AppDashboardBackgroundWave, AppDashboardBackgroundDots } from '@skunkworksai/ui-kit'
+
+// Default — same as omitting the prop
+<AppDashboard background={<AppDashboardBackgroundWave />}>...</AppDashboard>
+
+// Dot grid
+<AppDashboard background={<AppDashboardBackgroundDots />}>...</AppDashboard>
+
+// Custom — must render the gradient (sidebar/header have no background of their own)
+<AppDashboard background={<MyCustomBackground />}>...</AppDashboard>
+```
+
+| Preset | Description |
+|--------|-------------|
+| `AppDashboardBackgroundWave` | Perlin noise wave grid + mouse-follow glow. Default. |
+| `AppDashboardBackgroundDots` | Uniform dot grid. Dots fade near cursor (closer = lower opacity). |
+
+### Custom background contract
+
+Custom backgrounds receive `animated`, `interactive`, and `themeClass` from `AppDashboardBackgroundContext`:
+
+```tsx
+import { useAppDashboardBackgroundContext } from '@skunkworksai/ui-kit'
+
+function MyBackground() {
+  const { animated, interactive, themeClass } = useAppDashboardBackgroundContext()
+  return (
+    // gradient required — sidebar and header depend on it
+    <div className={`absolute inset-0 bg-gradient-to-br from-sidebar to-sidebar-accent ${themeClass}`}>
+      {animated && <canvas ... />}
+    </div>
+  )
+}
+```
+
+Rules:
+- **Must** render as `absolute inset-0`.
+- **Must** include `bg-gradient-to-br from-sidebar to-sidebar-accent` — sidebar and header have no own background.
+- **Must** apply `themeClass` from context so CSS tokens resolve correctly.
+- **Must** gate canvas/animation behind the `animated` flag from context.
+- **Never** hardcode colors — use CSS variables from `src/tokens/tokens-source.css`.
+
+## Background animation
+
+The canvas animation runs by default. Use `animated` to control it:
+
+```tsx
+// Default — animation on, respects OS reduced-motion setting
+<AppDashboard animated="auto">
+  <PageContent />
+</AppDashboard>
+
+// Force animation off — static gradient only (best for perf-constrained apps)
+<AppDashboard animated="off">
+  <PageContent />
+</AppDashboard>
+
+// Force animation on regardless of prefers-reduced-motion
+<AppDashboard animated="on">
+  <PageContent />
+</AppDashboard>
+```
+
+**When `animated="off"`:** no canvas element, no `requestAnimationFrame` loop, no glow — only the `bg-gradient-to-br from-sidebar to-sidebar-accent` base layer. Removes all CPU/GPU cost from the background.
+
+**When `animated="auto"` (default):** animation runs normally unless the user's OS has `prefers-reduced-motion: reduce` set, in which case the canvas is skipped automatically. No consumer code needed for accessibility compliance.
+
+## AppThemeProvider requirement
+
+The default header includes a theme toggle that requires `AppThemeProvider` in the tree:
+
+```tsx
+import { AppThemeProvider } from '@skunkworksai/ui-kit'
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <AppThemeProvider>{children}</AppThemeProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+Without it, the toggle renders but does nothing.
+
+## Nav types
+
+```ts
+type AppDashboardNavSection = {
+  label?: string
+  items: AppDashboardNavItem[]
+}
+
+type AppDashboardNavItem = {
+  title: string                                         // label and tooltip text
+  icon: React.ElementType                               // lucide-react icon component (not JSX, the component itself)
+  isActive?: boolean                                    // marks the current route
+  onClick?: (e: React.MouseEvent<HTMLElement>) => void  // click handler on the menu button / anchor
+  url?: string                                          // when set, renders button as <a href>
+}
+```
+
+## Router integration
+
+Use `url` + `onClick` together for router-driven navigation. `onClick` fires first — call `e.preventDefault()` to suppress the native anchor navigation, then call your router's navigate function.
+
+### react-router-dom
+
+```tsx
+import { useNavigate } from "react-router-dom"
+
+function Shell() {
+  const navigate = useNavigate()
+
+  const nav = [
+    {
+      items: [
+        {
+          title: "Dashboard",
+          icon: LayoutDashboard,
+          isActive: location.pathname === "/",
+          url: "/",
+          onClick: (e) => { e.preventDefault(); navigate("/") },
+        },
+        {
+          title: "Sites",
+          icon: MapPin,
+          isActive: location.pathname === "/sites",
+          url: "/sites",
+          onClick: (e) => { e.preventDefault(); navigate("/sites") },
+        },
+      ],
+    },
+  ]
+
+  return <AppDashboard nav={nav}>...</AppDashboard>
+}
+```
+
+If both `url` and `onClick` are set and `onClick` does **not** call `e.preventDefault()`, the anchor's native navigation runs after the handler.
+
+If only `onClick` is needed (no anchor href), omit `url` — the button renders as a `<button>` element.
+
+## usePageTitle hook
+
+Pages declare their own title from within the page component — no shell wiring required.
+
+```tsx
+import { usePageTitle } from "@skunkworksai/ui-kit"
+
+function IncidentsPage() {
+  usePageTitle({
+    title: "Incidents",
+    subtitle: "Active alerts across all sites.",
+    breadcrumbs: [{ label: "Dashboard", href: "/" }, { label: "Incidents" }],
+    actions: <AppButton>+ New Alert</AppButton>,
+  })
+
+  return <div>...</div>
+}
+
+// In the shell — no pageTitle prop needed on AppDashboard
+<AppDashboard nav={nav}>
+  <IncidentsPage />
+</AppDashboard>
+```
+
+**Rules:**
+- Must be called inside a component rendered within `AppDashboard` — throws outside that tree.
+- Clears automatically on unmount.
+- `pageTitle` prop on `AppDashboard` is the fallback — `usePageTitle` takes priority when both are set.
+- Pass a stable object (top-level const or `useMemo`) to avoid unnecessary re-renders.
+
+## Usage examples
+
+### Minimal (default everything)
+
+```tsx
+<AppDashboard>
+  <p>Page content here.</p>
+</AppDashboard>
+```
+
+### Custom nav
+
+```tsx
+const nav = [
+  { items: [{ title: "Home", icon: Home, isActive: true }] },
+  { label: "Manage", items: [{ title: "Sites", icon: MapPin }] },
+]
+
+<AppDashboard nav={nav}>
+  <PageContent />
+</AppDashboard>
+```
+
+### No searchbar, no avatar
+
+```tsx
+<AppDashboard header={{ searchbar: null, avatar: null }}>
+  <PageContent />
+</AppDashboard>
+```
+
+### Full-bleed content area
+
+```tsx
+<AppDashboard mainClassName="p-0">
+  <FullBleedContent />
+</AppDashboard>
+```
+
+### With page title
+
+```tsx
+<AppDashboard
+  pageTitle={{
+    title: "Sites",
+    subtitle: "Manage and monitor all sites.",
+    breadcrumbs: [{ label: "Dashboard", href: "/" }, { label: "Sites" }],
+    actions: <AppButton>+ Add Site</AppButton>,
+  }}
+>
+  <PageContent />
+</AppDashboard>
+```
+
+## Rules
+
+- **Do** use `AppDashboard` as the layout for every page — do not compose the scaffold manually.
+- **Do** omit `nav` when the UI Kit default nav is sufficient.
+- **Do** set `isActive` on exactly one nav item per page when using custom `nav`.
+- **Do** pass icons as `React.ElementType` (the component, not `<Icon />`).
+- **Do** use `url` + `onClick` on nav items for router integration — never wire up sidebar DOM queries.
+- **Do** use `usePageTitle()` in page components to declare titles — avoids growing switch/map in the shell.
+- **Do** customize the header via the `header` prop — never rebuild `AppHeader` yourself inside `AppDashboard`.
+- **Don't** add `bg-*`, `dark`, or `border-*` to anything wrapping `AppDashboard`. Use `backgroundTheme` instead.
+- **Do** set `animated="off"` in perf-constrained consumer apps (older hardware, low-end mobile-web, slow networks).
+- **Don't** conditionally toggle `animated` at runtime — it triggers a component remount. Set it once at the root layout level.
+- **Don't** import `AppDashboardContent`, `AppDashboardMain`, `AppSidebarProvider`, `AppHeader`, etc. to rebuild the scaffold yourself.
+- **Don't** use DOM queries (`data-sidebar="menu-button"`) to bridge sidebar clicks to a router — use the `onClick` prop on nav items.
+- **Don't** hardcode color values — all colors come from CSS variables.
+
+If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+On mobile (<768px) the sidebar collapses to a Sheet drawer toggled via the header trigger; `AppDashboardMain` has no top-left rounding and uses `p-4` padding. On desktop (≥768px) rounding restores to `rounded-tl-3xl`, padding increases to `p-6`, and the Perlin canvas background re-enables mouse interaction. No consumer changes are needed — layout adapts automatically based on viewport width.

package/rules/data-table.md

@@ -0,0 +1,91 @@
+# AppDataTable
+
+> Docs: https://ui-kit.vercel.app/docs/components/data-table
+
+```tsx
+import { AppDataTable, type AppDataTableProps } from "@skunkworksai/ui-kit"
+import type { ColumnDef } from "@tanstack/react-table"
+```
+
+## AppDataTable
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `TData[]` | required | Row data array. |
+| `columns` | `ColumnDef<TData, TValue>[]` | required | Column definitions (from `@tanstack/react-table`). |
+| `filterColumn` | `string` | first column's `accessorKey` | Column key to filter on. |
+| `filterPlaceholder` | `string` | `"Filter..."` | Filter input placeholder text. |
+| `pageSize` | `number` | `10` | Rows per page. |
+| `enableSorting` | `boolean` | `true` | Click-to-sort on column headers. |
+| `enableFiltering` | `boolean` | `true` | Show filter text input. |
+| `enablePagination` | `boolean` | `true` | Show pagination controls. |
+| `enableColumnVisibility` | `boolean` | `true` | Show columns toggle dropdown. |
+| `className` | `string` | — | Additional classes on the outer wrapper. |
+
+## Usage
+
+### Basic with all features
+```tsx
+type Payment = { id: string; amount: number; status: string; email: string }
+
+const columns: ColumnDef<Payment>[] = [
+  { accessorKey: "email", header: "Email" },
+  { accessorKey: "status", header: "Status" },
+  { accessorKey: "amount", header: "Amount" },
+]
+
+<AppDataTable
+  data={payments}
+  columns={columns}
+  filterColumn="email"
+  filterPlaceholder="Filter by email..."
+/>
+```
+
+### With custom cell renderers
+```tsx
+const columns: ColumnDef<Payment>[] = [
+  { accessorKey: "email", header: "Email" },
+  {
+    accessorKey: "status",
+    header: "Status",
+    cell: ({ row }) => (
+      <AppBadge variant={statusVariantMap[row.getValue("status")]}>
+        {row.getValue("status")}
+      </AppBadge>
+    ),
+  },
+  {
+    accessorKey: "amount",
+    header: "Amount",
+    cell: ({ row }) =>
+      new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(
+        row.getValue("amount")
+      ),
+  },
+]
+```
+
+### Plain table (no controls)
+```tsx
+<AppDataTable
+  data={rows}
+  columns={columns}
+  enableSorting={false}
+  enableFiltering={false}
+  enablePagination={false}
+  enableColumnVisibility={false}
+/>
+```
+
+## Rules
+- ✅ Import `ColumnDef` from `@tanstack/react-table` — it is re-exported from `@skunkworksai/ui-kit` for convenience but the type comes from TanStack
+- ✅ All features enabled by default — explicitly disable what you don't need
+- ✅ Set `filterColumn` when you want a specific column to be filterable; defaults to first column's `accessorKey`
+- ✅ Use `cell` renderers in column defs to format values or render `App*` components
+- ❌ Do not add custom sorting/filtering/pagination logic outside of column defs — pass props to control all behavior
+- ❌ If a prop you need is missing, stop and inform the design team
+
+## Responsive
+
+The toolbar (filter input + columns toggle) wraps with `flex-wrap` on small screens, and the pagination footer also wraps on small screens. The underlying `Table` already scrolls horizontally via shadcn's `overflow-auto` wrapper — no consumer changes needed.

package/rules/date-picker.md

@@ -0,0 +1,65 @@
+# AppDatePicker
+
+> Docs: https://ui-kit.vercel.app/docs/components/date-picker
+
+```tsx
+import { AppDatePicker, type AppDatePickerProps } from "@skunkworksai/ui-kit"
+```
+
+## AppDatePicker
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `"single" \| "range"` | `"single"` | Selection mode. Determines the shape of `value` and `onChange`. |
+| `value` | `Date \| undefined` (single) or `DateRange \| undefined` (range) | — | Controlled selected value. |
+| `onChange` | `(date: Date \| undefined) => void` (single) or `(range: DateRange \| undefined) => void` (range) | — | Callback when selection changes. |
+| `placeholder` | `string` | `"Pick a date"` / `"Pick a date range"` | Trigger button text when no date selected. |
+| `disabled` | `boolean` | `false` | Disables the trigger button. |
+| `className` | `string` | — | Additional classes on the trigger button. |
+
+## Usage
+
+### Single date (controlled)
+```tsx
+const [date, setDate] = React.useState<Date | undefined>()
+
+<AppDatePicker value={date} onChange={setDate} />
+```
+
+### Date range (controlled)
+```tsx
+import type { DateRange } from "react-day-picker"
+
+const [range, setRange] = React.useState<DateRange | undefined>()
+
+<AppDatePicker mode="range" value={range} onChange={setRange} />
+```
+
+### With initial value
+```tsx
+const [date, setDate] = React.useState<Date | undefined>(new Date())
+
+<AppDatePicker value={date} onChange={setDate} />
+```
+
+### Disabled
+```tsx
+<AppDatePicker value={undefined} onChange={() => {}} disabled />
+```
+
+### Custom placeholder
+```tsx
+<AppDatePicker
+  value={date}
+  onChange={setDate}
+  placeholder="Select invoice date"
+/>
+```
+
+## Rules
+- ✅ Always control via `value` + `onChange` — this component is controlled only
+- ✅ When using `mode="range"`, the `value` type is `DateRange` from `react-day-picker` and `onChange` receives `DateRange | undefined`
+- ✅ Set trigger button width explicitly via `className` (e.g. `className="w-64"` or `className="w-full"`) — no default width
+- ✅ The range mode shows 2 months side by side — ensure there's enough horizontal space
+- ❌ Do not use without `onChange` — the component is always controlled
+- ❌ If a prop you need is missing, stop and inform the design team