customize-portolan-browser

Files (5)

• SKILL.md
• catalog-ui-contract.md · reference/
• proposal.md · reference/
• verification.md · reference/
• verify-template.mjs · reference/

SKILL.md (first lines)

<!-- drift: depends-on: portolan-browser, portolan-spec -->

# Customize a Portolan browser for a publisher

This skill adapts an existing browser to one publisher and one catalog. The result reuses
the publisher's visual language and words. It stays a working Portolan browser.

`cholmes/stlouis-data-browser` follows this shape for the City of St. Louis mirror.
`cholmes/trimet-data-browser` follows it for the TriMet mirror. Both keep their changes in a
small set of files, so `git pull upstream main` causes few conflicts.

## Scope

This skill changes the user interface only.

- The catalog is authoritative. Do not edit catalog metadata, styles, legends, thumbnails,
  bounding boxes, source links, converted assets, or data files. Report a catalog defect.
  Do not correct it in the browser.
- Prefer configuration. Change site-local components only when the approved design needs
  behavior that configuration cannot express.
- Upstream work needs separate approval. Report a generic browser defect. Do not edit the
  upstream repository or open an upstream pull request without an explicit request.
- Publication needs separate approval. Do not deploy, publish, push, or open a pull request
  unless the user asks.

## Inputs you must have

Ask for any input you do not have. Do not invent a catalog. Do not pick an unrelated browser
version. Do not infer the publisher from weak evidence.

1. **The catalog.** A local path or a URL to `catalog.json`.
2. **The browser.** A `portolan-browser` checkout or repository, at a known commit.
3. **Publisher evidence.** A reference site, screenshots, or both. Prefer the live site.

## Step 1: Inspect the inputs

Read the catalog structure and several representative collections. Read the browser
configuration surface, the theme, the tests, and `AGENTS.md`. Read the publisher's live site
and take its real CSS values.

Extract only evidence that changes the interface:

- typography, colors, spacing, icons, logos, link treatment, and button states;
- the publisher's words for datasets, rows, departments, topics, tags, downloads, and maps;
- the publisher's page hierarchy and the elements it makes prominent;
- catalog dimensions that hold enough values to support navigation;
- differences between collections, such as geometry type, extent, size, styles,
  legends, metadata richness, and available assets.

Prefer official CSS, design tokens, and reusable assets. Confirm that you may reuse an asset
before you copy it. Read `reference/catalog-ui-contract.md` for the catalog fields the
browser reads.

## Step 2: Propose the design and stop

Give the user a compact proposal. Wait for approval. Revise the proposal when feedback
changes your reading of the evidence. Do not edit the browser before approval.

`reference/proposal.md` lists the required contents and explains how to keep the
interpretation restrained.

## Step 3: Implement the approved proposal

Work down this ladder. Move to the next layer only when the current one cannot express the
approved requirement.

### Layer 1: the root catalog

The root catalog sets 9 options through a `stac_browser` field, with no rebuild. They are
`apiCatalogPriority`, `cardViewMode`, `crossOriginMedia`, `defaultCollectionSort`,
`defaultItemSort`, `defaultThumbnailSize`, `displayGeoTiffByDefault`, `preferredAssets`, and
`showThumbnailsAsAssets`. Read them. Never write them, because the catalog is immutable here.

### Layer 2: `config.js`

`src/merged-config.js` merges four sources in order. They are `config.js`, the `SB_CONFIG`
file, `SB_*` environment variables, and `window.STAC_BROWSER_CONFIG` from
`public/runtime-config.js`. Command line parameters no longer exist.

The keys a rebrand normally sets are `catalogUrl`, `catalogTitle`, `catalogImage`,
`catalogTitleAfterImage`, `allowExternalAccess`, `allowedDomains`, `enforcedColorMode`,
`supportedLocales`, `pathPrefix`, `historyMode`, `cardViewMode`, `defaultCollectionSort`,
`showKeywordsInCatalogCards`, `preferredAssets`, `socialSharing`, `registryUrl`, and
`footerLinks`. `docs/options.md` documents every key.

A browser that serves one catalog sets `catalogUrl`, and sets `allowExternalAccess` to false.
That choice skips the registry start page.

Develop against a local catalog copy with an environment override:

```bash
npx serve /path/to/catalog --cors -l 8081
SB_catalogUrl=http://localhost:8081/catalog.json pnpm start
```

### Layer 3: words, through the locale files

Terminology is configuration. `src/locales/<code>/custom.json` merges over `texts.json`, so
you override a string without a code change. Rename the STAC nouns there:

```json
{
  "stacCollection": "Dataset | Datasets",
  "stacItem": "Row | Rows"
}
```

Apply these cautions. The `catalogs`, `items`, and `search` groups hold their own worded
copies of the same nouns, so change those keys too. Repeat every override in each locale
listed in `supportedLocales`. Each `footerLinks` label resolves as an i18n key first, and
falls back to the literal text.

### Layer 4: content slots, through widget hooks

`widgets.config.js` maps a hook id to an array of widget definitions. The browser has 23
hooks. `docs/widgets.md` lists them, and `pnpm run docs:hooks` regenerates that list. The
useful ones for a landing page are `root-start`, `root-before-content`, `footer-start`,
`view-catalog-meta-start`, `view-catalog-catalogs-start`, and `view-catalog-items-end`.

From portolan-sdi/portolan-skills, Apache-2.0.

More from portolan-sdi/portolan-skills