@stamcat/craftsman 0.0.31-beta.3 → 0.0.31

package/AGENTS.md

@@ -4,15 +4,16 @@ This document explains how code-generation agents should use this library safely
 
 Full guidance has been split out for progressive loading:
 
-- **Global guidelines** (exports, hard rules, code block rendering, style utilities, theme authoring, `isEmpty`, code gen patterns, fallback strategy): see the [craftsman-component-usage skill](.github/skills/craftsman-component-usage/SKILL.md).
+- **Global guidelines** (exports, hard rules, code block rendering, style utilities, theme authoring, `isEmpty`, code gen patterns, fallback strategy): see the [craftsman-component-usage skill](skills/craftsman-component-usage/SKILL.md).
 - **Component-specific guidelines** (props, behavior notes, examples): each component has its own `AGENTS.md` co-located with its source, for example [src/components/Button/AGENTS.md](src/components/Button/AGENTS.md).
-- **Device/browser detection** (prefer `react-device-detect` over custom user-agent/viewport checks): see the [craftsman-device-detection skill](.github/skills/craftsman-device-detection/SKILL.md).
+- **Device/browser detection** (prefer `react-device-detect` over custom user-agent/viewport checks): see the [craftsman-device-detection skill](skills/craftsman-device-detection/SKILL.md).
 
 ## Quick Reference
 
 Use these imports:
 
 ```tsx
+import { Accordion } from "@stamcat/craftsman/Accordion";
 import { Button } from "@stamcat/craftsman/Button";
 import { Carousel } from "@stamcat/craftsman/Carousel";
 import { Checkbox } from "@stamcat/craftsman/Checkbox";
@@ -41,9 +42,9 @@ Do not assume a root export like `@stamcat/craftsman` unless that export is expl
 
 ## Hard Rules for Agents
 
-1. Never deep-import from package internals (for example `@stamcat/craftsman/src/...`).
+1. Never deep-import from package internals (for example `@stamcat/craftsman/src/...`). This applies to Sass too — `@use "@stamcat/craftsman/src/styles/utilities/functions"` will fail to resolve; use the published subpath `@stamcat/craftsman/styles/utilities/functions` instead.
 2. Only use documented component entry points.
-3. Do not import storybook files or internal style utilities from consuming applications.
+3. Do not import storybook files from consuming applications. Style utilities are fine to import, but only via their published subpaths (`@stamcat/craftsman/styles/utilities/functions`, `/mixins`, `/placeholders`) — never via a `/src/...` path.
 4. Prefer standard React props first; use custom props only when required.
 
 

package/Components.esm.js

@@ -1,81 +1,83 @@
 import { __exportAll as e } from "./_virtual/_rolldown/runtime.esm.js";
-import { Button as t } from "./src/components/Button/Button.esm.js";
-import { Input as n } from "./src/components/Input/Input2.esm.js";
-import { InputPassword as r } from "./src/components/InputPassword/InputPassword.esm.js";
-import { Loader as i } from "./src/components/Loader/Loader.esm.js";
-import { RadioButton as a } from "./src/components/RadioButton/RadioButton.esm.js";
-import { Checkbox as o } from "./src/components/Checkbox/Checkbox.esm.js";
-import { Textarea as s } from "./src/components/Textarea/Textarea.esm.js";
-import { Text as c } from "./src/components/Text/Text2.esm.js";
-import { Modal as l } from "./src/components/Modal/Modal2.esm.js";
-import { Select as u } from "./src/components/Select/Select.esm.js";
-import { DatePicker as d } from "./src/components/DatePicker/DatePicker2.esm.js";
-import { DateRangePicker as f } from "./src/components/DateRangePicker/DateRangePicker2.esm.js";
-import { InputPhone as p } from "./src/components/InputPhone/InputPhone2.esm.js";
-import { InputNumber as m } from "./src/components/InputNumber/InputNumber2.esm.js";
-import { Toggle as h } from "./src/components/Toggle/Toggle2.esm.js";
-import { Pagination as g } from "./src/components/Pagination/Pagination2.esm.js";
-import { Carousel as _ } from "./src/components/Carousel/Carousel2.esm.js";
-import { TimePicker as v } from "./src/components/TimePicker/TimePicker2.esm.js";
-import { DateTimePicker as y } from "./src/components/DateTimePicker/DateTimePicker2.esm.js";
-import { Tooltip as b } from "./src/components/Tooltip/Tooltip2.esm.js";
-import { Notice as x } from "./src/components/Notice/Notice2.esm.js";
-import { SortableList as S } from "./src/components/SortableList/SortableList2.esm.js";
-import { IconAmazonPay as C } from "./src/components/Icons/IconAmazonPay.esm.js";
-import { IconAmex as w } from "./src/components/Icons/IconAmex.esm.js";
-import { IconApplePay as T } from "./src/components/Icons/IconApplePay.esm.js";
-import { IconDiscover as E } from "./src/components/Icons/IconDiscover.esm.js";
-import { IconGooglePay as D } from "./src/components/Icons/IconGooglePay.esm.js";
-import { IconMaestro as O } from "./src/components/Icons/IconMaestro.esm.js";
-import { IconMastercard as k } from "./src/components/Icons/IconMastercard.esm.js";
-import { IconPayPal as A } from "./src/components/Icons/IconPayPal.esm.js";
-import { IconSepa as j } from "./src/components/Icons/IconSepa.esm.js";
-import { IconShopPay as M } from "./src/components/Icons/IconShopPay.esm.js";
-import { IconSquare as N } from "./src/components/Icons/IconSquare.esm.js";
-import { IconStripe as P } from "./src/components/Icons/IconStripe.esm.js";
-import { IconUnionPay as F } from "./src/components/Icons/IconUnionPay.esm.js";
-import { IconVenmo as I } from "./src/components/Icons/IconVenmo.esm.js";
-import { IconVisa as L } from "./src/components/Icons/IconVisa.esm.js";
+import { Accordion as t } from "./src/components/Accordion/Accordion2.esm.js";
+import { Button as n } from "./src/components/Button/Button.esm.js";
+import { Input as r } from "./src/components/Input/Input2.esm.js";
+import { InputPassword as i } from "./src/components/InputPassword/InputPassword.esm.js";
+import { Loader as a } from "./src/components/Loader/Loader.esm.js";
+import { RadioButton as o } from "./src/components/RadioButton/RadioButton.esm.js";
+import { Checkbox as s } from "./src/components/Checkbox/Checkbox.esm.js";
+import { Textarea as c } from "./src/components/Textarea/Textarea.esm.js";
+import { Text as l } from "./src/components/Text/Text2.esm.js";
+import { Modal as u } from "./src/components/Modal/Modal2.esm.js";
+import { Select as d } from "./src/components/Select/Select.esm.js";
+import { DatePicker as f } from "./src/components/DatePicker/DatePicker2.esm.js";
+import { DateRangePicker as p } from "./src/components/DateRangePicker/DateRangePicker2.esm.js";
+import { InputPhone as m } from "./src/components/InputPhone/InputPhone2.esm.js";
+import { InputNumber as h } from "./src/components/InputNumber/InputNumber2.esm.js";
+import { Toggle as g } from "./src/components/Toggle/Toggle2.esm.js";
+import { Pagination as _ } from "./src/components/Pagination/Pagination2.esm.js";
+import { Carousel as v } from "./src/components/Carousel/Carousel2.esm.js";
+import { TimePicker as y } from "./src/components/TimePicker/TimePicker2.esm.js";
+import { DateTimePicker as b } from "./src/components/DateTimePicker/DateTimePicker2.esm.js";
+import { Tooltip as x } from "./src/components/Tooltip/Tooltip2.esm.js";
+import { Notice as S } from "./src/components/Notice/Notice2.esm.js";
+import { SortableList as C } from "./src/components/SortableList/SortableList2.esm.js";
+import { IconAmazonPay as w } from "./src/components/Icons/IconAmazonPay.esm.js";
+import { IconAmex as T } from "./src/components/Icons/IconAmex.esm.js";
+import { IconApplePay as E } from "./src/components/Icons/IconApplePay.esm.js";
+import { IconDiscover as D } from "./src/components/Icons/IconDiscover.esm.js";
+import { IconGooglePay as O } from "./src/components/Icons/IconGooglePay.esm.js";
+import { IconMaestro as k } from "./src/components/Icons/IconMaestro.esm.js";
+import { IconMastercard as A } from "./src/components/Icons/IconMastercard.esm.js";
+import { IconPayPal as j } from "./src/components/Icons/IconPayPal.esm.js";
+import { IconSepa as M } from "./src/components/Icons/IconSepa.esm.js";
+import { IconShopPay as N } from "./src/components/Icons/IconShopPay.esm.js";
+import { IconSquare as P } from "./src/components/Icons/IconSquare.esm.js";
+import { IconStripe as F } from "./src/components/Icons/IconStripe.esm.js";
+import { IconUnionPay as I } from "./src/components/Icons/IconUnionPay.esm.js";
+import { IconVenmo as L } from "./src/components/Icons/IconVenmo.esm.js";
+import { IconVisa as R } from "./src/components/Icons/IconVisa.esm.js";
 import "./src/components/Icons/index.esm.js";
 //#region src/components/index.ts
-var R = /* @__PURE__ */ e({
-	Button: () => t,
-	Carousel: () => _,
-	Checkbox: () => o,
-	DatePicker: () => d,
-	DateRangePicker: () => f,
-	DateTimePicker: () => y,
-	IconAmazonPay: () => C,
-	IconAmex: () => w,
-	IconApplePay: () => T,
-	IconDiscover: () => E,
-	IconGooglePay: () => D,
-	IconMaestro: () => O,
-	IconMastercard: () => k,
-	IconPayPal: () => A,
-	IconSepa: () => j,
-	IconShopPay: () => M,
-	IconSquare: () => N,
-	IconStripe: () => P,
-	IconUnionPay: () => F,
-	IconVenmo: () => I,
-	IconVisa: () => L,
-	Input: () => n,
-	InputNumber: () => m,
-	InputPassword: () => r,
-	InputPhone: () => p,
-	Loader: () => i,
-	Modal: () => l,
-	Notice: () => x,
-	Pagination: () => g,
-	RadioButton: () => a,
-	Select: () => u,
-	SortableList: () => S,
-	Text: () => c,
-	Textarea: () => s,
-	TimePicker: () => v,
-	Toggle: () => h,
-	Tooltip: () => b
+var z = /* @__PURE__ */ e({
+	Accordion: () => t,
+	Button: () => n,
+	Carousel: () => v,
+	Checkbox: () => s,
+	DatePicker: () => f,
+	DateRangePicker: () => p,
+	DateTimePicker: () => b,
+	IconAmazonPay: () => w,
+	IconAmex: () => T,
+	IconApplePay: () => E,
+	IconDiscover: () => D,
+	IconGooglePay: () => O,
+	IconMaestro: () => k,
+	IconMastercard: () => A,
+	IconPayPal: () => j,
+	IconSepa: () => M,
+	IconShopPay: () => N,
+	IconSquare: () => P,
+	IconStripe: () => F,
+	IconUnionPay: () => I,
+	IconVenmo: () => L,
+	IconVisa: () => R,
+	Input: () => r,
+	InputNumber: () => h,
+	InputPassword: () => i,
+	InputPhone: () => m,
+	Loader: () => a,
+	Modal: () => u,
+	Notice: () => S,
+	Pagination: () => _,
+	RadioButton: () => o,
+	Select: () => d,
+	SortableList: () => C,
+	Text: () => l,
+	Textarea: () => c,
+	TimePicker: () => y,
+	Toggle: () => g,
+	Tooltip: () => x
 });
 //#endregion
-export { t as Button, _ as Carousel, o as Checkbox, d as DatePicker, f as DateRangePicker, y as DateTimePicker, C as IconAmazonPay, w as IconAmex, T as IconApplePay, E as IconDiscover, D as IconGooglePay, O as IconMaestro, k as IconMastercard, A as IconPayPal, j as IconSepa, M as IconShopPay, N as IconSquare, P as IconStripe, F as IconUnionPay, I as IconVenmo, L as IconVisa, n as Input, m as InputNumber, r as InputPassword, p as InputPhone, i as Loader, l as Modal, x as Notice, g as Pagination, a as RadioButton, u as Select, S as SortableList, c as Text, s as Textarea, v as TimePicker, h as Toggle, b as Tooltip, R as components_exports };
+export { t as Accordion, n as Button, v as Carousel, s as Checkbox, f as DatePicker, p as DateRangePicker, b as DateTimePicker, w as IconAmazonPay, T as IconAmex, E as IconApplePay, D as IconDiscover, O as IconGooglePay, k as IconMaestro, A as IconMastercard, j as IconPayPal, M as IconSepa, N as IconShopPay, P as IconSquare, F as IconStripe, I as IconUnionPay, L as IconVenmo, R as IconVisa, r as Input, h as InputNumber, i as InputPassword, m as InputPhone, a as Loader, u as Modal, S as Notice, _ as Pagination, o as RadioButton, d as Select, C as SortableList, l as Text, c as Textarea, y as TimePicker, g as Toggle, x as Tooltip, z as components_exports };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stamcat/craftsman",
-  "version": "0.0.31-beta.3",
+  "version": "0.0.31",
   "type": "module",
   "description": "A powerful, lightweight framework for design systems",
   "repository": {
@@ -16,6 +16,8 @@
   "bugs": {
     "url": "https://github.com/Stamcat/craftsman/issues"
   },
+  "x-agent-instructions": "./AGENTS.md",
+  "x-agent-components": "./src/components/*/AGENTS.md",
   "types": "./src/components/index.d.ts",
   "main": "./Components.esm.js",
   "homepage": "https://github.com/Stamcat/craftsman#readme",
@@ -79,6 +81,10 @@
     "./styles/utilities/placeholders": {
       "default": "./src/styles/utilities/_placeholders.scss"
     },
+    "./Accordion": {
+      "types": "./src/components/Accordion/Accordion.d.ts",
+      "default": "./src/components/Accordion/Accordion.esm.js"
+    },
     "./Button": {
       "types": "./src/components/Button/Button.d.ts",
       "default": "./src/components/Button/Button.esm.js"

package/skills/craftsman-component-usage/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: craftsman-component-usage
+description: 'Global AI agent guidelines for using the @stamcat/craftsman component library — package exports, hard import rules, code block rendering, Toast usage, and code generation patterns. Use when generating or reviewing code that imports from @stamcat/craftsman or needing per-component prop contracts (Button, Input, Modal, DatePicker, TimePicker, Carousel, Pagination, etc). See the craftsman-style-utilities, craftsman-utility-functions, and craftsman-device-detection skills for styling, utility function, and device detection guidance.'
+---
+
+# Craftsman Component Library Usage
+
+Global rules for AI agents generating code against `@stamcat/craftsman`. For a specific component's props, behavior notes, and examples, open that component's `AGENTS.md` co-located with its source — see the index below. For styling utilities and theme authoring, see the [craftsman-style-utilities skill](../craftsman-style-utilities/SKILL.md). For the `isEmpty` utility and style utility parity notes, see the [craftsman-utility-functions skill](../craftsman-utility-functions/SKILL.md). For device/browser/OS detection, see the [craftsman-device-detection skill](../craftsman-device-detection/SKILL.md).
+
+## What This Package Currently Exports
+
+The package is built with component-level entry points only.
+
+```tsx
+import { Accordion } from "@stamcat/craftsman/Accordion";
+import { Button } from "@stamcat/craftsman/Button";
+import { Carousel } from "@stamcat/craftsman/Carousel";
+import { Checkbox } from "@stamcat/craftsman/Checkbox";
+import { DatePicker } from "@stamcat/craftsman/DatePicker";
+import { DateRangePicker } from "@stamcat/craftsman/DateRangePicker";
+import { Input } from "@stamcat/craftsman/Input";
+import { InputNumber } from "@stamcat/craftsman/InputNumber";
+import { InputPassword } from "@stamcat/craftsman/InputPassword";
+import { InputPhone } from "@stamcat/craftsman/InputPhone";
+import { Loader } from "@stamcat/craftsman/Loader";
+import { Modal } from "@stamcat/craftsman/Modal";
+import { Pagination } from "@stamcat/craftsman/Pagination";
+import { RadioButton } from "@stamcat/craftsman/RadioButton";
+import { Select } from "@stamcat/craftsman/Select";
+import { Text } from "@stamcat/craftsman/Text";
+import { Textarea } from "@stamcat/craftsman/Textarea";
+import { TimePicker } from "@stamcat/craftsman/TimePicker";
+import { DateTimePicker } from "@stamcat/craftsman/DateTimePicker";
+import { Toggle } from "@stamcat/craftsman/Toggle";
+import { Tooltip } from "@stamcat/craftsman/Tooltip";
+import { Notice } from "@stamcat/craftsman/Notice";
+import { SortableList } from "@stamcat/craftsman/SortableList";
+```
+
+Do not assume a root export like `@stamcat/craftsman` unless that export is explicitly added to package `exports`.
+
+## Hard Rules for Agents
+
+1. Never deep-import from package internals (for example `@stamcat/craftsman/src/...`). This applies to Sass too — `@use "@stamcat/craftsman/src/styles/utilities/functions"` will fail to resolve; use the published subpath `@stamcat/craftsman/styles/utilities/functions` instead.
+2. Only use documented component entry points.
+3. Do not import storybook files from consuming applications. Style utilities are fine to import, but only via their published subpaths (`@stamcat/craftsman/styles/utilities/functions`, `/mixins`, `/placeholders`) — never via a `/src/...` path.
+4. Prefer standard React props first; use custom props only when required.
+
+## Component Index
+
+Each entry links to the `AGENTS.md` co-located with that component's source for props, behavior notes, and examples.
+
+| Component | Docs |
+|---|---|
+| Accordion | [../../src/components/Accordion/AGENTS.md](../../src/components/Accordion/AGENTS.md) |
+| Button | [../../src/components/Button/AGENTS.md](../../src/components/Button/AGENTS.md) |
+| Input | [../../src/components/Input/AGENTS.md](../../src/components/Input/AGENTS.md) |
+| InputPassword | [../../src/components/InputPassword/AGENTS.md](../../src/components/InputPassword/AGENTS.md) |
+| Checkbox | [../../src/components/Checkbox/AGENTS.md](../../src/components/Checkbox/AGENTS.md) |
+| RadioButton | [../../src/components/RadioButton/AGENTS.md](../../src/components/RadioButton/AGENTS.md) |
+| Modal | [../../src/components/Modal/AGENTS.md](../../src/components/Modal/AGENTS.md) |
+| Pagination | [../../src/components/Pagination/AGENTS.md](../../src/components/Pagination/AGENTS.md) |
+| Carousel | [../../src/components/Carousel/AGENTS.md](../../src/components/Carousel/AGENTS.md) |
+| Loader | [../../src/components/Loader/AGENTS.md](../../src/components/Loader/AGENTS.md) |
+| Textarea | [../../src/components/Textarea/AGENTS.md](../../src/components/Textarea/AGENTS.md) |
+| Select | [../../src/components/Select/AGENTS.md](../../src/components/Select/AGENTS.md) |
+| InputPhone | [../../src/components/InputPhone/AGENTS.md](../../src/components/InputPhone/AGENTS.md) |
+| DatePicker | [../../src/components/DatePicker/AGENTS.md](../../src/components/DatePicker/AGENTS.md) |
+| DateRangePicker | [../../src/components/DateRangePicker/AGENTS.md](../../src/components/DateRangePicker/AGENTS.md) |
+| InputNumber | [../../src/components/InputNumber/AGENTS.md](../../src/components/InputNumber/AGENTS.md) |
+| TimePicker | [../../src/components/TimePicker/AGENTS.md](../../src/components/TimePicker/AGENTS.md) |
+| Text | [../../src/components/Text/AGENTS.md](../../src/components/Text/AGENTS.md) |
+| DateTimePicker | [../../src/components/DateTimePicker/AGENTS.md](../../src/components/DateTimePicker/AGENTS.md) |
+| Tooltip | [../../src/components/Tooltip/AGENTS.md](../../src/components/Tooltip/AGENTS.md) |
+| Toggle | [../../src/components/Toggle/AGENTS.md](../../src/components/Toggle/AGENTS.md) |
+| Notice | [../../src/components/Notice/AGENTS.md](../../src/components/Notice/AGENTS.md) |
+| SortableList | [../../src/components/SortableList/AGENTS.md](../../src/components/SortableList/AGENTS.md) |
+
+Not yet part of the documented public export surface: `Progress` (source exists but is incomplete — see Known Limitations).
+
+## Code Block Rendering
+
+Craftsman's global styles automatically style `<code>` and `<code><pre>` elements. **Never create custom inline styles or wrapper divs to simulate a code block.** Use the native elements directly:
+
+```tsx
+// Inline code — renders with pill/badge style
+<code>someValue</code>
+
+// Block code — renders with dark background, padding, and border-radius
+<code><pre>{`your
+multiline
+code here`}</pre></code>
+```
+
+The two modes are driven by `_code.scss`:
+- `<code>` alone → light gray background, inline display
+- `<code>` containing `<pre>` → dark background (`--gray800`), block display, padded and rounded
+
+Do not create `preStyle`, `codeBlockStyle`, or equivalent inline style objects for this purpose. The global styles handle it.
+
+## Toast (react-toastify)
+
+Craftsman re-exports `toast` and `ToastContainer` from `react-toastify`. No custom wrapper is needed, and there is no dedicated component folder for it.
+
+Import:
+
+```tsx
+import { toast, ToastContainer } from "react-toastify";
+import "react-toastify/dist/ReactToastify.css";
+```
+
+Usage:
+
+- Render one `<ToastContainer>` near the root of your app.
+- Call `toast(...)` anywhere in response to user actions.
+- `ToastContainer` props: `position`, `autoClose`, `theme` (`"light" | "dark" | "colored"`), `closeOnClick`, `pauseOnHover`, `draggable`, `newestOnTop`.
+
+Example:
+
+```tsx
+// Root layout
+<ToastContainer position="bottom-right" autoClose={3000} theme="light" />
+
+// Anywhere in the app
+toast("Saved successfully!");
+toast.error("Something went wrong.");
+toast.success("Profile updated.");
+toast.warning("Unsaved changes.");
+toast.info("New version available.");
+```
+
+## Code Generation Patterns to Prefer
+
+1. Generate fully typed React usage examples.
+2. Keep accessibility props in place (`aria-label`, `disabled`, semantic `type`).
+3. Use `variant="primary"` for main actions and `variant="text"` for low-emphasis actions.
+4. For loading states, pair `Loader` with accessible status text where needed.
+5. **Functional component declaration order** — always organize the body in this sequence:
+   1. Hook calls (`useSomething`)
+   2. State (`useState`)
+   3. Derived state / variables (values computed from state or props)
+   4. Action handlers (`const handle*`, `const dispatch*`, `useEffect`)
+
+## Known Limitations (Current Package State)
+
+1. The README now covers installation, theming, and getting-started usage; treat this skill and the per-component `AGENTS.md` files as the source of truth for deeper agent usage.
+2. Theme utilities exist in source but are not guaranteed public package exports.
+3. `Progress` exists in source but is incomplete and intentionally omitted from documentation for now.
+
+## Safe Fallback Strategy for Agents
+
+If uncertain about available exports:
+
+1. Use only `Button`, `Checkbox`, `DatePicker`, `Input`, `InputPassword`, `InputPhone`, `Loader`, `Modal`, `RadioButton`, `Select`, `Text`, and `Textarea` from their component entry points.
+2. Do not invent package APIs.
+3. Prefer native HTML elements for anything not explicitly exported.

package/skills/craftsman-device-detection/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: craftsman-device-detection
+description: 'Device/browser detection conventions for @stamcat/craftsman — use react-device-detect instead of hand-rolled user-agent sniffing or window.innerWidth checks. Use when writing responsive logic, conditional rendering by device/browser/OS, or reviewing code that branches on viewport size or navigator.userAgent.'
+---
+
+# Craftsman Device Detection
+
+`react-device-detect` is already a dependency of `@stamcat/craftsman` (it powers the mobile wheel-picker fallback in `TimePicker`). **Prefer it over custom implementations** for any device, browser, or OS branching logic. Consuming apps should install it directly rather than writing their own detection.
+
+## Hard Rule
+
+Never write custom detection logic such as:
+
+```ts
+// DO NOT — fragile, reinvents an already-solved problem
+const isMobile = /Mobi|Android/i.test(navigator.userAgent);
+const isMobile = window.innerWidth < 768;
+```
+
+Use the library instead:
+
+```tsx
+import { isMobile } from "react-device-detect";
+
+if (isMobile) {
+    // mobile-specific behavior
+}
+```
+
+CSS media queries are still the right tool for pure layout/visual breakpoints (see the [craftsman-style-utilities skill](../craftsman-style-utilities/SKILL.md) for `breakpoint()`). Reach for `react-device-detect` when the decision depends on the actual device/browser/OS rather than viewport width alone, or when the branch happens in JS/TS rather than CSS.
+
+## Common Named Exports
+
+```tsx
+import {
+    isMobile,
+    isTablet,
+    isDesktop,
+    isBrowser,
+    isSmartTV,
+    isAndroid,
+    isIOS,
+    isMobileOnly,
+    browserName,
+    osName,
+    deviceType,
+    BrowserView,
+    MobileView,
+    TabletView,
+} from "react-device-detect";
+```
+
+- `isMobile` / `isTablet` / `isDesktop` / `isBrowser` — boolean flags for conditional logic.
+- `isMobileOnly` — `true` for phones, `false` for tablets (use this, not `isMobile`, when tablets must be excluded).
+- `browserName`, `osName`, `deviceType` — string values for logging/analytics, not for branching (prefer the boolean flags for that).
+- `BrowserView` / `MobileView` / `TabletView` — declarative wrapper components that render `children` only on the matching device, as an alternative to `if (isMobile)` branches in JSX.
+
+## Example: Conditional Rendering
+
+```tsx
+import { MobileView, BrowserView } from "react-device-detect";
+
+<MobileView>
+    <CompactNav />
+</MobileView>
+<BrowserView>
+    <FullNav />
+</BrowserView>
+```
+
+## Orientation
+
+For portrait/landscape detection, use the `useMobileOrientation` hook rather than comparing `window.innerWidth`/`innerHeight`:
+
+```tsx
+import { useMobileOrientation } from "react-device-detect";
+
+const { isPortrait, isLandscape } = useMobileOrientation();
+```