diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c6e9c8..d14b9f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,7 @@ Entries are newest-first. Dates are UTC, ISO 8601 (§14). Versioning policy: bum for upstream skill changes, registry updates (§2.1, §15.1), factual corrections to normative content, and brand/identity changes. +- **v1.42 (2026-08-05):** **§13 corrected — a component system per platform, not one for every platform.** §13 required **Material Design** as "the required component system for all graphical applications," a rule written when the graphical surface in scope was Flutter and web. It has been unsatisfiable for native desktop since the day it was written: **GTK 4** ships Adwaita and the GNOME HIG, **Qt 6** ships Fusion and the KDE HIG, and neither has a Material component set to theme — so a GTK or Qt application could not pass the §16 audit gate no matter how it was built, and the only honest options were a permanent filed deviation or an application that matches neither its own toolkit nor Material. Worse, imposing a foreign component system on a native toolkit fights exactly the platform integration §18 depends on: the accessibility bridge, the window manager, the system high-contrast and reduced-motion preferences, and the settings portal are all wired to the toolkit's own vocabulary. §13 is accordingly rewritten around the requirement that actually carries the intent — **every graphical application declares exactly one component system, in its `README.md` beside the §5.2 posture section, and follows it consistently** — with the system determined by the platform rather than by preference: **Material Design** for Flutter, web, mobile, and cross-platform GUI, and for custom-drawn or immediate-mode UI that declares no platform HIG; **GNOME HIG** via libadwaita for GTK 4; **KDE HIG** via Qt Quick Controls or Fusion for Qt 6. Material Design remains the default wherever the platform supplies no system of its own, so nothing that was compliant under v1.41 becomes non-compliant here — the clause is narrowed, never widened. Three things are explicitly unchanged: **§11 binding is unconditional** — whichever system is declared, every palette reference still goes through the named `steelbore` theme (§11.1), because a component system chooses the widget vocabulary and never supplies the colors; **WCAG 2.2 Level AA** remains the contrast floor with the measured pairing stated; and **§18 still governs wherever the two overlap**. The §16 checklist bullet is rewritten from "Material Design UI/UX" to the declare-and-follow form naming all three systems, and the Skill Cross-References table gains `spacecraft-gtk-guidelines` and `spacecraft-qt-guidelines` rows — the two skills that implement this section for the native-desktop toolkits. Both are Rust-first under §3.1 (`gtk-rs` for GTK, CXX-Qt for Qt), so choosing a native desktop toolkit does not become a route around the memory-safe-language preference. - **v1.41 (2026-08-04):** **§3.1.1 added — TypeScript over JavaScript.** §3.1 named Rust as the preferred language and prescribed ASLR+CFI where Rust is not viable, but it had nothing to say about the one runtime where that framing does not apply: JavaScript is already memory-safe, so the memory-safety lever is inert, and the section fell silent exactly where a stability rule was still needed. §3.1.1 supplies it — **type safety is the Priority 1 lever on this runtime**. Where a memory-safe alternative exists (Rust to WebAssembly, Rust or Go on a server, Flutter/Dart for a UI) §3.1 still chooses it; where the JavaScript runtime is genuinely required — a browser page, a Node/Deno/Bun program, an Electron app, an npm-distributed tool, a VS Code extension — the **source language MUST be TypeScript**, and plain JavaScript source becomes a documented exemption rather than a default. Six requirements attach: `"strict": true` plus `noUncheckedIndexedAccess`, `noImplicitOverride`, and `exactOptionalPropertyTypes` (relaxing `strict` is a Priority 1 regression); no `any` and no non-null `!` in production paths (use `unknown` and narrow); `@ts-ignore` prohibited outright in favor of `@ts-expect-error` with a stated reason, which fails the build once the suppression stops being needed; **run-time validation at every trust boundary**, since a type annotation is a compile-time claim and asserting an unverified shape is the silent-failure mode §3.1 already forbids; **`tsc --noEmit` gating CI**, because esbuild, SWC, and Bun strip types without checking them, and a project that only transpiles has not satisfied this section; and loading `spacecraft-typescript-guidelines` before writing or reviewing TypeScript. Emitted `.js` and source maps in a build directory are derived artifacts and out of scope — the rule governs what is authored and committed. Three narrow cases need no filing: a tool's own configuration file that must be `.js` (e.g. `eslint.config.js` where no TypeScript loader exists), a vendored or upstream-derived file carried under §4.2, and generated output. Everything else — including "it is only a small script" — requires a documented technical exemption, on the same footing as the §3.1 memory-safe-language exemption. §16 gains a checklist bullet; the skill cross-reference table gains a TypeScript row. - **v1.40 (2026-07-27):** **Two gaps closed: where work may be sent, and what must be measured before a skill is packed.** **§6.4 added — Authorized Contribution Targets (Non-Negotiable).** §6.3 has always said how a commit must be signed on "a Spacecraft Software-controlled Git remote" without ever defining that set, so nothing in the standard stopped a script, a CI job, or an assistant-driven session from pushing a branch or opening a pull request against a third-party repository. §6.4 names the authorized namespaces — `github.com/Spacecraft-Software` and `github.com/UnbreakableMJ`, with a future Spacecraft Software-controlled host (Gitway) inheriting the same standing — and makes every other destination **outbound** and **default-deny**: silence is a denial, not permission. **Automation never initiates** an outbound contribution, and authorization for one does not carry to the next task, session, or repository; only Mohamed Hammad, acting explicitly and per contribution, may authorize one (§5.4). The rule is not git-only — publishing to a package registry under a namespace Spacecraft Software does not control (`crates.io`, npm, PyPI, AUR, Nixpkgs, Guix, Flathub) and filing issues or patches on an external tracker or mailing list are outbound under the same rule. **Forks stay free**: a fork under an authorized namespace may be created and pushed to at will, because that is our namespace — turning a fork branch into an upstream PR is the gated act. Where an upstream change is needed, §4.2's carry-the-patch-in-tree route is preferred to upstreaming. The free-software/GNU posture (§1) yields the identity clauses (§2, §11–§12, §15) but **not** this one: sending anything to GNU, the FSF, or Savannah still needs explicit authorization. An unauthorized submission MUST be withdrawn as soon as it is discovered, and recorded. **§5.6 added — Skill Packaging Requirements.** Skills are software-class artifacts (§4.1.1) whose loader limits are only discovered at install time, after the packing work is done: a `SKILL.md` frontmatter `description` over **1024** characters is rejected on load. §5.6 caps it at **1000 rendered characters** — a deliberate 24-character margin — and pins down *rendered*: a YAML folded scalar (`description: >`) joins its wrapped lines with single spaces and keeps a trailing newline, so raw line lengths are not the measurement, and block (`>`/`|`) and single-line plain or quoted forms alike are counted after folding. The cap MUST be **machine-enforced** in two places — the skill repository's CI on every pull request and push to the default branch, *and* the command that produces the distributable bundle. A developer-installed git hook is a convenience, never the gate: hooks are opt-in per clone. An over-limit skill MUST NOT be packed, committed, or published; trim the description rather than raise the cap. §16 gains a checklist bullet for each section. - **v1.39 (2026-07-26):** **Three external palettes registered, and a new class for the two that cannot conform.** **§11.3.5 added — Tokyo Night**, taken verbatim from the upstream editor theme (canvas Night `#1A1B26`, `surface` the documented Storm background `#24283B`, `surface-alt` the Night `bg_dark` `#16161E`, which sits darker than the canvas as §11.0.1 permits). It needed no Spacecraft-derived substitutes: every role token clears 4.5:1 on all three backgrounds — accent `#7AA2F7` 6.79:1, structure `#BB9AF7` 7.39:1, success `#9ECE6A` 9.35:1, error `#F7768E` 6.46:1, warning `#E0AF68` 8.55:1, focus `#7DCFFF` 9.96:1 — so it is registered as a conforming alternate, with `tokyonight-high-contrast` lifting the two tokens below 7:1 on the canvas (`accent` → `#97B6F9` 8.44:1, `error` → `#F998AA` 8.22:1). The upstream comment tone `#565F89` (2.76:1) is recorded as not bindable to any role token. **§11.5 added — Fidelity Palettes (registered, non-conforming):** a new class for palettes reproduced exactly from a widely used external theme so tooling can meet a user already working in it. **Solarized Dark (§11.5.1) and Solarized Light (§11.5.2)** are registered verbatim from Ethan Schoonover's Solarized — no token substituted, deepened, or lifted to make a number pass — and they **do not** satisfy §11's contrast guarantee. Solarized Dark: body text `base0` 4.75:1 on the canvas, twelve pairings below 4.5:1, and `structure`/`border` (2.97:1) and `error` (2.81:1) below 3:1 on `base02`. Solarized Light is worse: body text `base00` measures **4.13:1, under the AA floor**, and `success` (2.97:1), `warning` (2.98:1), and `focus` (2.93:1) fall below 3:1, so an interface built on it cannot signal status by color at all. §11.5 therefore bars adopting a fidelity palette as a project's §11.4 palette, keeps `steelbore-mono` as the accessible-mode path, and ships no `-high-contrast` sibling for them (lifting would change the values they exist to reproduce); † and ‡ mark the two failure bands throughout. Solarized defines one elevated tone per mode, so `surface-alt` shares `surface`. **§11.4.1 added — Reference Names:** every palette gains an additive reference name for prose (`steelbore-color-palette`, `steelboreclassic-color-palette`, `blue-color-palette`, `blackpinkpanther-color-palette`, `matrixgreen-color-palette`, `navywhite-color-palette`, `tokyonight-color-palette`, `solarizeddark-color-palette`, `solarizedlight-color-palette`). Slugs are unchanged and remain the machine identifier, so no consumer breaks. **§11.4** gains bullets for both additions. diff --git a/The_Steelbore_Standard.md b/The_Steelbore_Standard.md index 853e5fa..9d53e96 100644 --- a/The_Steelbore_Standard.md +++ b/The_Steelbore_Standard.md @@ -29,7 +29,7 @@ repository](https://github.com/Spacecraft-Software/Standard), newest entry first. It is kept out of this document so the standard reads as the rules *in force* rather than the record of how they got there. -This document is **version 1.41**, updated 2026-08-04 (§14: UTC, ISO +This document is **version 1.42**, updated 2026-08-05 (§14: UTC, ISO 8601). The skill encoding of the standard keeps a parallel history in `spacecraft-standard-constitution/references/CHANGELOG.md` in the [Construct @@ -1345,8 +1345,33 @@ or another FOSS-licensed repository. # §13 — UI/UX Design System -- **Material Design** is the required component system for all graphical - applications. Theme Material components with the §11 color palette. +- **Every graphical application declares exactly one component system**, + named in its `README.md` beside the §5.2 posture section, and themes + it with the §11 palette. Which system is determined by the platform, + not by preference: + + | Application class | Required component system | + |----|----| + | **Flutter, web, mobile, and cross-platform GUI** | **Material Design** | + | **GTK 4 desktop** | **GNOME HIG** via libadwaita — `spacecraft-gtk-guidelines` | + | **Qt 6 desktop** | **KDE HIG** via Qt Quick Controls / Fusion — `spacecraft-qt-guidelines` | + | **Custom-drawn or immediate-mode UI** | Material Design, unless a platform HIG is declared | + + **Rationale.** Material Design is a coherent, accessible system and + remains the default wherever the platform does not supply one. A + native desktop toolkit does supply one: GTK ships Adwaita and the + GNOME HIG, Qt ships Fusion and the KDE HIG, and both are wired into + the platform’s window management, settings, and accessibility stack. + Imposing Material on top of either produces an application that + matches neither its own toolkit nor Material, and that fights the very + platform integration §18 depends on. The mandate is therefore that a + system is **declared and followed consistently** — not that one + particular system is used everywhere. + +- **§11 binding is unconditional.** Whichever system is declared, all + palette references go through the named `steelbore` theme (§11.1). A + component system chooses the widget vocabulary; it never supplies the + colors. - **WCAG 2.2 Level AA** contrast is the minimum for all color pairings. Any new color additions must be WCAG-verified before adoption, and the @@ -2028,8 +2053,11 @@ Before finalising **any** Spacecraft Software artifact, mentally verify: - [ ] **§12** FOSS-licensed fonts only (Share Tech Mono / Inconsolata) -- [ ] **§13** Material Design UI/UX; WCAG 2.2 AA verified, stating which - pairing was measured +- [ ] **§13** Exactly one component system declared in `README.md` and + followed — Material Design for Flutter/web/mobile/cross-platform, + GNOME HIG for GTK 4, KDE HIG for Qt 6; themed through the `steelbore` + theme (§11.1); WCAG 2.2 AA verified, stating which pairing was + measured - [ ] **§14** ISO 8601 dates; 24h time; UTC Z is the default primary timestamp (companion local time with UTC offset permitted, never a @@ -2085,6 +2113,8 @@ skipping it. | Writing or reviewing shell scripts | `spacecraft-cli-shell` + `spacecraft-cli-preference` | | Generating DOCX / ODT / PDF on demand | `spacecraft-document-format` | | Authoring or building a Texinfo manual | `spacecraft-texinfo-document` | +| Writing GTK 4 / GNOME desktop code (§13) | `spacecraft-gtk-guidelines` | +| Writing Qt 6 / KDE desktop code (§13) | `spacecraft-qt-guidelines` | | Creating IDE / terminal themes | `spacecraft-theme-factory` | | Implementing or auditing accessibility (§18) | `spacecraft-accessibility` | | All other Spacecraft Software work | `spacecraft-standard-constitution` | diff --git a/The_Steelbore_Standard.texi b/The_Steelbore_Standard.texi index 74191ae..d1585fc 100644 --- a/The_Steelbore_Standard.texi +++ b/The_Steelbore_Standard.texi @@ -5,11 +5,11 @@ @setfilename The_Steelbore_Standard.info @documentencoding UTF-8 @documentlanguage en -@settitle The Steelbore Standard 1.41 +@settitle The Steelbore Standard 1.42 @c %**end of header -@set VERSION 1.41 -@set UPDATED 2026-08-04 +@set VERSION 1.42 +@set UPDATED 2026-08-05 @set SUBDOMAIN https://Standard.SpacecraftSoftware.org/ @copying @@ -66,7 +66,7 @@ Maintained by Mohamed Hammad * Key Bindings:: §10 — CUA + Vim key binding requirements. * Color Palette:: §11 — WCAG-compliant color palette. * Typography:: §12 — FOSS-licensed font requirements. -* UI/UX Design System:: §13 — Material Design & visual design system. +* UI/UX Design System:: §13 — Declared component system & visual design. * Date Time Units:: §14 — ISO 8601, UTC Z, metric units. * Attribution:: §15 — Maintainer, project pages, credits. * Development Progress Tracking:: §17 — Development progress tracking and reporting. @@ -2600,9 +2600,44 @@ or another FOSS-licensed repository. @chapter §13 — UI/UX Design System @itemize @item -@strong{Material Design} is the required component system for all -graphical applications. Theme Material components with the §11 color -palette. +@strong{Every graphical application declares exactly one component +system}, named in its @file{README.md} beside the §5.2 posture section, +and themes it with the §11 palette. Which system is determined by the +platform, not by preference: + +@multitable {Flutter, web, mobile, and cross-platform GUI} {@strong{GNOME HIG} via libadwaita --- @code{spacecraft-gtk-guidelines}} +@headitem +Application class + @tab Required component system +@item +@strong{Flutter, web, mobile, and cross-platform GUI} + @tab @strong{Material Design} +@item +@strong{GTK 4 desktop} + @tab @strong{GNOME HIG} via libadwaita --- @code{spacecraft-gtk-guidelines} +@item +@strong{Qt 6 desktop} + @tab @strong{KDE HIG} via Qt Quick Controls / Fusion --- @code{spacecraft-qt-guidelines} +@item +@strong{Custom-drawn or immediate-mode UI} + @tab Material Design, unless a platform HIG is declared +@end multitable + +@strong{Rationale.} Material Design is a coherent, accessible system and +remains the default wherever the platform does not supply one. A native +desktop toolkit does supply one: GTK ships Adwaita and the GNOME HIG, Qt +ships Fusion and the KDE HIG, and both are wired into the platform's +window management, settings, and accessibility stack. Imposing Material +on top of either produces an application that matches neither its own +toolkit nor Material, and that fights the very platform integration §18 +depends on. The mandate is therefore that a system is @strong{declared +and followed consistently} --- not that one particular system is used +everywhere. +@item +@strong{§11 binding is unconditional.} Whichever system is declared, all +palette references go through the named @code{steelbore} theme (§11.1). +A component system chooses the widget vocabulary; it never supplies the +colors. @item @strong{WCAG 2.2 Level AA} contrast is the minimum for all color pairings. Any new color additions must be WCAG-verified before adoption, @@ -3626,7 +3661,10 @@ literals in UI logic --- and ship the palette's @item ☐ @strong{§12} FOSS-licensed fonts only (Share Tech Mono / Inconsolata) @item -☐ @strong{§13} Material Design UI/UX; WCAG 2.2 AA verified, stating which +☐ @strong{§13} Exactly one component system declared in @file{README.md} +and followed --- Material Design for Flutter/web/mobile/cross-platform, +GNOME HIG for GTK 4, KDE HIG for Qt 6; themed through the +@code{steelbore} theme (§11.1); WCAG 2.2 AA verified, stating which pairing was measured @item ☐ @strong{§14} ISO 8601 dates; 24h time; UTC Z is the default primary @@ -3702,6 +3740,12 @@ Generating DOCX / ODT / PDF on demand Authoring or building a Texinfo manual @tab @code{spacecraft-texinfo-document} @item +Writing GTK 4 / GNOME desktop code (§13) + @tab @code{spacecraft-gtk-guidelines} +@item +Writing Qt 6 / KDE desktop code (§13) + @tab @code{spacecraft-qt-guidelines} +@item Creating IDE / terminal themes @tab @code{spacecraft-theme-factory} @item