Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: document hook naming convention (useXDS prefix) (#335)

Cindy Zhang0a7a863873f6
diff --git a/.context/decisions/api-guidance.md b/.context/decisions/api-guidance.md
index 4a0abc8712..af6d65832e 100644
--- a/.context/decisions/api-guidance.md
+++ b/.context/decisions/api-guidance.md
@@ -82,6 +82,19 @@ Every component file includes a structured header for traceability:
---
+## Hook Naming
+
+Public hooks use the `useXDS` prefix:
+
+| Prefix | Scope | Examples |
+|--------|-------|---------|
+| `useXDS` | Public API | `useXDSCollapsible`, `useXDSPopover`, `useXDSTheme` |
+| `use` (no prefix) | Internal only | `useFocusTrap`, `useControllableState` |
+
+Utility hooks that can be generally applied and have no strict connection to XDS concepts can skip the prefix (e.g., `useGridFocus`, `useListFocus`).
+
+---
+
## Prop Naming
### Booleans