Skip to content

Commit 474e62e

Browse files
authored
docs: explain why this project exists and wire accessibility into usage-rules (#103)
## Summary - 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 stays first-class, no meaning conveyed by color alone, no TUI as the primary interface, line-based prompts, `--output json` as a fully-supported path for every command. - Indexes it from `AGENTS.md`'s Standards section, same pattern as Conventional Commits. - Closes #102. ## Test plan - [x] Reviewed `documents/motivation.adoc` content directly with the author before writing - [x] Confirmed `app/usage-rules.md`/`AGENTS.md` additions don't overlap with the still-unmerged dogfooding section in #101 - independent, non-conflicting appends to the same files 🤖 Generated with [Claude Code](https://claude.com/claude-code)
1 parent cb29772 commit 474e62e

3 files changed

Lines changed: 88 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ and best practices for agents to follow.
1717
- Conventional Commits: app/usage-rules.md — enforced by the `commit-msg`
1818
and `pre-push` hooks at `githooks/` (run `mix setup` once per clone to
1919
activate them).
20+
- Accessibility: app/usage-rules.md — the actual reason this project
21+
exists; see documents/motivation.adoc for the full why.
2022

2123
<!-- usage-rules-start -->
2224
<!-- ash-start -->

app/usage-rules.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,24 @@
1616
- Enforced in CI across a whole PR's commit range by the same
1717
`ci/conventional_commits.sh` the `pre-push` hook uses (skips GitHub's own
1818
auto-generated update-branch merge commits).
19+
20+
## Accessibility
21+
22+
- This project exists so its author can keep using Linear from a terminal
23+
and a screen reader after losing sight entirely — see
24+
`documents/motivation.adoc` for why. Every design/review decision here
25+
weighs accessibility accordingly, not as a nice-to-have.
26+
- Plain, linear text output is first-class: every command's normal output
27+
must read correctly top-to-bottom through a screen reader, with no
28+
reliance on spatial layout or color to convey meaning.
29+
- Never encode meaning in color alone (success/failure, warnings, which
30+
field is which) — color may only decorate a signal that's also present
31+
in the text itself.
32+
- No TUI as the primary interface for anything `lc` does — full-screen,
33+
redraw-based UIs fight screen readers. If one's ever added, it must be
34+
optional, never required.
35+
- Interactive prompts stay line-based (readline-style) — nothing that
36+
repaints the screen, uses cursor-position tricks, or expects visually
37+
tracking a moving selection.
38+
- `--output json` stays a fully-supported second path for every command,
39+
not just a scripting afterthought.

documents/motivation.adoc

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
= {my-title}
2+
Tj Vanderpoel (bougyman) <tj.vanderpoel@prizepicks.com>
3+
:revdate: Aug 14, 2026
4+
:my-title: Motivation
5+
:icons: font
6+
:env-github:
7+
ifdef::env-github[]
8+
:tip-caption: :bulb:
9+
:note-caption: :information_source:
10+
:important-caption: :heavy_exclamation_mark:
11+
:caution-caption: :fire:
12+
:warning-caption: :warning:
13+
endif::[]
14+
:toc:
15+
16+
== Why this exists
17+
18+
I have a progressive eye condition. I don't know when it will take the rest
19+
of my sight, only that it will. When it does, Linear's web app - like every
20+
other visually-rendered web UI - stops being something I can use. A
21+
terminal, paired with a screen reader, doesn't.
22+
23+
`linear-cli` isn't a convenience project or a learning exercise that
24+
happens to be about Linear (`documents/initial-plan.adoc` frames it that
25+
way, and that's true too - but it's not the reason it exists). It's the
26+
tool that lets me keep doing this job after my eyes stop being part of the
27+
equation. That's the actual requirement driving it, and it doesn't expire
28+
when the port is "done."
29+
30+
== What this means going forward
31+
32+
Accessibility isn't a feature to schedule - it's the reason this codebase
33+
exists at all. Concretely, that means:
34+
35+
* **Plain, linear text output stays first-class.** Every command's normal
36+
output has to read correctly top-to-bottom through a screen reader, with
37+
no reliance on spatial layout, color, or a sighted re-scan of the
38+
terminal to make sense of it.
39+
* **No meaning conveyed by color alone.** Color can decorate; it can never
40+
be the only signal for something the user needs to know (success/failure,
41+
warnings, which field is which).
42+
* **No TUI as the primary interface.** `documents/initial-plan.adoc`
43+
already ruled a TUI out as a non-goal for other reasons; that stance now
44+
has a harder requirement behind it. A full-screen, redraw-based interface
45+
fights screen readers instead of working with them. If a TUI or dashboard
46+
(e.g. Stokowski's) ever becomes part of this project's own surface, it
47+
has to be optional, never the only way to get something done.
48+
* **Interactive prompts stay simple.** Standard line-based prompts (the
49+
kind `IO.gets`/readline-alikes produce) work fine with a screen reader.
50+
Anything that repaints the screen, relies on cursor-position tricks, or
51+
expects the user to visually track a moving selection doesn't.
52+
* **Machine-readable output stays a real, tested path.** `--output json`
53+
isn't just for scripting - it's a second correct way to consume anything
54+
this tool produces, and it should stay that easy to reach for every
55+
command.
56+
* **When in doubt, test it the hard way.** Read the actual output linearly,
57+
color stripped, top to bottom, before deciding a change is done. If that
58+
doesn't make sense read that way, it isn't finished.
59+
60+
== A note for whoever works on this next
61+
62+
This applies to human contributors and to any agent (Claude or otherwise)
63+
picking up work in this repo. Don't treat accessibility as one more
64+
non-functional requirement to weigh against others. It's the actual
65+
reason `lc` exists. Weigh changes against it accordingly.

0 commit comments

Comments
 (0)