Focus Ladder

Turn a task you can't start into five-minute rungs, shown one at a time. Keyboard-first, screen-reader friendly, offline, no account, built for ADHD and executive dysfunction.

Comment

The problem, and who it is for

For a lot of people with ADHD, executive dysfunction, anxiety or plain burnout, the hard part of a task is not doing it. It is starting it. A to-do item like "write the essay" sits there for days because it has no first move, and every productivity app answers by adding more structure around the same unstartable item: due dates, priorities, colour labels, streaks. The structure becomes one more thing to feel bad about.

Focus Ladder is for one person in one moment: someone staring at a task that has become a wall. It is not a planner or a to-do list. It does three things and nothing else.

What it does

  1. Brain dump → ladder. You type whatever is weighing on you, messy is fine, several tasks at once if you like. Focus Ladder turns each task into a ladder of rungs where every rung is five minutes or less and the first rung is always physical: open the document, stand in the room, put the book in front of you. Mention a deadline and that task goes first.
  2. One rung at a time. The focus view shows exactly one rung, why it matters, and six big buttons: Done (D), Too big (B), Again (A), Not now (S), a gentle timer (T), and Stuck? (?). "Too big" splits a rung into two-minute pieces, and splitting again always makes them smaller, so it converges on something you can actually begin. "Stuck?" offers three ways past the wall, none of which is giving up.
  3. No shame mechanics. No streaks, no red, no overdue counters. Skipping is a decision, not a failure. The finish screen counts minutes of progress, not minutes you "should" have done.

It works offline, installs as an app, needs no account, and sends nothing anywhere unless you choose to connect your own AI provider.

Accessibility was the design brief, not a checklist

  • Everything works with the keyboard alone, with visible focus. Shortcuts never fire while you are typing.
  • Focus moves to the heading on every view change, and aria-live regions announce rung changes, timer events and results, so screen-reader users always know where they are.
  • Four text sizes, system / light / dark / high-contrast themes, Atkinson Hyperlegible and monospace font options, and reduced motion, all defaulting to your system preferences.
  • Every control is a real button or input with a label; every target is at least 44 px.
  • axe-core runs against every rendered view in the automated test suite.

How I built it

Plain HTML, CSS and ES modules. No framework, no build step, zero runtime dependencies. The deployed site on GitHub Pages is the source tree served as-is.

The heart is a deterministic ladder engine (src/engine/). A parser splits the dump into tasks and extracts the verb, the object, any quantity ("read 3 chapters" produces three reading rungs) and deadline hints. Each task is scored against 23 task archetypes (writing, studying, admin, cleaning, applying, coding, calls, cooking and more); verb matches count extra and broad archetypes are down-weighted so "finish the problem set" lands on assignment, not generic project. The matching template is filled with the person's own words and then five invariants are enforced and tested: rungs are 1–5 minutes, the first rung is physical setup of ≤ 2 minutes, a task has at most 10 rungs, deadline tasks come first, and the same input always gives the same ladder.

AI mode is optional and bring-your-own-key. Settings accept any OpenAI-compatible endpoint (presets for Groq's free tier, OpenAI, Gemini and local Ollama). The model is asked for strict JSON; the reply is validated field by field, passed through the same invariants, and if anything is off you get the template ladder with a note. The key lives only in your browser and is excluded from exports. The app never breaks because the AI did.

Persistence is localStorage with a safe in-memory fallback (sandboxed iframes and some private modes throw on access). A service worker caches the shell for offline use. The chime is two sine notes from the Web Audio API, so there are no audio files to download.

Tests: 82 Vitest tests cover the parser, every archetype template (minutes, first-rung rule, banned shaming words), ladder invariants, splitting convergence, AI validation and fallback with a mocked fetch, persistence and export/import, plus axe-core accessibility checks on every view rendered in jsdom. CI runs them on every push.

Challenges

  • Template wording that reads like a person wrote it. Early output said things like "Open 3 chapters of the stats textbook". Fixing it meant stripping captured quantities from the object, keeping compound phrases intact ("5 shirts and 2 towels"), and rewording templates to tolerate "about" clauses.
  • Broad verbs beating specific nouns. "Finish the problem set" matched the generic project archetype because finish earned a verb bonus. Archetype weights fixed it, and the matching test table now pins 23 cases.
  • Things that only break in the real world. localStorage access throws inside sandboxed iframes, which would have killed any embedded demo; a CSS display rule silently defeated the hidden attribute on the timer; a single replacement-pattern character sequence corrupted the demo bundle. Each one got a test or a guard.

What I learned

The product is the constraints, not the features. Once "five minutes or less" and "first rung is physical" were enforced in code and tests rather than just written in a design doc, every other decision got easier, including what not to build (no scheduling, no streaks, no accounts). I also learned that accessibility work done first makes the keyboard-only demo the best demo, not a compromise.

Limitations

  • Template mode recognises 23 task families; an unrecognised task gets a sensible generic ladder, not a tailored one.
  • English only for now; deadline and quantity detection are heuristic.
  • AI mode depends on the provider you pick allowing browser requests (Groq, OpenAI and Gemini do; Ollama needs OLLAMA_ORIGINS).
  • Automated and keyboard testing so far. A full screen-reader audit with real users is the next step, and I would love help from people who use NVDA, JAWS or VoiceOver daily.

What's next

User testing with ADHD and neurodivergent student groups; a shared-ladder link so a friend or coach can see the same rungs ("body doubling" without a call); more archetypes and the first non-English templates; an optional on-device model for AI mode so even that needs no key.

Pre-existing work and AI assistance

No pre-existing codebase was used; everything was built during the Taskforge window. The code, tests and documentation were written with substantial AI pair-programming assistance (Claude, through Hyperagent), working from my concept, design principles and scope decisions. I reviewed the output, ran the test suite and tested the app in the browser before submitting. Example tasks in the app and video are generic and contain no personal data.

Built With

Share this project:

Updates

Submission history