feat(styleguide): ban relative links

contribute/style-guide-extended.mdx

@@ -20,7 +20,7 @@ Definitions (used throughout).
 
 Out of scope. Editorial process, CI wiring, analytics/metrics, and governance live outside this guide. (This guide is about writing.) (Why: focusing on writing rules keeps this document stable and avoids process churn.)
 
-Living document. This guide evolves with the documentation. Editors **MAY** update rules as the information architecture and best practices change. When the guide changes, all existing documentation **MUST** be re-validated against the new rules and updated as needed to keep the docs consistent. (Why: styles must adapt as the product and IA evolve; re-validation prevents long-term drift.)
+Living document. This guide evolves with the documentation. Editors **MAY** update rules as the information architecture and best practices change. When the guide changes, all existing documentation **MUST** be re-validated against the new rules and updated as needed to keep the docs consistent. (Why: styles must adapt as the product and the information architecture evolve; re-validation prevents long-term drift.)
 
 ### Severity model (release‑blocking)
 
@@ -624,16 +624,25 @@ Start the node with `--threads` (see [validator flags → `--threads`](/ecosyste
 
 ### 12.3 Link targets and format
 
-- Internal links **SHOULD** be relative and stable; anchors **MUST** resolve correctly. (Why: relative links survive domain/structure changes; broken anchors waste time.) \[HIGH]
-- Cross‑section links **SHOULD** jump to precise anchors instead of page tops. (Why: deep links land readers on the exact answer.)
+- Internal links **MUST** be root‑absolute and stable (start with `/`); anchors **MUST** resolve correctly. **MUST NOT** use relative segments like `./` or `../` in Markdown/MDX link URLs or HTML/JSX. (Why: files and folders move frequently; root‑absolute links remain correct across moves; relative segments are brittle and costly to maintain.) \[HIGH]
+- Cross‑section links **SHOULD** deep‑link to the exact section or anchor instead of the page top. (Why: deep links land readers on the exact answer.)
 - A See also section **MAY** close a page with 1–3 essential links; prefer a linear path that needs none. (Why: minimal exits keep readers on task while still offering critical follow‑ups.)
 
 ### 12.4 Avoid circularity and drift
 
 - Each fact **MUST** have a single canonical home. If you need the same fact elsewhere, link to it. (Why: one source avoids conflicting copies and simplifies updates.)
 - **MUST NOT** link to outdated or superseded pages except when documenting historical behavior. (Why: stale links propagate errors and erode trust.) \[HIGH]
 
-### 12.5 External references
+### 12.5 Images and media
+
+- Images **MUST** be embedded using the `<Image>` MDX component. Markdown image syntax `![...](...)` and raw `<img ...>` are **PROHIBITED**. (Why: the component provides dark‑theme control, consistent sizing/zoom, and stable rendering.) \[HIGH]
+- Image sources **MUST** be root‑absolute and live under `/resources/images/` (for example, `<Image src="/resources/images/<GROUP>/<FILE>.png" />`, where `<GROUP>` is the logical image category and `<FILE>` is the filename). **MUST NOT** use relative `src` such as `./` or `../`. (Why: content moves often; root‑absolute paths remain valid.) \[HIGH]
+- Provide a `darkSrc` when contrast or readability differs in dark mode. Keep aspect ratios consistent across a page to avoid layout shift. (Why: visual stability improves reading flow.)
+- SVG note: if `src` points to an SVG and `darkSrc` is omitted, the dark‑theme image is auto‑inverted. Supply an explicit `darkSrc` when inversion is not desired. (Why: ensures accurate colors and legibility.)
+- Provide meaningful, non‑empty `alt` text for every image; `alt` **MUST NOT** be empty. (Why: screen readers rely on `alt` to convey image meaning; empty `alt` hides content from assistive tech.) \[HIGH]
+- When using `<Image>`, prefer the `width`/`height` props for predictable layout; avoid arbitrary inline styling. (Why: predictable dimensions prevent layout shift and maintain consistency.)
+
+### 12.6 External references
 
 Objective. Use authoritative, stable sources and deep links; avoid volatile or non‑authoritative pages. (Why: reliable links reduce drift, link rot, and conflicting guidance.)
 
@@ -819,7 +828,7 @@ Objective. Keep repository structure and UI labels consistent. (Why: predictable
 
 ### 16.3 Links and anchors
 
-- Internal links **SHOULD** be relative to avoid domain coupling; ensure anchors are stable. (Why: relative links survive domain or path changes; stable anchors prevent 404s.)
+- Internal links **MUST** be root‑absolute (start with `/`) and **MUST NOT** include `./` or `../`; ensure anchors are stable. (Why: root‑absolute links survive file moves and changes to the information architecture; relative segments break during reorganizations.) \[HIGH]
 - Trailing slashes: Follow a single repo‑wide policy set by the site generator, and apply it consistently across all internal links. (Why: consistency prevents duplicate routes, cache misses, and SEO issues.)
 - Cross‑section links **SHOULD** target specific anchors rather than page tops. (Why: deep links land readers directly on the needed detail.)
 

contribute/style-guide.mdx

@@ -104,7 +104,14 @@ Each safety callout should briefly state the risk, scope, rollback/recovery (if
 - Do not paste reference tables into guides. Link instead. Duplicated tables go stale.
 - Use descriptive link text, not “click here”.
 - Link core TON terms to the Glossary on first useful mention unless you define them on the page.
-- Prefer stable, relative links and precise anchors.
+- Internal links **MUST** be root‑absolute (start with `/`). Deep‑link to the exact section or anchor that contains the needed fact (not the page top). **MUST NOT** use relative segments like `./` or `../` in any Markdown/MDX link. (Why: content moves frequently; root‑absolute links survive reorganizations.)
+
+## Images
+
+- Use the `<Image>` component for all images. Markdown image syntax `![...](...)` and raw `<img ...>` are not allowed.
+- Store images under `resources/images/` and reference them with root‑absolute paths, for example `<Image src="/resources/images/<GROUP>/<FILE>.png" />`. **MUST NOT** use relative `src` such as `./` or `../`.
+- Provide meaningful, non‑empty `alt` text (never `alt=""`); add `darkSrc` when the dark theme needs different contrast. Keep sizes/aspect ratios consistent across a page.
+- SVGs: if you omit `darkSrc`, colors are auto‑inverted in dark mode; add `darkSrc` if inversion isn’t correct.
 
 ## Terminology and names