Skip to content
oto
Menu
Overview
IntroductionConceptsArchitectureContributingReleasing
Design
oto — System Design ProposalDomain Research: Prometheus Alertmanager + Slackoto — Red-Team Memooto — SCOPE BOUNDARY (the doctrine)oto — BINDING SPECIFICATION v1
ADRs
0001 — PostgreSQL is the sole datastore; River is the job queue0002 — `internal/<domain>/{api,service,repository,domain}` with three model sets0003 — Alert, AlertOccurrence and AlertEvent are three distinct entities0004 — oto owns alert identity; Alertmanager's fingerprint is recomputed, not trusted0005 — A durable group key, and the AlertGroup generation owns the Slack thread0006 — The Alertmanager API v2 reconciler is mandatory, not optional0007 — Webhook response contract: 202 or 503. Never 4xx, never 429.0008 — Slack: `chat.update` in place is primary; threads are secondary; one colour attachment0009 — Rule definitions are snapshotted and versioned at fire time0010 — Server-Sent Events with durable resume, not WebSocket0011 — Validation is seven layers with two opposite trust models0012 — Pastel product chrome, saturated colour reserved exclusively for state0013 — oto is alert-first: the Flight Recorder Test defines the scope boundary0014 — Postgres is the only store; no TSDB or column store in v10015 — No stream processor; River in Postgres is the pipeline0016 — Cluster context arrives via MCP, on demand; never the Kubernetes event firehose0017 — Alertmanager-style matchers, not CEL; and a filter AST that keeps the door open0018 — Slack distribution: a customer-built internal app, credentials in config0019 — MIT licence0020 — Broadcast the transitions that must be seen0021 — Correctness and testing strategy0022 — Length-prefixed identity pre-images0023 — Terminal thread states are decided first, and the send is three phases0024 — Retention defaults, what each boundary destroys, and cold storage0025 — The alert list resolves rule snapshots in a batch, not per row0026 — `refire_grace` and the flap thresholds, derived from a real rule corpus0027 — Delivery drills: a synthetic alert through the real pipeline, and the mark that keeps it out of the numbers0028 — Non-urgency motion: one-shot events, honest activity loops, and nothing else0029 — Type and radius scales, read off the product rather than drawn for it0030 — Tier A repainted as Washi & Ink / Konshi Sutra; accent moves to beni0031 — Sharp corners and higher-contrast grid lines within Washi & Ink; colours unchanged0032 — Dark-theme accent moves from beni to plum-blossom blue-and-white; light untouched0033 — The alert filters are a toolbar above the table, not a panel in the rail0034 — Notifications is a destination, and the record it keeps is readable0035 — Decorative ink as a masked wash: one primitive, four motifs, and the placements it is refused0036 — AlertOccurrence becomes AlertCase, and `case` is argued against FR-1 by name0037 — A Wording is Liquid, and the structure around it stays oto's0038 — The group key is derived from the alert's own labels0039 — Group close stays activity-driven0040 — A Case is `open` or `closed`, and it is never reopened0041 — The Alert/Case allocation, and the one rule that decides it0042 — Storm damping is removed, because the defence was built before its object0043 — The Slack action row renders five elements, and the fifth is the snooze pair0044 — A count condition is a silence the operator asked for, and `below_threshold` is how oto says so0045 — A Case is a conversation, and one Slack thread per alert is the accepted cost0046 — Corners round again: ADR 0031's radius override is reversed0047 — A channel answers to a connection, and Slack gets two scopes back0048 — A Wording is spelled by its channel, and the marks in between are oto's0049 — A Wording is selected by its own clause, not by a route0050 — A NotificationTemplate is one whole message, and its policy says which one0051 — A `raw` template owns the whole message, and a template may carry its replies0052 — An Incident is drawn over Cases, and its response is handed off0053 — An Investigator reads, proposes, and never decides delivery0054 — A Remedy earns the write path0055 — An incident-tool integration is data or a bridge, never code inside oto0056 — A Case the upstream stopped speaking about expires, and says why
Setup
Configuration referenceReaching an incident tool: the envelope, a mapping, or a bridgeInvestigatorsRemediesConnecting oto to SlackThe live Slack verification runTuning otoConnecting oto to VictoriaMetrics (vmalert)The generic webhook and `oto.notification.v1`
Runbooks
oto runbooksAlert search — optional partial/substring matching on alert namesoto_clock_skew_secondsoto_delivery_claim_lost_totaloto_ingest_accepted_totaloto_ingest_alerts_totaloto_ingest_duplicate_totaloto_ingest_duration_secondsoto_ingest_fingerprint_mismatch_totaloto_ingest_process_duration_secondsoto_ingest_rejected_totaloto_ingest_shed_totaloto_job_duration_secondsoto_job_queue_depthoto_jobs_dead_totaloto_jobs_enqueued_totaloto_jobs_failed_totaloto_jobs_panics_totaloto_jobs_snoozed_totaloto_jobs_started_totaloto_jobs_succeeded_totaloto_jobs_unknown_version_totaloto_render_invalid_totaloto_slack_unknown_action_totaloto_stream_connectionsoto_stream_events_coalesced_totaloto_stream_events_dropped_totaloto_stream_events_fetched_totaloto_stream_events_published_totaloto_stream_fetch_errors_totaloto_stream_listener_reconnects_totaloto_stream_notify_malformed_totaloto_stream_notify_received_totaloto_stream_poll_recovered_totaloto_stream_resync_totaloto_thread_gap_recovered_totaloto_thread_head_wait_secondsoto_thread_order_decisions_total

0035 — Decorative ink as a masked wash: one primitive, four motifs, and the placements it is refused

Status: Accepted · 2026-08-17 · adds §M.9 to the SPEC · sits alongside ADR 0028 (which still owns motion), ADR 0030 (the palette the tints derive from), ADR 0031 (the geometry this coexists with) and ADR 0032 (why the accent reads differently per theme)

Context

Section titled “Context”

The brand sheet’s brush existed as two inlined logo components and nothing else. Wordmark.tsx and Logo.tsx are currentColor SVG elements, which is exactly right for a mark that sits in the DOM as content — and useless for decoration, because a decorative stroke has to sit behind or beside something without occupying a slot in the layout.

ADR 0031 took the interface to sharp corners and a crisp technical grid. That is the right call for a table an operator reads at 3am, and it left the product with no surviving trace of the ink-painting language ADR 0030 chose: text-page was a type step and a font weight, every empty state was the same 32 px fūrin, and /login was a centred glyph on a flat cream field.

Four motifs were queued, and a design study found they all resolved to the same three lines of CSS: a CSS mask over a Tier-A token fill. There was no token for that fill, no utility for the mask, and no guard for what the mask does under forced colours. Landing the four independently meant four hardcoded tints that drift apart — none of which TestNoStateHueInChrome would catch, because a decorative rgba() is not a state hue.

Decision

Section titled “Decision”

1. Three derived tints, in a bare :root block. --oto-wash (6% of --oto-text), --oto-wash-heading (12% of --oto-border-strong) and --oto-wash-heading-accent (12% of --oto-accent), each written as color-mix(in oklab, var(--token) N%, transparent).

Two properties of that placement are load-bearing rather than incidental. Derived, not themed: the mix names a token that is themed, so one declaration is correct in both palettes and the two cannot drift. Outside every [data-theme] block: tokens.test.ts reads only theme-prefixed rules, so nothing here is asked for a dark counterpart, and contrast.test.ts demands a measured pair for every token in §M.4/§M.5 — which a decorative tint has no way to supply, because its obligation is a composite and not a pair. The same arrangement --oto-row-h and the §M.8 type steps have had since U6 and ADR 0029.

2. One @utility, oto-ink, carrying the whole CSS half of the accessibility contract. The fill, the mask layers, pointer-events: none, user-select: none, and display: none under forced-colors: active. The last is the one everybody misses and the reason this is a primitive rather than a convention: under forced colours the OS overrides the tint to a system colour at full strength, and a 6% wash becomes an opaque slab across the panel. A per-motif copy of these lines is three chances to omit it.

3. One component, Ink.tsx, carrying the other half. aria-hidden, which no stylesheet can set, and the /motifs/ URL as a typed union, so a misspelt motif is a compile error rather than a mask that resolves to nothing and paints a flat rectangle of wash.

4. The contrast guarantee is geometry, not a carefully chosen opacity. Where ink shares a screen with text it is not made faint enough to be safe — a second mask layer, a horizontal gradient transparent across a fixed centre column, is intersected with the art (mask-composite: intersect) so the ink is incapable of entering the column the text is centred in, at every viewport width and with no media query.

This is the decision with the most evidence behind it. --oto-text-subtle is 4.90:1 on --oto-bg in light and 4.37:1 under a flat 6% wash — an AA failure, in one theme only, at the weight the wash was supposed to be safe at. Nothing in CI would have caught it: contrast.test.ts measures token pairs and not composites, and the axe row that would see it is the one UNWRITTEN entry in §M.7. §M.9 tabulates that failure as a ❌ row and ink.test.ts recomputes it, so the number that justifies the geometry is itself a gate rather than a claim.

5. Four placements permitted, and the refusals are the design. The door; a page heading; a full-page empty state; and nothing else. PanelHeader/PanelTitle/SECTION_LABEL are refused because alert detail stacks six panels and at six a gesture becomes a texture — which is also why the shared EmptyState did not grow a motif prop but got a separate PageEmptyState beside it: six of its eighteen call sites are sub-panels on one alert. Body copy, tertiary text, rows, chips and status surfaces are refused outright.

6. sakura is gated to expired, and that required the product to grow a sentence. expired is the one state whose meaning is transience (§M.1: “oto stopped hearing about this”, never “resolved”), and an empty alert list filtered to it used to borrow the copy a typo’d cluster name gets. isExpiredOnly() now tells the two apart and the screen says which one it is — the motif is the second channel beside that sentence (U1), never a substitute for it.

Consequences

Section titled “Consequences”
  • web/public/ stops being an empty directory with a 0-byte .gitkeep and becomes web/public/motifs/ — five assets and a README that records, beside the files, the three things that are easy to get wrong about a mask (preserveAspectRatio, opaque-black fill, two shapes not one stretched one).
  • /login gains atmosphere and the form stays bare — no bg-surface plate. Plating it is the trivially safe way to guarantee contrast and it turns a threshold into a card.
  • Two page headings (alert-detail, group-detail) carry a brush; the other pages have no text-page heading to put one behind, so nothing there changed.
  • Five full-page empty states carry kumo and one carries sakura. The blocked-filter state on /alerts is a full-page empty state and deliberately gets no motif: kumo means “nothing is wrong”, and there a filter is wrong and there is a fix two lines below it.
  • Two new gates (ink.test.ts, Ink.test.tsx), both reading off disk, both listed in §M.7.
  • Nothing new animates. U9’s decorative one-shot budget is unchanged and still spent by the fūrin.

Alternatives rejected

Section titled “Alternatives rejected”
  • A hardcoded rgba() per motif. The status quo, and the reason this ADR exists. No gate sees it (it is not a state hue), and it is wrong the moment the theme flips.
  • An <img> or a second inlined <svg> per motif. An <img> cannot take currentColor, so it needs one file per theme; an inlined <svg> occupies a slot in the layout, which is the one thing decoration must not do. Logo.tsx is 72 KB of path data and inlining it a second time for the login wash would have doubled that for a shape nobody reads.
  • A motif prop on the shared EmptyState. Rejected on arithmetic: eighteen call sites, six of them sub-panels on one page.
  • Choosing an opacity low enough to look safe, instead of a carve-out. Rejected with a number — see decision 4. It is not that a lower opacity could not be found; it is that nothing in this repository could prove one had been.
  • One stretched asset for both heading shapes. A mask has no fixed aspect, so it is possible. Stretching the thin tapered rule to heading height produces a shape that reads as a wave rather than as a stroke.
  • Kumo as a group boundary. Built twice and rejected twice; recorded in §M.9 and in git-bug 2a64686 so it is not re-derived. It is a taste decision rather than a rules one — the band is Tier A and carries no fact — and nothing here forbids a third attempt that starts from what the first two learned.