How to use this page

This file is the consolidated machine-readable reference for the Forge kitchensink showcase. Each section follows the same shape: Purpose (when to use it), Styling (CSS classes and tokens), Markup (DOM pattern or Python emitter), Behavior (client scripts, if any), then a live example. The canonical stylesheet for this shell is css/forge-theme.css (imported as assets/forge-theme.css in generated pages). Bootstrap 5.3 provides utilities (.d-flex, .gap-*, .mb-*) layered on top of Forge tokens (--forge-*).

Scope

This page documents the handbook/showcase theme. Product marketing pages use forgesdlc-theme.css and fs-* classes — see the Product theme section. Full-page shells are Python functions in components/layouts.py.

Tokens · Color palette

Purpose: Semantic colors for backgrounds, surfaces, accents, and text hierarchy. Always prefer var(--forge-*) over raw hex in custom CSS so light/dark and future tweaks stay consistent.
Styling: Tokens live on :root in forge-theme.css / forge-light-theme.css. Key names: --forge-bg, --forge-surface, --forge-surface-2, --forge-amber, --forge-cyan, --forge-orange, --forge-emerald, --forge-text through --forge-text-4, --forge-border.
Markup: Reference in inline styles: style="color:var(--forge-cyan)" or in CSS rules. Swatch UI uses .ks-swatch, .ks-swatch-box, .ks-swatch-label.
Behavior: forge-theme.js sets data-bs-theme on <html> from cookie forge_color_scheme (light / dark / auto). Tokens swap via CSS when the theme changes.
Python: No dedicated renderer — use tokens in strings you pass to render_* helpers or in generator templates.

Example

surface

amber

cyan

emerald

text-3

Tokens · Typography

Purpose: Display headings, body, labels, and monospace code. Keeps handbook and showcase visually aligned with brand fonts.
Styling: .font-display — Proxima Nova Black (900). Body uses Open Sans. .font-label / .section-label for small labels. .forge-support — muted explanatory text. .forge-gradient-text — amber→cyan gradient on display text. Utilities: .text-amber, .text-cyan, .text-dim, .text-dim-2, .text-muted-4. CSS variables: --font-display, --font-label, --font-mono.
Markup: Apply classes to <h1>–<h3>, <p>, <span>. Links in prose pick up cyan styling from theme rules.
Python: e(s) / e_content(s) / bold(s) in components/components.py escape text for safe HTML insertion.

Example

Display heading

Body with strong, link, inline code.

Support line — smaller, lower contrast.

Gradient display text

amber · cyan · dim

Tokens · Spacing & layout width

Purpose: Rhythm between blocks; content max-width for readability.
Styling: Bootstrap spacing: .p-*, .m-*, .gap-*, .g-* on grids. Showcase sections use .ks-section and .ks-section-title for vertical rhythm. Typical content caps: ~56rem article column, wider for landing — see theme comments in forge-theme.css.
Markup: Wrap page sections in <section class="ks-section" id="…"> so showcase.js scroll-spy can track them (requires an id).

Example

Utility	Role
`.mb-3`	Margin below a block
`.gap-3`	Flex/grid gap (1rem)

Surfaces · Glass panels

Purpose: Frosted panels for cards, stats, and dashboard tiles.
Styling: .glass — default cyan-accent hover glow. .glass-amber — amber border/glow on hover. .glass-solid — opaque surface, less blur. Often combined with .p-3 / .p-4.
Markup: <div class="glass p-3">…</div>

Example

Glass

Cyan hover glow.

Glass amber

Amber accent.

Glass solid

Solid fill.

Surfaces · Cards

Purpose: Clickable or static tiles with hover “breathe” border animation.
Styling: .forge-card base. .card-amber for amber accent variant. .breathe-link on <a> (interactive). .breathe-static on <div> (decorative). .card-label for small upper label inside card.
Markup: Link card: <a class="forge-card breathe-link" href="…">. Static: <div class="forge-card breathe-static">.

Example

Cyan

Link card

breathe-link

Amber

Amber link

card-amber

Static

Non-link

breathe-static

Surfaces · Bento grid

Purpose: Responsive grid of equal cells (often glass tiles).
Styling: Container .bento-grid. Column template: .bento-3 (three columns → one column on small screens).
Markup: <div class="bento-grid bento-3"> with glass children.

Example

Cell 1

Cell 2

Cell 3

Surfaces · Tables

Purpose: Data tables with Forge striping and horizontal scroll on narrow viewports.
Styling: Wrap <table> in .forge-table-wrap. Table classes: .table, .table-sm, .table-striped, optional .mb-0.
Python: render_table(headers, rows, striped=True, cell_escape=False) and render_io_table(rows) emit the wrap + table.

Example (Python-generated)

Column A	Column B
Alpha	One
Beta	Two

Surfaces · Dividers

Purpose: Section break without heavy chrome.
Styling: <hr class="forge-divider"> — gradient rule using token colors.

Example

Above the line

Below the line

Controls · Buttons

Purpose: Primary actions and secondary outlines in brand colors.
Styling: Bootstrap .btn plus .btn-forge (amber fill), .btn-forge-outline (amber outline), .btn-cyan-outline (cyan outline). Sizing: .btn-sm etc.
Markup: <button type="button" class="btn btn-forge"> or <a> with same classes.

Example

Controls · Badges

Purpose: Compact status or tag chips.
Styling: Base .forge-badge plus tone: .badge-cyan, .badge-amber, .badge-emerald, .badge-red, .badge-dim.
Markup: <span class="forge-badge badge-cyan">Label</span>

Example

Cyan Amber Emerald Red Dim

Controls · Callouts / alerts

Purpose: Highlighted notes: info, warning, success, error, neutral surface.
Styling: Wrapper .forge-callout + variant: .forge-callout-cyan, .forge-callout-amber, .forge-callout-emerald, .forge-callout-red, .forge-callout-surface. Optional .callout-label with .text-cyan / .text-amber etc. For a pinned toolbar in showcase_page main content, use .ks-sticky-panel (sticky below .site-header via --site-header-h; darker glass surface in forge-theme.css / docs-theme.css).
Python: render_alert(content, variant=…, label=…) maps variants info|warning|success|danger|secondary|light to those classes. For bespoke markup, hand-write the divs as below.

Example (hand markup)

Info

Cyan callout body.

Example (render_alert)

Note

Generated by render_alert(..., variant="info", label="Note").

Controls · Code blocks & inline

Purpose: Syntax-colored blocks (manual spans) or Markdown-derived <pre>.
Styling: Block container .forge-code. Inner spans: .keyword, .highlight, .comment for demo styling. Markdown pipeline adds .forge-code to <pre> via enhance_code_blocks in transforms.py.
Markup: Inline: <code>, <kbd> for keys.

Example

def build_page(): # returns HTML string return layout(body)

Navigation · Sidebar patterns

Purpose: Handbook-style left rail: flat links or collapsible groups.
Styling: Classic: .forge-sidebar, .nav-section-label, .nav-rail, .nav-link (.active for current), .nav-group-toggle, .nav-sub-group, .nav-sub-link. Site header brand: .forge-brand + .brand-icon (see sticky header in showcase_page). Collapsible doc pattern: .doc-sidebar-group, .doc-sidebar-row, .doc-sidebar-toggle (showcase also uses .doc-sidebar-toggle--full for full-width family rows), .doc-sidebar-heading / .doc-sidebar-heading--label, .doc-sidebar-children, .doc-sidebar-link, .doc-sidebar-sublink.
Behavior: Showcase sidebar is server-rendered HTML. Some consumer sites hydrate chapter sidebars with JSON + JS — structure classes stay the same for CSS.

Example

Navigation · Flow diagram (CSS)

Purpose: Horizontal process / pipeline steps without SVG.
Styling: Row .forge-flow. Steps .forge-flow-node with optional .node-active. Separators .forge-flow-arrow.

Example

A → B → C

Navigation · Breadcrumbs, skip link, mobile, footer

Purpose: Accessibility and orientation: skip to content, breadcrumb trail, mobile menu trigger, page footer.
Styling: Breadcrumbs: <ol class="breadcrumb small mb-3"> with .breadcrumb-item, .active, aria-current. Skip link is visually hidden until focused. Footer uses render_footer patterns (links + support text).
Python: render_breadcrumbs([(href, label), …]) — use href=None for active crumb. render_skip_link(target="#main"). render_mobile_nav_button() for offcanvas toggle. render_footer(date, label=…) for generated-page footer.

Example (render_breadcrumbs)

Example (render_skip_link)

Tab to focus the skip link.

Python · `components/components.py` API

Purpose: Atomic HTML fragments composed by site generators; layouts in layouts.py wrap full pages.
Escaping: e(s) — full escape for attributes; e_content(s) — for text nodes; bold(s).
Tables: render_table, render_io_table.
Sections: render_section — titled block with optional label.
Diagrams (Mermaid): render_mermaid_block, render_diagrams_section.
Callouts / banners: render_alert, render_template_banner, render_canonical_note.
Nav & content: render_breadcrumbs, render_nav_buttons, render_external_sources_section, render_flow_details_section.
ToC: render_toc_sidebar, render_toc_sidebar_simple — expect heading ids in body.
Chrome: render_skip_link, render_mobile_nav_button, render_footer.
Headers / product: render_page_header, render_page_header_chapter, render_tier_nav, render_cross_refs, render_authorship_signal, render_product_landing_hero, wrap_product_site_article, render_product_footer.

Example (output shape of render_mermaid_block)

showcase_page does not inject the Mermaid module script; handbook/chapter layouts pass has_mermaid=True so mermaid.run executes. Below is the static DOM shape (diagram renders only when Mermaid JS is present).

graph LR A[Agent] --> B[HTML]

Python · Complete function inventory

Every public symbol in components/components.py that emits markup (plus escaping helpers). Parameters and edge cases live in the module docstrings — this table is for coverage checking and routing agents to the right helper.

Function	Returns	Role / emitted markup
`e(s)`	str	HTML-escape for attributes (includes quotes).
`e_content(s)`	str	Escape for text nodes (no quote encoding).
`bold(s)`	str	Wrap escaped content in `<strong>`.
`render_table(headers, rows, …)`	str	Striped Forge table inside `.forge-table-wrap`.
`render_io_table(rows)`	str	Intent/Inputs/Outputs/Participants/Timebox columns via `render_table`.
`render_section(sid, title, inner, …)`	str	Article section: optional top `.forge-divider`, `<section id>`, optional `.section-label`, `<h2 class="font-display">`.
`render_mermaid_block(diagram, expandable=False)`	str	`.forge-diagram` + `.mermaid`; if expandable, adds `forge-diagram-trigger` and `openDiagramModal(this)`.
`render_diagrams_section(title, sid, diagrams)`	str	Calls `render_section` with intro line + one `render_mermaid_block` per diagram string.
`render_alert(content, variant=…, label=…)`	str	Maps Bootstrap-like variants to `.forge-callout-*`; content is not re-escaped (HTML allowed).
`render_template_banner()`	str	Fixed amber template warning via `render_alert`.
`render_canonical_note(canonical_md, generator=…)`	str	Surface callout pointing editors at source Markdown + generator command.
`render_breadcrumbs(crumbs)`	str	`(href, label)` pairs; `href=None` marks active crumb.
`render_nav_buttons(prev_link, next_link)`	str	Prev/next `.btn-cyan-outline` / `.btn-forge-outline` row; empty if both unset.
`render_external_sources_section(sid, items, …)`	str	Unstyled list of external links + blurbs; optional pointer to REFERENCE-LINKS.md.
`render_flow_details_section(sid, items)`	str	Per-diagram narrative: `(title, paragraph)` tuples as `<h3>` + paragraph inside `render_section`.
`render_toc_sidebar(toc)`	str	Right column wrapper + `.forge-toc`; entries `(id, text, level)` — level 3 links get extra left padding.
`render_toc_sidebar_simple(toc)`	str	Same nav markup without level (chapter pages).
`render_skip_link(target="#main")`	str	`.skip-link` anchor for accessibility.
`render_mobile_nav_button(target_id=…)`	str	Fixed hamburger `.btn-forge` toggling Bootstrap offcanvas sidebar.
`render_footer(date, label=…)`	str	Muted top-border footer with generation note.
`render_page_header(title, subtitle=…, …)`	str	Handbook-style page title block (labels + display heading).
`render_page_header_chapter(…)`	str	Chapter variant of page header (methodology pages).
`render_tier_nav(groups)`	str	Product sidebar tier groups (used with `product_page` / fs theme).
`render_cross_refs(items, variant=…)`	str	`.fs-cross-refs` aside; `variant="subtle"` lowers emphasis.
`render_authorship_signal(lead, support=…)`	str	`.landing-authorship` aside for human direction vs agent output.
`render_product_landing_hero(…)`	str	Hero stack: kicker, gradient H1, tagline, CTAs — classes `.landing-hero-*` in product CSS.
`wrap_product_site_article(inner_html)`	str	Wraps body in `.fs-main > article` for product landing content.
`render_product_footer(…)`	str	`.fs-footer` block with brand line + handbook link.

Transforms · `components/transforms.py`

Purpose: Post-process Markdown-generated HTML into Forge-themed markup.
Order: apply_all runs: convert_mermaid_blocks → enhance_tables → enhance_blockquotes → enhance_code_blocks. Returns (html, has_mermaid).
enhance_tables: Wraps bare <table> with .forge-table-wrap and adds .table .table-sm .table-striped.
enhance_blockquotes: Maps **Warning** / **Note** / **Template** lead-ins to colored callouts; generic blockquotes become .forge-callout-surface.
enhance_code_blocks: Adds .forge-code to <pre>.
convert_mermaid_blocks: Finds <pre><code class="language-mermaid"> and replaces with .forge-diagram + .mermaid div.
extract_toc: Parses <h2 id> / <h3 id> for right-rail ToC tuples.

Complete API

Function	Returns	Role
`apply_all(html)`	tuple[str, bool]	Canonical pipeline end-to-end; returns `(html, has_mermaid)` for layout script injection.
`convert_mermaid_blocks(html)`	tuple[str, bool]	Replaces fenced Mermaid `<pre><code class="language-mermaid">` with `.forge-diagram` + `.mermaid`.
`enhance_tables(html)`	str	Wraps bare `<table>` and adds Forge table classes.
`enhance_blockquotes(html)`	str	Maps blockquotes to `.forge-callout-`; recognizes Warning* / Note / Template prefixes.
`enhance_code_blocks(html)`	str	Adds `.forge-code` to `<pre>` (including language-* code classes).
`extract_toc(html)`	list[tuple[str, str, int]]	Collects `<h2 id>` / `<h3 id>` for ToC builders.

Diagrams · SVG template assets

Purpose: Reusable diagram archetypes under assets/svg/template-*.svg — content instances live in consuming repos.
Styling: Thumbnail cards use .forge-diagram, .forge-diagram-trigger, .ks-diagram-card, .ks-thumb in gallery.
Markup: Typical thumb: <div class="forge-diagram forge-diagram-trigger …" onclick="openDiagramWithDetail(this, 'linear')"><img src="assets/svg/template-….svg" alt="…">. The key (linear, loop, …) must exist in DIAGRAM_DETAILS inside showcase.js.
Behavior: openDiagramWithDetail clones SVG into the modal and wires hover/legend from JS metadata.

Live thumbnails for all 24 templates follow in the next sections — each card is clickable.

Diagrams · All 24 SVG templates (visual)

Below are the same archetypes as diagrams.html: one .bento-grid.bento-3 per family, each tile uses onclick="openDiagramWithDetail(this, '<key>')" where <key> matches DIAGRAM_DETAILS in js/showcase.js. Scroll is long by design so models and humans can see every asset.

Process & Flow

How work moves through stages.

linear-flow

loop-cycle

gate-chain

swimlane

decision-flow

funnel

Structural & Relational

How things are organized or connected.

tree

board-columns

checklist

network

venn

Timeline & Scheduling

Events or work spread across time.

gantt

timeline

roadmap

Data Charts

Quantitative data visualization (Excel / Power BI territory).

bar-chart

line-chart

pie-donut

stacked-bar

area-chart

scatter

Comparison & Status

Current state, thresholds, or relative positioning.

quadrant

gauge

kpi-card

Specialized

Domain-specific visualization patterns.

heatmap

Diagrams · Mermaid

Purpose: Diagram-as-code blocks rendered by Mermaid at runtime.
Styling: Wrapper <div class="forge-diagram breathe-static"> (optional forge-diagram-trigger + onclick for expand). Inner <div class="mermaid small"> holds escaped source text.
Python: render_mermaid_block(diagram, expandable=False) — when expandable, adds trigger and openDiagramModal(this).

Diagrams · Modal DOM contract

Purpose: Full-screen/lightbox SVG viewer shared by diagram gallery and layout previews.
Markup: Backdrop #diagramModal.diagram-modal-backdrop containing .diagram-modal, header (#diagramModalTitle, close button .diagram-modal-close calling closeDiagramModal()), body with #diagramModalCanvas.diagram-modal-canvas and #diagramModalDetail.diagram-modal-detail.
Behavior: showcase.js implements openDiagramWithDetail, openDiagramModal, openLayoutPreview (iframe + legend), scroll-spy on .ks-section[id] for ToC/sidebar.

Motion · Pulse

Purpose: Continuous soft glow to draw attention (hero metrics, alerts).
Styling: .pulse on cyan/glass surfaces; .pulse-amber on amber glass.

Example

pulse

pulse-amber

Motion · Breathe

Purpose: Hover border/shadow oscillation on cards and diagram shells.
Styling: .breathe-link (clickable) and .breathe-static (non-link). Often paired with .forge-card or .forge-diagram.

Example

breathe-link

breathe-static

Motion · Stat counters

Purpose: Large number + label in a glass tile (dashboards, landing stats).
Styling: Container .forge-stat inside glass. Value .stat-value (add .text-amber / .text-cyan or inline color). Label .stat-label.

Example

Label A

Label B

Layouts · Overview

Purpose: Full HTML documents: handbook_page, chapter_page, product_page, showcase_page, landing_page, gallery_page, split_page in components/layouts.py.
Canonical shell: showcase_page is the reference documentation layout (header + sidebar + body + optional right ToC). Consumer generators should mirror generator/build-showcase.py _render_page kwargs.
Live previews: Build writes preview-handbook.html, preview-chapter.html, preview-product.html, preview-split.html next to other showcase HTML via layout_previews.py. The Page Layouts page opens them in a modal iframe.

Layout functions (layouts.py)

Layout	Structure / theme	Used by
`handbook_page`	Blueprint handbook: sidebar + article + right ToC column.	blueprints-website
`chapter_page`	Methodology chapter shell; uses `docs-theme.css`; often JS-hydrated nav.	blueprints-website chapters
`product_page`	Marketing/product article + tier sidebar; `forgesdlc-theme.css`.	forgesdlc.com
`showcase_page`	Sticky site header + sidebar + body + optional right `.forge-toc` — canonical doc shell.	Kitchensink showcase; consumer doc generators
`landing_page`	Top nav + hero + body; no sidebar.	Showcase `index.html`
`gallery_page`	Same shell as showcase but main column full width (no right ToC column).	`diagrams.html`
`split_page`	Two-column main: left demo, right documentation.	Optional detail / playground pages

Layouts · `showcase_page`

Parameters: browser_title, page_title, sidebar_html, body_html, toc_html (optional), breadcrumb_html, footer_html, extra_css, extra_js (list of src paths), theme_css_href, theme_js_href.
Structure: Sticky header (brand, breadcrumb, H1) + scrollable left sidebar + main column + optional right .forge-toc.
Used by: Kitchensink showcase (this site) for most pages.

Layouts · `landing_page`

Parameters: hero_html, body_html, nav_links_html, footer_html — no sidebar.
Used by: Showcase index (index.html).

Layouts · `gallery_page`

Parameters: Like showcase but no right-rail ToC column — wider main for grids.
Used by: diagrams.html.

Layouts · `split_page`

Parameters: left_html (demo), right_html (docs). extra_js passed separately in builder.
Used by: Optional pattern for playground + explanation pages.

Layouts · `handbook_page`

Parameters: sidebar_html, body_html, toc_html — three-column blueprint handbook.
Used by: blueprints-website generator.

Layouts · `chapter_page`

Styling: Uses docs-theme.css for chapter chrome.
Used by: Methodology chapters in blueprints-website.

Layouts · `product_page`

Styling: forgesdlc-theme.css, fs-* layout and tier sidebar.
Used by: forgesdlc.com static generator.

JS · `forge-theme.js`

Purpose: Theme preference persistence and Bootstrap data-bs-theme sync.
Cookie: forge_color_scheme values: light, dark, auto (follow system).
DOM: Dropdown roots .forge-theme-dropdown; items with data-forge-color-scheme; label .forge-theme-current.
Events: Dispatches forge-theme-applied on window with effective theme.
Mermaid / SVG: File header documents diagram scaling and cluster animation hooks used on content pages.

JS · `showcase.js`

Scroll-spy: IntersectionObserver on .ks-section[id]; toggles .active on .forge-toc .nav-link and #ks-sidebar-nav a[href^="#"].
Diagram modal: DIAGRAM_DETAILS map keys match onclick keys in gallery cards. openLayoutPreview embeds showcase pages or preview-*.html in the modal iframe.

Product · `forgesdlc-theme.css` & `fs-*`

Purpose: Marketing/product site look separate from handbook dark docs.
Tokens: CSS variables use --fs-* prefix (see stylesheet). Classes include .fs-layout, .fs-sidebar, .fs-brand, .landing-hero-*, .fs-cross-refs.
Python: render_product_landing_hero, render_cross_refs, render_product_footer, wrap_product_site_article emit product markup.
Live preview: After python3 generator/build-showcase.py, open showcase/preview-product.html (or use the Layouts page “Open live preview” for product) — do not load product CSS on this handbook-themed page or variables will clash.

Relative link from this file: preview-product.html (same directory as for-agents.html).

How to use this page

Tokens · Color palette

Tokens · Typography

Display heading

Tokens · Spacing & layout width

Surfaces · Glass panels

Surfaces · Cards

Link card

Amber link

Non-link

Surfaces · Bento grid

Surfaces · Tables

Surfaces · Dividers

Controls · Buttons

Controls · Badges

Controls · Callouts / alerts

Controls · Code blocks & inline

Navigation · Sidebar patterns

Navigation · Flow diagram (CSS)

Navigation · Breadcrumbs, skip link, mobile, footer

Python · components/components.py API

Python · Complete function inventory

Transforms · components/transforms.py

Diagrams · SVG template assets

Diagrams · All 24 SVG templates (visual)

Process & Flow

Structural & Relational

Timeline & Scheduling

Data Charts

Comparison & Status

Specialized

Diagrams · Mermaid

Diagrams · Modal DOM contract

Motion · Pulse

Motion · Breathe

Motion · Stat counters

Layouts · Overview

Layouts · showcase_page

Layouts · landing_page

Layouts · gallery_page

Layouts · split_page

Layouts · handbook_page

Layouts · chapter_page

Layouts · product_page

JS · forge-theme.js

JS · showcase.js

Product · forgesdlc-theme.css & fs-*

Diagram

Python · `components/components.py` API

Transforms · `components/transforms.py`

Layouts · `showcase_page`

Layouts · `landing_page`

Layouts · `gallery_page`

Layouts · `split_page`

Layouts · `handbook_page`

Layouts · `chapter_page`

Layouts · `product_page`

JS · `forge-theme.js`

JS · `showcase.js`

Product · `forgesdlc-theme.css` & `fs-*`