Skip to content

gentleeduck/duck-ui / skills/duck-primitives

duck-primitives

Verified

Use when building or modifying headless, unstyled @gentleduck/primitives components. Covers the accessibility-first primitive layer: ARIA roles, keyboard navigation, focus management, state machines, scoped context, Slot/asChild, Presence animations, and the compound component architecture. Not for styled components - use duck-ui for that.

@gentleduck/primitives

You are an expert on the headless primitive layer. Your scope is strictly packages/duck-primitives/src/. These are unstyled, accessibility-first React components that handle ARIA, keyboard nav, focus trapping, and state internally. The styled registry-ui components are built on top of these.

Where Primitives Live

packages/duck-primitives/src/{name}/
├── {name}.tsx           # Root component (React.FC), context provider, state
├── trigger.tsx          # Trigger sub-component (React.forwardRef)
├── content.tsx          # Content sub-component (React.forwardRef)
├── {sub-part}.tsx       # Other sub-parts (overlay, portal, arrow, close, etc.)
├── {name}.libs.ts       # Internal helpers (NOT exported from index), may have 'use client'
└── index.ts             # Named exports only (NEVER wildcard)

Import: import * as DialogPrimitive from '@gentleduck/primitives/dialog'

Built with tsdown. Exports: "./*": { "types": "./dist/*/index.d.ts", "default": "./dist/*/index.js" }

Architecture Patterns

Scoped Context (createContextScope)

Every primitive uses createContextScope for isolated, composable context:

import { createContextScope, type Scope } from '../libs/create-context'

const DIALOG_NAME = 'Dialog'
export type ScopedProps<P> = P & { __scopeDialog?: Scope }
export const [createDialogContext, createDialogScope] = createContextScope(DIALOG_NAME)
export const [DialogProvider, useDialogContext] = createDialogContext<DialogContextValue>(DIALOG_NAME)

The scoped hook always takes two args: useDialogContext(COMPONENT_NAME, __scopeDialog).

For cross-primitive composition (e.g., Select depends on Popper):

const [createSelectContext, createSelectScope] = createContextScope(SELECT_NAME, [
  createCollectionScope, createPopperScope,
])
export const usePopperScope = createPopperScope()
// In root: const popperScope = usePopperScope(__scopeSelect)
// Then:    <PopperPrimitive.Root {...popperScope}>

State via useControllableState

All open/close state uses this pattern. The caller param is required:

const [open, setOpen] = useControllableState({
  prop: openProp, defaultProp: defaultOpen ?? false,
  onChange: onOpenChange, caller: DIALOG_NAME,
})

Root = React.FC, Sub-parts = React.forwardRef

Root components are provider-only (no DOM), so they use React.FC. Sub-components that render DOM use React.forwardRef. See CODING-STYLE.md for full code examples of both patterns.

Slot and asChild

Primitive.button renders a native <button> by default. When asChild is true, it renders a Slot that merges all behavior (props, ref, event handlers) onto the consumer's child element.

Decision Guide: Choosing the Right Primitive Building Block

DismissableLayer vs useEscapeKeydown

  • Use DismissableLayer when you need: Escape to close, click-outside to close, focus-outside to close, and correct stacking with nested layers (e.g., Dialog, Popover, DropdownMenu).
  • Use useEscapeKeydown alone only for lightweight components that never stack and only need Escape (rare - Tooltip uses its own timer-based close instead).

Presence vs conditional rendering ({open && <Content />})

  • Use <Presence present={...}> when the component needs exit animations. Presence keeps the element in the DOM during the leave animation and removes it after.
  • Use conditional rendering only for components that never animate (e.g., internal helper wrappers).
  • forceMount on Portal/Content keeps the element in DOM permanently; Presence then controls visibility for animation. Content reads forceMount from its parent Portal via usePortalContext.

Portal: when and how

  • Use a Portal sub-component (like DialogPortal) when content must escape parent overflow/stacking contexts (modals, dropdowns, popovers, tooltips).
  • Portal wraps each child in <Presence> + <PortalPrimitive> and provides forceMount to children via its own context.
  • The base Portal primitive (src/portal/) uses ReactDOM.createPortal to document.body by default, accepts a container prop for custom targets.

Overlay: when to include one

  • Include an Overlay sub-component for modal primitives (Dialog, Sheet, AlertDialog) that need a backdrop.
  • Overlay only renders when context.modal is true. It wraps content in RemoveScroll for scroll locking.
  • Non-modal primitives (Popover, Tooltip, HoverCard) never use Overlay.

Focus restoration

  • Modal content: always restore focus to trigger on close via context.triggerRef.current?.focus() in onCloseAutoFocus.
  • Non-modal content: only restore focus if the user did NOT interact outside. Track this with hasInteractedOutsideRef.

Internal Hooks & Libs

Hooks (src/hooks/): useCallbackRef, useControllableState (requires caller), useEscapeKeydown, useFocusGuards, useId, useLayoutEffect (isomorphic), usePrevious, useSize, useStateMachine

Libs (src/libs/): createContext/createContextScope, createCollection, composeEventHandlers, useComposedRefs/composeRefs

Creating a New Primitive

  1. Create packages/duck-primitives/src/{name}/ directory.
  2. Read dialog/ first as the canonical reference primitive.
  3. Create {name}.tsx - define COMPONENT_NAME const, ScopedProps<P>, createContextScope, context value type, useControllableState for state, useDirection(dir), useId() for IDs. Export getState helper. Set displayName.
  4. Create sub-part files (trigger, content, etc.) - each defines its own COMPONENT_NAME, uses useComposedRefs, composeEventHandlers, Primitive.{tag}. Required attrs: data-slot, data-state, dir, type="button" on buttons. Props spread after data/aria attrs, ref last.
  5. If the primitive needs a popup layer: create portal.tsx (FC, not forwardRef) with its own context providing forceMount; create content.tsx wrapping children in <Presence> > <FocusScope> > <DismissableLayer>.
  6. If modal: add overlay.tsx with RemoveScroll, hideOthers in content, disableOutsidePointerEvents.
  7. If item-based (menu, select): use createCollection for keyboard nav and typeahead.
  8. Create index.ts - named exports with full name + short alias. Export create{Name}Scope for composition.
  9. Follow the Conventions Checklist before finishing.

Common Errors

  1. Context error - sub-component outside its Provider (check __scope threading)
  2. Event swallowing - not using composeEventHandlers (replaces consumer's handler)
  3. State desync - mixing controlled/uncontrolled; forgetting caller in useControllableState
  4. SSR hydration - using useLayoutEffect instead of the isomorphic version from ../hooks/use-layout-effect

Do Not

  • Use wildcard exports in index.ts - always named exports with full + short alias
  • Import from registry-ui or from sibling primitives - only from ../libs/, ../hooks/, and shared primitives like ../portal, ../presence, ../primitive-elements
  • Use React.forwardRef for root/provider components - use React.FC (no DOM)
  • Use React.FC for sub-components that render DOM - use React.forwardRef
  • Omit the caller param from useControllableState
  • Call the scoped context hook with only one arg - always (COMPONENT_NAME, __scope)
  • Use data-disabled="true" - use data-disabled="" (empty string) to match [data-disabled]
  • Skip data-slot, data-state, dir, or type="button" attributes
  • Create a primitive without COMPONENT_NAME constant at top of each file
  • Forget displayName on every component (including internal impl components)
  • Skip useComposedRefs when both forwardedRef and a context ref are needed

Edge Cases

See CODING-STYLE.md for detailed edge cases with code. Key ones:

  • Nested layers: Escape only closes the topmost DismissableLayer; right-click outside prevents dismiss
  • Modal vs non-modal: Dialog delegates to separate impl components; modal traps focus + uses aria-hidden via hideOthers
  • Scope composition: Dependent primitives must compose scopes and thread usePopperScope(__scope)
  • Collection pattern: Item-based primitives use createCollection for keyboard nav and typeahead
  • Scroll locking: Modal overlay uses RemoveScroll (from react-remove-scroll); dialog.libs.ts has ref-counted lockScrollbar for additional scroll lock needs
  • RTL: Root uses useDirection(dir); sub-components pass dir={context.dir}

Available Primitives

alert-dialog, arrow, avatar, checkers, command, context-menu, dialog, direction, dismissable-layer, dropdown-menu, focus-scope, hover-card, input-otp, menu, menubar, mount, navigation-menu, pagination, popover, popper, portal, presence, primitive-elements, progress, radio-group, roving-focus, select, sheet, slider, slot, toggle, toggle-group, tooltip, visibility-hidden

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall