Skip to main content

Docs Component Guide

Use these components and block styles to keep the playbook visually consistent across concept pages and project docs.

Inline badges​

Use DocBadge when a section needs a compact AI-specific label.

import DocBadge from '@site/src/components/DocBadge';

<DocBadge tone="info" label="Concept" />
<DocBadge tone="success" label="Production pattern" />
<DocBadge tone="neutral" label="Build step" />
<DocBadge tone="warning" label="Eval" />
<DocBadge tone="danger" label="Security note" />

Example:

Concept Production pattern Build step Eval Security note

Structured content blocks​

Use the shared doc-block classes for rich callouts inside chapters.

<div className="doc-block doc-block--concept">
  <DocBadge tone="info" label="Concept" />
  <p>Explain the core idea in plain language.</p>
</div>

Available block variants:

  • doc-block--concept
  • doc-block--production
  • doc-block--build
  • doc-block--eval
  • doc-block--security
  • doc-block--portfolio

Example:

Security note

Approval flows, tool permissions, and prompt injection boundaries should be visible in the docs, not hidden in prose.

Project implementation cards​

Use ProjectStatusCard near the top of a project page.

import ProjectStatusCard from '@site/src/components/ProjectStatusCard';

<ProjectStatusCard
  project="AI Provider Gateway"
  status="Runnable"
  folderHref="https://github.com/AnkitParekh007/Agentic-Engineering-Playbook/tree/main/projects/p01-ai-provider-gateway"
  stack={['TypeScript', 'Express', 'Zod']}
  commands={[
    'npm install',
    'npm run typecheck',
    'npm run build',
    'npm run smoke',
  ]}
  proves="One normalized API surface can support streaming, schemas, and trace logging."
  next="Replace the placeholder provider with a real model client and add fallback routing."
/>

Example:

Project implementationAI Provider Gateway
Runnable

Stack

TypeScriptExpressZod

Folder

Open project folder

What it proves

One normalized API surface can support streaming, schemas, and trace logging.

Next upgrade path

Replace the placeholder provider with a real model client and add fallback routing.

Key commands

npm install
npm run typecheck
npm run build
npm run smoke

Command blocks​

Use CommandCard for commands instead of long raw fences when the commands are important to the build flow.

import CommandCard from '@site/src/components/CommandCard';

<CommandCard
  title="Core commands"
  commands={[
    'npm install',
    'npm run build',
    'npm run smoke',
  ]}
/>

Example:

Core commandsbash
npm install
npm run build
npm run smoke

Usage guidance​

  • Use DocBadge and doc-block together for concept-heavy sections.
  • Use ProjectStatusCard once near the top of a project page.
  • Use CommandCard when commands are central to the learner workflow.
  • Keep typography, spacing, and badge tone choices consistent across docs. Prefer the shared components over one-off custom HTML blocks.
  • Keep callouts practical. If a block does not help the learner build, cut it.