Log inSign up

stevekrouse

legibility

Public
legibility.fyi — making the concept of legibility legible
Edit with AI
2 Branches
Val Town is a collaborative website to build and scale JavaScript apps.
Deploy APIs, crons, & store data – all from the browser, and deployed in milliseconds.
Sign up now
main.tsx
README.md

legibility.fyi

An info-site that makes the idea of legibility legible.

Legibility: how easily something can be understood.

Most writing about legibility is about its downside — James C. Scott's Seeing Like a State, the state flattening the complexity it can't read. This site is about the other side: legibility as one of the most powerful tools we have, for thinking and for getting what you want. "Legibility, by people who don't hate it."

The site has to practice what it preaches. If you can't understand legibility at a glance here, the site has failed at its one job. So it stays short, and lets examples do the teaching.

Pages

  • / — the definition and a few sharp examples.
  • /gallery — legible-vs-illegible pairs.
  • /references — a chronological reading pile.
  • /ask — a SQLite-backed directory of excellent public asks.
  • /ask/:slug — a canonical page for one ask.

The long, personal version of the argument lives as an essay on stevekrouse.com, not here.

Tech

Val Town val stevekrouse/legibility. Hono + JSX SSR (npm:hono/jsx, React-free), Twind for styling, and val-scoped SQLite for the ask directory and bot event ledger. main.tsx is wrapped with Val Town's hotReload.

Page content is JSX markup, not HTML template strings. Ask.md remains as the legacy source for the initial directory import; the live index now reads entries.

@legibility_bot

Ledge E Bill curates strong public asks, answers questions about legibility, handles useful mentions and DMs, edits directory entries, escalates difficult decisions to Steve, and follows authors whose asks are added.

GET and POST /bot/twitter_webhook implement X CRC validation and signed event delivery. POST signatures are verified before any payload is stored or processed. Events are deduplicated in bot_events and processed fire-and-forget so X receives a fast acknowledgement.

The system prompt is loaded at runtime from SYSTEM_PROMPT.md. Directory and X actions are constrained in code: replies and DMs can target only the originating channel, ask_dad can target only Steve's fixed user ID, authors are verified before follows, and update/delete authorization is checked.

Required environment variable names:

  • TWITTER_CONSUMER_KEY
  • TWITTER_CONSUMER_SECRET
  • TWITTER_BEARER_TOKEN
  • TWITTER_ACCESS_TOKEN
  • TWITTER_ACCESS_TOKEN_SECRET
  • TWITTER_OAUTH2_CLIENT_ID
  • TWITTER_OAUTH2_CLIENT_SECRET
  • TWITTER_OAUTH2_ACCESS_TOKEN
  • TWITTER_OAUTH2_REFRESH_TOKEN

See bot/README.md for architecture, verification, replay, and audit restore instructions. No credential values belong in code, docs, logs, or reports.

Next steps