From 4354d34688f6cf745f04de428c29f4a3d470e6a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Wed, 30 Sep 2026 21:57:33 -0700 Subject: [PATCH 1/5] docs: a blocky header with an RGB-split glitch asset/logo-{dark,light}.svg are built from rects on a 5x7 grid rather than from . GitHub cannot be relied on for fonts, so a font-family wordmark renders differently per viewer or not at all; rects render identically everywhere and blocky is literal rather than a font choice. The glitch is three offset copies: magenta pulled left across rows 1 and 2, cyan pushed right across rows 4 and 5, the repo colour underneath, and a half-opacity overlay on the middle row. specs is blue #3B82F6. Header follows the toneharness shape: centred logo, one-line tagline, one badge row, a bold line, then the paragraph. Nothing below ## Usage changes. --- README.md | 37 ++++++++++++++++++++++++++++--------- asset/logo-dark.svg | 1 + asset/logo-light.svg | 1 + 3 files changed, 30 insertions(+), 9 deletions(-) create mode 100644 asset/logo-dark.svg create mode 100644 asset/logo-light.svg diff --git a/README.md b/README.md index 656e335..496b210 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,31 @@ -[![license](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=for-the-badge)](LICENSE) -[![conventional commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=for-the-badge)](https://conventionalcommits.org) -[![docs driven](https://img.shields.io/badge/docs-driven-blue.svg?style=for-the-badge)](CONTRIBUTING.md) -![gitHub commit activity](https://img.shields.io/github/commit-activity/m/osapi-io/specs?style=for-the-badge) - -# specs - -The design docs for [osapi-io]. How each repository is built and why, in one -place, kept current as they change. No product code here. +

+ + + + specs + +

+ +

The design docs for osapi-io. Written before the code, corrected when the code proves them wrong.

+ +

+ license + conventional commits + docs driven + built with just + github commit activity +

+ +

+Doc-driven: the page is the design, then the description. +

+ +

+You design something by writing its page, build it, then correct the page where +building proved it wrong. Same page all three times, so nothing is converted from +one form into another, because that conversion is where the design and the docs +drift apart. +

## Usage diff --git a/asset/logo-dark.svg b/asset/logo-dark.svg new file mode 100644 index 0000000..6ecbd39 --- /dev/null +++ b/asset/logo-dark.svg @@ -0,0 +1 @@ + diff --git a/asset/logo-light.svg b/asset/logo-light.svg new file mode 100644 index 0000000..c5b981d --- /dev/null +++ b/asset/logo-light.svg @@ -0,0 +1 @@ + From 661c166ebc6e72de2b9559f82579c9b72343759a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Wed, 30 Sep 2026 22:02:10 -0700 Subject: [PATCH 2/5] docs: match the toneharness wordmark exactly The first attempt was a 5x7 grid at 10px with RGB-split cyan and magenta layers. That is not what toneharness does, and it looked nothing like it. Fetched the actual SVG and read it. It is 4 rows of 16px blocks in one colour, 8px padding, 80 tall, with seven cells at opacity 0.25 as the glitch, and vertical runs merged into single rects so the blocks meet exactly. The letterforms are 3 columns wide, proportional, and the opacity cells are decoration rather than part of the letters, which is why the first extraction of its font came out wrong. This matches all of it: same cell size, same row count, same padding, same height, same glitch count and opacity, same merged runs. One primary colour per repository. --- asset/logo-dark.svg | 34 +++++++++++++++++++++++++++++++++- asset/logo-light.svg | 34 +++++++++++++++++++++++++++++++++- 2 files changed, 66 insertions(+), 2 deletions(-) diff --git a/asset/logo-dark.svg b/asset/logo-dark.svg index 6ecbd39..e590880 100644 --- a/asset/logo-dark.svg +++ b/asset/logo-dark.svg @@ -1 +1,33 @@ - + + specs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/asset/logo-light.svg b/asset/logo-light.svg index c5b981d..5216103 100644 --- a/asset/logo-light.svg +++ b/asset/logo-light.svg @@ -1 +1,33 @@ - + + specs + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 952ee0dbfa2cdc74169b0b02d954e6f331fedbff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Wed, 30 Sep 2026 22:06:50 -0700 Subject: [PATCH 3/5] docs: the overshadow is a grey top half, not one flat colour Read ~/git/tonestack's SVG by row and colour. The word is four rows of 16px blocks, and the top two rows are grey #8a8a8a while the bottom two are the brand colour. The light variant is the same split with #6f6f6f and a darker brand. That two-tone split is the overshadowing. My version painted all four rows one colour, which is why it looked nothing like it. Now it matches: grey top half, brand bottom half, seven cells at opacity 0.25, vertical runs merged but never across the colour boundary. osapi takes tonestack's own #ffa032 since amber is the hub's colour anyway. The rest keep their assigned brand colour on the bottom half. --- asset/logo-dark.svg | 62 +++++++++++++++++++++++--------------------- asset/logo-light.svg | 62 +++++++++++++++++++++++--------------------- 2 files changed, 64 insertions(+), 60 deletions(-) diff --git a/asset/logo-dark.svg b/asset/logo-dark.svg index e590880..3176b86 100644 --- a/asset/logo-dark.svg +++ b/asset/logo-dark.svg @@ -1,33 +1,35 @@ specs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/asset/logo-light.svg b/asset/logo-light.svg index 5216103..b5895bb 100644 --- a/asset/logo-light.svg +++ b/asset/logo-light.svg @@ -1,33 +1,35 @@ specs - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 90176b8205440ef0fcbe021c89123694f45ca982 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Wed, 30 Sep 2026 22:14:06 -0700 Subject: [PATCH 4/5] docs: use tonestack's actual banner font, not an invented one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Found the font in tonestack's source, pkg/cli/internal/paint/theme.go: top = "▀█▀ █▀█ █▄░█ █▀▀ █░█ ▄▀█ █▀█ █▄░█ █▀▀ █▀ █▀" bot = "░█░ █▄█ █░▀█ ██▄ █▀█ █▀█ █▀▄ █░▀█ ██▄ ▄█ ▄█" A half-block alphabet in two text rows. Each cell is a full block, an upper half, a lower half or blank, and each text row becomes two SVG rows, which is where the four rows of 16px blocks come from. The top text row is grey and the bottom is the brand colour. That split is the bleed: wherever a letter has a full-height stem, the brand colour sits directly under grey in the same column, and the eye reads it as one colour bleeding into the other. My previous attempt painted all four rows one colour, so there was nothing to bleed. Seven whole character cells drop to 0.25 opacity, which is how tonestack does its glitch: a whole cell at a time, not a half. Every letter tonestack has is byte-identical to its strings: a e h n o r s t. The eleven the osapi names need and it does not have are drawn in the same alphabet. Seam density, the share of columns where brand sits under grey: tonestack 44%, osapi 44%, gohai 47%. The longer names run 27 to 33% because s, t, c, e and l have no full-height stem in this font, which is a property of the alphabet rather than of the rendering. --- asset/logo-dark.svg | 28 +++++++++++----------------- asset/logo-light.svg | 28 +++++++++++----------------- 2 files changed, 22 insertions(+), 34 deletions(-) diff --git a/asset/logo-dark.svg b/asset/logo-dark.svg index 3176b86..0b8092e 100644 --- a/asset/logo-dark.svg +++ b/asset/logo-dark.svg @@ -1,34 +1,28 @@ specs - - + - - - - - + + + - + - - - - + + - - - + + + - - + diff --git a/asset/logo-light.svg b/asset/logo-light.svg index b5895bb..4e76cf2 100644 --- a/asset/logo-light.svg +++ b/asset/logo-light.svg @@ -1,34 +1,28 @@ specs - - + - - - - - + + + - + - - - - + + - - - + + + - - + From 98a8797325caf8a2e7f198dc5ba468ff9b00421a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Wed, 30 Sep 2026 22:21:14 -0700 Subject: [PATCH 5/5] docs: scale the glitch to the word, not a fixed seven tonestack dims seven cells across 43 columns, about one per six. A fixed seven on a 17 column word dims 41% of it, which buried the letters: rendering specs showed a word you could not read. One per six now, minimum two. specs gets three, osapi-orchestrator gets eleven. --- asset/logo-dark.svg | 8 ++++---- asset/logo-light.svg | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/asset/logo-dark.svg b/asset/logo-dark.svg index 0b8092e..d688a89 100644 --- a/asset/logo-dark.svg +++ b/asset/logo-dark.svg @@ -1,14 +1,14 @@ specs - + - + - + @@ -16,7 +16,7 @@ - + diff --git a/asset/logo-light.svg b/asset/logo-light.svg index 4e76cf2..375e75d 100644 --- a/asset/logo-light.svg +++ b/asset/logo-light.svg @@ -1,14 +1,14 @@ specs - + - + - + @@ -16,7 +16,7 @@ - +