From ad410934dfc38b3ab549aea8145a8b20a05d0b37 Mon Sep 17 00:00:00 2001 From: "Tj (bougyman) Vanderpoel" Date: Thu, 13 Aug 2026 14:51:27 -0400 Subject: [PATCH] docs: explain why this project exists and wire accessibility into usage-rules Adds documents/motivation.adoc - the accessibility need driving this whole project, in writing. Adds an Accessibility section to app/usage-rules.md with the concrete commitments it implies (plain linear text output, no meaning via color alone, no TUI as the primary interface, line-based prompts, --output json as a real path), indexed from AGENTS.md alongside Conventional Commits. Closes #102. --- AGENTS.md | 2 ++ app/usage-rules.md | 21 +++++++++++++ documents/motivation.adoc | 65 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 88 insertions(+) create mode 100644 documents/motivation.adoc diff --git a/AGENTS.md b/AGENTS.md index e5f24ca..ff43e98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,8 @@ and best practices for agents to follow. - Conventional Commits: app/usage-rules.md — enforced by the `commit-msg` and `pre-push` hooks at `githooks/` (run `mix setup` once per clone to activate them). +- Accessibility: app/usage-rules.md — the actual reason this project + exists; see documents/motivation.adoc for the full why. diff --git a/app/usage-rules.md b/app/usage-rules.md index 17ea9a2..37b0996 100644 --- a/app/usage-rules.md +++ b/app/usage-rules.md @@ -16,3 +16,24 @@ - Enforced in CI across a whole PR's commit range by the same `ci/conventional_commits.sh` the `pre-push` hook uses (skips GitHub's own auto-generated update-branch merge commits). + +## Accessibility + +- This project exists so its author can keep using Linear from a terminal + and a screen reader after losing sight entirely — see + `documents/motivation.adoc` for why. Every design/review decision here + weighs accessibility accordingly, not as a nice-to-have. +- Plain, linear text output is first-class: every command's normal output + must read correctly top-to-bottom through a screen reader, with no + reliance on spatial layout or color to convey meaning. +- Never encode meaning in color alone (success/failure, warnings, which + field is which) — color may only decorate a signal that's also present + in the text itself. +- No TUI as the primary interface for anything `lc` does — full-screen, + redraw-based UIs fight screen readers. If one's ever added, it must be + optional, never required. +- Interactive prompts stay line-based (readline-style) — nothing that + repaints the screen, uses cursor-position tricks, or expects visually + tracking a moving selection. +- `--output json` stays a fully-supported second path for every command, + not just a scripting afterthought. diff --git a/documents/motivation.adoc b/documents/motivation.adoc new file mode 100644 index 0000000..fb2365e --- /dev/null +++ b/documents/motivation.adoc @@ -0,0 +1,65 @@ += {my-title} +Tj Vanderpoel (bougyman) +:revdate: Aug 14, 2026 +:my-title: Motivation +:icons: font +:env-github: +ifdef::env-github[] +:tip-caption: :bulb: +:note-caption: :information_source: +:important-caption: :heavy_exclamation_mark: +:caution-caption: :fire: +:warning-caption: :warning: +endif::[] +:toc: + +== Why this exists + +I have a progressive eye condition. I don't know when it will take the rest +of my sight, only that it will. When it does, Linear's web app - like every +other visually-rendered web UI - stops being something I can use. A +terminal, paired with a screen reader, doesn't. + +`linear-cli` isn't a convenience project or a learning exercise that +happens to be about Linear (`documents/initial-plan.adoc` frames it that +way, and that's true too - but it's not the reason it exists). It's the +tool that lets me keep doing this job after my eyes stop being part of the +equation. That's the actual requirement driving it, and it doesn't expire +when the port is "done." + +== What this means going forward + +Accessibility isn't a feature to schedule - it's the reason this codebase +exists at all. Concretely, that means: + +* **Plain, linear text output stays first-class.** Every command's normal + output has to read correctly top-to-bottom through a screen reader, with + no reliance on spatial layout, color, or a sighted re-scan of the + terminal to make sense of it. +* **No meaning conveyed by color alone.** Color can decorate; it can never + be the only signal for something the user needs to know (success/failure, + warnings, which field is which). +* **No TUI as the primary interface.** `documents/initial-plan.adoc` + already ruled a TUI out as a non-goal for other reasons; that stance now + has a harder requirement behind it. A full-screen, redraw-based interface + fights screen readers instead of working with them. If a TUI or dashboard + (e.g. Stokowski's) ever becomes part of this project's own surface, it + has to be optional, never the only way to get something done. +* **Interactive prompts stay simple.** Standard line-based prompts (the + kind `IO.gets`/readline-alikes produce) work fine with a screen reader. + Anything that repaints the screen, relies on cursor-position tricks, or + expects the user to visually track a moving selection doesn't. +* **Machine-readable output stays a real, tested path.** `--output json` + isn't just for scripting - it's a second correct way to consume anything + this tool produces, and it should stay that easy to reach for every + command. +* **When in doubt, test it the hard way.** Read the actual output linearly, + color stripped, top to bottom, before deciding a change is done. If that + doesn't make sense read that way, it isn't finished. + +== A note for whoever works on this next + +This applies to human contributors and to any agent (Claude or otherwise) +picking up work in this repo. Don't treat accessibility as one more +non-functional requirement to weigh against others. It's the actual +reason `lc` exists. Weigh changes against it accordingly.