Zenzic Style Guide

"The rigour applied to code must extend to every pixel the user sees."

This document codifies the Zenzic Visual Language — the binding rules for all Zenzic documentation pages. Every contributor must follow these rules. Reviewers must reject PRs that violate them.

Directive: ZRT-DOC-002

1. Card Rule (High-Density UX)

Navigation cards orient. They do not replace the sidebar.

Structure

Every card in a <div class="grid cards" markdown> block must have exactly:

An icon (<Icon name="..." /> — see §3).
A bold title.
A description of at most two lines.
A single action link using the arrow prefix.

Canonical example

- <Icon name="play" /> &nbsp; **User Guide**

    Everything you need to install, configure, and integrate Zenzic into
    your CI/CD workflow.

    [<Icon name="arrow-right" /> Explore the Guide](../../../how-to/install.mdx)

Forbidden patterns

Pattern	Why
Horizontal link chains (`·`-separated)	Creates a wall of text; impossible to scan
Nested `<li>` lists inside a card	Breaks card height uniformity
`---` separators inside a card	Adds visual noise without information gain
Cards with zero action links	Dead-end; the user has nowhere to go

Exception

Presentation cards (e.g., homepage "Zenzic in Action" demos) may omit the action link because their purpose is visual demonstration, not navigation. They must still receive the card CSS (border, hover, transition).

2. Admonition Taxonomy

Each admonition type has one — and only one — semantic role.

Type	Role	When to use
`:::tip`	Quick Win	One-liner commands the reader can run immediately
`:::info`	Zenzic Output	CLI output blocks and Zenzic report samples
`:::danger`	Security Gate	Exit Code 2 (credentials) and Exit Code 3 (path traversal) only
`:::warning`	Design Constraint	Architectural rules, contributor policies, "use sparingly" caveats
`:::note`	Clarification	Engine-specific facts, contributor onboarding, multi-step guidance
`:::info`	Cross-Reference Bridge	Links from the current section to the next actionable step
`:::info`	Community CTA	Engagement calls ("Help us grow", "Join the discussion")
`:::note`	Philosophy	Project vision, design manifesto, Zenzic standards

Enforcement

If a block does not fit any category above, rewrite it as prose. Admonitions are not decoration.

3. Iconography Law (ZRT-DOC-003)

The `<Icon />` Component

Every icon in the documentation must be rendered with:

<Icon name="icon-name" />

Optional size override (default is 1.15em, inherits from surrounding text):

<Icon name="shield-check" size={20} />

All icon names follow the Lucide icon set naming convention (lowercase, hyphen-separated).

Hierarchy

Priority	Set	Syntax	Notes
1	Lucide	`<Icon name="play" />`	All UI and navigation icons

Rules

Semantic consistency: if an icon represents "Contribute" on one page, it

must be the same icon on every page.
Uniform syntax: every icon in a card grid uses <Icon name="..." />.

No mixing of syntaxes or icon sets.
Tree-shaking contract: before using a new icon name, add it to the

explicit iconsMap in src/components/Icon.tsx. Unregistered names render a red placeholder and emit a console.warn.

4. Anchor ID Protocol (ZRT-DOC-004)

When to add explicit IDs

Add {#id} to a heading when it satisfies both of:

It is an H2 or H3 heading (never H1 — Docusaurus auto-generates H1 IDs from sidebar_label).
It is referenced by a cross-page link ([text](page.mdx#anchor)).

i18n Invariant

The canonical ID is always the English slug. Italian (and any future language) pages must use the same {#id} value:

{/* EN */}
## Getting Started \{#getting-started}

{/* IT */}
## Inizia Ora \{#getting-started}

This ensures the VSM resolver and cross-language links never break due to translation-dependent slug generation.

Heading format

## Section Title \{#section-title}

Do not add IDs to headings that are never linked to externally. Every explicit ID is a maintenance contract.

5. Code Block Rule

Every opening fence must carry a language tag:

Fence	Verdict
```python	✓
```bash	✓
```toml	✓
```text	✓ (plain output)
```	✗ FORBIDDEN

Use text for output that has no syntax highlighting. Naked fences hurt accessibility tools and syntax highlighters.

Gutter specificity: for CLI output shown inside :::info blocks, always use the text tag to prevent the syntax highlighter from generating random colours on log strings or file paths.

6. SPDX Header

Every .md file must begin with:

{/* SPDX-FileCopyrightText: 2026 PythonWoods <[email protected]> */}
{/* SPDX-License-Identifier: Apache-2.0 */}

Files with YAML frontmatter place the SPDX block immediately after the closing ---.

7. Visual Consistency Checklist

Before submitting a PR, verify:

8. ZenzicUI Gateway

All branded terminal output in Zenzic flows through a single object: ZenzicUI in src/zenzic/ui.py. Command modules must never instantiate Console or ZenzicUI directly — they must call get_ui() and get_console() from zenzic.cli._shared.

Core methods

Method	When to use
`print_header(version)`	The top-of-output Zenzic Frame banner — once per command invocation
`make_panel(content, *, title, border_style)`	Styled Rich `Panel` — for structured output blocks
`print_exception_alert(message, *, context, title, border_style)`	Error panels for `ZenzicError` and `PluginContractError`

Usage pattern

# In any _check.py / _clean.py / _standalone.py command
from . import _shared

# Print the Zenzic banner header
_shared.get_ui().print_header(__version__)

# Print a styled panel
panel = _shared.get_ui().make_panel(
    "Content here",
    title="Panel Title",
    border_style="bold cyan",
)
_shared.get_console().print(panel)

Why the gateway matters

The --no-color and --force-color CLI flags call configure_console(), which atomically replaces the module-level console and _ui singletons. Any locally-created Console or ZenzicUI instance will be frozen before the flag takes effect, silently ignoring the user's color preference.

The force_terminal parameter must always be None (auto-detect) in the module-level Console, never False. Explicit False disables color system detection entirely — resulting in no ANSI styling even in truecolor terminals. This is the most common source of visual regressions in the Zenzic CLI layer.

Checklist addition

Add to your PR checklist:

No Console(...) or ZenzicUI(...) instantiation in command modules.
All banner output uses get_ui().print_header(), not a locally-created UI instance.
force_terminal on any new Console call is None or conditional (True if ... else None), never False.

9. ZenzicPalette — Zero Hex Law

ZenzicPalette in src/zenzic/ui.py is the sole authorised source of colour values in the entire Zenzic codebase. This is the Zero Hex Law.

The Law

:::warning Design Constraint

No hex colour string (e.g. #4f46e5) and no raw Rich colour name (e.g. "red", "cyan") may appear anywhere in src/ except inside ZenzicPalette._* private class attributes. Every other file must address only the semantic public attributes shown below.

:::

Semantic palette

Attribute	Hex	Meaning
`ZenzicPalette.BRAND`	`#4f46e5`	Zenzic primary / brand accent (Indigo)
`ZenzicPalette.SUCCESS`	`#10b981`	OK · clean · pass (Emerald)
`ZenzicPalette.WARNING`	`#f59e0b`	Caution · advisory (Amber)
`ZenzicPalette.ERROR`	`#f43f5e`	Failure · broken links (Rose)
`ZenzicPalette.DIM`	`#64748b`	Muted · secondary text (Slate)
`ZenzicPalette.FATAL`	`#8b0000`	Security breach · path traversal (Critical Red)

Pre-composed style strings

For the most common combinations, use a STYLE_* constant instead of constructing f"bold {X}" inline:

Constant	Expands to
`ZenzicPalette.STYLE_BRAND`	`"bold #4f46e5"`
`ZenzicPalette.STYLE_OK`	`"bold #10b981"`
`ZenzicPalette.STYLE_WARN`	`"bold #f59e0b"`
`ZenzicPalette.STYLE_ERR`	`"bold #f43f5e"`
`ZenzicPalette.STYLE_DIM`	`"#64748b"`

Usage pattern

# CORRECT — semantic alias via ZenzicPalette
from zenzic.ui import ZenzicPalette

table = Table(border_style=ZenzicPalette.DIM, header_style=ZenzicPalette.STYLE_BRAND)
text = Text.from_markup(f"[{ZenzicPalette.BRAND}]Zenzic[/]")
panel = Panel("...", border_style=ZenzicPalette.STYLE_ERR)

# FORBIDDEN — hex literal outside ZenzicPalette
text = Text.from_markup("[#4f46e5]Zenzic[/]")   # ✗

# FORBIDDEN — flat constant import (removed in)
from zenzic.ui import INDIGO, EMERALD            # ✗

# FORBIDDEN — inline alias
P = ZenzicPalette                              # ✗  use full qualification

Updating the palette

To change a colour, edit only the corresponding _PRIVATE hex attribute inside ZenzicPalette in src/zenzic/ui.py. All semantic aliases and pre-composed style strings derive from those private attributes — the entire codebase updates automatically.

Checklist addition

Add to your PR checklist:

No hex literal (#rrggbb) anywhere in src/ outside ZenzicPalette._*.
No raw Rich colour names ("red", "cyan") for brand-palette usage — use ZenzicPalette.*.
No local alias P = ZenzicPalette — always use the full class name.
No from zenzic.ui import INDIGO (or any removed flat constant).

10. MDX Asset Componentization Law

Directive: ZRT-DOC-010

:::warning Design Constraint

Any vector asset intended for exclusive use within MDX pages must be implemented as a React component (.tsx), never as a static .svg file.

:::

Rationale

Static .svg files cannot:

React to Docusaurus theme variables (--ifm-color-*, light/dark mode switching).
Use <Translate> for i18n — text is baked into XML, requiring manual duplication.
Update deterministically when the underlying data model changes — they require find-and-replace surgery across XML nodes.

React components (.tsx) solve all three: they read CSS variables at runtime, wrap strings with <Translate>, and derive their data from a single source of truth.

Permitted uses of static `.svg` files

Use case	Permitted?	Reason
OpenGraph social cards (`static/assets/social/`)	✓	Consumed by `<meta og:image>`, not by React
GitHub README illustrations (wordmarks, logos)	✓	Rendered by GitHub Markdown, no React context
Architecture/brand diagrams (`static/assets/brand/`)	✓	Pure graphics — no data nodes, no text strings
Terminal output panels inside MDX pages	✗	Use `<ZenzicOutput />` instead
Any text-bearing illustration inside an MDX page	✗	Use a `.tsx` component

Migration path

When a static SVG carrying text or data nodes must be converted:

Create src/components/<Name>.tsx with the same visual layout.
Replace text literals with <Translate id="..."> strings.
Source numeric data (weights, codes, scores) from the canonical Python module via a generated JSON fixture, not from hardcoded SVG attributes.
Register the component in src/theme/MDXComponents.js for global MDX availability.
Delete the original .svg file.

Checklist addition

Add to your PR checklist:

No new .svg file added to static/assets/terminal/ (use ZenzicOutput or a .tsx component).
Any text-bearing SVG introduced inside an MDX page is implemented as .tsx.

1. Card Rule (High-Density UX)​

Structure​

Canonical example​

Forbidden patterns​

Exception​

2. Admonition Taxonomy​

Enforcement​

3. Iconography Law (ZRT-DOC-003)​

The <Icon /> Component​

Hierarchy​

Rules​

4. Anchor ID Protocol (ZRT-DOC-004)​

When to add explicit IDs​

i18n Invariant​

Heading format​

5. Code Block Rule​

6. SPDX Header​

7. Visual Consistency Checklist​

8. ZenzicUI Gateway​

Core methods​

Usage pattern​

Why the gateway matters​

Checklist addition​

9. ZenzicPalette — Zero Hex Law​

The Law​

Semantic palette​

Pre-composed style strings​

Usage pattern​

Updating the palette​

Checklist addition​

10. MDX Asset Componentization Law​

Rationale​

Permitted uses of static .svg files​

Migration path​

Checklist addition​

1. Card Rule (High-Density UX)

Structure

Canonical example

Forbidden patterns

Exception

2. Admonition Taxonomy

Enforcement

3. Iconography Law (ZRT-DOC-003)

The `<Icon />` Component

Hierarchy

Rules

4. Anchor ID Protocol (ZRT-DOC-004)

When to add explicit IDs

i18n Invariant

Heading format

5. Code Block Rule

6. SPDX Header

7. Visual Consistency Checklist

8. ZenzicUI Gateway

Core methods

Usage pattern

Why the gateway matters

Checklist addition

9. ZenzicPalette — Zero Hex Law

The Law

Semantic palette

Pre-composed style strings

Usage pattern

Updating the palette

Checklist addition

10. MDX Asset Componentization Law

Rationale

Permitted uses of static `.svg` files

Migration path

Checklist addition