Micro UI Components for Tech Posts: kbd, Badges, Tags, Inline Code, and Copy Buttons

Why these micro components matter (and how they fail)

In SRE land, we obsess over error budgets because they force honesty. Micro UI components need the same energy. If your docs site has a copy button that sometimes copies extra prompts, you’ve created an error budget for your readers’ time, and you’re spending it without tracking it.

Micro components are “behavioral APIs”

Every component teaches the user a behavior:

• <kbd> teaches “press this exact key sequence.” If wrong, you break flows and accessibility.
• Inline code teaches “this token is exact.” If styled like normal text, it becomes “optional.”
• Badges teach “this is safe/official/stable.” If you use them as decoration, you create implied guarantees.
• Tags teach “this content belongs to a cluster of meaning.” If tags are inconsistent, search becomes folklore.
• Copy buttons teach “you can trust copied commands.” If that trust is broken once, it’s broken forever.

Failure modes you should assume will happen

These are not theoretical. I’ve watched each one cost real incident time:

• Prompt pollution: copy button includes cr0x@server:~$ prompt; pasted into a script; script fails; on-call loses 20 minutes.
• Invisible characters: non-breaking space in an inline code token; copy/paste fails; user blames the tool.
• Badge misreads: a “Recommended” badge interpreted as “Supported”; teams deploy it; security later says “we never approved that.”
• Keyboard mismatch: showing Ctrl for macOS; readers press wrong; they assume feature is broken.
• Code font drift: inline code uses a proportional font; l, I, and 1 become a guessing game.

Paraphrased idea from Google SRE’s Ben Treynor Sloss: reliability is a feature, and you have to prioritize it. Your docs UI is part of reliability, because it determines whether humans can execute the right actions under pressure.

Joke #1: A copy button that copies the prompt is like a seatbelt that sometimes becomes a scarf. Technically fabric, practically chaos.

Fast diagnosis playbook: find the bottleneck in minutes

You have complaints: “copy doesn’t work,” “kbd looks weird,” “badges confuse people.” Don’t open Figma yet. Diagnose like an SRE.

First: confirm the actual failure

1. Reproduce with one real user path: mobile Safari + desktop Chrome + one screen reader pass.
2. Capture the copied payload: confirm whether invisible characters, prompts, or newlines are included.
3. Check the DOM semantics: are you using real <kbd> and <code>, or <span class="code"> cosplay?

Second: identify whether it’s a CSS/JS/build issue

1. CSS issue: component renders but looks wrong; behavior works. Check computed styles, dark mode, font loading, and specificity wars.
2. JS issue: copy button doesn’t copy, copies stale content, or fails under CSP. Check console errors, permissions, and fallback path.
3. Build/content issue: markdown renderer wraps prompts, escapes, or normalizes whitespace. Check the pipeline and sanitizers.

Third: decide the fix class

• Hotfix when users are copying wrong commands: add prompt-stripping, update clipboard logic, ship now.
• Hardening when it’s mostly aesthetic but causes confusion: unify tokens, add tests, enforce linting.
• Redesign when semantics are wrong: switch to native HTML elements and accessible patterns.

The <kbd> element: keyboard truth serum

<kbd> is one of those HTML elements people rediscover every few years, like a tool you already own but somehow keep renting. Use it whenever you instruct key presses. It is semantic, stylable, and screen-reader-friendly when used correctly.

When to use <kbd> vs inline code

• Use <kbd> for keys and shortcuts: Ctrl + C, Shift + ?.
• Use <code> for literal tokens: systemctl, --help, /etc/ssh/sshd_config.
• Do not use inline code for keyboard keys. Readers interpret code as text to copy, not actions to press.

How <kbd> fails in real docs

• Platform mismatch: showing Ctrl on macOS where people expect ⌘ (Command). Fix: conditional rendering or dual display.
• Nested shortcuts: <kbd>Ctrl + C</kbd> is less accessible than separate keys. Better: Ctrl+C.
• Over-styling: you add heavy shadows and gradients; it looks like a clickable button; users click it and get nothing.

Opinionated rules

• Keep kbd styling subtle: border, background, small padding, monospace optional.
• Use consistent separators: I prefer + with no surrounding spaces for compactness: Ctrl+C.
• Don’t invent key names: use Esc not “Escape Key.” Use Enter not “Return” unless platform-specific.

Inline code: typography, semantics, and copy safety

Inline code is where technical writing either earns trust or loses it. It tells the reader: “this exact string matters.” If your inline code is visually weak, it reads like emphasis. If it’s visually loud, it reads like an error. Aim for “precise and calm.”

Inline code should behave like a checksum

The reader should be able to eyeball an inline token and know it’s exact. That means:

• A monospace font with clear glyphs (1 vs l vs I).
• Consistent background and border that works in dark mode.
• No line breaks inside tokens unless you deliberately allow wrapping (then add word-break rules).

Typical failure: “smart punctuation” and typography engines

Many pipelines apply typographic substitutions: curly quotes, en-dashes, non-breaking spaces. In prose, it’s fine. In commands, it’s sabotage. Your renderer should:

• Disable smart punctuation inside <code> and <pre>.
• Preserve ASCII characters exactly.
• Normalize line endings (LF) if your copy button targets terminals.

Badges: status, risk, and the danger of implied promises

Badges are small labels with outsized authority. They look official even when they’re not. That’s why product marketing loves them—and why ops teams should be suspicious.

Good badges answer one question each

• Status: Stable, Beta, Deprecated.
• Scope: Linux-only, macOS-only, Kubernetes.
• Risk: Destructive, Requires root.
• Compliance: Approved, Needs review (careful: implies governance).

Badges you should avoid

• Vibes badges: “Awesome,” “Hot,” “Trending.” That belongs on social media, not runbooks.
• Ambiguous badges: “Recommended” without a policy behind it. Recommended by whom, under which constraints, with which rollback plan?
• Color-only semantics: red/green without text. Accessibility and international users will punish you quietly.

Make badge meaning enforceable

A badge should map to a rule you can test. Example: “Deprecated” means the page includes a replacement link and a deprecation date (or at least version). “Destructive” means the command block includes a “what it changes” line and a dry-run alternative.

Tags: navigation, search intent, and not lying to your reader

Tags are either a calm indexing system or a junk drawer. Most sites choose the junk drawer and then wonder why search and discovery are miserable.

Tags should match how people search

Users don’t search “observability.” They search “why kubectl port-forward hangs” or “copy button not working safari.” Use multi-word tags that resemble queries, and keep a controlled vocabulary.

Two different things people call “tags”

• Content taxonomy tags: used for navigation, related posts, filtering. Needs governance.
• Inline chips/labels: used inside the page as metadata. Needs clarity, not volume.

Operational rule: keep the tag set small and curated

If anyone can invent tags, they will. And then your “Kubernetes,” “k8s,” “kube,” and “K8s” tags will each have five posts, none of which the reader finds. Enforce canonical tags at build time. If you can’t enforce, don’t pretend.

Copy command buttons: the sharpest knife in your drawer

The copy button is a force multiplier. It saves time and reduces transcription errors. It also enables people to run commands they don’t understand faster than they can regret it. That means your job is to make the copied payload correct, safe, and obvious.

What a good copy button guarantees

• Exact content: no prompts, no line numbers, no hidden characters.
• Clear scope: copies a single code block, not surrounding text.
• Feedback: “Copied” state that is not color-only and doesn’t shift layout.
• Fallback: works without Clipboard API when blocked; at least provides select-to-copy.
• Telemetry: you can measure usage and failures without logging the command itself.

Prompt handling: decide your policy

Pick one. Document it. Enforce it.

• No prompts in copyable blocks: show prompts visually via CSS pseudo-elements, not in the text. Best for reliability.
• Prompts allowed but stripped on copy: copy logic removes leading $, #, and common prompt patterns. More complex, more fragile.
• Prompts included: only acceptable for “teaching terminals” where the prompt is part of the lesson, and you label it clearly (“not directly copyable”).

Clipboard security: don’t be creepy

Copy-to-clipboard is a privileged action in practice. Browsers gate it behind user gestures for a reason. Your copy code should:

• Only run on a click/tap, not on page load or hover.
• Never rewrite the clipboard on scroll or selection changes.
• Avoid copying secrets. If your docs contain tokens, you already have a bigger problem, but don’t make it worse.

Joke #2: A copy button that silently fails is the UI equivalent of a RAID controller blinking “trust me.” It’s always fine until it’s spectacularly not.

Facts & historical context you can actually use

• HTML has had <kbd> since early specs, intended for user input examples; it’s not a modern invention, just an often-ignored one.
• “Copy to clipboard” used to be a Flash-era hack on many sites; the modern Clipboard API replaced a pile of insecure workarounds.
• Monospace fonts vary wildly in glyph clarity; some popular developer fonts still make O and 0 too similar, which matters in inline code.
• Terminals normalized the idea of prompts ($ for user, # for root), but there is no universal prompt format, so stripping prompts is inherently heuristic.
• Non-breaking spaces were introduced for typography, not code; they routinely leak into inline code via WYSIWYG editors and can break shell parsing.
• Markdown fenced code blocks popularized the “copyable snippet” pattern, but Markdown renderers differ on whitespace preservation and HTML escaping.
• Badges exploded in popularity with README culture; over time they shifted from status signals to decoration, reducing trust in the signal.
• Keyboard shortcut notation is culturally inconsistent: macOS uses symbols (⌘, ⌥), Windows uses words (Ctrl, Alt). Your docs need a policy, not hope.

Three corporate mini-stories (how this goes wrong in real life)

1) Incident caused by a wrong assumption: “copy copies the command”

A mid-sized SaaS company rolled out a new internal runbook portal. It had a glossy code block component with a copy button and a “shell” style prompt. Engineering leadership was happy: fewer typos, faster mitigation, less training time.

The wrong assumption was subtle: the UI team assumed the prompt was “presentation,” so they put it directly in the code block text. It rendered beautifully. And the copy button copied the entire block, prompts included.

During an incident, an on-call engineer copied a mitigation command into a root shell on a production host. The pasted line started with cr0x@server:~$, which the shell interpreted as a command name. The mitigation failed. They tried again, got the same failure, and started debugging the service instead of the runbook.

Meanwhile, the incident timer didn’t care. The team lost precious minutes, escalated unnecessarily, and only later noticed the prompt garbage in their terminal history. The postmortem was uncomfortable because no one wanted to admit “the docs UI broke prod.” But it did.

The fix was boring and immediate: prompts became CSS pseudo-elements; copy payload became the raw command text only; and every code block gained a “Tested on: bash” line. The bigger fix was cultural: runbook UI got treated as a production system with regression tests.

2) Optimization that backfired: “ship fewer bytes, ship less trust”

A large enterprise documentation platform decided to optimize performance. They replaced server-side rendered code blocks with a client-side component that hydrated after page load. The goal: smaller HTML, faster first paint, more interactive code blocks with badges and copy actions.

It looked great in synthetic tests. The problem was user reality: corporate browsers with strict Content Security Policy, locked-down clipboard permissions, and aggressive script blockers. Hydration frequently failed or was delayed.

Users saw code blocks without copy buttons, then copy buttons appeared late, then disappeared on navigation because the SPA router reused nodes incorrectly. Some users copied stale commands from a previous page because the copy handler referenced an old DOM id. That is the kind of bug that doesn’t show up in unit tests; it shows up in “why did we run that command on the wrong cluster.”

Eventually the platform rolled back to server-rendered code blocks with progressive enhancement: the code is always present, always selectable, and the copy button is an enhancement, not a dependency. The “optimization” saved kilobytes and spent credibility. Not a trade you can win.

3) Boring but correct practice that saved the day: lint rules and golden tests

A smaller team maintained runbooks for a storage platform. They were not fancy. The UI was plain. But they had a ruthless build pipeline: every pull request ran a linter that rejected inline code containing non-ASCII whitespace and rejected code blocks that began with prompts unless explicitly marked as “terminal transcript.”

People complained at first. Writers wanted to paste from terminals. Engineers wanted to move fast. The linter was the annoying friend who always checks your work.

Then a real incident hit: a widespread outage with dozens of responders across time zones. They were copying mitigation commands under stress. The runbooks behaved: copy buttons copied exactly the commands, no prompts, no formatting surprises, no “why did it insert a curly quote.”

The team later realized they’d avoided a whole class of failures not because they were smarter, but because they had guardrails. The practice was boring. It was also correct. In ops, boring is an achievement.

Practical tasks: 14 checks with commands, outputs, and decisions

These tasks assume you run a docs site or blog in production (static site generator, CDN, maybe a Node service). The point is not the exact stack. The point is: you can verify micro component behavior the same way you verify storage latency—by observing real artifacts.

Task 1: Confirm the copy payload contains no prompt markers

cr0x@server:~$ node -e 'const s="cr0x@server:~$ sudo systemctl restart nginx\n"; console.log(s.replace(/^.*\$\s+/gm,""))'
sudo systemctl restart nginx

What the output means: The prompt-stripping regex removed everything up to $ at line start.

Decision: If your UI includes prompts in code text, implement a reliable “strip on copy” policy or stop embedding prompts in the copyable source.

Task 2: Detect non-breaking spaces in exported HTML

cr0x@server:~$ grep -RIn --binary-files=without-match $'\xC2\xA0' public/ | head
public/posts/storage-runbook/index.html:842:Use zpool status before changes.

What the output means: The output shows a non-breaking space in an inline code token.

Decision: Fix the content pipeline: replace NBSP with ASCII space inside code, and add a build gate that fails on this pattern.

Task 3: Verify that inline code is actually <code> elements

cr0x@server:~$ rg -n "kubectl get pods

What the output means: Your renderer is producing fake code spans.

Decision: Switch to semantic <code> so accessibility tools and CSS can treat it correctly. Fake code spans are how inconsistencies breed.

Task 4: Ensure code blocks keep whitespace exactly

cr0x@server:~$ python3 - <<'PY'
s = "echo one\n\tprintf 'two'\n"
print(repr(s))
PY
"echo one\n\tprintf 'two'\n"

What the output means: Tabs and newlines are explicit. Your code block component must preserve them; some renderers collapse tabs into spaces inconsistently.

Decision: If you see tabs used in code samples, either enforce spaces or ensure your renderer and copy logic preserve tabs exactly.

Task 5: Check for curly quotes and en-dashes in code samples

cr0x@server:~$ rg -n "[\u2018\u2019\u201C\u201D\u2013\u2014]" content/ | head
content/posts/ssh-hardening.md:57:Run: `ssh –V` and verify output

What the output means: That dash is an en-dash, not a hyphen. Shell flags will fail.

Decision: Add a linter rule: reject smart punctuation inside backticks and fenced blocks. Fix the source content.

Task 6: Validate that copy buttons exist only where intended

cr0x@server:~$ rg -n "data-copy-button" public/ | wc -l
128

What the output means: You have 128 instances. That’s your inventory.

Decision: If that number jumps unexpectedly in a release, you probably changed a template and are now attaching copy buttons to non-command snippets (JSON fragments, stack traces, etc.). Decide whether that’s desirable.

Task 7: Confirm Clipboard API usage is gated behind user gesture

cr0x@server:~$ rg -n "navigator\.clipboard\.writeText" assets/ | head
assets/js/copy.js:41:await navigator.clipboard.writeText(text)

What the output means: You found the call site.

Decision: Inspect that handler: it must be in a click/tap callback. If it’s inside a load event, you’ll get failures and possible security warnings.

Task 8: Check CSP headers for clipboard compatibility and inline script breakage

cr0x@server:~$ curl -sI https://docs.example.internal | sed -n '1,20p'
HTTP/2 200
content-security-policy: default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'
content-type: text/html; charset=utf-8

What the output means: Scripts can only load from self. Inline scripts will be blocked unless you use nonces/hashes.

Decision: If your copy button relies on inline JS, it will break in this environment. Ship the copy logic as an external file or use CSP nonces.

Task 9: Verify your site serves the correct code font assets (and doesn’t 404)

cr0x@server:~$ curl -sI https://docs.example.internal/assets/fonts/JetBrainsMono.woff2 | head -n 5
HTTP/2 200
content-type: font/woff2
cache-control: public, max-age=31536000, immutable

What the output means: Font loads and is cacheable.

Decision: If you see 404 or wrong MIME types, your inline code will fall back to system fonts unpredictably. Fix the build or CDN configuration.

Task 10: Measure whether your copy script is a performance anchor

cr0x@server:~$ ls -lh public/assets/js/ | rg "copy|code|highlight"
-rw-r--r--  1 cr0x cr0x  3.2K Jan 10 12:11 copy.js
-rw-r--r--  1 cr0x cr0x  188K Jan 10 12:11 highlight.js

What the output means: Syntax highlighting is 188K; copy logic is 3.2K.

Decision: Don’t bundle copy logic into a huge highlight runtime if you can avoid it. Ship copy as tiny progressive enhancement, and load highlighting only when needed.

Task 11: Catch duplicate or inconsistent tags in your taxonomy

cr0x@server:~$ jq -r '.posts[].tags[]' public/search-index.json | sort | uniq -c | sort -nr | head
  42 kubernetes troubleshooting
  17 k8s troubleshooting
  11 Kubernetes troubleshooting

What the output means: You have three variants for the same concept, including case drift.

Decision: Canonicalize tags at build time. Pick one form (lowercase, multi-word query-like tags) and rewrite the rest.

Task 12: Confirm badges map to known states (not free text)

cr0x@server:~$ jq -r '.posts[].badges[]?' public/search-index.json | sort | uniq -c | sort -nr
  59 stable
  14 beta
   7 recommended
   3 Stable
   2 hot

What the output means: “Stable” duplicates “stable,” and you have “hot,” which is not a state, it’s a mood.

Decision: Lock badge values to an enum. If someone wants a new badge, they propose it like a schema change, not like a tweet.

Task 13: Verify that terminal transcript blocks are labeled and not copyable by default

cr0x@server:~$ rg -n "terminal-transcript" public/ | head
public/posts/mysql-recovery/index.html:411:
cr0x@server:~$ tail -n 50 /var/log/mysql/error.log
...

What the output means: Transcript blocks are classified.
Decision: If it’s a transcript, consider disabling copy or copying only the command lines (not the output). Make the UI explicit.
Task 14: Spot prompt strings inside code blocks that claim to be copyable
cr0x@server:~$ rg -n "^\w+@[^:]+:.*\\$ " content/ | head
content/runbooks/restart-nginx.md:12:cr0x@server:~$ sudo systemctl restart nginx

What the output means: The runbook includes a literal prompt line in source content.
Decision: Convert it to prompt-less code (preferred) or mark the block as transcript and adjust copy behavior. Don’t leave it ambiguous.
  

Common mistakes: symptoms → root cause → fix

1) Symptom: Users paste commands and get “command not found” with their username

Root cause: Prompt text is included in the copied payload (either because prompts are literal text or because line numbers are copied).

Fix: Render prompts via CSS pseudo-elements, or strip prompts on copy with conservative rules. Add a test that simulates copying and asserts the payload begins with the command.

2) Symptom: Copy works in Chrome but not in locked-down corporate browsers

Root cause: CSP blocks inline scripts or clipboard calls; or clipboard permissions require HTTPS and user gesture.

Fix: Ship copy logic as external JS allowed by CSP; ensure copy triggers only on click; implement fallback: select text + instruct user to press Ctrl+C.

3) Symptom: Inline flags like --max-time render as –max–time

Root cause: Smart punctuation engine transforms hyphens into en-dashes and double hyphens into em-dash patterns in certain editors.

Fix: Disable typographic substitutions inside code spans and code fences; add content lint rules to reject Unicode dash characters in code contexts.

4) Symptom: Keyboard shortcuts are misunderstood across OSes

Root cause: One shortcut notation is used universally; macOS users expect symbols, Windows/Linux users expect words.

Fix: Provide OS-specific rendering or dual notation: Ctrl (Windows/Linux) / ⌘ (macOS). If you can’t, at least label the platform explicitly.

5) Symptom: Badges create escalation loops (“security approved this, right?”)

Root cause: Badges imply governance without policy backing. Readers interpret UI authority as organizational authority.

Fix: Use badges only for states you can enforce and explain. Add a tooltip or legend that defines each badge in plain language.

6) Symptom: Tags don’t improve discovery; they fragment it

Root cause: Free-form tags, inconsistent casing, synonyms, and near-duplicates.

Fix: Canonical tag dictionary, enforced at build time; migrate old tags; treat taxonomy changes like schema migrations.

7) Symptom: Copying multi-line commands breaks because line continuations get lost

Root cause: Renderer wraps lines visually but alters whitespace, or copies soft-wrap artifacts, or inserts line breaks in the middle of tokens.

Fix: Ensure <pre> uses real newlines; avoid inserting <br> inside code; copy from the textContent of the code element, not from a styled clone.

8) Symptom: Dark mode makes inline code unreadable

Root cause: Inline code background/border colors are tuned only for light theme; contrast fails.

Fix: Define theme tokens for code background, border, and text; run contrast checks; keep inline code subtle but legible.

Checklists / step-by-step plan

Step-by-step: ship “trustworthy code blocks” in one week

1. Pick a policy for prompts: no prompts in copyable source (recommended) or strip-on-copy (acceptable with tests).
2. Standardize semantics: inline tokens use <code>; shortcuts use <kbd>; code blocks use <pre><code>.
3. Implement copy behavior:
   • Copy from raw textContent of the <code> element.
   • Normalize line endings to \n.
   • Optionally trim a single trailing newline (be consistent).
4. Add a UI affordance: “Copy” button with a non-layout-shifting “Copied” state and aria-live feedback.
5. Add a fallback: select-all behavior or instruction showing Ctrl+C / ⌘+C.
6. Telemetry, but not creepy: log “copy attempted,” “copy succeeded,” “copy failed,” by page and block id—not the command content.
7. Lint content:
   • Reject NBSP and smart quotes/dashes inside code contexts.
   • Reject prompts in non-transcript code fences.
8. Regression tests: golden tests on rendered HTML for representative pages; a browser test that clicks copy and asserts clipboard payload.
9. Write a legend for badges and tag policy: what each badge means, who owns it, and what “Deprecated” requires.

Checklist: badges and tags you can defend in a postmortem

• Every badge value is in a controlled list.
• Every badge has a defined meaning and an owner.
• “Deprecated” requires a replacement reference and a timeline statement.
• Tags are canonicalized (case, spacing) and mapped from synonyms.
• Tag set is small enough that a human can recognize duplicates.

Checklist: accessibility sanity checks

• <kbd> is not used for things that are not keys.
• Copy button is reachable via keyboard and has a visible focus state.
• Copy confirmation is announced via aria-live and not color-only.
• Badges are not communicated by color alone; text is present.
• Inline code has sufficient contrast in light and dark modes.

FAQ

1) Should I use <kbd> for single keys and shortcuts?

Yes. Use <kbd> for keys, and compose shortcuts with multiple <kbd> elements: Ctrl+C. It’s clearer and more accessible.

2) Is it okay to show prompts in code blocks?

Only if you treat the block as a transcript and label it as such. For copyable command snippets, prompts should be presentation-only (CSS) or stripped on copy with tests.

3) Why not always strip prompts on copy?

Because prompt formats vary and heuristics will eventually eat a legitimate command (especially when commands start with $ in examples, or when output contains similar patterns). If you can avoid prompts in the source, do that.

4) Should inline code wrap on small screens?

Sometimes. Paths and long flags can overflow. Use CSS to allow safe wrapping for long tokens while preserving copy correctness. If wrapping risks breaking meaning, keep it unwrapped and allow horizontal scroll.

5) Do copy buttons need telemetry?

If you care about reliability, yes. Track attempts/success/failure per page and per block. Do not log the copied string. You want rates and failure modes, not content.

6) What’s the most common “invisible character” that breaks commands?

Non-breaking space. It looks like a space, but shells don’t treat it as a separator. Smart dashes and curly quotes are close contenders.

7) How many badges is too many?

If a page has more than two or three badges, you’re probably encoding a paragraph of nuance into confetti. Put nuance into text; reserve badges for high-signal states.

8) Are tags still worth it when full-text search exists?

Yes, if you govern them. Tags are an opinionated index; search is a guess. Tags help users narrow scope (“linux-only commands”) and find related operational contexts.

9) Do I need different keyboard shortcut notation for macOS?

Ideally, yes. At minimum, label the platform. Best is dual notation or OS-aware rendering so the user doesn’t have to translate in their head.

10) Should I use syntax highlighting everywhere?

No. Highlighting is expensive and often useless for single-line commands. Use it where it adds meaning (configs, code), and keep shell commands clean and copy-safe.

Conclusion: next steps you can ship this week

Micro components don’t look like “production,” which is exactly why they quietly cause production problems. Fixing them is not a redesign project. It’s reliability work: tighten semantics, remove ambiguity, add guardrails, measure outcomes.

1. Audit copy behavior on your top 20 pages: confirm the clipboard payload is prompt-free and whitespace-correct.
2. Enforce content linting for NBSP and smart punctuation in code contexts. Make it fail builds. Yes, people will complain. Let them complain now instead of during an incident.
3. Define badge and tag governance: controlled vocabularies, owners, and meanings. If you can’t define meaning, delete the badge.
4. Make accessibility non-optional: real <kbd>, real <code>, keyboard operable copy buttons, and visible focus states.
5. Add one browser test that clicks copy and asserts the clipboard string. It’s the cheapest insurance you’ll buy this quarter.

Do those, and your docs stop being “pretty text on the internet” and start being what they should be: an operational instrument panel that doesn’t lie when the room is on fire.