# Code block

> Exact text to copy: a file name, its language, line numbers outside the copy, and changed lines marked with an asterisk in the right margin, the way revised script pages are.

Source: https://kwark.space/designSystem/components/code-block

## Usage

### What it is
Exact text someone will copy: a configuration file, a command, a snippet of HTML. What makes it Kwark's is the margin. Screenplays mark every changed line of a revised page with an **asterisk in the right margin**, so an actor finds the new words without rereading the page. A code block does the same: changed lines carry the asterisk, and the bar says which (*Lines 4–6 changed*). Readers who have pasted the old version see at once what to update.

### When to use
- Configuration, commands and code in documentation, release notes, the MCP page, and help for agents.
- Any text where whitespace and every character matter.

### When not to
- Screenplay text. That is the [Screenplay page](https://kwark.space/designSystem/components/screenplay-page.md), in Courier Prime.
- A single value to copy (an invite link, a project ID). Use a copy field.
- Prose that happens to mention a file name. Use inline `code`.

### Variants
| Variant | Use |
|---|---|
| File | A file name and language in the bar, line numbers in the gutter |
| Shell (`--shell`) | Commands; a quiet `$` prompt per line, no line numbers |
| Revised | `data-rev` on changed lines; the bar names them |

### Copy
- **Copy** sits in the bar, a real button, 28px (44px on touch).
- It copies the code exactly: line numbers, prompts and asterisks are drawn by CSS and never copied.
- After the clipboard write succeeds, it says **Copied** with a check for 2 seconds, then returns. If the write fails, it says **Select and copy** and selects the text. Never claim success before the write resolves.

### Writing
The bar names the file as it is on disk (*.mcp.json*) or the place it runs (*Terminal*). The revision note counts lines: *Lines 4–6 changed*.

**Do:** *.mcp.json · JSON · Lines 4–6 changed*, asterisks in the right margin, **Copy** in the bar.

**Don't:** A grey box with no language, line numbers that get pasted with the code, and a copy icon that says nothing.

## Style

### Anatomy

1. **Frame**: 1px `--k-line`, 10px corners, `--k-inset` ground for the code.
2. **Bar**: 40px, `--k-surface`, 1px rule under it. File name 12px 500 with a 14px icon; language 12px `--k-text-2`; revision note 12px on `--k-chart-mango` at 18%; Copy on the right.
3. **Copy button**: 28px, 6px corners, 14px icon and the word; hover `--k-raise`; copied state in `--k-ok`.
4. **Code**: a focusable region (not a bare `<pre>`: each line is its own block), `--k-font-mono` at 12px, line height 1.7, 16px padding; scrolls sideways inside the block, never wraps by default.
5. **Gutter**: line numbers from a CSS counter, 32px, right-aligned, `--k-text-2`, not selectable.
6. **Revision mark**: `*` in the 20px right margin, 600, `--k-text`; the line has a 6% text-colour ground.
7. **Tokens**: keys `--k-text`, strings `--k-accent`, punctuation `--k-text-2`. No more than three colours.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-inset` | #f1f5f9 | #141414 |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent` | #98633f | #98633f |
| `--k-info` | #255799 | #7db4f0 |
| `--k-chart-mango` | #b4802e | var(--k-brand-mango) |
| `--k-ok` | #2c6e49 | #6cc08a |
| `--k-font-mono` | ui-monospace, 'SF Mono', Menlo, Consolas, monospace |  |
| `--k-fs-meta` | 12px |  |
| `--k-radius-card` | 10px |  |
| `--k-radius-control` | 6px |  |

### States
| State | Look |
|---|---|
| Rest | As drawn |
| Copy hover | `--k-raise` |
| Copy focus | 2px `--k-focus` outline, 2px offset |
| Copied (`data-state="copied"`) | Check icon, *Copied*, `--k-ok` text |
| Failed | *Select and copy*, the code selected |
| Long line | Scrolls sideways; the gutter and the asterisk stay put |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<figure class="kw-codeblock">
  <figcaption class="kw-codeblock__bar"><span class="kw-codeblock__file"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/></svg>.mcp.json</span><span class="kw-codeblock__lang">JSON</span><span class="kw-codeblock__rev">Lines 4–6 changed</span><button class="kw-codeblock__copy" type="button" aria-label="Copy .mcp.json"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v1"/></svg><span>Copy</span></button></figcaption>
  <div class="kw-codeblock__pre" tabindex="0" role="region" aria-label=".mcp.json, 9 lines"><code><span class="kw-cl"><span class="kw-tk-p">{</span></span><span class="kw-cl">  <span class="kw-tk-k">"mcpServers"</span><span class="kw-tk-p">: {</span></span><span class="kw-cl">    <span class="kw-tk-k">"kwark-design"</span><span class="kw-tk-p">: {</span></span><span class="kw-cl" data-rev>      <span class="kw-tk-k">"command"</span><span class="kw-tk-p">:</span> <span class="kw-tk-s">"node"</span><span class="kw-tk-p">,</span></span><span class="kw-cl" data-rev>      <span class="kw-tk-k">"args"</span><span class="kw-tk-p">: [</span><span class="kw-tk-s">"kwark-design-mcp.mjs"</span><span class="kw-tk-p">],</span></span><span class="kw-cl" data-rev>      <span class="kw-tk-k">"env"</span><span class="kw-tk-p">: {</span> <span class="kw-tk-k">"KWARK_DS_DIR"</span><span class="kw-tk-p">:</span> <span class="kw-tk-s">"./public/designSystem"</span> <span class="kw-tk-p">}</span></span><span class="kw-cl">    <span class="kw-tk-p">}</span></span><span class="kw-cl">  <span class="kw-tk-p">}</span></span><span class="kw-cl"><span class="kw-tk-p">}</span></span></code></div>
</figure>
<figure class="kw-codeblock kw-codeblock--shell">
  <figcaption class="kw-codeblock__bar"><span class="kw-codeblock__file"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5 8 4 4-4 4M12 16h7"/></svg>Terminal</span><span class="kw-codeblock__lang">Shell</span><button class="kw-codeblock__copy" type="button" data-state="copied" aria-label="Copied the build command"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"/></svg><span>Copied</span></button></figcaption>
  <div class="kw-codeblock__pre" tabindex="0" role="region" aria-label="Build command, 2 lines"><code><span class="kw-cl">node design-system/build.mjs</span><span class="kw-cl">node --test tests/design-system-site.test.cjs</span></code></div>
</figure>
```

### Copy behaviour
```js
button.addEventListener('click', async () => {
  const text = pre.querySelector('code').innerText; // numbers, prompts and asterisks are CSS pseudo-elements, so never copied
  try { await navigator.clipboard.writeText(text); setState('copied'); }
  catch { selectAll(pre); setState('failed'); }
});
```
Write each line as `<span class="kw-cl">` with no newline characters between them (the spans are blocks; `innerText` puts the newlines back), so CSS can number them. Add `data-rev` to changed lines.

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Reaches **Copy**, then the code area (it scrolls with arrow keys) |
| Enter or Space on Copy | Copies; the result is announced |

### Screen readers
- Copy is named with what it copies: *Copy .mcp.json*.
- The result goes to a polite live region: *Copied .mcp.json* or *Copy did not work. The text is selected.*
- The code area is named with the file and its length.
- Changed lines are named in the bar in text, so the asterisk is not the only signal.

## For agents

### Rules

- **Must** copy the text byte for byte; numbers, prompts and asterisks are never in the copied text.
- **Must** say Copied only after the clipboard write succeeds.
- **Always** name the file or place and the language in the bar.
- **Must** mark changed lines with the right-margin asterisk and name them in the bar.
- **Never** use Courier Prime for code; it is for screenplay text only.

### AI readiness test

**Task:** Show the updated MCP connection snippet on the release notes page after the server path changed.

**Give the agent:** Code block, the MCP page, Releases.

**Constraint:** Readers have the old snippet already pasted in their config.

**A reliable answer:**
- File name and JSON in the bar
- Changed lines marked with the asterisk and named in the bar
- Copy copies only the JSON
- Copied shown after the write succeeds
