# Component conventions

Package: @commenda/pathfinder@0.1.0
Page: /docs/guides/component-conventions

Component-specific rules, Figma sources and reviewed differences live on each component page. These conventions apply across the library.

## Styling and distribution [#styling-and-distribution]

Import `@commenda/pathfinder/styles.css` once, after host styles. Use public root or component subpath exports. Applications do not need to scan Pathfinder source or compile Tailwind utilities. Public components support React 18 and 19 and both Next.js router families; event handlers belong in client components in App Router.

Pathfinder resets Tailwind’s default theme. Its private `--spacing-0` alias points to the existing `none` token so zero-size, inset, margin, padding and minimum-width utilities compile. A packed-CSS test guards this contract.

## Accessible presentation [#accessible-presentation]

Use meaningful labels, associate supporting and error text with controls, and preserve focus visibility. Figma’s fixed specimen heights are minimums when content wraps or text is enlarged. Decorative artwork must not compete with the accessible control name.

## Forms and application state [#forms-and-application-state]

Use native names, autocomplete, refs and blur handlers with your form library. Pathfinder has no dependency on a form framework. Controlled changes request application updates; uncontrolled form resets restore defaults. Error messages and disabled reasons remain associated with the control. Prefixes and suffixes do not become part of submitted values.

Applications own network requests, validation schemas, permissions and persistence. A visual loading or success state is an explicit application signal, not evidence that a request completed.

## Right-to-left layouts [#right-to-left-layouts]

Set HTML direction on the document or section and use `DirectionProvider` for primitive keyboard and positioning behavior. Pathfinder styles use logical properties.

```tsx
import { DirectionProvider } from '@commenda/pathfinder';

<DirectionProvider direction="rtl">
  <div dir="rtl">{children}</div>
</DirectionProvider>;
```

## Documentation and verification [#documentation-and-verification]

Storybook and Fumadocs share example implementations. Code previews and AI Markdown include source from those examples. Figma references provide evidence for rules; screenshots are not runtime component artwork. Follow each component’s documented contract instead of inferring public props from Figma variant names.

Before completing a change, verify relevant keyboard behavior, focus return, wrapping, empty and error states, touch, 320px layouts, 200% zoom and reduced motion. Check RTL where supported. Export, stylesheet and declaration changes also require packed-consumer checks. These are development gates; implementation notes record which checks actually ran.