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:

1. An icon (:material-*: / :octicons-*: — see §3).
2. A bold title.
3. A description of at most two lines.
4. A single action link using the arrow prefix.

Canonical example¶

- :material-play:   **User Guide**

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

    [:material-arrow-right: Explore the Guide](../../../how-to/install.md)

Forbidden patterns¶

3. Iconography Law (Material for MkDocs)¶

This section details the specifications and guidelines for 3. Iconography Law (Material for MkDocs) within the Zenzic ecosystem.

Native Emoji & Icon Shortcodes¶

Every icon in the documentation MUST be rendered using native Material for MkDocs shortcodes:

:material-icon-name:
:octicons-icon-name-16:

Examples:

• :material-bug-outline:
• :material-file-document-edit-outline:
• :material-sparkles:
• :octicons-git-pull-request-16:
• :material-arrow-right:

Rules¶

• Strict Shortcode Rule: Custom pseudo-tags like <Icon name="..." /> are strictly forbidden. Always use native Material for MkDocs :material-*: / :octicons-*: shortcodes.
• 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 native :material-*: / :octicons-*: shortcodes.
• No emoji in headings: Emoji characters (⚡, 🛡️, 🚀, etc.) are permitted in running prose only. They must not be used as heading prefix decorators. Heading hierarchy communicates document structure; emoji communicates marketing enthusiasm. These are incompatible roles. Headings containing emoji will be rejected in PR review.

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

This section details the specifications and guidelines for 4. Anchor ID Protocol (ZRT-DOC-004) within the Zenzic ecosystem.

When to add explicit IDs¶

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

1. It is an H2 or H3 heading (never H1 — some engines auto-generate H1 IDs from sidebar labels).
2. It is referenced by a cross-page link ([text](page.md#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:

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 source documentation file (.md, .md, and equivalent content files) must carry SPDX metadata.

Minimum header pattern:

<!-- SPDX-FileCopyrightText: 2026 PythonWoods <[email protected]> -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

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

Significant Contribution Rule (MUST)¶

For significant changes (new logic, major content blocks, structural rewrites), contributors must add their own SPDX-FileCopyrightText line below the project line.

<!-- SPDX-FileCopyrightText: 2026 PythonWoods <[email protected]> -->
<!-- SPDX-FileCopyrightText: 2026 Contributor Name <[email protected]> -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

Trivial edits (typos, punctuation, formatting-only changes) do not require an additional contributor line.

Legal Governance Model¶

Zenzic does not require a CLA transfer model. Governance is based on:

• DCO (Developer Certificate of Origin) for authorship attestation.
• REUSE/SPDX for per-file copyright and license traceability.

Contributors retain copyright on significant changes and declare authorship via SPDX headers.

7. Visual Consistency Checklist¶

Before submitting a PR, verify:

• Every card grid follows §1 (single action link).
• Every admonition matches its §2 role.
• All icons use native :material-*: / :octicons-*: shortcodes.
• Cross-referenced H2/H3 headings have explicit {#id} (§4). No anchors on H1.
• No naked code fences exist (§5).
• SPDX header is present (§6).
• No hex literal (#rrggbb) in src/ outside ZenzicPalette._* (§9).
• All colour references use ZenzicPalette.* — no removed flat constants (§9).
• Any text-bearing diagram inside a Markdown page uses native HTML/Jinja or Mermaid syntax (§10).

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¶

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¶

Semantic palette¶

Pre-composed style strings¶

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

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. Markdown Asset Componentization Law¶

Directive: ZRT-DOC-010

For the detailed architectural rationale behind this directive, see Markdown Asset Componentization Rationale.

Checklist addition¶

Add to your PR checklist:

• Any text-bearing diagram or illustration inside a Markdown page is implemented via native HTML/Jinja or Mermaid.