Help us improve
Share bugs, ideas, or general feedback.
From builder-design
Use when designing how AI-generated content is rendered — streaming text, structured data, citations, code blocks, and uncertainty signals. Covers both visual rendering and the accessibility layer.
npx claudepluginhub rbraga01/a-team --plugin builder-designHow this skill is triggered — by the user, by Claude, or both
Slash command
/builder-design:ai-output-designThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
```
Provides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
Share bugs, ideas, or general feedback.
AI OUTPUT IS NOT STATIC CONTENT.
"Just render the markdown" and "the model formats it" both ship walls of unstyled text with no hierarchy, no confidence signals, and no accessibility layer.
Defined rendering rules + typographic hierarchy + confidence signals IS output design.
Trigger when:
Model responses contain markdown. Define which elements to render and how:
| Element | Render as | Notes |
|---|---|---|
# H1 | Use sparingly in responses — demote to H3 | H1 inside a response clashes with page hierarchy |
**bold** | <strong> | Full weight only; no extra color |
_italic_ | <em> | Used for emphasis, not decoration |
`inline code` | <code class="inline"> | Monospace, tinted background |
```code block``` | Syntax-highlighted <pre><code> | Language label, copy button, max-height with scroll |
- list | <ul> with custom bullet | 0.5rem gap between items |
1. ordered | <ol> | Numbers bold, content regular weight |
> blockquote | Left bar, muted text | Use for citations or model asides |
| ` | table | ` |
--- | <hr> | Thin, muted; use sparingly |
Rules:
AI responses can be very long. Typography is the only structural tool.
.ai-response {
font-size: 1rem; /* Body: 16px */
line-height: 1.7; /* Generous for readability */
max-width: 72ch; /* Reading line length */
color: var(--ink);
}
.ai-response h3 { font-size: 1.15rem; font-weight: 700; margin-top: 1.5em; }
.ai-response h4 { font-size: 1rem; font-weight: 600; margin-top: 1.25em; }
.ai-response p { margin: 0.75em 0; }
.ai-response ul,
.ai-response ol { padding-left: 1.5em; margin: 0.75em 0; }
.ai-response li { margin: 0.3em 0; }
Line length: cap at 65–75ch. AI responses are dense — long lines prevent reading.
When the model produces tables, cards, or structured lists:
Tables:
<div class="table-wrapper" role="region" aria-label="AI-generated table" tabindex="0">
<table>
<thead><tr><th scope="col">...</th></tr></thead>
<tbody>...</tbody>
<caption>Source: AI-generated on [date]</caption>
</table>
</div>
role="region" + tabindex="0" makes the scroll container keyboard-navigable.table-wrapper, not the pageLong structured lists from the model:
10 items: add a "Show all N items" expand
Not every model response should look equally authoritative.
High confidence (no hedging detected, grounded in retrieved context):
→ Normal rendering
Low confidence (hedging phrases, outside knowledge cutoff, no retrieved context):
→ Amber left bar + "Low confidence — verify before using"
→ [Show sources] or [Check manually] action
Model refusal or "I don't know":
→ Distinct visual treatment (grey, softer)
→ "I don't have reliable information about this" — never leave blank
→ [Rephrase] or [Try a different question] action
Implement confidence detection with a post-processing step — do not rely solely on the model to label its own uncertainty.
AI responses have no natural length limit. Design for length:
Create an explicit list of which markdown elements your surface renders and how. Use the table in Section 1 as your starting point. Any element not listed is undefined behaviour in production.
Add the CSS in Section 2 (or its equivalent in your stack) to the response container. Line height 1.7 and max-width: 72ch are not optional — long AI responses with tight line height and full-width layout are measurably harder to read.
For tables: role="region" + tabindex="0" on the scroll wrapper, <caption> required. For long lists: define the expand threshold (default: 10 items).
Implement the post-processing step that detects hedging language and applies the amber treatment. A regex over ["I think", "I'm not certain", "approximately", "I believe", "may", "might"] in the response text is a minimum viable implementation.
Test with a response over 800 words (section anchor links), a code block over 50 lines (collapsible), and a list over 10 items (expand). If your rendering system doesn't handle these, they ship as walls of content.
These thoughts mean output design was skipped — stop:
When ai-output-design is satisfied, state it like this:
Output design complete.
Surface: <response container name>
Rendering:
Markdown elements: all 11 elements defined with visual treatment ✓
H1/H2 demoted: yes ✓ / Code blocks: syntax-highlighted, max-height, copy button ✓
Line length: capped at 72ch ✓ / Line height: 1.7 ✓
Structured data:
Tables: role="region" + tabindex, caption, responsive scroll ✓
Long lists: > 10 items expandable ✓
Confidence signals:
Low confidence: amber bar + verify message + action ✓
Refusal / no-data: distinct grey treatment + alternative action ✓
Progressive disclosure: responses > 800 words have section anchors ✓
Documented in: design/specs/<feature>-output.md ✓
Undesigned AI output reads as a developer tool, not a product. Typography, line length, element hierarchy, and uncertainty signals are what separate a rendered model response from a polished product feature. The model generates tokens; the UI design determines whether users can read, trust, and act on what it produces.