# Visual assets

Package: @commenda/pathfinder@0.1.0
Page: /docs/assets

Browse the collections below, search by name, and select artwork to copy its import. The [machine-readable asset reference](/assets.txt) records the complete public surface and any explicit exclusions.

<AssetPreview />

## Install and render [#install-and-render]

Import `@commenda/pathfinder/styles.css` once. Each collection has its own entry point. Individual components also have direct imports, such as `@commenda/pathfinder/icons/SearchMdIcon`. No application Tailwind scan, SVG loader, remote asset service, or asset-copy step is required.

Artwork renders as native inline SVG. Pathfinder generates and compiles the React components at package build time; consuming apps need no SVG loader. Monochrome paths use `currentColor`; multicolor artwork preserves its source colors. Simple glyphs are server components. Artwork with masks, clipping paths, or gradients uses a small client boundary with React `useId` so repeated instances remain unique through server rendering and hydration. Original embedded raster images are retained where they are part of a supplied logo.

### Category namespaces [#category-namespaces]

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

<Icons.Flags.US label="United States" />
<Icons.Interface.SearchMd size={16} tone="quiet" />
<Icons.FileTypes.Pdf label="PDF document" />
<Icons.Folder status="closed" size={24} />
<Icons.Status status="completed" label="Completed" />
<Icons.Progress.Ring value={33} label="Documents complete" />
<Icons.Logos.Integrations.Quickbooks label="QuickBooks" />
<Icons.Logos.Payments.Visa label="Visa" />
<Icons.Logos.Software.Google label="Google" />
<Icons.Logos.Commenda.Lockup label="Commenda" />
```

The categories autocomplete in TypeScript and preserve each component's props. Country names use uppercase codes; territory hyphens are removed in JSX names, for example `Icons.Flags.GEAB`. Every component's namespace is listed in the [machine-readable asset reference](/assets.txt) and `assets.json`. Static member access is tree-shakeable. Passing whole categories around or indexing them dynamically may retain that category's artwork; use `CountryFlag` from `/flags/dynamic` when the country code comes from data.

### Folder and status rules [#folder-and-status-rules]

**ASSET-API-01:** Use one `Icons.Folder` component with the required `status="open" | "closed"` prop. It renders the illustrated document-folder family. Choose `size={16 | 24 | 40}`; the default is 16. Do not use the former `Icons.FileTypes.Folder` or `Icons.FileTypes.FolderOpen` aliases. Outline interface-folder glyphs are a separate family under `Icons.Interface`.

**ASSET-API-02:** `Icons.Status` is a component, not a category namespace. Its required `status` is one of `to-do`, `scheduled`, `in-progress`, `in-review`, `completed`, `canceled`, `blocking`, `blocked-by`, `failed`, or `needs-attention`. Always supply a translated `label`. Use `size={12 | 16 | 20 | 24}`; the default is 16. Replace `Icons.Status.Completed` with `<Icons.Status status="completed" label="Completed" />`. Existing named `StatusIcon` imports continue to work.

### Native sizing [#native-sizing]

**ASSET-SIZE-01:** `size` selects an authored optical variant. `width` and `height` control the rendered dimensions while the source `viewBox` preserves its proportions. You do not need another downloaded file for a different display size.

```tsx
<Icons.Interface.SearchMd size={24} width={32} height={32} tone="inherit" />
<Icons.Logos.Integrations.Quickbooks width={48} height={48} label="QuickBooks" />
```

Native SVG attributes such as `aria-label`, `aria-labelledby`, `aria-describedby`, `className`, `style`, and event handlers are forwarded to the SVG. Event handlers belong in client components. Prefer `label` for a simple accessible name; an explicit `aria-label` takes precedence. Refs and replacement children are not part of this API.

## Accessibility rules [#accessibility-rules]

- **ASSET-A11Y-01:** Omit `label` for decorative artwork beside equivalent visible text. Meaningful standalone artwork needs an explicit, localized `label`.
- **ASSET-A11Y-02:** Name an icon-only button on the button. The icon stays decorative; a tooltip alone is insufficient.
- **ASSET-A11Y-03:** Status and progress information must have a readable name/count. Color is never the only signal. Assets do not create focus stops.
- **ASSET-SOURCE-01:** Canonical source SVGs, original checksums, and verified shared-source mappings are retained locally. Never fetch temporary Figma URLs at runtime. Do not hand-edit generated components.

## AI and provenance [#ai-and-provenance]

The same pages are available through the Markdown links, `/llms.txt`, and `/llms-full.txt`. Import `@commenda/pathfinder/assets.json` to inspect the versioned catalog without importing a runtime registry. It records availability, source node IDs, sizes, export names, upstream versions, and downloaded-source checksums. Shared source references record deduplication without losing the original Figma IDs. Activity’s tooltip and motion variants are explicitly excluded from the static API.

Brand marks remain their owners' trademarks. See the package's third-party notices for source licenses. The package remains UNLICENSED.