From 8969afdac13f1eeb0be48f29ecb826aabb49d404 Mon Sep 17 00:00:00 2001 From: Torsten Mahr Date: Thu, 17 Sep 2026 19:45:40 +0200 Subject: [PATCH] Retire the Instrument Workshop mandate for published sites (1.12.0) Retires W05 and W06, which required every published site to vendor the shared Instrument Workshop design language, and adds W09: a site's visual design must be made for the project it describes rather than left at a framework default or reused unchanged from another project. Prompted by rebuilding OpenPromptr's site, which was correct against W05 but read as generic once actually looked at. See decision 0013 for the full reasoning and alternatives considered. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01Kjr8Vb74FWo974AkG8NYsU --- .github/badges/conformance.svg | 6 +- .github/conformance.yml | 5 +- CHANGELOG.md | 15 ++++ .../0013-sites-are-designed-not-templated.md | 86 +++++++++++++++++++ docs/repository-quality-standard.md | 65 ++++++-------- docs/self-assessment.md | 6 +- standard.yml | 16 ++-- templates/conformance.yml | 3 +- 8 files changed, 148 insertions(+), 54 deletions(-) create mode 100644 docs/decisions/0013-sites-are-designed-not-templated.md diff --git a/.github/badges/conformance.svg b/.github/badges/conformance.svg index 272b93e..6f85935 100644 --- a/.github/badges/conformance.svg +++ b/.github/badges/conformance.svg @@ -1,10 +1,10 @@ - - trsdn standard: v1.11.1 - Healthy + + trsdn standard: v1.12.0 - Healthy trsdn standard - v1.11.1 - Healthy + v1.12.0 - Healthy diff --git a/.github/conformance.yml b/.github/conformance.yml index 0f1c233..5b1b424 100644 --- a/.github/conformance.yml +++ b/.github/conformance.yml @@ -6,8 +6,8 @@ # The badge in .github/badges/ is generated from this file. Change the evidence # first, then this record, then regenerate. Never the other way round. -standard_version: "1.11.1" -assessed_on: "2026-09-02" +standard_version: "1.12.0" +assessed_on: "2026-09-17" state: "Healthy" evidence: "docs/self-assessment.md" @@ -111,6 +111,7 @@ criteria: W06: na W07: na W08: na + W09: na A01: na A02: na A03: na diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e01c01..af3424b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,21 @@ recorded here. Versions follow the compatibility policy in the [Repository Quality Standard](docs/repository-quality-standard.md). +## 1.12.0 - 2026-09-17 + +- Retired `W05` and `W06`, which required every published site to vendor + **Instrument Workshop**, the shared design language. Added `W09`: a site's + visual design must be made for the project it describes, not left at a + framework default or reused unchanged from another project. Sites may still + use Instrument Workshop where it fits; nothing requires or recommends it as + the default any longer. + [Site Design](docs/repository-quality-standard.md#site-design) replaces the + former Design Language subsection. See + [decision 0013](docs/decisions/0013-sites-are-designed-not-templated.md). +- Released as minor: retiring a criterion narrows applicability and adding one + widens the catalog, and neither can turn a recorded `Pass` into a `Fail` + under [Versioning And Compatibility](docs/repository-quality-standard.md#versioning-and-compatibility). + ## 1.11.1 - 2026-09-02 - Made diff --git a/docs/decisions/0013-sites-are-designed-not-templated.md b/docs/decisions/0013-sites-are-designed-not-templated.md new file mode 100644 index 0000000..5926973 --- /dev/null +++ b/docs/decisions/0013-sites-are-designed-not-templated.md @@ -0,0 +1,86 @@ +# 0013 - Sites are designed for the project, not assembled from a shared kit + +- Status: Accepted +- Date: 2026-09-17 + +## Context + +[Decision 0009](0009-published-sites-and-content-boundaries.md) required every +published site to vendor **Instrument Workshop**, the shared, privately +maintained design language, on the reasoning that a design language earns its +value from consistent use and that contrast, focus, target size, and density +are better decided once than re-litigated per site. + +Rebuilding `OpenPromptr`'s site surfaced what that consistency actually cost. +The page carried the same panel chrome, badge shapes, and callout treatment as +every other site built from the same two stylesheets, regardless of what +`OpenPromptr` is — a native macOS teleprompter mirror, not the kind of project +the shared components were shaped around. The result read as competent and +generic at once: correct against `W05`, and indistinguishable from a site for +a different product entirely. A visitor learned nothing about `OpenPromptr` +from the page that the page's own words didn't already say; the design carried +no information. + +`W05`'s trade was consistency for distinctiveness, made once for every project +in the estate. That trade was reasonable when it was written and only one or +two sites existed to test it against. It stops being reasonable once "look +like they come from the same hand" is read literally: nine-plus unrelated +products — a teleprompter tool, a scrum aid, a Windows markdown viewer, an +about-me page — sharing one visual identity is not a property a reader values, +it is a signal that nobody spent a design decision on any of them individually. + +## Decision + +Retire `W05` and `W06` in place, keeping both identifiers per [decision +0001](0001-criterion-identifiers-are-permanent.md). Append `W09`: a site's +visual design must be made for the project it describes, evidenced by a look at +the page rather than a vendored file. The [Site +Design](../repository-quality-standard.md#site-design) subsection replaces the +former Design Language subsection and drops the Instrument Workshop mandate; a +site may still use it where it genuinely fits, but nothing requires it, and +nothing recommends it as the default. + +`W07` — no third-party resources, no cookies, no analytics — is untouched. It +was never about the design language; it applies to whatever a site's design +turns out to need. + +## Alternatives considered + +**Narrow `W05`'s wording in place, rather than retiring it.** Reads where a +reader already looks, and needed no new identifier. Rejected on version impact: +under [Versioning And Compatibility](../repository-quality-standard.md#versioning-and-compatibility), +narrowing a criterion's meaning so that a recorded `Pass` could become a `Fail` +is a major change, and a site that vendored Instrument Workshop in good faith +under the old wording should not have its recorded result invalidated by this +one. Retiring the old criterion and appending a new one buys the same outcome +at a minor bump — the same pattern [decision 0012](0012-history-on-the-default-branch-is-protected.md) +used for the same reason. + +**Leave `W05`/`W06` as optional rather than retired.** An optional criterion +with no stated condition for when it applies is not assessable — nothing in +[Baseline](../repository-quality-standard.md#baseline) or elsewhere in this +standard is graded "maintainer's choice", because a result that can't be +wrong isn't evidence of anything. Retiring the pair and stating the new +requirement as `W09` keeps every Published Site criterion falsifiable. + +**Replace Instrument Workshop with a second shared design language instead of +removing the requirement.** Would repeat the same trade under a different +name. The actual problem was requiring any one visual identity across +unrelated products, not which identity was required. + +## Consequences + +Recorded `Pass` results for `W05` and `W06` in any repository's conformance +record stay valid for the standard version they name — [decision +0001](0001-criterion-identifiers-are-permanent.md) and the versioning policy +both hold. Neither criterion is assessed again after this version; a +repository's next conformance pass drops them and picks up `W09` +unassessed, which is due for reassessment rather than a regression. + +A site that still vendors Instrument Workshop keeps rendering exactly as +before and is not asked to change; `W09` is not failed by using it, only by a +site with no design intent behind it at all — an unstyled scaffold, a +framework default left untouched, or another project's site carried over +without adapting it. `OpenPromptr`'s rebuilt site, and the reasoning that +produced it, is the worked example `W09` is checked against until a second one +exists. diff --git a/docs/repository-quality-standard.md b/docs/repository-quality-standard.md index 71cc8f7..edaea6f 100644 --- a/docs/repository-quality-standard.md +++ b/docs/repository-quality-standard.md @@ -1,7 +1,7 @@ # Repository Quality Standard -- Version: 1.11.1 -- Last reviewed: 2026-09-02 +- Version: 1.12.0 +- Last reviewed: 2026-09-17 - Review cadence: every six months, even when nothing changes This document is the public source of truth for repository quality across @@ -488,10 +488,11 @@ Record the rationale rather than leaving the profile unclaimed. | W02 | The repository and the site link to each other | Repository homepage field, and a repository link in the site's persistent navigation or footer | | W03 | The landing view states what the project is, who it is for, and its current status before any scrolling | Site source | | W04 | The site carries the content baseline | [Site Content Baseline](#site-content-baseline) | -| W05 | The site uses the shared design language rather than ad-hoc styling | [Design Language](#design-language) | -| W06 | The design language version the site was built against is recorded | Version note, manifest entry, or vendored file header | +| W05 | Retired 2026-09-17 (standard 1.12.0) — the shared-design-language mandate is replaced by `W09`; see [decision 0013](decisions/0013-sites-are-designed-not-templated.md) | None — retired | +| W06 | Retired 2026-09-17 (standard 1.12.0) — recording a vendored design-language version is no longer required; see [decision 0013](decisions/0013-sites-are-designed-not-templated.md) | None — retired | | W07 | The site loads no third-party resources, sets no cookies, and carries no analytics | Site source and a documented network review | | W08 | The site states each fact once and links to the repository for depth | [Content Boundaries](#content-boundaries) | +| W09 | The site's visual design is made for this project, not left at a framework or template default | [Site Design](#site-design) | A site is a shipped user interface, so [Accessibility](#accessibility) applies to it in full. Those criteria are not restated here. @@ -527,41 +528,27 @@ started to duplicate the repository, which `W08` forbids. A site may be a single page. Nothing in this section requires more than one, and a single honest page beats a navigation tree over empty sections. -### Design Language - -The shared design language is **Instrument Workshop**. Sites use it rather than -inventing styling per repository, so that the projects look like they come from -the same hand and so that accessibility decisions — contrast, focus, target -size, density — are made once rather than re-litigated per site. - -It is consumed by copying two stylesheets into the repository and loading the -tokens first: - -```html - - -``` - -`iw-root` goes on ``, the theme is an attribute on ``, and density is -an attribute on any container. There is no package to install, no build step, and -no framework or JavaScript requirement. - -Copying rather than depending is deliberate, and copying is expressly permitted. -The design system is maintained separately and privately, so a public site cannot -resolve it at build time. The stylesheets may be vendored into public -repositories, which means the design language becomes visible in every site built -from it — that is accepted, because a design language earns its value from -consistent use rather than from being hidden. A vendored copy also means a site -keeps rendering when the source repository moves, which is the same property -`P09` wants from a statistics card. - -`W06` exists because a vendored copy has no version unless one is written down. -Record which version was copied, in a manifest, a note, or a comment at the top -of the vendored file. Without it, nobody can tell whether a site is three -revisions behind or current. - -Deviating is allowed where the design language has no answer, and the deviation -is recorded. Deviating because it was quicker is a `Fail`. +### Site Design + +There is no shared design language every site is required to use, and no +default one to reach for. `W09` asks whether a visitor can tell the page was +built for what it describes, or whether it is unstyled HTML, a framework's +default theme, or another project's site reused unchanged. That test is +judgement, not a checklist, so what counts as evidence is a brief, honest look +at the page rather than a single artifact. + +Colour, type, and layout are chosen for the project's own subject matter, and +the accessibility fundamentals that a shared system used to settle once — +contrast, visible keyboard focus, a legible type scale, sane behaviour down to +a phone width — are handled per site instead. `W07` still applies in full: a +distinctive site self-hosts its own fonts, images, and scripts rather than +reaching for a font CDN or an icon service. + +This replaces the shared design language, **Instrument Workshop**, that earlier +versions of this standard required every site to vendor (`W05`, `W06`; both +retired — see [decision 0013](decisions/0013-sites-are-designed-not-templated.md)). +A site is not penalised for still using it: nothing here forbids vendoring it +where it genuinely fits, only the requirement that every site do so by default. ## Content Boundaries diff --git a/docs/self-assessment.md b/docs/self-assessment.md index 7d99c03..313167e 100644 --- a/docs/self-assessment.md +++ b/docs/self-assessment.md @@ -1,7 +1,7 @@ # Self-Assessment: trsdn/.github -- Standard version: 1.11.1 -- Assessed on: 2026-09-02 +- Standard version: 1.12.0 +- Assessed on: 2026-09-17 - State: **Healthy** - Record: [`.github/conformance.yml`](../.github/conformance.yml) @@ -91,7 +91,7 @@ right to be ignored. ## Not applicable -**Published Site `W01`-`W08`.** This repository defines the standard; it does not +**Published Site `W01`-`W09`.** This repository defines the standard; it does not ship a product. Everyone who reads the standard reads it while working inside a repository — applying it, citing a criterion in an issue, or acting on it as an agent — and a page in front of it would add a surface to maintain while answering diff --git a/standard.yml b/standard.yml index 7556249..9458958 100644 --- a/standard.yml +++ b/standard.yml @@ -3,8 +3,8 @@ # Generated by scripts/standard.py from # docs/repository-quality-standard.md. Do not edit by hand. -version: "1.11.1" -last_reviewed: "2026-09-02" +version: "1.12.0" +last_reviewed: "2026-09-17" prefixes: A: "Archived" @@ -300,12 +300,12 @@ criteria: evidence: "[Site Content Baseline](#site-content-baseline)" - id: "W05" section: "Published Sites" - requirement: "The site uses the shared design language rather than ad-hoc styling" - evidence: "[Design Language](#design-language)" + requirement: "Retired 2026-09-17 (standard 1.12.0) — the shared-design-language mandate is replaced by `W09`; see [decision 0013](decisions/0013-sites-are-designed-not-templated.md)" + evidence: "None — retired" - id: "W06" section: "Published Sites" - requirement: "The design language version the site was built against is recorded" - evidence: "Version note, manifest entry, or vendored file header" + requirement: "Retired 2026-09-17 (standard 1.12.0) — recording a vendored design-language version is no longer required; see [decision 0013](decisions/0013-sites-are-designed-not-templated.md)" + evidence: "None — retired" - id: "W07" section: "Published Sites" requirement: "The site loads no third-party resources, sets no cookies, and carries no analytics" @@ -314,6 +314,10 @@ criteria: section: "Published Sites" requirement: "The site states each fact once and links to the repository for depth" evidence: "[Content Boundaries](#content-boundaries)" + - id: "W09" + section: "Published Sites" + requirement: "The site's visual design is made for this project, not left at a framework or template default" + evidence: "[Site Design](#site-design)" - id: "G01" section: "Agent Readiness" requirement: "Agent-facing instructions exist at a discoverable, tool-neutral location" diff --git a/templates/conformance.yml b/templates/conformance.yml index 9fa1d55..c8ebcea 100644 --- a/templates/conformance.yml +++ b/templates/conformance.yml @@ -20,7 +20,7 @@ # The badge is generated from this file. Change the evidence first, then this # record, then regenerate. Never the other way round. -standard_version: "1.11.1" +standard_version: "1.12.0" assessed_on: "YYYY-MM-DD" state: "Needs work" evidence: "docs/self-assessment.md" @@ -99,6 +99,7 @@ criteria: W06: unknown W07: unknown W08: unknown + W09: unknown G01: unknown G02: unknown G03: unknown