# Frontmatter (frontmatter)

> Key/value metadata between literal YAML delimiters, with per-row emphasis, dimming, and a stacked layout.

- Entry: component
- Category: UI
- Preview capabilities: controls
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/frontmatter
- JSON: https://jbm-ui.bns.studio/catalog/frontmatter.json
- Registry item: https://jbm-ui.bns.studio/r/frontmatter.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/frontmatter
```

Also installs @jbm/tokens, @jbm/scene-geometry (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/frontmatter.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/frontmatter.tsx` | `src/jbm/ui/frontmatter.tsx` | `@/jbm/ui/frontmatter` |

## API

### `Frontmatter` (component)

Mono definition list framed by `---` lines on a cream block. Two columns (keys at least 112px, values twice as wide) by default; `stacked` puts each value under its key at full width. Static: no timers or animation; change row props to emphasize or dim fields.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` | `FrontmatterRow[]` | required | Fields in display order. Each row renders `key:` and its value; `key` is also the React key, so keep keys unique. |
| `stacked` | `boolean` | `false` | Stack each value under its key in one full-width column, for narrow or portrait compositions. |
| `style` | `CSSProperties` | none | Inline styles merged last over the cream background, 18px padding, and 14px mono type; use for width or font size. |

### `FrontmatterRow` (type)

One field: `key` (string), `value` (ReactNode), optional `highlight` (3px vermilion bar left of the key), and optional `dim` from 0 to 1 (clamped; 1 fades key and value to 28% opacity).

## Stage

fluid: Width fills the container (minWidth 0) and height follows the rows. Chrome adds 36px of padding, two delimiter lines, and 24px of list margin; rows are separated by 12px (6px plus 12px per value when stacked), and long values wrap anywhere. Set style.width for a fixed box.

## Examples

### Stacked skill metadata with an emphasized and a dimmed field

```tsx
import { Frontmatter } from "@/jbm/ui/frontmatter"

<Frontmatter
  stacked
  rows={[
    { key: "name", value: "pdf-processing", highlight: true },
    { key: "description", value: "Extrae tablas de archivos PDF." },
    { key: "license", value: "Apache-2.0", dim: 0.6 },
  ]}
/>
```

## QA

- Toggle Stack fields: two-column mode keeps keys aligned at 112px minimum; stacked mode indents values under their keys with no overlap.
- Toggle Highlight fields: only the vermilion bar appears; text position does not shift because the bar space is always reserved.
- Drag Dim optional field from 0 to 1: key and value fade together to about 28% opacity and stay legible.
- Check a long unbroken value on a narrow screen: it wraps inside the block instead of overflowing.

## Docs

- [Paper and filing illustrations guide](https://jbm-ui.bns.studio/docs/design-video-components.md)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [SceneGeometry (scene-geometry)](https://jbm-ui.bns.studio/catalog/scene-geometry.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
