From f3c6f54ac78941a50dcb04c0cb34da9ef71111dc Mon Sep 17 00:00:00 2001
From: Gusarich <danielsedovzzz@gmail.com>
Date: Mon, 24 Nov 2025 12:18:31 +0300
Subject: [PATCH 1/5] feat(styleguide): improvements

---
 contribute/style-guide-extended.mdx | 81 +++++++++++++++++++++++------
 contribute/style-guide.mdx          | 10 +++-
 2 files changed, 75 insertions(+), 16 deletions(-)

diff --git a/contribute/style-guide-extended.mdx b/contribute/style-guide-extended.mdx
index a03171a08..beb9fc5d3 100644
--- a/contribute/style-guide-extended.mdx
+++ b/contribute/style-guide-extended.mdx
@@ -100,7 +100,8 @@ Rules (binding).
 - **MUST NOT** use filler or patronizing words: simply, just, obviously, clearly, please note. Replace with exact instructions (Why: filler wastes time and can sound condescending; precise verbs tell the reader exactly what to do.)
 - Emojis in prose and headings **MUST NOT** appear. Use clear text or an `<Aside>` when emphasis is needed. (Why: emojis are ambiguous, distract from procedures, and do not localize reliably.)
 - Emojis in code/command blocks **MAY** appear only when they are part of runnable code or a literal command/output string. Do not add emojis for decoration; the snippet **MUST** remain copy‑pasteable and executable as shown. If quoting a UI/log message that contains an emoji, keep it verbatim inside quotes. (Why: runnable examples take precedence; avoiding decorative emojis preserves clarity and execution.)
-- Emojis in compact tables **MAY** be used sparingly as visual indicators (for example, `✅` / `❌`) and **MUST** be paired with a text label in the same cell or a descriptive header (e.g., “Supported — Yes/No”). Do not rely on an emoji alone to convey meaning. (Why: paired text preserves clarity for screen readers, localization, and cases where emojis don’t render.)
+- Emojis in compact tables **MAY** be used sparingly as visual indicators only when they follow a widely understood convention (for example, `✅` / `❌` for supported/not supported, or `★` to mark a recommended option) and **MUST** be paired with a text label in the same cell or a descriptive header (e.g., “Supported — Yes/No”). Do not rely on an emoji alone to convey meaning, and **MUST NOT** use decorative or non‑standard pictograms (for example, a play triangle to indicate videos). (Why: paired, conventional icons preserve clarity for screen readers, localization, and cases where emojis don’t render.)
+- Even where emojis are technically allowed (code/output or compact tables), they **SHOULD** be rare and **MUST** have a clear purpose. If the same meaning is clear without the emoji, remove it. (Why: conventional text remains clearer for global readers and translators.)
 - Use plain terms over legalese/Latinisms. “Use” not “utilize”; “before” not “prior to.” (Why: common words improve comprehension and reduce rereads; they are also translated more consistently.)
 - Avoid first‑person pronouns (“we”, “I”, “our”). When an organization, product, or service is the actor, use its proper name (e.g., “Tonkeeper”, “TON”) or a neutral noun (“the node”, “the SDK”). Prefer imperative instructions without “you”. See [§5.8](#58-dont-get-personal) and [§5.10](#510-pronouns-and-person-references). (Why: neutral, explicit actors read cleanly and translate reliably.)
 
@@ -260,6 +261,16 @@ See also: [Appendix B](#b-banned-and-preferred-terms) lists additional banned in
 
 - For organizations, products, and services, use the proper name (e.g., “TON”, “Tonkeeper”) or the neutral “it”; do not use “we/I/our” in documentation. (Why: consistent, neutral references read cleanly and translate reliably.)
 
+### 5.11 Parentheses
+
+- Parentheses **MAY** be used for short clarifications and abbreviation expansions (for example, “The Open Network (TON)”) but **SHOULD NOT** be used for extended side remarks. (Why: side remarks buried in parentheses are easy to miss and hard to translate.)
+
+- When a parenthetical includes an extra idea, condition, or step, split the sentence into two sentences or move the extra idea into its own sentence or list item instead of nesting it in parentheses. (Why: one idea per sentence is easier to parse and localize.)
+
+- Where a parenthetical is necessary for precision, keep it short and avoid chaining more than one set of parentheses in the same sentence. (Why: multiple nested asides make sentences hard to read.)
+
+- This rule applies to TON documentation pages. This style guide itself **MAY** use parentheses more freely when explaining rules and rationale. (Why: meta‑documentation sometimes needs extra commentary that would be distracting in task pages.)
+
 ## 6. Punctuation and mechanics
 
 Objective. Remove ambiguity and increase scan speed with consistent mechanics. (Why: predictable punctuation choices make sentences easier to parse and reduce misreads.)
@@ -282,21 +293,18 @@ Objective. Remove ambiguity and increase scan speed with consistent mechanics. (
 
 - House rule — quoting style: Use the international style with American spelling. Quotation punctuation **MUST** remain outside closing quotes unless it is part of the quoted text. This differs from American book style; keep it consistent. (Why: keeps code‑adjacent strings accurate and avoids adding punctuation that isn’t part of the literal.) \[HIGH]
 
-  - Use double quotation marks for log/error strings and literal UI text by default; place punctuation outside unless it’s part of the string. For interactive controls and key names, you **MAY** use `<kbd>` instead of quotes. (Why: quotes remain the convention for messages/text; `<kbd>` can improve readability for controls/keys.)
-
-  - This rule applies to quoted UI/log/error strings only; it does not apply to code spans or headings. (Why: code spans and headings have their own styling rules.)
-
-  - Good (international): Click “Settings”, then select “Network”.
+- Use double quotation marks for log/error strings and other literal UI text when quoting it as text; place punctuation outside unless it is part of the string. (Why: quotes remain the convention for messages/text and keep literals copyable.)
 
-  - Bad (American style here): Click “Settings,” then select “Network.”
+- This rule applies to quoted UI/log/error strings only; it does not apply to code spans or headings. (Why: code spans and headings have their own styling rules.)
 
 - Log messages and error strings **MUST** appear verbatim in quotation marks; **MUST NOT** add emphasis or change casing/punctuation. (Why: exact copying/grepping depends on matching strings.) \[HIGH]
 
-- UI/menu labels and keyboard keys **MAY** use `<kbd>` when referring to literal controls or key names; the label **MUST** be verbatim. Quotation marks are also acceptable for UI text; prefer one style consistently within a page/section. (Why: `<kbd>` is intended for controls/keys and aids scanning; quotes keep a single convention—both are readable when used consistently.)
+- When referencing interactive controls or keyboard keys that the reader should click or press, you **MUST** use `<kbd>Label</kbd>` for the control or key name. You **MUST NOT** use quotation marks, bold, or italics to style controls in instructions. (Why: `<kbd>` is designed for controls/keys and keeps actions easy to scan and copy.)
 
-  - Good (alternative): Click `<kbd>Settings</kbd>`, then select `<kbd>Network</kbd>`.
+  - Good: Click `<kbd>Settings</kbd>`, then select `<kbd>Network</kbd>`.
+  - Bad: Click “Settings” or **Settings**.
 
-  - For quoted UI strings, follow the house quoting style above. Punctuation follows normal sentence rules outside `<kbd>`. (Why: consistent punctuation keeps text readable and copyable.)
+- UI or menu labels that appear in screenshots or descriptive text but are not being presented as actions **MAY** be written in quotes. Avoid mixing `<kbd>` and quoted labels arbitrarily; prefer one style consistently within a page/section. For quoted UI strings, follow the house quoting style above. Punctuation follows normal sentence rules outside `<kbd>`. (Why: consistent styling keeps text readable and copyable.)
 
 - Error codes/identifiers **MUST** use code formatting: `ERR_FEE_TOO_LOW`, `EADDRINUSE`, `ENOENT`. (Why: code styling distinguishes tokens from prose and aids scanning and copy/paste.)
 
@@ -306,16 +314,36 @@ Objective. Remove ambiguity and increase scan speed with consistent mechanics. (
 
 - Bold and italics **SHOULD** be used sparingly in body text. Prefer structure (headings, lists), precise wording, or an admonition over visual emphasis. (Why: heavy emphasis reduces scan speed and harms raw‑Markdown readability.)
 
+##### Bold
+
+- Bold **SHOULD** mark scan points: a skimming reader should be able to bounce between bolded words and still understand the key actions or constraints in a section. (Why: using bold as a scan path keeps pages skimmable.)
+
+- Use bold for a few critical words in a heading or paragraph, not whole sentences. If the paragraph still communicates the same information when bold is removed, prefer plain text and drop the bold. (Why: unnecessary bold increases noise without adding meaning.)
+
 - You **MUST NOT** bold entire sentences, paragraphs, or whole list items. If a label is needed, use a heading or an appropriate callout instead. (Why: large bold blocks create visual noise and duplicate heading semantics.) \[HIGH]
 
-- You **MUST NOT** use bold to style tokens, flags, filenames, or UI/log messages; use code font for tokens, quotation marks for log/error strings and UI text, and you **MAY** use `<kbd>` for UI/menu labels and key names. (Why: consistent, literal styling keeps examples copy‑pasteable, searchable, and accessible.) \[HIGH]
+- You **MUST NOT** use bold to style tokens, flags, filenames, or UI/log messages; use code font for tokens, quotation marks for log/error strings and UI text, and `<kbd>` for UI/menu labels and key names. (Why: consistent, literal styling keeps examples copy‑pasteable, searchable, and accessible.) \[HIGH]
 
 - Within a paragraph, you **SHOULD NOT** use more than one short bold span (≤ 3 words). Reserve it for rare emphasis that clarifies meaning, not for decoration. (Why: limiting emphasis keeps true highlights noticeable.)
 
-- Italics **MAY** be used for first‑mention term emphasis or titles of publications; avoid using italics for recurring emphasis in procedures. (Why: minimal, conventional italics aid comprehension without competing with steps.)
+##### Italics
+
+- Italics **MAY** be used for first‑mention term emphasis or titles of publications, books, papers, or standards. Avoid using italics for recurring emphasis in procedures. (Why: minimal, conventional italics aid comprehension without competing with steps.)
+
+- When introducing an important concept on a concept or explanation page and a glossary link is not attached, you **MAY** italicize the first meaningful mention to signal definition, then stop italicizing later mentions. (Why: one highlighted introduction is enough to draw attention without cluttering the scan path.)
+
+- Use italics for subtle emphasis that matters in sentence context but should not become a scan target. Use bold when the reader should find a word while scanning quickly. (Why: separating roles for bold and italics keeps both predictable.)
 
 - Link text **MUST NOT** be styled with bold or italics. Do not wrap links in emphasis (for example, `**[Foo](/foo)**`, `_ [Foo](/foo)_`) and do not put bold or italic markup inside the link label. When the link label is a code identifier, use inline code as the label (for example, ``[`foo_bar`](/ref/foo_bar)``). (Why: links are already visually distinct; extra emphasis adds noise and makes scanning harder.) \[HIGH]
 
+##### Styling workflow
+
+- Draft new pages in plain text with minimal styling. Focus on content and structure first; use headings, lists, and code blocks without worrying about emphasis. (Why: drafting plain keeps attention on information, not formatting.)
+
+- During editing, apply the bold and italics rules above: add emphasis only where it meaningfully improves scanning or clarity, and remove any emphasis that does not change what the reader learns. (Why: editing is the right time to tune emphasis.)
+
+- Apply the same minimal‑first approach to headings, `<Aside>` callouts, tables, and visual components such as `<Card>` or `<Image>`: if the content is clear without extra framing, prefer the simpler version. (Why: reducing decorative chrome makes structure and behavior stand out.)
+
 - Markdown delimiters: Italics **MUST** use a single underscore (`_emphasis_`); bold **MUST** use double asterisks (`**strong**`). **MUST NOT** use single asterisks for italics or double underscores for bold. (Why: consistent, formatter‑friendly delimiters reduce diff noise and ambiguity.)
 
 ### 6.3 Code styling
@@ -404,6 +432,7 @@ Objective. Keep text fast to read and effortless to scan. (Why: quick comprehens
 ### 8.1 Paragraphs and sentences
 
 - One idea per paragraph. Paragraphs **SHOULD** be ≤ 5 sentences; single‑sentence paragraphs are acceptable for emphasis. These are recommended norms, not hard caps—exceed only when clarity requires it. (Why: tight, focused paragraphs are easier to scan; short norms keep pages consistent without blocking necessary detail.)
+- Each sentence **SHOULD** convey one main idea. If a sentence starts to describe two distinct actions or conditions, split it into two sentences or convert the extra actions into a list. (Why: one‑idea sentences are easier to scan and translate; lists make multi‑step actions obvious.)
 - Sentences **SHOULD** average 15–20 words. Long, multi‑clause sentences **SHOULD** be split. Front‑load key points. (Why: mid‑length sentences reduce cognitive load; splitting prevents misreads; leading with the main point speeds understanding.)
 
 ### 8.2 Structure for scanning
@@ -551,15 +580,22 @@ A Caution or Warning **MUST** appear when a page or step: (Why: visible callouts
 - modifies validator configuration, networking, or consensus‑affecting parameters; (Why: misconfiguration can halt or fork nodes and degrade the network.) \[HIGH]
 - performs chain‑affecting operations (e.g., resharding, pruning, halting, replay). (Why: these actions can corrupt the state, reduce availability, or cause data loss.) \[HIGH]
 
+- On pages with many such steps, you **MAY** combine these into a page‑level safety summary plus short local callouts for individual commands instead of repeating full details every time. (Why: a shared summary avoids repetition while still making risks visible near each step.)
+
 ### 11.2 How to write the callout
 
-A safety callout **MUST** include: (Why: readers need to know the risk, scope, recovery, and safe environment before proceeding.) \[HIGH]
+A guide that contains safety‑critical steps **MUST** clearly communicate all of the following, either in a page‑level safety summary, in local callouts near each step, or in combination: (Why: readers need to know the risk, scope, recovery, and safe environment before proceeding.) \[HIGH]
 
 1. Risk (what can go wrong), (Why: sets severity and helps decide whether to proceed.)
 1. Scope (what the command affects), (Why: clarifies blast radius—single node, wallet, or network.)
-1. Rollback/mitigation steps, and (Why: gives a path to recovery or damage control.)
+1. Rollback/mitigation steps where feasible, and (Why: gives a path to recovery or damage control.)
 1. Environment label (testnet vs mainnet) with safer default instructions first. (Why: testnet reduces harm; explicit labels prevent accidental mainnet use.)
 
+Common patterns:
+
+- Page‑level safety summary. Place a single `<Aside>` near the top of the guide that describes overall risk, scope, rollback/mitigation strategy, and testnet/mainnet expectations for the full set of commands. (Why: one visible summary prevents readers from missing critical context.)
+- Local step‑level warnings. Add short `<Aside>` elements next to each hazardous step that call out the specific risk or environment for that step and, when needed, refer back to the page‑level summary instead of repeating full details (for example, “See the safety note at the top of this page before running this on mainnet.”). (Why: local notes tie the warning to the exact action without duplicating the whole summary.)
+
 Rendering (component) \[HIGH]
 
 - Safety callouts **MUST** use the `<Aside>` component; **MUST NOT** use Markdown blockquotes (`>`) or headings to simulate warnings. (Why: a single component keeps appearance, accessibility, and behavior consistent.)
@@ -779,7 +815,7 @@ Objective. Ensure content is usable by all readers and easy to localize. (Why: a
 - Long lists inside cells **SHOULD** be converted to bullet lists placed below the table. (Why: lists outside tables are easier to scan and navigate.)
 - Provide text alternatives for complex figures when feasible. (Why: alt or adjacent text lets screen‑reader users and translators access the content.)
 - Keyboard‑only navigation **SHOULD** be considered when adding interactive elements. (Why: some users cannot use a mouse; keyboard support is a basic accessibility need.)
-- Emojis **MAY** appear in compact tables as secondary indicators (e.g., `✅ Supported`, `❌ Not supported`) when paired with clear text in the same cell. **MUST NOT** rely on emojis alone to encode meaning or status. (Why: paired text remains accessible and understandable when emojis don’t render or in translation.)
+- Emojis **MAY** appear in compact tables as secondary indicators only when they follow a widely understood convention (e.g., `✅ Supported`, `❌ Not supported`) and are paired with clear text in the same cell. **MUST NOT** rely on emojis alone to encode meaning or status, and **MUST NOT** use decorative pictograms or one‑off icons that do not have a clear, conventional meaning. (Why: paired, conventional indicators remain accessible and understandable when emojis do not render or in translation.)
 
 ### 15.3 Localization readiness
 
@@ -870,6 +906,16 @@ Objective. Keep repository structure and UI labels consistent. (Why: predictable
 - If experimental, briefly state scope and limitations; link to the stable alternative when available. (Why: scope limits misuse and points to the dependable path.)
 - Status labels (experimental/deprecated) are independent of safety callouts (see [§11](#11-safety-critical-content-blockchain-specific)). Apply both when applicable. (Why: status communicates lifecycle; safety communicates risk—readers need both.)
 
+### 16.6 Components used in content
+
+- New content **MUST NOT** introduce `<Card>` components on normal documentation pages; prefer headings, lists, and links for navigation and structure. (Why: cards add visual chrome that is rarely needed for comprehension.)
+
+- Existing `<Card>` usages **SHOULD** be treated as style exceptions and either removed over time or confined to top‑level index pages where the card layout directly improves navigation. Any remaining usage **SHOULD** be documented as an explicit exception with scope, owner, and review date per [§18](#18-style-exceptions-and-edge-cases). (Why: limiting exceptions keeps the overall style consistent and maintainable.)
+
+- When an index‑style page genuinely needs card‑like tiles, you **MAY** use `<Card>` as a documented exception; keep the content inside each card minimal and avoid duplicating information from the linked pages. (Why: cards should support navigation, not introduce a second layer of prose.)
+
+- More generally, follow the “minimal styling” workflow from [§6.2](#62-quotation-marks-and-emphasis): components such as `<Card>`, `<Aside>`, `<Image>`, or tab containers **SHOULD** appear only when they improve comprehension or navigation, not as decoration. (Why: reduced decorative chrome makes structure and behavior stand out.)
+
 ## 17. Content hygiene and timeless writing
 
 Objective. Reduce staleness, duplication, and maintenance costs. (Why: fresh, non‑duplicated content is cheaper to maintain and more trustworthy for readers.)
@@ -918,6 +964,8 @@ Use the least severe callout that communicates the point; overuse reduces impact
 
 Implementation. Render callouts with the `<Aside>` component (see `/snippets/aside.mdx`). **MUST NOT** use Markdown blockquotes (`>`) to simulate callouts. The only supported `type` values are `note`, `tip`, `caution`, and `danger`. Map levels to types: Note → `type="note"`; Tip → `type="tip"`; Caution → `type="caution"`; Warning → `type="danger"`. Use `title` to set the visible label when needed (e.g., `title="Important"`). (Why: consistent components and a fixed type set keep callouts accessible and visually coherent.) \[HIGH]
 
+- On pages with multiple hazardous actions, combine a page‑level safety `<Aside>` at the top (describing overall risk, scope, rollback/mitigation where feasible, and environment) with short local `<Aside>` elements near each dangerous step that can refer back to the summary instead of repeating it. (Why: the combination keeps risks visible without duplicating long warnings at every step.)
+
 | Level     | When to use                                              | MUST include                                    |
 | --------- | -------------------------------------------------------- | ----------------------------------------------- |
 | Note      | Auxiliary info or minor edge cases                       | Short, actionable text only                     |
@@ -939,6 +987,9 @@ Examples
 - Warning — funds at risk
   “Transfers on mainnet are final.”
 
+- Warning — page with many risky steps
+  “Read the safety note at the top of this page before running any mainnet commands.”
+
 (Admonition usage aligns with the safety requirements in [§11](#11-safety-critical-content-blockchain-specific).)
 
 ### B. Banned and preferred terms
diff --git a/contribute/style-guide.mdx b/contribute/style-guide.mdx
index dfa738b0e..731897d5b 100644
--- a/contribute/style-guide.mdx
+++ b/contribute/style-guide.mdx
@@ -12,6 +12,10 @@ This guide covers the basics: how to structure pages, write examples, and keep d
 - Lead with a working example. Show a copy‑pasteable snippet early and the expected output. This shows it works.
 - Use a neutral, precise tone. Write in the present tense, active voice, and second person (“Run the node”). This makes actions clear.
 - Keep it scannable. Use short sections and paragraphs, clear headings, lists, and tables. Most readers skim to find the next action.
+- Aim for one main idea per sentence. Split long, multi‑clause sentences or turn them into lists.
+- Use bold only for a few scan‑worthy words in a paragraph, not full sentences or tokens. If a skimming reader loses nothing when the bold is removed, drop it.
+- Use italics for new or defined terms and subtle emphasis; use bold for words a skimming reader should find quickly.
+- Draft in plain text first. During editing, add minimal emphasis and remove any styling that does not change meaning.
 
 ## Page types
 
@@ -43,6 +47,7 @@ This guide covers the basics: how to structure pages, write examples, and keep d
 - Prefer end‑to‑end examples on testnet by default. Safe defaults encourage trying the steps.
 - Label partial snippets as Not runnable and link to a complete example.
 - Do not hard‑wrap long commands. Use soft wrap in the UI or safe continuation if the shell supports it. Hard wraps break execution.
+- For UI buttons, menu items, and key names, wrap the label in `<kbd>…</kbd>` instead of quotes or bold. This keeps controls easy to spot and consistent with the main style guide.
 
 Good
 
@@ -64,6 +69,8 @@ Define placeholders
 
 Add a Caution or Warning when a step moves funds, changes fees or withdrawals, exposes or stores private keys or mnemonics, modifies validator or network settings, or performs chain‑affecting operations such as resharding, pruning, halting, or replay. These actions can cause irreversible loss or outages.
 
+On long guides with many risky commands, combine a clear page‑level warning at the top (covering risk, scope, rollback where feasible, and environment) with short local notes next to each critical step. Local notes can be brief if they point back to the main warning.
+
 Pattern
 
 > Warning — funds at risk
@@ -89,7 +96,7 @@ Add a Caution or Warning when a page or step:
 - Uses destructive flags or commands that delete, rewrite, or lock state (for example, `--purge`, `--force`).
 - Runs on mainnet, where actions are irreversible; label the environment and give the safer testnet first.
 
-Each safety callout should briefly state the risk, scope, rollback/recovery (if any), and the environment label (testnet vs mainnet).
+Make sure the guide as a whole clearly covers the risk, scope, rollback or mitigation (where feasible), and the environment label (testnet vs mainnet). For a single hazardous step, put these points directly in its callout. On long risky guides, put a big safety callout at the top and keep step‑level notes short, pointing back to that summary.
 
 ## Titles and headings
 
@@ -133,6 +140,7 @@ Each safety callout should briefly state the risk, scope, rollback/recovery (if
 - Write descriptive headings and link text.
 - Tables should have headers and units (for example, “Latency (ms)”) and keep cells brief.
 - Provide text alternatives for complex figures when possible.
+- Avoid emojis. Only use them where they follow a common convention (for example, `✅ Supported`, `❌ Not supported`) and always pair them with text.
 
 ## Secrets and environments
 

From 572db220643b9d39edf4b10c9db21b25d8fd59be Mon Sep 17 00:00:00 2001
From: Gusarich <danielsedovzzz@gmail.com>
Date: Mon, 24 Nov 2025 12:31:42 +0300
Subject: [PATCH 2/5] fixes

---
 contribute/style-guide-extended.mdx | 26 ++++++--------------------
 1 file changed, 6 insertions(+), 20 deletions(-)

diff --git a/contribute/style-guide-extended.mdx b/contribute/style-guide-extended.mdx
index beb9fc5d3..b37464b38 100644
--- a/contribute/style-guide-extended.mdx
+++ b/contribute/style-guide-extended.mdx
@@ -269,8 +269,6 @@ See also: [Appendix B](#b-banned-and-preferred-terms) lists additional banned in
 
 - Where a parenthetical is necessary for precision, keep it short and avoid chaining more than one set of parentheses in the same sentence. (Why: multiple nested asides make sentences hard to read.)
 
-- This rule applies to TON documentation pages. This style guide itself **MAY** use parentheses more freely when explaining rules and rationale. (Why: meta‑documentation sometimes needs extra commentary that would be distracting in task pages.)
-
 ## 6. Punctuation and mechanics
 
 Objective. Remove ambiguity and increase scan speed with consistent mechanics. (Why: predictable punctuation choices make sentences easier to parse and reduce misreads.)
@@ -336,16 +334,6 @@ Objective. Remove ambiguity and increase scan speed with consistent mechanics. (
 
 - Link text **MUST NOT** be styled with bold or italics. Do not wrap links in emphasis (for example, `**[Foo](/foo)**`, `_ [Foo](/foo)_`) and do not put bold or italic markup inside the link label. When the link label is a code identifier, use inline code as the label (for example, ``[`foo_bar`](/ref/foo_bar)``). (Why: links are already visually distinct; extra emphasis adds noise and makes scanning harder.) \[HIGH]
 
-##### Styling workflow
-
-- Draft new pages in plain text with minimal styling. Focus on content and structure first; use headings, lists, and code blocks without worrying about emphasis. (Why: drafting plain keeps attention on information, not formatting.)
-
-- During editing, apply the bold and italics rules above: add emphasis only where it meaningfully improves scanning or clarity, and remove any emphasis that does not change what the reader learns. (Why: editing is the right time to tune emphasis.)
-
-- Apply the same minimal‑first approach to headings, `<Aside>` callouts, tables, and visual components such as `<Card>` or `<Image>`: if the content is clear without extra framing, prefer the simpler version. (Why: reducing decorative chrome makes structure and behavior stand out.)
-
-- Markdown delimiters: Italics **MUST** use a single underscore (`_emphasis_`); bold **MUST** use double asterisks (`**strong**`). **MUST NOT** use single asterisks for italics or double underscores for bold. (Why: consistent, formatter‑friendly delimiters reduce diff noise and ambiguity.)
-
 ### 6.3 Code styling
 
 - Code, filenames, paths, API endpoints, flags, and literals **MUST** use code formatting (inline backticks or fenced blocks). **MUST NOT** add punctuation inside code that isn’t part of the code. (Why: visual separation prevents misreading and keeps examples copy‑pasteable without edits.) \[HIGH]
@@ -591,6 +579,8 @@ A guide that contains safety‑critical steps **MUST** clearly communicate all o
 1. Rollback/mitigation steps where feasible, and (Why: gives a path to recovery or damage control.)
 1. Environment label (testnet vs mainnet) with safer default instructions first. (Why: testnet reduces harm; explicit labels prevent accidental mainnet use.)
 
+- These elements describe the information the reader needs; they are **NOT** required as literal labels such as “Risk:” or “Scope:”. Safety callouts **SHOULD** read as concise, natural prose rather than templated checklists. (Why: natural language is easier to read and avoids robotic, placeholder‑style warnings.)
+
 Common patterns:
 
 - Page‑level safety summary. Place a single `<Aside>` near the top of the guide that describes overall risk, scope, rollback/mitigation strategy, and testnet/mainnet expectations for the full set of commands. (Why: one visible summary prevents readers from missing critical context.)
@@ -608,15 +598,11 @@ Example (MDX)
 import { Aside } from '/snippets/aside.jsx';
 
 <Aside type="danger" title="Funds at risk">
-  Running the following command on mainnet transfers funds irreversibly.
-
-  Do first (testnet):
+  Sending TON on mainnet is irreversible. Start with a small transfer on TON Testnet, then repeat on TON Mainnet only after checking the address and network carefully; there is no rollback on mainnet.
 
   ```bash
   jetton transfer --to <ADDR> --amount <AMOUNT> --network testnet
   ```
-
-  If you must use mainnet: There is no rollback. On‑chain transfers are irreversible.
 </Aside>
 ````
 
@@ -908,11 +894,11 @@ Objective. Keep repository structure and UI labels consistent. (Why: predictable
 
 ### 16.6 Components used in content
 
-- New content **MUST NOT** introduce `<Card>` components on normal documentation pages; prefer headings, lists, and links for navigation and structure. (Why: cards add visual chrome that is rarely needed for comprehension.)
+- On normal documentation pages, **SHOULD NOT** use `<Card>` components; prefer headings, lists, and inline links for navigation and structure. (Why: cards add visual chrome that is rarely needed for comprehension.)
 
-- Existing `<Card>` usages **SHOULD** be treated as style exceptions and either removed over time or confined to top‑level index pages where the card layout directly improves navigation. Any remaining usage **SHOULD** be documented as an explicit exception with scope, owner, and review date per [§18](#18-style-exceptions-and-edge-cases). (Why: limiting exceptions keeps the overall style consistent and maintainable.)
+- Existing `<Card>` usages **SHOULD** be confined to top‑level index or overview pages where the card layout clearly improves navigation. Over time, simplify or remove cards that do not provide a clear navigation benefit. (Why: keeping cards to a few deliberate entry pages avoids fragmenting the visual style.)
 
-- When an index‑style page genuinely needs card‑like tiles, you **MAY** use `<Card>` as a documented exception; keep the content inside each card minimal and avoid duplicating information from the linked pages. (Why: cards should support navigation, not introduce a second layer of prose.)
+- When an index‑style page genuinely needs card‑like tiles, you **MAY** use `<Card>`; keep the content inside each card minimal and avoid duplicating information from the linked pages. (Why: cards should support navigation, not introduce a second layer of prose.)
 
 - More generally, follow the “minimal styling” workflow from [§6.2](#62-quotation-marks-and-emphasis): components such as `<Card>`, `<Aside>`, `<Image>`, or tab containers **SHOULD** appear only when they improve comprehension or navigation, not as decoration. (Why: reduced decorative chrome makes structure and behavior stand out.)
 

From 26b54f75439107e0f01a84ada3e4a7a47986678d Mon Sep 17 00:00:00 2001
From: Gusarich <danielsedovzzz@gmail.com>
Date: Mon, 24 Nov 2025 17:12:58 +0300
Subject: [PATCH 3/5] fix: formatting

---
 contribute/style-guide-extended.mdx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/contribute/style-guide-extended.mdx b/contribute/style-guide-extended.mdx
index b37464b38..6e7b6c71f 100644
--- a/contribute/style-guide-extended.mdx
+++ b/contribute/style-guide-extended.mdx
@@ -564,8 +564,11 @@ Objective. Prevent reader harm when funds, keys, or validator/network state are
 A Caution or Warning **MUST** appear when a page or step: (Why: visible callouts make risk obvious before a reader runs a command.) \[HIGH]
 
 - moves funds or changes fee/withdrawal behavior; (Why: users can lose money or block withdrawals.) \[HIGH]
+
 - exposes, stores, or transmits private keys/mnemonics; (Why: leaked secrets allow account takeover and theft.) \[HIGH]
+
 - modifies validator configuration, networking, or consensus‑affecting parameters; (Why: misconfiguration can halt or fork nodes and degrade the network.) \[HIGH]
+
 - performs chain‑affecting operations (e.g., resharding, pruning, halting, replay). (Why: these actions can corrupt the state, reduce availability, or cause data loss.) \[HIGH]
 
 - On pages with many such steps, you **MAY** combine these into a page‑level safety summary plus short local callouts for individual commands instead of repeating full details every time. (Why: a shared summary avoids repetition while still making risks visible near each step.)

From b9629b65a52b81ad4535ff0d5af3250b0db1318b Mon Sep 17 00:00:00 2001
From: Gusarich <danielsedovzzz@gmail.com>
Date: Mon, 24 Nov 2025 20:05:04 +0300
Subject: [PATCH 4/5] fix

---
 contribute/style-guide-extended.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contribute/style-guide-extended.mdx b/contribute/style-guide-extended.mdx
index 6e7b6c71f..57bf4b652 100644
--- a/contribute/style-guide-extended.mdx
+++ b/contribute/style-guide-extended.mdx
@@ -314,7 +314,7 @@ Objective. Remove ambiguity and increase scan speed with consistent mechanics. (
 
 ##### Bold
 
-- Bold **SHOULD** mark scan points: a skimming reader should be able to bounce between bolded words and still understand the key actions or constraints in a section. (Why: using bold as a scan path keeps pages skimmable.)
+- Bold **SHOULD** mark scan points: a skimming reader should be able to bounce between bolded words and still understand the key actions or constraints in a section. (Why: using bold as a scan path keeps pages easy to scan.)
 
 - Use bold for a few critical words in a heading or paragraph, not whole sentences. If the paragraph still communicates the same information when bold is removed, prefer plain text and drop the bold. (Why: unnecessary bold increases noise without adding meaning.)
 

From 291b041f2b21549b293e4dc9b08547a422e44606 Mon Sep 17 00:00:00 2001
From: Gusarich <danielsedovzzz@gmail.com>
Date: Tue, 25 Nov 2025 20:58:48 +0300
Subject: [PATCH 5/5] fixes

---
 contribute/style-guide-extended.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/contribute/style-guide-extended.mdx b/contribute/style-guide-extended.mdx
index 57bf4b652..61244b032 100644
--- a/contribute/style-guide-extended.mdx
+++ b/contribute/style-guide-extended.mdx
@@ -326,7 +326,7 @@ Objective. Remove ambiguity and increase scan speed with consistent mechanics. (
 
 ##### Italics
 
-- Italics **MAY** be used for first‑mention term emphasis or titles of publications, books, papers, or standards. Avoid using italics for recurring emphasis in procedures. (Why: minimal, conventional italics aid comprehension without competing with steps.)
+- Italics **MAY** be used for first‑mention term emphasis or titles of publications, books, papers, or standards. Avoid using italics for recurring emphasis in procedures. (Why: minimal, conventional italics aid comprehension.)
 
 - When introducing an important concept on a concept or explanation page and a glossary link is not attached, you **MAY** italicize the first meaningful mention to signal definition, then stop italicizing later mentions. (Why: one highlighted introduction is enough to draw attention without cluttering the scan path.)
 
@@ -571,11 +571,11 @@ A Caution or Warning **MUST** appear when a page or step: (Why: visible callouts
 
 - performs chain‑affecting operations (e.g., resharding, pruning, halting, replay). (Why: these actions can corrupt the state, reduce availability, or cause data loss.) \[HIGH]
 
-- On pages with many such steps, you **MAY** combine these into a page‑level safety summary plus short local callouts for individual commands instead of repeating full details every time. (Why: a shared summary avoids repetition while still making risks visible near each step.)
+If page has many actions potentially requiring a safety callout, you **MAY** combine these into a page‑level safety summary plus short local callouts instead of repeating full details every time. (Why: a shared summary avoids repetition while still making risks visible.)
 
 ### 11.2 How to write the callout
 
-A guide that contains safety‑critical steps **MUST** clearly communicate all of the following, either in a page‑level safety summary, in local callouts near each step, or in combination: (Why: readers need to know the risk, scope, recovery, and safe environment before proceeding.) \[HIGH]
+A page that contains safety-critical actions **MUST** clearly communicate all of the following, either in a page‑level safety summary, in local callouts near each step, or in combination: (Why: readers need to know the risk, scope, recovery, and safe environment before proceeding.) \[HIGH]
 
 1. Risk (what can go wrong), (Why: sets severity and helps decide whether to proceed.)
 1. Scope (what the command affects), (Why: clarifies blast radius—single node, wallet, or network.)