Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/badges/conformance.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
5 changes: 3 additions & 2 deletions .github/conformance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down Expand Up @@ -111,6 +111,7 @@ criteria:
W06: na
W07: na
W08: na
W09: na
A01: na
A02: na
A03: na
Expand Down
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
86 changes: 86 additions & 0 deletions docs/decisions/0013-sites-are-designed-not-templated.md
Original file line number Diff line number Diff line change
@@ -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.
65 changes: 26 additions & 39 deletions docs/repository-quality-standard.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -488,10 +488,11 @@ Record the rationale rather than leaving the profile unclaimed.
| <a id="w02"></a>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 |
| <a id="w03"></a>W03 | The landing view states what the project is, who it is for, and its current status before any scrolling | Site source |
| <a id="w04"></a>W04 | The site carries the content baseline | [Site Content Baseline](#site-content-baseline) |
| <a id="w05"></a>W05 | The site uses the shared design language rather than ad-hoc styling | [Design Language](#design-language) |
| <a id="w06"></a>W06 | The design language version the site was built against is recorded | Version note, manifest entry, or vendored file header |
| <a id="w05"></a>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 |
| <a id="w06"></a>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 |
| <a id="w07"></a>W07 | The site loads no third-party resources, sets no cookies, and carries no analytics | Site source and a documented network review |
| <a id="w08"></a>W08 | The site states each fact once and links to the repository for depth | [Content Boundaries](#content-boundaries) |
| <a id="w09"></a>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.
Expand Down Expand Up @@ -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
<link rel="stylesheet" href="/assets/core.tokens.css">
<link rel="stylesheet" href="/assets/instrument-workshop.css">
```

`iw-root` goes on `<body>`, the theme is an attribute on `<html>`, 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

Expand Down
6 changes: 3 additions & 3 deletions docs/self-assessment.md
Original file line number Diff line number Diff line change
@@ -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)

Expand Down Expand Up @@ -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
Expand Down
16 changes: 10 additions & 6 deletions standard.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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"
Expand All @@ -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"
Expand Down
3 changes: 2 additions & 1 deletion templates/conformance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -99,6 +99,7 @@ criteria:
W06: unknown
W07: unknown
W08: unknown
W09: unknown
G01: unknown
G02: unknown
G03: unknown
Expand Down