Kwark. Design System
Open Kwark

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.

ComponentsData displayReady for Kwark
.mcp.jsonJSONLines 4–6 changed
{ "mcpServers": { "kwark-design": { "command": "node", "args": ["kwark-design-mcp.mjs"], "env": { "KWARK_DS_DIR": "./public/designSystem" } } }}
TerminalShell
node design-system/build.mjsnode --test tests/design-system-site.test.cjs
.mcp.jsonJSONLines 4–6 changed
{ "mcpServers": { "kwark-design": { "command": "node", "args": ["kwark-design-mcp.mjs"], "env": { "KWARK_DS_DIR": "./public/designSystem" } } }}
TerminalShell
node design-system/build.mjsnode --test tests/design-system-site.test.cjs
<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>

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, 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.

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

Do

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

Don’t

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

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.

<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

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.

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.

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

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…