diff --git a/contribute/style-guide-extended.mdx b/contribute/style-guide-extended.mdx index 5a236114..1965294c 100644 --- a/contribute/style-guide-extended.mdx +++ b/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,8 +624,8 @@ 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 @@ -633,7 +633,16 @@ Start the node with `--threads` (see [validator flags → `--threads`](/ecosyste - 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 `` MDX component. Markdown image syntax `![...](...)` and raw `` 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, ``, where `` is the logical image category and `` 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 ``, 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.) diff --git a/contribute/style-guide.mdx b/contribute/style-guide.mdx index 81afcfb1..dfa738b0 100644 --- a/contribute/style-guide.mdx +++ b/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 `` component for all images. Markdown image syntax `![...](...)` and raw `` are not allowed. +- Store images under `resources/images/` and reference them with root‑absolute paths, for example ``. **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