feat: add the Cacti design system for the MkDocs documentation site

[RafaelAPB]

Problem

The Hyperledger Cacti documentation site (built with MkDocs / Material for MkDocs) ships the default theme palette and stock typography. As the project surface grows — connectors, validators, SATP flows, Weaver — the docs read as generic rather than on-brand, and there is no shared token layer to keep pages visually consistent.

We need a documented, token-driven visual system applied to the MkDocs site so it feels more like Hyperledger Cacti. This design system will provide the foundations for UIs built on top of Cacti.
We have created a simple design system with the Hyperledger Cacti logo as a starting point.

A first attempt:

Proposed solution

No response

Alternatives considered

Apply the Cacti design system — a desert-botanical token set derived from the Hyperledger Cacti brand mark — to the MkDocs Material theme. Concretely:

1. Color tokens. Override palette in mkdocs.yml with the Cacti semantic tokens, mapped to Material's primary, accent, and custom CSS variables:

--cacti-green-700	#4e8c5e	Primary action / links
--cacti-green-500	#7fbf8a	Focus ring, success
--cacti-green-900	#2c5238	Primary pressed
--cacti-bloom-500	#ef9a4f	Bloom accent (used sparingly)
--cacti-bloom-700	#c2762f	Warning / accent pressed
--cacti-ink-900	#101314	Page ink / dark canvas
--cacti-ink-500	#3b4548	Muted text
--cacti-paper	#f7f9f6	Light page background

2. Typography. Load Barlow (600/700/800) for display headings and the wordmark voice; keep the system sans stack for body and UI labels. Wire --font-display and --font-body as CSS variables and map them to Material's heading and body selectors via an extra extra_css stylesheet.

3. Spacing & radius. Author against an 8pt rhythm (--space-1 … --space-7: 4–64px) and a three-step radius scale (--radius-sm/md/lg), exposed as CSS variables in the extra stylesheet so callouts and admonitions share the same corners and padding.

4. Light + dark. Provide a paired light/dark palette using Material's palette-toggle, re-mapping the semantic tokens under a .cacti-dark / data-theme="dark" scope (ink-900 canvas, green-500 primary, paper foreground).

5. Component styling. Re-skin the Material primitives to the token system:

Admonitions (note, tip, warning, danger) → Cacti semantic colors (--success, --warning, --danger) with a 4px left border.

Code blocks → ink-900 canvas, mono stack, bloom accent for the copy button.

Inline badges / labels → the Cacti pill badge style (radius-pill, uppercase caption).

Nav header & tabs → surface background, primary active state, focus ring.

Authoring guidance. Add a docs/design-system.md page documenting the tokens, when to use the bloom accent (at most one element per view), and the do-not-use-raw-literals rule, so contributors extend the system consistently.

Affected package(s)

please apply to cacti and cacti-demos docs

Additional context

Reference design-system artifact (tokens, typography, components) was drafted from the Hyperledger Cacti brand and logo.

The palette is intentionally constrained: three green steps, one bloom accent, and a six-step neutral ink ramp — designed to be applied without a sprawling override file.

We have taken a first step on creating this design system. CSS, system design markdown, and HTML proof of concept are available:

css: https://gist.github.com/RafaelAPB/c7fc324e06f541067a2ca442b25d428d
design system md: https://gist.github.com/RafaelAPB/9cb54619adbbb97668a4f766749eb930
assets: https://gist.github.com/RafaelAPB/58a412595f3e9aa4113ac79831f34b98

PoC:

index.html