Sentinel Style Guide

"The Sentinel's rigour in code must extend to every pixel the user sees."

This document codifies the Sentinel 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 (<Icon name="..." /> — 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

- <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](../usage/index.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 "Sentinel 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	Sentinel Output	CLI output blocks and Sentinel 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, Sentinel creed

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:

1. It is an H2 or H3 heading (never H1 — Docusaurus auto-generates H1 IDs from sidebar_label).
2. 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:

• Every card grid follows §1 (single action link).
• Every admonition matches its §2 role.
• All icons use <Icon name="..." /> — no :lucide-*:, :octicons-*:, or :material-*: shortcodes remain (§3).
• Any new icon name is registered in src/components/Icon.tsx (§3).
• Cross-referenced H2/H3 headings have explicit {#id} (§4). No anchors on H1.
• No naked code fences exist (§5).
• SPDX header is present (§6).
• Italian mirror is structurally identical to English.