To add new built-in components, patterns, or tools, edit library/library.json. The file is a JSON array where each object represents one library item. The REST endpoint picks up changes automatically through its cache invalidation (the transient is refreshed when the file’s modification time changes).

Field reference #

Here is a complete item object with every available field:

{
  "id": "unique-slug",
  "name": "Display Name",
  "type": "component",
  "category": "category-slug",
  "description": "Short description shown on the card.",
  "tags": ["tag1", "tag2"],
  "version": "1.0.0",
  "wireframe": "assets/img/your-image.svg",
  "preview": "https://your-site.com/preview/your-component",
  "docs": "https://your-docs-url",
  "copyable": true,
  "json": "{\"type\":\"your/block\"}"
}

Required fields #

id is a unique slug that identifies the item. It is used internally to track starred status, recent history, and usage counts in localStorage. Once an item is published with an ID, do not change it or users will lose their starred/recent state for that item.

name is the display name shown on the card and in the detail view.

type must be one of component, pattern, or tool. This determines which type filter the item appears under.

category is a slug used for the category filter dropdown and the badge colour. Use an existing slug to inherit its colour, or define a new one and add a matching CSS class (see Badge Colours below).

Optional fields #

description is a short text shown on the card and in the detail view. Keep it to one or two sentences.

tags is an array of strings. The search input checks tags alongside the name and description. Add relevant keywords here to make the item easier to find.

version is shown as a small badge in the detail view. Useful for tracking iterations.

wireframe is a relative path to an SVG file in the assets/img/ directory. This image is shown on cards and in the sidebar detail view. If omitted, placeholder.svg is used.

svgCode is a raw SVG markup string. This is primarily used by custom items created through the panel UI. When both wireframe and svgCode are present, svgCode takes precedence.

preview is an https:// URL embedded as an iframe in the detail view (full-width mode only). When set, the viewport preset buttons (Mobile, Tablet, Full) become available. Point this to a live demo page of the component.

docs is an https:// URL for the Docs button in the detail view. Opens in a new tab.

copyable defaults to true. Set it to false for tools so the Copy JSON button is not shown.

toolId is the key of a registered tool in the TOOLS map in panel.js. When this field is present and the tool is registered, clicking the card opens the tool view instead of the standard detail view.

json is the block JSON string that gets copied to the clipboard when the user clicks Copy JSON. If omitted, the Copy JSON button is hidden and the Docs button becomes the primary action.

The json field in detail #

The json field can contain more than just the block data. It supports two optional keys that are displayed in the detail panel:

{
  "type": "your/block",
  "version": "1.0.0",
  "config": {
    "propName": "defaultValue",
    "anotherProp": true
  },
  "usage": "Short usage instruction or HTML snippet shown in the detail panel."
}

config is an object of key/value pairs. The detail view renders these as a table showing each property name and its default value. Use this to document the configurable options of your component.

usage is a string rendered as a monospaced code block in the detail view. Use it for a short instruction, an HTML snippet showing how to trigger the component, or any other quick-reference text the user might need after pasting.

Adding a tool #

Tools require both a library entry in library.json and a renderer function in panel.js.

In panel.js, the TOOLS map at the top of the file registers tool renderers. Each entry maps a toolId string to a function that returns a DocumentFragment. The fragment must contain exactly two children:

1. A .ek-tool-body element for the scrollable tool content
2. A .ek-detail-actions element for the sticky action bar at the bottom

In sidebar mode, the action bar uses position: sticky. In full-width mode, it uses absolute positioning. The panel handles this automatically based on the layout mode.

In library.json, set the toolId field on the item to match the key you used in the TOOLS map. Set copyable to false since tools do not have JSON to copy.

Badge colours #

Each category slug maps to a CSS class named ek-badge-{category} in panel.css. The following slugs have built-in colours:

Slug	Colour
interactions	Green
feedback	Amber
media	Blue
layout	Purple
forms	Red
navigation	Yellow
sections	Light blue
cards	Coral
footer	Mint
heroes	Lavender
marketing	Orange
design	Cyan

If you create a new category, add a corresponding .ek-badge-{slug} rule to panel.css. Without it, the badge still renders using the default neutral style (--ek-surface background, --ek-muted text), so nothing breaks. It just looks generic.