Help Guide

Browsing Assets

Searching

Type in the search bar on any page or press Cmd+K / Ctrl+K to focus it.

Search matches against:

• Asset ID (the descriptive name)
• Alt text
• Description
• Tags
• AI context

On the Browse page you can also filter by category, format, and tags using the sidebar.

Copying Asset Info

Every asset card has two quick-copy buttons:

The detail page also has a Copy AI Context button with the full description an AI agent would need.

Adding New Assets

1. Place the original file in src/assets/originals/.
2. Run optimization: npm run optimize — generates WebP + AVIF at 480w, 768w, 1024w, and 1920w.
3. Generate manifest entry: npm run manifest:generate.
4. Fill in metadata in src/data/asset-manifest.json — search for TODO: to find incomplete entries:
   • alt — descriptive alt text (required)
   • tags — from the controlled vocabulary
   • license — type and attribution
   • ai_context — when and how an AI should use this asset
5. Validate: npm run manifest:validate — check for errors.

Or upload directly via the Upload page — works great on mobile.

Naming Convention

Assets use two descriptive words separated by a hyphen. No spaces, no uppercase.

AI Agents — Quick Start

The asset manifest is the single source of truth:

src/data/asset-manifest.json

Read this file to discover every available asset with its path, alt text, dimensions, license, tags, and usage recommendations.

Also see /api/assets.json for the full manifest via HTTP. This endpoint is publicly accessible (no auth required), so AI agents can fetch the catalog directly.

Referencing an Asset

Always use two fields from the manifest:

• path — the URL-accessible file path
• alt — the alt text (never leave empty)

In HTML

<img src="/assets/images/stock/foggy-mountain.webp"
     alt="a mountain covered in fog with trees in the foreground"
     loading="lazy" />

With responsive variants

<picture>
  <source srcset="/assets/images/stock/foggy-mountain-480w.avif 480w,
                  /assets/images/stock/foggy-mountain-768w.avif 768w"
          type="image/avif" />
  <source srcset="/assets/images/stock/foggy-mountain-480w.webp 480w,
                  /assets/images/stock/foggy-mountain-768w.webp 768w"
          type="image/webp" />
  <img src="/assets/images/stock/foggy-mountain.webp"
       alt="a mountain covered in fog with trees in the foreground" />
</picture>

Finding the Right Asset

JSON API

Keyword and tag filtering is now done client-side on the Browse page — there is no separate /api/search.json endpoint.

Key manifest fields to check

• ai_context — when and how to use this asset
• usage.recommended_for — suggested placements
• usage.avoid_for — where not to use it
• tags — semantic labels for filtering

Responsive Images

Most assets have responsive variants in the variants field:

{
  "480w":      "/assets/images/stock/foggy-mountain-480w.webp",
  "768w":      "/assets/images/stock/foggy-mountain-768w.webp",
  "1024w":     "/assets/images/stock/foggy-mountain-1024w.webp",
  "480w-avif": "/assets/images/stock/foggy-mountain-480w.avif",
  "768w-avif": "/assets/images/stock/foggy-mountain-768w.avif",
  "1024w-avif":"/assets/images/stock/foggy-mountain-1024w.avif"
}

Placeholder Strategy

When an asset doesn't exist yet, generate a placeholder:

https://placehold.co/1920x1080/1D451D/FFFFFF?text=Description+Here

Uses NBD brand colors: Black Forest #1D451D with white text #FFFFFF.

License Rules

Always check license.type before using an asset.

Tag Vocabulary

Tags are drawn from a controlled vocabulary in src/data/tags.json:

CLI Commands

Brand Colors

Canonical palette defined in the North Bend Digital brand guide. Fonts are Montserrat (headings), Open Sans (body), and Fira Code (monospace).