# Designed blocks

A company's own HTML and CSS on a door's page, with Kapi's live parts filled in for each person. Make one with Kapi, with your own AI or from HTML.

A designed block is a company's own HTML and CSS on a door's page: a welcome, a section, or a whole page made of one block. It sits among Kapi's other blocks, styled by the door's [look](https://docs.kapiworks.com/build/looks) around it. Kapi fills its live parts with each person's own data, such as their name and their steps to start, and shows it in a sealed frame from Kapi's content address, where nothing in it runs.

## Make a designed block

In Works Studio, open an audience, then **Setup**, then **Pages**, and add a **Designed block** to a page. There are three ways to make one:

* **Make it with Kapi.** Describe the block, and Kapi's AI writes it.
* **Copy prompt for your AI.** Copies [the prompt](#the-prompt), with what you described, for ChatGPT, Claude, Gemini or any AI. Paste what your AI makes back into Works Studio.
* **Paste HTML** from a designer.

Every way ends in Kapi's reader, then [the checks](#the-checks).

## The format

```text
THE DESIGNED BLOCK FORMAT
- One HTML document or fragment, at most 60 KB after Kapi reads it: <!doctype html>, <html lang="en-GB">, a head with one <style>, then the body. Kapi shows it on a door page under Kapi's own header and menu, so it has no header, menu, sign-in or footer of its own.
- Elements: html, head, body, main, section, article, header, footer, aside, nav, div, span, p, h1, h2, h3, h4, h5, h6, ul, ol, li, dl, dt, dd, blockquote, figure, figcaption, hr, br, strong, em, b, i, u, s, small, mark, sub, sup, abbr, cite, q, code, pre, time, a, img, table, thead, tbody, tfoot, tr, th, td, caption, colgroup, col, details, summary, address, wbr.
- SVG elements, for drawings: svg, g, path, circle, rect, line, polyline, polygon, ellipse, title, desc, defs, lineargradient, radialgradient, stop, clippath, mask, text, tspan.
- Mark a decorative drawing aria-hidden="true".
- Live parts: <kapi-name></kapi-name>, <kapi-progress></kapi-progress>, <kapi-steps></kapi-steps>, <kapi-learning></kapi-learning>, <kapi-updates></kapi-updates>, <kapi-contact></kapi-contact>.
- Put each live part where it belongs and leave it empty. Kapi fills it with each person's own data, in Kapi's words.
- Door links: kapi:home, kapi:learning, kapi:certificates, kapi:resources, kapi:updates, kapi:start, kapi:page/{address}.
- kapi:page/{address} opens one of the door's pages by its address. Other links: https://, which opens in a new tab, and mailto:.
- Pictures, in <img src> or CSS url(): kapi-asset:logo, the company's logo; kapi-asset:photo, the door's photo; and kapi-asset:picture/{name} for up to 6 pictures uploaded with the block, PNG, JPEG or WebP up to 2 MB each.
- Every picture has alt text that says what it shows, or aria-hidden="true" when it is decoration.
- Door colours: var(--door-colour), var(--door-on-colour), var(--door-colour-strong), var(--door-fill), var(--door-on-fill), var(--door-paper), var(--door-ink), var(--door-muted), var(--door-line), var(--door-progress).
- The door colours have dark values when the person's theme is dark. Use --door-fill with --door-on-fill for buttons and bands, --door-on-colour for words on the door colour, and --door-colour-strong for lines, rings and progress on paper.
- For other dark styles, start a rule with .dark, as in .dark .hero { … }.
- Fonts: the device's own, such as system-ui, -apple-system, "Segoe UI", Roboto, Arial and sans-serif. Web fonts don't load.
- Kapi removes data- attributes, tabindex, and class names that start with kapi-, which belong to Kapi's live parts.
- No scripts, forms, buttons, frames, video or audio. Kapi removes them, and a block that loses something people would see doesn't publish until its words change.
- CSS content: only symbols and counters, such as an arrow, a tick or a step number. No words.
```

## Kapi's live parts

Place a live part where it belongs and leave it empty. When a person opens the page, Kapi fills it with their own data, in Kapi's words, so a step shows as done only when the person has done it. Kapi empties the live parts when it reads a block, so a design shows only Kapi's data in them.

| Live part | What Kapi fills in |
| --- | --- |
| `<kapi-name></kapi-name>` | The person's first name. |
| `<kapi-progress></kapi-progress>` | How far the person has come, in Kapi's words, such as how many of their steps are done. |
| `<kapi-steps></kapi-steps>` | The person's steps to start, each with its state, such as done or up next. |
| `<kapi-learning></kapi-learning>` | The person's learning: what is required and by when, and what to continue. |
| `<kapi-updates></kapi-updates>` | The newest updates the person may see. |
| `<kapi-contact></kapi-contact>` | Who to ask: the door's contacts, each with their role and email address. |

## Door links

A door link opens a part of the door without leaving it.

| Door link | Opens |
| --- | --- |
| `kapi:home` | The door's Home. |
| `kapi:learning` | My learning, or Courses in a customer door. |
| `kapi:certificates` | The person's certificates. |
| `kapi:resources` | Resources. |
| `kapi:updates` | Updates. |
| `kapi:start` | The steps to start. |
| `kapi:page/{address}` | One of the door's pages, by its address: lowercase letters, numbers and single hyphens, up to 40 characters. |

Other links go to `https://` addresses, which open in a new tab, or to `mailto:` addresses.

## Pictures

A block shows the company's logo as `kapi-asset:logo`, the door's photo as `kapi-asset:photo`, and up to 6 pictures uploaded with it as `kapi-asset:picture/{name}`: PNG, JPEG or WebP, up to 2 MB each. Each picture has alt text that says what it shows, or `aria-hidden="true"` when it is decoration.

## What Kapi removes

Kapi's reader is code, not AI. It keeps the format above and removes scripts, `on…` attributes, `javascript:` and `data:` links, frames, video, sound, forms, `link`, `meta`, `base` and `template` elements, `@import`, `@font-face`, `url()` from other websites, `expression()`, `behavior`, `-moz-binding` and `image-set()`. It reads each `style` element in the head on its own, so a broken one leaves the others as they are. It removes `kapi-` classes from the company's own elements.

A block is at most 60 KB after reading, and Kapi reads nothing over 400 KB. Reading a block Kapi has read changes nothing.

## What Kapi says

Kapi's readers say the same things about looks and designed blocks. Each finding says what Kapi changed and links to how to fix it.

Problems stop publishing: something people would see was removed, a link goes nowhere, a picture has no description, or the block is too large. Removing something people would see leaves words that no longer make sense, so the words change first. In Works Studio, **Let Kapi fix** rewrites them within the format, and **Copy prompt for your AI** gives your own AI what Kapi found.

| Finding | What Kapi says |
| --- | --- |
| [`not_readable`](https://docs.kapiworks.com/build/reference/doors/not-readable) | Kapi couldn't read this. Paste the whole file again, or ask your AI to write it again from Kapi's prompt. |
| [`too_large`](https://docs.kapiworks.com/build/reference/doors/too-large) | This is over … after Kapi read it. Make it shorter or simpler. |
| [`not_steady`](https://docs.kapiworks.com/build/reference/doors/not-steady) | Kapi couldn't read this the same way twice, so it can't show it safely. Simplify the markup, then try again. |
| [`removed_frame`](https://docs.kapiworks.com/build/reference/doors/removed-frame) | Kapi left out an embedded frame or player. Change the words around it, and put videos in a course or resource. |
| [`removed_media`](https://docs.kapiworks.com/build/reference/doors/removed-media) | Kapi left out a video, sound or drawing area. Change the words around it, and put videos in a course or resource. |
| [`removed_form`](https://docs.kapiworks.com/build/reference/doors/removed-form) | Kapi left out a form, field or button. Change the words around it, and use a link to a door page, a Kapi form or Who to ask instead. |
| [`outside_picture`](https://docs.kapiworks.com/build/reference/doors/outside-picture) | Kapi left out a picture from another website. Upload it with the block, or use the logo or the door's photo. |
| [`missing_picture`](https://docs.kapiworks.com/build/reference/doors/missing-picture) | This block shows pictures that weren't uploaded with it (…). Upload them, or remove them. |
| [`missing_alt`](https://docs.kapiworks.com/build/reference/doors/missing-alt) | A picture has no description. Add alt text, or mark a decorative picture aria-hidden="true". |
| [`dead_link`](https://docs.kapiworks.com/build/reference/doors/dead-link) | A link only ran code, so it does nothing now. Point it at a page, or remove it. |
| [`unsafe_link`](https://docs.kapiworks.com/build/reference/doors/unsafe-link) | A link goes somewhere Kapi doesn't open. Use https://, mailto: or a door link such as kapi:home. |
| [`body_style`](https://docs.kapiworks.com/build/reference/doors/body-style) | Kapi left out a style inside the page's body. Put every `<style>` in the head. |

Notes say what Kapi left out that nobody would see, such as a tracker script, a web font or a page setting. They don't stop publishing.

| Finding | What Kapi says |
| --- | --- |
| [`removed_code`](https://docs.kapiworks.com/build/reference/doors/removed-code) | Kapi left out a piece of code. Door pages don't run code. |
| [`removed_external`](https://docs.kapiworks.com/build/reference/doors/removed-external) | Kapi left out something loaded from another website, such as fonts or trackers. |
| [`removed_head`](https://docs.kapiworks.com/build/reference/doors/removed-head) | Kapi left out a page setting from the head. |
| [`removed_tag`](https://docs.kapiworks.com/build/reference/doors/removed-tag) | Kapi kept the words of an element it doesn't show, without the element. |
| [`removed_attribute`](https://docs.kapiworks.com/build/reference/doors/removed-attribute) | Kapi left out an attribute it doesn't use, such as data- or tabindex. |
| [`web_font`](https://docs.kapiworks.com/build/reference/doors/web-font) | Door pages don't load web fonts (…); people see their device's own font. |
| [`removed_rule`](https://docs.kapiworks.com/build/reference/doors/removed-rule) | Kapi left out a rule whose selector isn't one of Kapi's block classes. |
| [`removed_property`](https://docs.kapiworks.com/build/reference/doors/removed-property) | Kapi left out a style a door page can't use (…). |
| [`removed_at_rule`](https://docs.kapiworks.com/build/reference/doors/removed-at-rule) | Kapi left out an @ rule it doesn't allow. Looks may use @media for width, contrast and motion. |
| [`motion_unguarded`](https://docs.kapiworks.com/build/reference/doors/motion-unguarded) | Kapi left out an animation or transition outside @media (prefers-reduced-motion: no-preference). |

## The checks

While you preview the door, your browser checks each designed block in its sealed frame:

* axe-core's WCAG 2.2 AA rules, at 1180 and 375 pixels wide, in light and dark;
* no sideways scrolling at 320 pixels;
* every live part shows: none hidden, of no size, or covered.

Kapi keeps the result with the block's height at each width, so the page keeps the block's space while it opens. Publishing needs a passing result for every designed block, and Kapi's server reads every block again when you publish.

## The prompt

**Copy prompt for your AI** copies this prompt, with your company's name, the door and what you described. Here it is for a made-up company:

```text
Kapi Works designed block prompt · Northwind Payroll · Partners door

Design a block for my company, Northwind Payroll, on Kapi Works, our learning platform: one HTML document for the people who come through our Partners door. Kapi shows it on one of the door's pages, and fills in each person's own data where you place Kapi's live parts.

What I want: A welcome for new resellers: a short hello, their steps to start and who to ask.

THE DESIGNED BLOCK FORMAT
- One HTML document or fragment, at most 60 KB after Kapi reads it: <!doctype html>, <html lang="en-GB">, a head with one <style>, then the body. Kapi shows it on a door page under Kapi's own header and menu, so it has no header, menu, sign-in or footer of its own.
- Elements: html, head, body, main, section, article, header, footer, aside, nav, div, span, p, h1, h2, h3, h4, h5, h6, ul, ol, li, dl, dt, dd, blockquote, figure, figcaption, hr, br, strong, em, b, i, u, s, small, mark, sub, sup, abbr, cite, q, code, pre, time, a, img, table, thead, tbody, tfoot, tr, th, td, caption, colgroup, col, details, summary, address, wbr.
- SVG elements, for drawings: svg, g, path, circle, rect, line, polyline, polygon, ellipse, title, desc, defs, lineargradient, radialgradient, stop, clippath, mask, text, tspan.
- Mark a decorative drawing aria-hidden="true".
- Live parts: <kapi-name></kapi-name>, <kapi-progress></kapi-progress>, <kapi-steps></kapi-steps>, <kapi-learning></kapi-learning>, <kapi-updates></kapi-updates>, <kapi-contact></kapi-contact>.
- Put each live part where it belongs and leave it empty. Kapi fills it with each person's own data, in Kapi's words.
- Door links: kapi:home, kapi:learning, kapi:certificates, kapi:resources, kapi:updates, kapi:start, kapi:page/{address}.
- kapi:page/{address} opens one of the door's pages by its address. Other links: https://, which opens in a new tab, and mailto:.
- Pictures, in <img src> or CSS url(): kapi-asset:logo, the company's logo; kapi-asset:photo, the door's photo; and kapi-asset:picture/{name} for up to 6 pictures uploaded with the block, PNG, JPEG or WebP up to 2 MB each.
- Every picture has alt text that says what it shows, or aria-hidden="true" when it is decoration.
- Door colours: var(--door-colour), var(--door-on-colour), var(--door-colour-strong), var(--door-fill), var(--door-on-fill), var(--door-paper), var(--door-ink), var(--door-muted), var(--door-line), var(--door-progress).
- The door colours have dark values when the person's theme is dark. Use --door-fill with --door-on-fill for buttons and bands, --door-on-colour for words on the door colour, and --door-colour-strong for lines, rings and progress on paper.
- For other dark styles, start a rule with .dark, as in .dark .hero { … }.
- Fonts: the device's own, such as system-ui, -apple-system, "Segoe UI", Roboto, Arial and sans-serif. Web fonts don't load.
- Kapi removes data- attributes, tabindex, and class names that start with kapi-, which belong to Kapi's live parts.
- No scripts, forms, buttons, frames, video or audio. Kapi removes them, and a block that loses something people would see doesn't publish until its words change.
- CSS content: only symbols and counters, such as an arrow, a tick or a step number. No words.

RULES
1. Plain, warm UK English for the people who come through this door. Take facts, names, numbers, links and pictures only from me. If you need one I haven't given, ask me.
2. Place Kapi's live parts where people need them. Don't write their data yourself.
3. Words have a contrast of at least 4.5:1 with their background, and large words at least 3:1, in light and dark. Headings go in order, and link words make sense on their own.
4. Everything fits widths from 320 to 1180 pixels without sideways scrolling, with type in rem so people can enlarge it.
5. Put any motion inside @media (prefers-reduced-motion: no-preference).
6. Give the whole document. Don't shorten it or write "…".

Before I publish, Kapi checks the block: axe-core's WCAG 2.2 AA rules at 1180 and 375 pixels wide, in light and dark, and sideways scrolling at 320 pixels, and that every live part shows.
If you can open web pages, read https://docs.kapiworks.com/build/pages first.
Reply with only the HTML document.
```

Your AI replies with one HTML document. Paste it into Works Studio, and Kapi reads it like any other block.