docs: point design standards references at the index, and retire the prose rules it now carries (#7165)

This commit is contained in:
James Rich authored and GitHub committed 2026-09-15 11:25:25 +00:00
1 parent e353898b94
commit 1cdb3eb127
5 files changed
+53 -18

No files matched your search

+1 -1
View File
@@ -4,7 +4,7 @@
Android-specific guidance for applying the Meshtastic design standards. All visual rules, color palettes, accessibility requirements, and cross-platform conventions live upstream.
> **Source of truth:** [`meshtastic/design/standards/`](https://github.com/meshtastic/design/tree/master/standards)
> Read `meshtastic_design_standards_latest.md` (a pointer to the current versioned spec — `meshtastic_design_standards_v1_4.md` at time of writing) for the full spec (colors, M3 mapping, accessibility, units/locale, agent checklist).
> That index names the current version; open it from there for the full spec (colors, M3 mapping, accessibility, units/locale, agent checklist). Don't fetch `meshtastic_design_standards_latest.md` over HTTP — it is a symlink, and GitHub returns its target's filename, 35 bytes, with HTTP 200.
> If this skill diverges from upstream, **upstream wins**.
## 1. How to Use the Standards
+1 -1
View File
@@ -108,7 +108,7 @@ specs/
The project constitution at `.specify/memory/constitution.md` defines non-negotiable principles.
All specs, plans, and tasks are validated against it during `/speckit.analyze`.
Current constitution (v1.3.6) enforces 7 principles:
Current constitution (v1.4.0) enforces 7 principles:
1. **KMP Core** — Business logic in `commonMain` only
2. **Zero Lint Tolerance**`spotlessCheck` + `detekt` must pass
+30 -3
View File
@@ -1,4 +1,27 @@
<!--
SYNC IMPACT REPORT
==================
Version change: 1.3.7 → 1.4.0
Modified principles:
- V. Design Standards Compliance: the canonical reference is now the standards
index (github.com/meshtastic/design/tree/master/standards) rather than the raw
URL for meshtastic_design_standards_latest.md, which returns 35 bytes with HTTP
200 because GitHub serves a symlink as its target's filename.
Adds a requirement: contributors and agents MUST NOT fetch that symlink over
HTTP. MINOR rather than PATCH because a new prohibition is materially expanded
guidance, not a clarification.
Added sections: none
Removed sections: none
Templates requiring updates:
- .specify/templates/spec-template.md ✅ updated (same raw URL in the UI checklist)
- .specify/templates/plan-template.md ✅ no reference
- .specify/templates/tasks-template.md ✅ no reference
- .specify/templates/checklist-template.md ✅ no change (CHK005 names no URL)
Downstream references (Amendment Procedure step 3):
- .skills/speckit/SKILL.md ✅ updated (declared constitution version)
- AGENTS.md ✅ no change (names no URL; principle count still 7)
Follow-up TODOs: none
SYNC IMPACT REPORT
==================
Version change: 1.3.5 → 1.3.6
@@ -123,8 +146,12 @@ times:
All user-facing UI MUST conform to the Meshtastic Client Design Standards:
- The canonical reference lives at:
`https://raw.githubusercontent.com/meshtastic/design/refs/heads/master/standards/meshtastic_design_standards_latest.md`
- The canonical reference is the standards index, which always names the current
version: <https://github.com/meshtastic/design/tree/master/standards>
- Contributors and agents MUST NOT fetch
`meshtastic_design_standards_latest.md` over HTTP. It is a symlink, and GitHub
serves a symlink as its target's filename, so the blob and raw views return 35
bytes with HTTP 200 and no error.
- New screens and significant UI changes (any screen with ≥3 composables or a new
navigation destination) MUST be reviewed against the design standards before merge.
- Deviations from the design standards require explicit justification in the PR description
@@ -263,4 +290,4 @@ summary derived from this constitution. The files `.github/copilot-instructions.
Constitution Check confirming all seven principles were evaluated. Complexity violations
require explicit justification in the Complexity Tracking table of the plan document.
**Version**: 1.3.6 | **Ratified**: 2026-05-07 | **Last Amended**: 2026-08-30
**Version**: 1.4.0 | **Ratified**: 2026-05-07 | **Last Amended**: 2026-09-15
+1 -1
View File
@@ -158,7 +158,7 @@
deviations with rationale.
-->
- [ ] New screens reviewed against [design standards](https://raw.githubusercontent.com/meshtastic/design/refs/heads/master/standards/meshtastic_design_standards_latest.md)
- [ ] New screens reviewed against [design standards](https://github.com/meshtastic/design/tree/master/standards)
- [ ] M3 component selection verified (e.g., `SwitchPreference` not raw `Switch`)
- [ ] Accessibility: TalkBack semantics, touch targets, color-independent info
- [ ] Typography: `titleMediumEmphasized` for emphasis, M3 scale for hierarchy
+20 -12
View File
@@ -2,8 +2,8 @@
title: Documentation Style
parent: Developer Guide
nav_order: 11
last_updated: 2026-09-10
description: How this repository's docs work, and the few prose rules the Meshtastic design standards leave to us.
last_updated: 2026-09-14
description: How this repository's docs work, and the one prose rule the Meshtastic design standards leave to us.
aliases:
- style
- style-guide
@@ -13,9 +13,9 @@ aliases:
# Documentation Style
Section 11 of the [Meshtastic Client Design Standards](https://github.com/meshtastic/design/blob/master/standards/meshtastic_design_standards_v1_5.md) is the style guide for everything under `docs/en/`. Read it first. It decides voice, plain language, terminology, page structure, instructions, cross-platform coverage, code and CLI examples, media, accessibility, admonition use, units, translation, versioning, and in-product text, and it closes with a checklist of the rules a reviewer can check without judgment.
Section 11 of the [Meshtastic Client Design Standards](https://github.com/meshtastic/design/tree/master/standards) is the style guide for everything under `docs/en/`. Read it first. It decides voice, plain language, terminology, page structure, instructions, cross-platform coverage, code and CLI examples, media, accessibility, admonition use, units, translation, versioning, and in-product text, and it closes with a checklist of the rules a reviewer can check without judgment.
This page carries what Section 11 doesn't: how documentation works in this repository, two forms that differ here, and a handful of prose rules the standards leave open. Where the two ever disagree on something not listed here, Section 11 wins and this page is wrong.
This page carries what Section 11 doesn't: how documentation works in this repository, two forms that differ here, and the one prose rule the standards leave open. Where the two ever disagree on something not listed here, Section 11 wins and this page is wrong.
Pages under `docs/en/` ship to three places — the in-app docs browser, the GitHub Pages site, and meshtastic.org — so one page has to read well in all of them, and its English source is the translation base for 40+ locales on Crowdin. Section 11.1 describes the sync: user pages land in `docs/software/android/` on the documentation site weekly, taken from the latest release, and pull requests against those paths there are reverted.
@@ -64,14 +64,22 @@ Two forms differ from Section 11. The first is a renderer requirement. The secon
## Prose rules Section 11 leaves open
- **VOICE-2** — Contractions are house voice (*you'll*, *doesn't*, *it's*) — but in warnings, write *do not*: negative contractions are too easy to misread when the cost of misreading is data loss.
- **LANG-1** — American English spelling: *color*, *behavior*, *honors*, *gray*, *organize*.
- **LANG-3** — Requirement words carry exact weight: *must* (obligation), *must not* (prohibition), *should* (recommendation), *can* (capability), *may* (permission). Never *shall*.
- **LANG-4** — Prefer *for example* and *such as* over *e.g.*, and *that is* over *i.e.*, in running prose. Inside table cells and parentheses, *e.g.* is acceptable where space is tight.
- **LANG-6** — Inclusive, literal language: *allowlist*/*blocklist*, singular *they*, no ableist idioms (*final check*, not *sanity check*), no violent metaphors (*the app stops responding*, not *hangs*).
- **LANG-7** — Oxford comma (*Android, iOS, and Windows*). Em dashes are spaced — like this — matching the entire existing corpus.
- **LANG-8** — Spell out zero through nine in prose; numerals for 10 and up, for all measurements and units (*3 dB*, *915 MHz*), for values the reader enters, and with `%`. Dates follow 11.12.
- **LANG-9** — Don't use *above* and *below* to point at other text — say *earlier*, *the following*, or link to the section. (Literal technical use is fine: *below the noise floor*.)
One rule. [design#154](https://github.com/meshtastic/design/pull/154) moved the rest into Section 11, where they read the same, so nothing about how you write changes — the rules have one home rather than two that can drift apart.
- **LANG-7** — Em dashes are spaced — like this — matching the entire existing corpus. Section 11 doesn't mention them.
These are retired, with the section that owns each. Their IDs aren't reused.
| Retired rule | Section |
|---|---|
| VOICE-2 — contractions, and *do not* in warnings | 11.2 |
| LANG-3 — requirement words | 11.3 |
| LANG-4 — *e.g.* and *i.e.* | 11.3 |
| LANG-6 — inclusive, literal language | 11.3 |
| LANG-7 — the Oxford comma half; the em dash stays | 11.3 |
| LANG-1 — American spelling | 11.4 |
| LANG-9 — *above* and *below* | 11.5 |
| LANG-8 — number style | 11.12 |
## Word list