Design tokens

flowchart LR
  client[Client]:::client
  service[Service]:::service
  client content@-->|Content| service
  class content dataflow

A token names a recurring visual decision and keeps its value in the shared source. Bosunkit uses CSS custom properties such as --text-dim, --bk-type-body-reading and --bk-diagram-service. These are the names to use in code. Dotted names from other design systems describe a similar idea; they are not Bosunkit exports.

Source and delivery

The editable source is design/bosunkit/tokens/. Import @bosunkit/tokens/index.css once before component styles. Its cascade layers put reset, tokens, components and instruments in a defined order.

tokens.json is generated output, not a second place to edit the design. The parser resolves var() aliases; CSS expressions such as color-mix() may remain expressions. It is not a complete browser cascade or a snapshot of a nested size scope. Use the browser's computed styles when rendering depends on a particular element.

@import "@bosunkit/tokens/index.css";

.document-summary {
  padding: var(--bk-document-inset);
  background: var(--surface);
  color: var(--text);
  font: var(--bk-document-body);
}

From a shared role to a component

The source includes direct values and aliases; it is not a strict three-tier naming schema. Prefer the narrowest role that expresses the intended meaning. A diagram service fill uses --bk-diagram-service; a component does not reconstruct that fill from a palette color. The report palette maps accent="01" to --data-categorical-operational-01 through its local --report-accent variable.

Reading, labels and diagram type

Report prose, metadata and diagram labels need different densities. Enlarging every text element makes a document harder to scan and can misalign controls. Choose the role before changing a size.

The diagram family is a neutral sans serif; document and UI roles use the shared body family. Diagram sizes are independent of the UI size-class scale. A scaled SVG scales its text too, so inspect dense drawings at their natural width as well as in the fitted column. Keep UI buttons on their control roles.

Reading measure and available space

--bk-report-width sets the standalone report-template measure and is available to document compositions. --bk-email-width sets the email-template measure. Neither defines the Fumadocs shell's page width or reserves space for its navigation. Report grids adapt to the space their parent provides.

Keep prose within a reading measure on larger displays. Let diagrams and tables use the available figure area inside the shell. A figure must not cover the sidebar or “On this page.” Mermaid fits its container by default; Expand reveals its natural drawing width inside a horizontal scroll region. Desktop preview can show a larger report composition without widening the documentation page itself.

Insets and section spacing come from --bk-document-inset and --bk-document-section-gap. Diagram padding and automatic rank spacing use the shared spacing scale. An authored MermaidLayout contains drawing coordinates and routes; those are content geometry, not CSS tokens or viewport breakpoints.

Editorial color and diagram roles

Report category accents and data-series colors distinguish subjects. They do not establish alert priority, publication approval or confidentiality. Name states in text and preserve category labels, connection names and line patterns when color changes.

Mermaid has separate canvas, group, node, service and connection roles. The Day palette uses a quiet paper surface and softly tinted services. Night, Dusk and Bright each resolve their own values; a Day color copied into diagram source bypasses that behavior.

Use the shared Mermaid classes client, service, storage and dataflow to opt into these roles. Authored classDef and style declarations retain precedence. Evaluate text against its actual fill and connectors against their canvas; a token name alone does not establish sufficient contrast.

Local theme scopes

PresentationScope places theme and size attributes on an element. CSS consumers inherit the nearest scope. The two diagrams below retain their explicit themes when the site's theme changes.

flowchart LR
  Client:::client --> Service:::service

flowchart LR
  Client:::client --> Service:::service

Read renderer tokens with getComputedStyle(container) on the diagram's own element. Reading document.documentElement ignores a local scope. Re-render generated artwork after its effective theme changes; CSS inheritance alone cannot recolor values already embedded in an SVG string.

Mermaid has global configuration. The shared renderer serializes initialization and rendering so simultaneous diagrams cannot exchange palettes. It resolves the connection role before adding the dataflow class to Mermaid source: raw var(--…) syntax is not valid in every diagram grammar position.

SVGs, Markdown and static exports

Keep renderer selectors inside their generated diagram. A generic .label rule from a component stylesheet must not change SVG label metrics. HTML labels can contain line breaks inside SVG foreignObject content; the shared renderer parses its generated markup as HTML to retain that content without XML tag mismatches. This does not grant arbitrary diagram HTML permission: strict rendering and source disclosure remain in place.

A copied Mermaid fence retains relationships and automatic layout. Exact reference placement belongs to the optional JSX layout object. Tokens provide visual consistency; they do not reproduce another drawing's coordinates, font rasterization or every reference pixel.

Add or change a role

1. Find the existing role that owns the meaning. Add a specialized role when several uses need the same visual decision; keep a single diagram's labels and coordinates in its source.
2. Define it in the appropriate token stylesheet, including every relevant theme or size scope. Aliases that depend on theme-local values must resolve within each explicit scope.
3. Keep index.css, the token writer and the design site's parser inputs aligned when adding a stylesheet. Regenerate JSON with node design/bosunkit/tokens/write-tokens-json.ts; do not edit that output manually.
4. Use the role at the shared component source and document it with a live example. Both documentation and reports consume that component; a specimen must not apply its own corrective styling.
5. Verify Night, Dusk, Day and Bright, nested scopes, fitted and expanded diagrams, narrow containers and the relevant static export. Check source disclosure and failure recovery as well as the successful drawing.

Using tokens

Related

• Themes and Typography: scoped palettes and complete text roles.
• Grid and Reports and docs: reading measures and composition.
• Mermaid: diagram classes, authored layouts, source and inspection controls.
• Report blocks and Report metadata: editorial roles in shared components.