Pathfinder

@commenda/pathfinder is Commenda's new React design-system package. It ships compiled ESM, TypeScript declarations, and a finished Tailwind v4 stylesheet. Components expose typed public APIs and compile their styles for use in consumer applications.

Installation and releases

The package is configured for public npm distribution. After the first release, run pnpm add @commenda/pathfinder; no npm login or installation token is needed. Inside this monorepo, keep using workspace:*.

See the installation guide for setup and stylesheet imports. Maintainers can follow Publishing Pathfinder in the source repository for initial npm setup and the release workflow.

Use in an application

// Pages Router: pages/_app.tsx. App Router: app/layout.tsx.
import '@commenda/pathfinder/styles.css';

import { Button } from '@commenda/pathfinder';

export const SaveButton = () => <Button>Save changes</Button>;

Interactive event handlers must live in a client component in App Router apps. The published Button entry retains use client; the root barrel does not force future server-compatible components into a client boundary. A direct @commenda/pathfinder/button import is also supported.

Consumers need no Tailwind dependency, source scanning, PostCSS plugin, or transpilePackages entry for Pathfinder. Import the stylesheet after your app's base stylesheet. Next.js still bundles the finished CSS as part of its build.

Navigation and display components

Import Separator, Breadcrumb, Tabs, Stepper, Accordion, Badge, Card/StatCard, and Avatar/AvatarGroup from the root or their component subpaths (@commenda/pathfinder/tabs, for example).

Tabs and Accordion accept typed item arrays and enforce controlled/uncontrolled selection contracts. Avatar accepts a person/organization/logo identity union. Card groups related options in headerConfig, footerConfig, and scrollConfig; Breadcrumb and StatCard use linkConfig for native destinations and router adapters.

See the component documentation for props, examples, and Figma-derived rules. Storybook groups these under Navigation, Disclosure, Layout, and Display. Fumadocs provides matching previews, formatted source, props/defaults, and AI-readable rules.

The new example snippets are generated from the actual rendered examples. After editing documentation/navigation/*Examples.tsx, run pnpm generate:examples from this package; check:examples prevents stale copied code during builds.

Workspace development

Follow the contribution guide for component structure, TypeScript rules, skill guidance, and required checks.

From the repository root:

pnpm pathfinder:build
pnpm pathfinder:dev
pnpm pathfinder:docs
pnpm pathfinder:storybook
pnpm --filter commenda-enterprise dev
pnpm --filter @commenda/pathfinder test

Run the watcher and enterprise dev server in separate terminals. Enterprise's dev/build/check-types commands build Pathfinder first, including on a clean checkout. Turbo also builds Pathfinder before its consumers.

pathfinder:dev only watches package output; it has no HTTP port. Fumadocs runs on 3002 and Storybook runs on 6006. Storybook starts its own package watcher, so a separate pathfinder:dev is not needed when using Storybook alone. Normal builds and watchers do not delete dist, avoiding output deletion while a consumer is running. After removing or renaming source modules, stop watchers and remove obsolete generated files before packing.

Enterprise uses Webpack for local development because Turbopack currently fails while compiling its dependency graph. Run these commands without sudo so build outputs remain writable by your user.

Use Fumadocs at http://localhost:3002/docs for component examples and props, and Storybook at http://localhost:6006 for interactive and worst-case testing. The enterprise /pathfinder demo page has been removed; demo components live only in the documentation/playground tooling.

Token CSS is generated from src/foundations at build time. After editing tokens or build configuration, restart the watcher. No Commenda workspace dependency is required at runtime by the published package.

Styling contract

• Pathfinder compiles its own Tailwind v4 styles. The docs app also uses v4 for its shell; consumers can use the compiled stylesheet without a Tailwind installation.
• Utilities and theme variables use the pf prefix. No Preflight is included.
• Override semantic variables such as --pf-color-primary on a theme container.
• Font defaults to Inter. Optionally import @commenda/pathfinder/fonts.css for self-hosted Inter, or provide --font-inter from the host font loader. System fonts remain the fallback.
• className is additive. Conflicting host utilities follow the CSS cascade; they are not automatically merged or guaranteed to override internal classes.
• Supported browser baseline: Safari 16.4+, Chrome 111+, Firefox 128+.
• Only the existing light theme is supplied in this foundation release.

Foundations

The reviewed Figma source lives in src/foundations: 81 scale/background colors, eight avatar pairs, 17 Inter styles, spacing, radius, control/icon/container sizes, strokes, breakpoints, elevation and motion. Existing app tokens are not modified.

import { colors, typography, spring } from '@commenda/pathfinder/tokens';
import '@commenda/pathfinder/styles.css';
import '@commenda/pathfinder/fonts.css'; // Optional self-hosted normal Inter.

export const Title = () => <h1 className="pf-txt-heading-24">Entities</h1>;

All pf-txt-* classes ship precompiled; choose semantic HTML independently. @commenda/pathfinder/tokens.json provides the same values, source node IDs and unit metadata for tooling and AI. Durations use milliseconds; spring durations use seconds. No motion library or automatic animation ships with the tokens.

Legacy Button color override variables remain available, now referencing the new scales. Its baseline is Inter Label/13 Strong (13/16 at weight 500), so the default button is now 32px tall at the 16px root. Long labels still wrap and increase height. Dark mode is deferred by the Figma specification. See Fumadocs Foundations and Storybook Foundations/Start here for reference tables and specimens.

Distribution

pnpm --dir packages/pathfinder pack --pack-destination /tmp

Packing rebuilds the package. Only dist, this README, and package metadata ship. React and React DOM are peer dependencies; Base UI is a runtime dependency. The package is publishable but has not been published. Registry/access settings and release automation will be configured before the first release.

Verification

pnpm pathfinder:lint
pnpm --filter @commenda/pathfinder lint:fix
pnpm --filter @commenda/pathfinder test
pnpm --filter @commenda/pathfinder check-types
pnpm --filter @commenda/pathfinder test:package
PATHFINDER_NEXT_SMOKE=1 pnpm --filter @commenda/pathfinder test:package
pnpm pathfinder:docs:build
pnpm pathfinder:storybook:build

The package tests cover behavior, compiled CSS/client boundaries, and public types under Bundler and NodeNext resolution. Packed-consumer tests install a tarball outside the workspace with React 18 and 19. The optional Next.js check builds Pages Router fixtures and an App Router server-component import without Tailwind. Fixture directories are retained in the system temporary directory.

Source components, stories, and behavior tests are colocated under src/components/<component>. Build helpers and test configuration have separate TypeScript checks; they are excluded from declaration output.

Lint standards

Pathfinder and its docs use a scoped ESLint 9 flat configuration; existing apps keep their own lint setup. CI rejects warnings as well as errors. Rules cover strict type-aware TypeScript (including unsafe any, unhandled promises and exhaustive switches), explicit type imports/exports, React hooks, accessible JSX, unused imports, and component package boundaries. Components cannot import Next.js, application code, private workspace packages, or generated output. Build-time token helpers remain outside component source.

Generated files and isolated consumer fixtures are excluded. Fixtures are checked by their own compiler/build tests. Stories and tests keep type checking and lint; only unbound-method checks are relaxed for mock assertions. Inline ESLint disables are rejected; document any necessary exception in the scoped config. Accessibility lint complements Storybook accessibility checks and keyboard tests.

Planned follow-up

Figma-based component styles, additional primitives, visual regression baselines, Changesets publishing, archived documentation versions, and optional MCP support follow this foundation. Current AI documentation includes package version metadata but does not yet retain historical releases.

Foundation source layout

Each foundation keeps its token definitions and Storybook specimens together:

src/foundations/
  index.ts
  color/        color-tokens.ts, Color.stories.tsx
  typography/   typography-tokens.ts, Typography.stories.tsx
  sizing/       sizing-tokens.ts, Sizing.stories.tsx
  elevation/    elevation-tokens.ts, Elevation.stories.tsx
  motion/       motion-tokens.ts, Motion.stories.tsx
  overview/     StartHere.stories.tsx
  shared/       foundations.stories.css

Edit a domain's token file to change values, and its colocated story to change examples. Stories import their domain directly. foundations/index.ts assembles the public /tokens interface and source provenance; consumers continue using the package exports. The shared folder contains specimen-only styling. Keep runtime token definitions independent of stories and React. Add a new domain when it has its own concepts and examples; individual scale entries do not need separate files or folders.

Visual assets

Import finished styles once, then use a collection or individual component:

import '@commenda/pathfinder/styles.css';
import { SearchMdIcon } from '@commenda/pathfinder/icons/SearchMdIcon';
import { USFlag } from '@commenda/pathfinder/flags/USFlag';

<SearchMdIcon size={16} tone="brand" />
<USFlag size={24} label="United States" />

Collections: /icons, /flags, /file-types, /status-icons, and /logos/{integrations,payments,software,commenda}. /flags/dynamic explicitly opts into the full flag registry for unknown-at-build-time country codes. /assets.json is the versioned source/import manifest. Assets render native inline SVG and accept width, height, and native SVG attributes. Simple glyphs stay server-compatible; artwork with masks/gradients uses a narrow client boundary with SSR-safe instance IDs. Both can be imported from server components; no SVG loader, consumer CSS compilation, remote images, or asset-copy step is required.

Keep one source for verified scalable artwork and use render dimensions for sizing. Optical variants and non-equivalent layouts retain their own source. Flags and scalable integration marks get their fixed hairline from compiled CSS. Repeated drawings share generated artwork modules. See the source guide for extraction, deduplication, checksums, and regeneration.

Storybook has separate searchable libraries under Assets, with compact category grids, size previews, searchable names, and a keyboard-accessible dialog for copyable imports and Figma links. Fumadocs exposes the same explorers alongside rules and examples at /docs/assets. Collection code loads separately. Set STORYBOOK_DOCS_URL when building a hosted Storybook to point its usage links at the deployed docs; local links default to port 3002. The asset rules and full import inventory flow into llms.txt, llms-full.txt, and page Markdown.

Category imports

import { Icons } from '@commenda/pathfinder';

<Icons.Flags.US label="United States" />
<Icons.Interface.SearchMd size={16} tone="quiet" />
<Icons.FileTypes.Pdf />
<Icons.Folder status="open" />
<Icons.Status status="completed" label="Completed" />
<Icons.Progress.Ring value={33} label="Documents complete" />
<Icons.Logos.Integrations.Quickbooks />

Icons.Logos also includes Payments, Software, and Commenda. These are ESM namespace exports with the same props as individual components. Use static member access for tree shaking. Passing or dynamically indexing entire namespaces may retain additional artwork. The asset manifest includes every namespace path; existing named and direct imports remain supported.

Styling contributions

Use pf: Tailwind v4 utilities and Pathfinder tokens for runtime components. Keep genuinely shared class recipes next to their consumers; retain CSS only for foundations, fonts, keyframes, and documented exceptions. The package compiles all utilities into styles.css; consumers need no Tailwind configuration. See the Fumadocs contribution guide for state, RTL, formatting, and packed-artifact checks.

AI content

Import Markdown, CodeBlock, and InlineReference from their markdown, code-block, and inline-reference subpaths. They use the existing compiled stylesheet. Optionally import @commenda/pathfinder/code-font.css for the Figma Geist Mono font.

The new code renderer uses Lowlight/Highlight.js. Streaming Markdown uses Streamdown without enabling its math or diagram plugins. Applications retain message IDs, message parts, routing, and orchestration. Existing consumers are not migrated. See the Fumadocs AI content integration guide for compatibility mappings.

Markdown is intentionally available through @commenda/pathfinder/markdown only (its types are also exported from the root). Streamdown has module side effects; keeping this runtime off the root barrel prevents unrelated icon and button imports from loading the Markdown parser.

AI input context is available from /attachment, /attachment-group, and /composer-context (also exported from the root). Attachments preserve host IDs, filenames, upload state, and callbacks; validation and responsive overflow are included, while uploads and viewer content remain app-owned. See the corresponding component docs for migration mappings and Figma rules.

AI drafting exports: /composer, /suggested-prompt, and /suggested-prompt-group. Composer uses a controlled string draft and AI SDK-compatible request statuses, composes attachments and context, and leaves uploads, request errors, dictation, and clearing to the host. See the corresponding docs for skill search and migration mapping.