---
title: Artifacts
description: Bespoke brand code, like animated backgrounds, patterns and shaders, with controls you tune once for the whole brand.
---

> Source: https://www.heyarchetype.com/docs/brand/artifacts

Artifacts hold the parts of your brand that a component library can't: animated backgrounds, patterns, textures, generative graphics, hero artwork and motion. Each artifact is a small piece of HTML, CSS and JavaScript that runs on its own. Agents use the real code instead of redrawing it from a description.

## Add an artifact

Open **Artifacts** and press **Add**. The **Add artifact** drawer has four tabs:

| Tab | What it does |
| --- | --- |
| **Marketplace** | Pick ready-made shaders to add in one go. |
| **Code** | Paste HTML, CSS and JavaScript. |
| **Upload** | Add a .html, .js, .jsx, .css or .svg file. |
| **URL** | Point at a raw file or page and Archetype fetches the source. |

The **Name** field is optional. Left blank, Archetype picks a name from the code.

### The shader marketplace

The marketplace holds more than 90 WebGL and WebGPU shaders, grouped into **Gradients**, **Patterns**, **Noise & texture**, **Light & edges**, **Interactive**, **Image & logo** and **Photo effects**. Search by name or category, and tick **Brand colors** to preview every tile in your own palette. Some shaders also use your logo or your photos.

Tick the shaders you want and press the add button, which counts them (for example "Add 3 shaders"). Shaders marked **WebGPU** need a browser that supports it, and browsers without it show the artifact's colors instead.

## Browse your artifacts

The Artifacts page shows a live preview of each artifact. Drag cards to reorder them, and filter by status once any artifact has one. Right-click a card to **Copy code**, **Copy handle**, rename, select or delete it.

## An artifact's page

Click an artifact to open it with a live preview. The panel on the right has four tabs.

### Documentation

What an agent reads before using the artifact:

- **Handle**: the stable name agents fetch it by, such as `aurora-backdrop`.
- **Description**: what it is and how it should be used.
- **When to use**: short tags for the contexts where it fits, up to 40 characters each.
- **Guidance**: free text for where it goes and how to tune it.
- **Dependencies**: libraries the code needs, such as `three` or `gsap`.

The status sits here too. Changes to the name and documentation are saved with the page's **Save**.

### Controls

If the artifact declares controls, they appear here as sliders, toggles, color pickers, selects, image pickers and buttons, all wired to the preview. Moving them doesn't change anything for the brand. Press **Save as brand default** to make the current values the brand's own, or **Reset** to go back.

Brand defaults are what the gallery thumbnail shows, what every component and template running the artifact uses, and what agents are told to apply.

If an artifact has **No controls declared**, the tab shows the block to add to its code, and **Copy full spec for Claude** copies the whole contract so you can ask Claude to add controls for you.

### Code

The artifact's source. Edit it and press **Save code**, or press **Copy code**.

### Comments

A thread on the artifact, with @mentions.

## Declare controls in your own code

An artifact declares its own controls in its code. The short version:

- `[default, min, max, step]` is a slider, a bare number infers its range, `true` is a toggle, a hex string is a color picker, and any other string is a text field.
- Objects with a `type` give you `select`, `color`, `image`, `pad` and `action`.
- One level of nesting makes a titled folder.
- Each value arrives as a CSS custom property on `:root` and on `window.artifactParams`. Define `window.onArtifactParams(p)` to redraw in JavaScript and `window.onArtifactAction(key)` to handle a button.

The full contract, with an example, is on the **Controls** tab of any artifact without controls.

## Ask Claude for a change

Press **Edit** in an artifact's header to ask for a change in plain words. Claude proposes a rewrite of the code, and you apply or discard it. Nothing changes until you apply. Each request uses AI credits. See [AI credits](/docs/billing/credits).

## Artifacts inside components and templates

An artifact can run inside a component example or a template slot. The component or template stores only a reference to the artifact, never a copy, so when you save new brand defaults or new code, every place that uses it updates.

## How agents use artifacts

Agents first get an index: each artifact's name, handle, description, when-to-use tags and guidance, and its controls with your brand defaults, without the source. Asking for one handle returns the full code, a usage snippet and the controls contract. Agents are told to use the code as given and apply your defaults.

Only artifacts that are **Complete** or have no status are served. See [Item states](/docs/workspace/states).

## Next steps

:::cards
- [Templates](/docs/brand/templates): Place artifacts in your layouts.
- [Components](/docs/brand/components): Build artifacts into your UI kit.
- [MCP tools](/docs/agents/tools): How agents fetch an artifact's code.
:::