From shipit-ui-design
Apply senior code-presentation patterns — terminal-style chrome, token-driven syntax highlighting, copy buttons, line numbers, line highlighting, language labels — to every code block Claude generates in UI (docs sites, developer marketing pages, READMEs, changelogs, MDX, dashboards with snippets). Auto-activates when generating components named CodeBlock / Snippet / CodeSample / Pre, when editing files matching *.mdx, or when the task mentions "syntax highlighting", "code sample", "developer", "docs".
How this skill is triggered — by the user, by Claude, or both
Slash command
/shipit-ui-design:code-presentationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Code blocks are the most-photographed surface on a developer site. They appear in install steps, tutorial source, README excerpts, changelogs, FAQ answers, and dashboard help panels. A default browser `<pre>` makes the rest of the design feel cheap. This skill is the rubric for rendering them so they read as deliberate craft and stay coherent with the project's tokens.
Code blocks are the most-photographed surface on a developer site. They appear in install steps, tutorial source, README excerpts, changelogs, FAQ answers, and dashboard help panels. A default browser <pre> makes the rest of the design feel cheap. This skill is the rubric for rendering them so they read as deliberate craft and stay coherent with the project's tokens.
- Max 300 lines per file. If a generated component would exceed, split before writing.
- No hardcoded design values. Colors, spacing, radii, shadows, durations, easings — all from tokens.
- Every interactive element has hover, active, focus-visible, and disabled states.
- All motion respects
prefers-reduced-motion.- Every image / illustration has alt text or
aria-hiddenif decorative.- Dark mode is never an afterthought — emitted alongside light from the start.
- Stack-respect: never introduce a new framework or styling system; adapt to what's there.
| File | When to read |
|---|---|
references/code-presentation/syntax-tokens.md | Before mapping any syntax color — gives the canonical token per token-type, per language. |
references/code-presentation/codeblock-recipe.md | Before generating or refactoring a <CodeBlock> component — props, anatomy, library decision, test cases. |
references/canonical-tokens.md | Whenever a token name is uncertain — converges naming variants. |
web/components/primitives/CodeBlock.tsx | The production reference implementation already shipped on the plugin's landing page. Treat as the visual ground truth. |
Every generated CodeBlock starts from the same skeleton — the only difference between a marketing snippet and a docs snippet is the chrome variant.
border-radius: var(--radius-xl), background: var(--color-surface-elevated), border: 1px solid var(--color-border), optional box-shadow: var(--shadow-sm) on hover. The card clips overflow so the chrome bar's bottom border meets the body cleanly.background: var(--color-surface), border-bottom: 1px solid var(--color-border-subtle). Holds traffic-light dots (left), language label (right), copy button (far right).gap: var(--space-2), colors --color-accent-500 / --color-accent-400 / --color-brand-400 (or --color-danger / --color-warning / --color-success if the project ships state colors and prefers literal traffic-light semantics). aria-hidden="true" — purely decorative.font-family: var(--font-mono), font-size: var(--text-2xs), color: var(--color-fg-subtle), text-transform: uppercase, letter-spacing: 0.08em. Right-aligned just before the copy button.<pre> with padding: var(--space-5) var(--space-6), font-family: var(--font-mono), font-size: var(--text-sm), line-height: 1.6, color: var(--color-fg). Horizontal overflow scrolls; vertical never scrolls (prefer multiple shorter blocks over a scrolling tower).<figcaption> above the card, font-mono, --text-xs, --color-fg-subtle, margin-bottom: var(--space-2). Used for filenames in terminal chrome and for short prose like "After the migration".The whole assembly is wrapped in <figure> so screen readers can announce caption + code as one unit.
The principle that separates a polished CodeBlock from an off-the-shelf one: every highlight color is a project token. Never import a stock theme like prism-tomorrow.css, github-dark.css, or Shiki's bundled nord — these ship their own neutrals, their own brand hue, and their own contrast budget, and they will clash with the project's palette in dark mode and on color-tinted surfaces.
Map each token-type (keyword, string, number, function-call, type, …) to a CSS variable in the project's existing scale. Keywords go on --color-brand-400, strings on --color-accent-300, comments on --color-fg-muted, punctuation on --color-fg. The full mapping for every token-type and every supported language lives in references/code-presentation/syntax-tokens.md — read it before authoring or auditing any tokenizer.
When the project ships only a brand ramp (no accent), collapse strings onto a desaturated step of brand (--color-brand-200) and keep numbers on --color-fg. The hierarchy must survive collapse.
Pick one based on the project's surface area, bundle budget, and SSR target. Do not pre-decide; ask the user or check the project before installing.
web/components/primitives/CodeBlock.tsx is this option, in production, and is the canonical reference.getHighlighter at build time; never client-render — the WASM payload is too heavy for a marketing page. Provide a custom theme that maps Shiki's scope names onto the project's CSS variables (recipe in codeblock-recipe.md)..token.keyword, .token.string, etc. — fully tokenizing requires a CSS file that overrides every Prism class onto var(--color-*). Worth the effort once; never inline-styling per-element.Selection criteria, in priority order: language count → bundle budget → theme control → SSR target. Verify at build time which library the host project already uses (grep -E "shiki|prismjs|highlight\\.js" package.json); if one is present, adopt it rather than installing a second.
Pick the chrome that matches the content, not the page.
--color-info, --color-accent, --color-warning). Use for source code in tutorials where the file's location matters as much as its content. Replaces the dots; keeps the language label.Prefer terminal for marketing surfaces, editor for tutorials, plain for prose.
Always present unless the consumer passes copy={false} (e.g., the block shows output, not an instruction). The copy button is a first-class interactive element and gets the full constitution rule 3 treatment.
--color-fg-muted text, 1 px --color-border-subtle border, --radius-md.--color-fg, background to --color-surface-elevated. Transition: --dur-150 var(--ease-out).transform: scale(0.97), snaps back on release.--color-ring, offset 2 px. Never removed.opacity: 0.5, cursor: not-allowed. Used when the code is empty or clipboard is unavailable.--color-brand. After 1500 ms, revert.Feedback rules: aria-label updates with state ("Copy code" → "Copied to clipboard"). Reduced-motion users get an instant revert (no fade). Always feature-detect: if (!navigator.clipboard) return; — never throw on browsers without the API.
Line numbers are noise on a 4-line install snippet and clarity on a 30-line tutorial. Default off. When showLineNumbers is on:
2.25rem.font-size: var(--text-xs), color: var(--color-fg-subtle), text-align: right, padding-right: var(--space-3).user-select: none — copying the block must yield clean code without 1 2 3 prefixes. This is the most common copy-button regression; test it every time.aria-hidden="true" — they're presentational, the code itself is the content.Used to call attention to the line being explained in surrounding prose. Each highlighted line gets a 2 px left border in --color-brand-500 and a soft background tint:
background: color-mix(in oklab, var(--color-brand-50) 40%, transparent);
border-left: 2 px solid var(--color-brand-500);
The tint must be subtle enough that surrounding lines remain readable; color-mix with 40 % alpha against the surface is the calibrated value. In dark mode, swap to --color-brand-900 at 60 %. Useful for tutorials, changelogs ("look at this line"), and code reviews.
When showing before-and-after, prefer two side-by-side terminal blocks (each labeled with a small status dot — --color-danger for "before", --color-brand or --color-success for "after") over inline + / - markers. Inline diff markers fight the syntax colors and ruin the copy-paste experience. The plugin's own landing page CodeExample section is the visual reference for this layout.
Side-by-side reads at a glance; inline reads as a puzzle.
<pre> carries role="region" and aria-label={caption ?? "Code sample"}. This makes the block navigable as a landmark for screen-reader users.aria-hidden="true". The label is redundant with the language prop on the <code class="language-tsx">, which assistive tech can announce.tabindex > 0. No keyboard traps.--color-surface-elevated (the card) and any tinted highlight background. Test in light and dark.prefers-reduced-motion: reduce — text swap only, no transition.| Scenario | Chrome | Line numbers | Line highlight | Copy |
|---|---|---|---|---|
Install command (npm i …) | Terminal | off | off | on |
Plugin installer (/plugin marketplace add …) | Terminal | off | off | on |
| Source-code tutorial | Editor | on | on (current line) | on |
| FAQ answer snippet | Plain | off | off | off |
| Diff comparison | Terminal × 2 side-by-side | off | off | on |
| Output / log excerpt | Terminal | off | off | off |
| Changelog "what changed" | Plain | on | on (changed lines) | off |
<pre> styling — Times New Roman or Menlo against a white box, no padding, no border. The single biggest tell of an unfinished docs page.#1a1a1a text on #0a0a0a background because the developer copied a "hacker" theme.1 npm install … instead of npm install ….navigator.clipboard being undefined (Safari in insecure contexts, older browsers). Always feature-detect.prism-tomorrow.css, github-dark.css) and ignoring the project's tokens. The block will be the only element on the page that doesn't track the user's brand color.references/code-presentation/syntax-tokens.md — full color map, every token-type, every language.references/code-presentation/codeblock-recipe.md — props contract, anatomy diagram, library recipes, test cases.references/code-presentation/index.md — the catalog of this folder.web/components/primitives/CodeBlock.tsx — the production reference implementation.references/canonical-tokens.md — token name conventions when in doubt.Searches MemPalace before answering questions about past work, people, projects, or prior decisions. Returns verbatim stored content instead of guessing from model memory.
Guides Payload CMS config (payload.config.ts), collections, fields, hooks, access control, APIs. Debugs validation errors, security, relationships, queries, transactions, hook behavior.
Implements vector databases with Pinecone, Weaviate, Qdrant, Milvus, pgvector for semantic search, RAG, recommendations, and similarity systems. Optimizes embeddings, indexing, and hybrid search.
npx claudepluginhub shipiit/shipit-ui-design --plugin shipit-ui-design