DEV Community: Sinisa Kusic

After Knowledge, Discipline

Sinisa Kusic — Tue, 28 Apr 2026 09:04:17 +0000

Anatomy of a Claude Code setup that pays for itself

The most common reaction when I show people my Claude Code workflow is some version of: "isn't that a lot of tokens?"

It is. The flow front-loads context, plans before it implements, runs scripted checks after edits, and writes structured artifacts to disk for later steps to pick up. Compared to typing "build me a feature" into a fresh chat, it spends more.

It also does the thing.

That second sentence is the one most takes on AI-assisted development skip over. The cost objection treats tokens as the only line item on the invoice. The bigger line item, by a wide margin, is the cost of correcting an agent that drifted out of scope, hallucinated an API, edited the wrong file, or confidently produced something that has to be thrown away. Once you account for that, the calculus inverts. Structure is cheaper than chaos.

This article is an anatomy of the structure I landed on. Everything described here lives in my dotfiles, public, at github.com/ku5ic/dotfiles/tree/main/claude. I will link the actual files as I go so you can read or steal whatever is useful.

The interface was already there

Before walking through the parts, it is worth saying out loud what the parts are made of, because nobody had this on their 2026 bingo card.

The interface that makes AI agents predictable and produces quality output is not a vector database. Not a fine-tuned model. Not a proprietary framework. Not an orchestration layer with a clever name.

It is markdown files in a sensible folder structure.

CLAUDE.md at the repo root. A docs folder the agent reads before it touches code. Command files that encode a workflow. Rules files that encode standards. Plain text. Version controlled. Diffable. Greppable. The exact tooling we have had for three decades.

For a couple of years the industry poured capital into building new primitives for LLMs. New storage layers, new retrieval mechanisms, new agent protocols, new runtime abstractions. Most of it was solving a problem the models did not actually have.

The models were trained on open source. Open source runs on markdown and folders. READMEs, contributing guides, architecture docs, ADRs, issue templates. That is the native format of the corpus. Of course the models respond to it. Of course structure in a repo produces structure in the output.

The unlock was not technical. It was noticing that the interface was already there.

Three things follow from that, and the rest of this article is mostly working out the implications.

First, the quality of your output is bounded by the quality of your written context. A thin CLAUDE.md produces thin work. A precise one produces precise work. Architecture documents, coding standards, and explicit constraints are no longer dead weight. They are executable.

Second, folder structure is a contract. When the agent can infer where things belong from the tree alone, it stops guessing. When it cannot, it invents. The same property that makes a codebase readable to a new hire makes it legible to a model.

Third, the skills that compound here are not prompt engineering. They are the unglamorous ones. Writing clearly. Structuring information. Keeping documentation close to the code it describes. The things senior engineers were already supposed to be doing.

The dotfiles I am about to walk through are not exotic. They are markdown files in folders. Every guardrail, every workflow stage, every skill, every command is a .md file with frontmatter, or a small shell script, or a JSON config. The whole repo is roughly 150KB of plain text. It works because the model was trained on plain text.

The joke writes itself. After all the frameworks and all the infrastructure, the winning move was a folder of markdown files and the discipline to keep them current. The future of AI-assisted engineering looks a lot like good engineering.

How it propagated

It did not start as a system. It started as one project.

There was a particular repo where I stopped treating Claude Code as a faster autocomplete and started treating it as a junior engineer who needed an onboarding document. I wrote a CLAUDE.md for it. The file captured the things I kept correcting Claude on: stop adding decorative comments, match the existing test style, do not edit lockfiles, do not invent file paths. It worked. The next project I touched, I copied it over. By the third repo I was diffing them against each other, and by the fourth I was tired of doing that.

The pattern was obvious in retrospect. The same five-stage rhythm kept emerging in every project regardless of stack: figure out what is here, plan the change, implement it in small steps, test, review. The same handful of guardrails kept being needed: do not push to main, do not commit AI signatures, do not pipe curl into a shell, do not write to my zshrc directly. The same handful of mini-context-collectors kept being needed: what is the project root, what stack is this, what is the base branch, what does the diff look like.

Once I saw the pattern, I extracted it. The dotfiles repo is the result. It is not a framework and not a methodology. It is just the parts of "use Claude Code well" that turned out to be project-independent.

The shape of the thing

Four namespaces of slash commands, six skills, four hooks, a handful of helper scripts, a settings.json that does real work, and a global CLAUDE.md that ties it together. Top-level layout:

claude/
  CLAUDE.md
  settings.json
  bin/
    detect-stack.sh
    project-name.sh
    project-root.sh
    git-base.sh
    run-checks.sh
  commands/
    flow/      preflight, plan, implement, test, review, fix, resume
    audit/     a11y, debt, doc-drift, perf, security
    meta/      feature, prompt, retro
    write/     commit, pr, release-notes, stakeholder
  hooks/
    inject-context.sh
    guard-bash.sh
    guard-edit.sh
    guard-commit.sh
    sanitize-output.sh
  skills/
    react-patterns, django-patterns, test-patterns,
    wcag-audit, security-patterns, markdown-report

The cost argument cuts through all of it. Each piece exists because the alternative, having Claude figure it out fresh every time, was demonstrably more expensive in the only currency that matters: my time spent re-steering it.

CLAUDE.md as the contract

Source: claude/CLAUDE.md.

The global CLAUDE.md is the document Claude Code reads on every session. Project-level CLAUDE.md files extend it. Mine is roughly 2,500 words and covers: project boot protocol, output rules, output discipline, token discipline, code style, verification before acting, anti-fabrication, environment and stack, commands and side effects, git workflow, decision frameworks, scope and planning, principles, ambiguity handling, communication style, the failure mode playbook, scratch artifact naming, and the canonical command namespace.

A few sections are worth singling out because they are the ones that pay for themselves the fastest.

The anti-fabrication section is short and explicit. Do not invent file paths that have not been seen via Read or Glob. Do not invent API shapes. Do not invent version numbers; read the lockfile or --version. Do not invent test results; if a test was not run, say "not run." This eliminates a specific failure mode that used to cost me real time: Claude confidently writing code against an imagined version of an API, me discovering it three steps later, both of us backing out the change.

The token discipline section tells Claude how to read efficiently: prefer rg and grep for locating, use Read only for understanding, cap git log to twenty entries unless justified, do not re-read a file in the same session unless an edit changed it, skip the obvious noise directories (node_modules, .next, dist, build, coverage, .turbo, vendor, target, __pycache__, .venv). This is direct token savings, but the more important effect is keeping Claude's context window populated with signal instead of noise.

The failure mode playbook is the most underrated section. It tells Claude what to do when quality checks fail, when the plan does not match reality, when a tool is unavailable, when context is exhausted, when the user issues a correction. Without it, the default behavior is to hide problems, keep going, and hope. With it, the default behavior is to stop and surface. Stopping early is one of the highest-leverage things an agent can do, and it does not happen unless you ask for it explicitly.

The flow namespace

Source: claude/commands/flow/.

Five commands form the main path of any feature work, plus two for off-ramp situations.

/flow:preflight

flow/preflight.md. Effort: medium. Read, do not write.

Preflight establishes shared understanding before any code is touched. It reads the project root CLAUDE.md, identifies the minimum file set the task will touch, reads those files, lists the CI checks the project actually defines (typecheck, lint, test, format) without running them, and notes uncommitted work and recent direction from git status and git log -5 --oneline.

The hard cap is twelve files read across preflight. If the minimum set exceeds twelve, the command stops and asks me to scope the task down. That cap is deliberate. A task that needs more than twelve files of context to understand is a task that needs to be split, not a task that needs more reading.

The output is a short preflight report written to ~/.claude/scratch/preflight-<project-name>-<YYYYMMDD-HHMM>.md. Subsequent commands read it.

/flow:plan

flow/plan.md. Effort: heavy.

Plan turns a confirmed task into an ordered, atomic implementation plan with explicit tradeoffs. The procedure is constrained: consider two implementation approaches, score each on scope, risk, effort, and reversibility, pick one and justify why, break the chosen approach into phased steps where each step is independently committable and leaves the codebase working, identify the test strategy per step, identify the rollback path.

Two approaches is the floor. It is not "consider many alternatives." It is "do not pick the first thing that comes to mind without comparing it to one other thing." That single constraint catches a surprising number of bad first instincts.

The plan is written to ~/.claude/scratch/plan-<project-name>-<task-slug>-<YYYYMMDD-HHMM>.md. I read it, push back on it, edit it directly, or send it back for revision. Implementation does not start until I have approved a plan I trust.

/flow:implement

flow/implement.md. Effort: heavy.

Implement executes one step of an approved plan. The scope rules are strict: stay in the files the plan names, do not refactor unrelated code, do not upgrade or add dependencies unless the plan explicitly includes them, comments only where the code does not explain itself, explain why and not what. If the plan turns out to be wrong mid-implementation, stop and surface the mismatch. Do not silently expand.

After each step the command runs the narrow verification the plan prescribed (one file's tests, one type check), then pauses and reports what was done, what was verified, and what is left in the step. The pause is enforced by the global rule in CLAUDE.md: pause after each /flow:* step and wait for user approval before continuing.

/flow:test

flow/test.md. Effort: medium.

Test adds or updates tests for the recent implementation work. It loads the test-patterns skill, scopes testing to the diff via git diff HEAD and git status, mirrors source paths for new test files, and writes tests that verify behavior rather than implementation. It runs the new tests narrowly first (single file), then the adjacent suite. After narrow tests pass, it runs the full check script (run-checks.sh, more on this below).

The discipline is in what it will not do: it will not introduce a new test framework, will not add snapshot tests if the project does not use them, and will not silently change implementation if a test reveals the implementation was wrong. That last one is important. A failing test is a signal, not a problem to suppress.

/flow:review

flow/review.md. Effort: heavy.

Review is the senior pass before handoff. It runs run-checks.sh to establish baseline check state (so pre-existing failures are noted before review begins), loads the relevant patterns skills for the stack, and reviews in eight ordered categories: correctness, types, accessibility, security, design principles, performance, maintainability, tests. Sections with no findings are skipped, not padded.

Two rules in this command matter more than the categories. First, an empty review is a valid result. Second, do not flag personal style unless it violates the project's lint config. Both push back against the agent's natural drift toward "find something to say." Reviews that invent findings to look thorough are reviews I have to spend tokens disagreeing with.

The review output goes to ~/.claude/scratch/review-<project-name>-<scope-slug>-<YYYYMMDD-HHMM>.md using the markdown-report skill format with a severity rubric.

/flow:fix and /flow:resume

flow/fix.md is for surgical fixes from a failing signal: test failure, type error, runtime error, lint error. Hypothesis stated in one sentence before changing anything. Smallest change that addresses the root cause. Stop conditions: if the hypothesis requires a refactor, stop and propose a separate /flow:plan. If the fix touches more than three files, stop and surface; this is no longer a fix. If the fix changes a public API, stop and ask for a plan.

flow/resume.md reorients against a partially executed plan. It diffs the plan against the current code state, reports which steps are done, partial, or pending, and recommends the next concrete action. It does not implement.

The audit namespace

Source: claude/commands/audit/.

Five audits, all stack-aware via the injected <repo-context> (described below).

audit/a11y.md runs a WCAG 2.2 AA audit using the wcag-audit skill. Bails if no frontend surface is detected.

audit/debt.md surfaces technical debt and architectural drift. Be direct and skeptical. Do not list minor style preferences.

audit/doc-drift.md detects divergence between code and the docs that describe it. Comparison task, does not rewrite docs. Routed to Haiku via model: haiku in the frontmatter, because the work is mechanical comparison rather than judgment.

audit/perf.md is static analysis. It does not run benchmarks. It flags what is likely slow and names what to measure.

audit/security.md is defensive review. Assume any input from outside the process boundary is hostile. Loads security-patterns.

Audits are not on the main path. They run when scope warrants.

The meta namespace

Source: claude/commands/meta/.

meta/feature.md shapes a fuzzy feature request into a structured brief before planning. It is the step before /flow:plan for tasks that are not yet sharp enough to plan against. Heavy effort, because the work is thinking.

meta/prompt.md turns a fuzzy ask into a sharp Claude Code prompt with context and acceptance criteria. Light effort, routed to Haiku. The work is rewriting with structure.

meta/retro.md is a structured retrospective for an incident, sprint, or completed feature. Routed to Haiku because it is structure-driven rather than analysis-heavy.

The write namespace

Source: claude/commands/write/.

All four are routed to Haiku via frontmatter, all four are light effort, all four are pure transformation tasks.

write/commit.md generates a commit message from the staged diff, matching project style. Reads git log --oneline -20 to detect the project's convention (Conventional Commits, ticket prefix, plain). Does not run git commit.

write/pr.md generates a PR description from the current diff. No codebase reading beyond the diff provided.

write/release-notes.md groups and rewrites commits unique to the current branch versus its base.

write/stakeholder.md reframes a technical finding for a non-technical audience.

These are the clearest case for model selection. Generating a commit message from a diff does not require Sonnet's reasoning. Haiku does it as well, faster, and at a fraction of the cost. The model choice is in the command's frontmatter, not in my head.

Effort tags and model routing

Every command starts with an effort tag: light, medium, or heavy. The tags are advisory for me when picking what to run, but they map cleanly to the model selection in frontmatter.

Light effort, mechanical transformation work runs on Haiku: the four write/* commands, audit:doc-drift, meta:prompt, and meta:retro. Everything else runs on the default model (Sonnet for me) because the work is judgment-heavy: planning, implementing, reviewing, debt audits, security audits, performance audits, feature briefs.

The cost argument is concrete here. Generating a PR description on Sonnet is a small overpayment. Doing it across every PR for a year is not. Routing it to Haiku via one line in frontmatter, model: haiku, recovers the difference without changing anything about how I invoke the command.

Skills as on-demand expertise

Source: claude/skills/.

Six skills, each a markdown file with frontmatter that tells Claude when to load it.

react-patterns: React and Next.js patterns, anti-patterns, and review checklist
django-patterns: Django patterns and review checklist
test-patterns: conventions for Vitest, Jest, RTL, Playwright, pytest
wcag-audit: WCAG 2.2 AA checklist and severity rubric
security-patterns: security checklist for frontend and backend
markdown-report: consistent format for audit and review artifacts

Skills are loaded on demand by the commands that need them. /flow:plan loads the patterns skill matching the detected stack. /flow:test loads test-patterns. /audit:a11y loads wcag-audit. /audit:security loads security-patterns. /flow:review loads multiple skills depending on what the diff touches.

This is the design choice that does the most for the cost argument: skills are not in the system prompt by default. They are pulled in only when relevant. The token budget for "everything Claude could possibly know about React" is paid only on tasks that actually involve React.

Hooks and the permission system

Source: claude/hooks/ and claude/settings.json.

This is the layer that takes the agent from "useful most of the time" to "I trust it to operate in my repos." Five hooks, registered in settings.json against tool events.

inject-context.sh

hooks/inject-context.sh. Fires on UserPromptSubmit. Runs once per session, gated by a session marker file in ~/.claude/scratch/.

It calls project-name.sh and project-root.sh, looks for a cached stack report at ~/.claude/cache/stack/<project-name>.txt, invalidates the cache if any stack sentinel file (package.json, pyproject.toml, Gemfile, Cargo.toml, go.mod) is newer than the cache, regenerates by running detect-stack.sh if needed, and prepends a <repo-context> block to the prompt:

<repo-context>
root: /Users/me/Code/some-project
js: yes (typescript, react, vitest, eslint) [pnpm]
node: 20.11.1
python: no
ruby: no
rust: no
</repo-context>

The cache is the part that matters for cost. Stack detection is not free. It runs jq over package.json, greps Python config files, checks for monorepo signals. Doing it on every prompt would be wasteful. Doing it once per session and reusing it across the conversation is cheap. Doing it once per project until a sentinel file changes is cheaper still.

The detection itself lives in bin/detect-stack.sh. Output is terse on purpose; each line is meant to be scanned in under a few hundred tokens of context.

The flip side of inject-context is that the global CLAUDE.md requires it. The very first line of the project boot protocol is: "Check the injected <repo-context> block. If absent, surface the issue and stop. The inject-context.sh hook did not fire." If the hook fails silently, Claude does not silently proceed without context. It stops and tells me.

guard-bash.sh

hooks/guard-bash.sh. Fires on PreToolUse for Bash. Reads the proposed command from stdin and blocks patterns that the permission system cannot reliably express.

What it blocks: fork bombs, piping network downloads into a shell interpreter, writes to raw disk devices (/dev/sd*, /dev/nvme*, /dev/disk*), direct writes to shell rc files, redundant shell redirects (2>&1 and &>, which the Bash tool doesn't need and which trigger permission prompts). Per-segment, after splitting on &&, ||, ;, and newlines: rm -rf against root or home or cwd, low-level disk tools (dd, shred, wipefs, mkfs), chmod 777, broad chmod +x against root or home, git push --force without --force-with-lease, force push to protected branches, git reset --hard on protected branches, --no-verify on commit/push/merge/rebase, git config --global from a project session, destructive SQL via psql -c, destructive redis-cli (FLUSHALL, FLUSHDB, CONFIG SET), find -delete, find -exec rm, keychain deletion, global package installs.

The contract is simple: exit 0 to allow, exit 2 to block with a reason shown to Claude. Any other non-zero exit is a soft failure that does not block. The hook fails open on its own errors. That last detail matters: a buggy guardrail that blocks legitimate commands is its own kind of damage.

guard-edit.sh

hooks/guard-edit.sh. Fires on PreToolUse for Edit, Write, MultiEdit. Blocks edits to lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb, Gemfile.lock, Cargo.lock, composer.lock, poetry.lock, uv.lock), edits inside .git/, and direct edits to shell rc files.

If the edit targets a CI workflow file (.github/workflows/*.yml), the hook logs a warning to stderr but does not block. CI workflow edits are sometimes legitimate but always worth surfacing.

guard-commit.sh

hooks/guard-commit.sh. Fires on PreToolUse for Bash, but only acts on git commit commands.

It blocks AI signatures (Co-Authored-By: Claude, Generated by Claude, robot emoji generation tags) and AI-tell phrasing in the commit subject (Certainly:, Here is:, In this commit:, etc., even when prefixed with a Conventional Commits type). This is the hook that exists because I forgot, more than once, to strip the AI signature from commits before pushing.

sanitize-output.sh

hooks/sanitize-output.sh. Fires on PostToolUse for Edit, Write, MultiEdit. Strips typographic punctuation from written files: em dashes, en dashes, smart quotes, ellipsis characters, Unicode arrows. Replaces them with their ASCII equivalents.

This sounds petty. It is petty. It also catches the case where Claude, despite the explicit rule in CLAUDE.md, writes an em dash anyway. Belt and suspenders. The rule exists in CLAUDE.md so the model usually does the right thing. The hook exists so the model cannot ship the wrong thing even when it slips.

The permission split: allow / ask / deny

Source: claude/settings.json.

The hooks handle the cases where I want a hard block. The permission system in settings.json handles the gradient of "this is fine," "ask me first," and "never."

Examples from the allow list: git status *, git diff *, git log *, git switch *, git stash *, git worktree *, npm run *, pnpm test *, pnpm exec *, npx *, vitest *, tsc *, prettier *, eslint *, rg *, grep *, fd *, find *, gh pr view *, gh pr diff *, gh run list *, Read(**), Edit(**), Write(**), plus the bin scripts. Plus all my skills explicitly listed by name.

Examples from the ask list: npm install *, pnpm add *, brew install *, cargo install *, git push *, git reset *, git rebase *, git commit --amend*, gh pr merge *, gh release create *, rm *, rmdir *, curl *, wget *, edits to config files (.env*, tsconfig*.json, next.config.*, vite.config.*, eslint.config.*, biome.json, prettier.config.*).

Examples from the deny list: sudo *, su *, rm -rf against root or home or cwd, chmod 777, dd *, mkfs *, shutdown *, reboot *, system configuration commands (launchctl, defaults, nvram, scutil, pfctl), reading secrets (.env, *.pem, *.key, SSH private keys, AWS credentials, gh hosts.yml, netrc, pgpass, npmrc, macOS keychains).

The split exists so the agent can move at speed when the operation is safe and stops to ask when the operation is not. Allow-listing read and search tools, scoped git read commands, build commands, and the project's own scripts means the agent does not get stuck asking for permission on routine work. Ask-listing destructive or scope-changing commands means I see them before they happen. Deny-listing things I will never approve under any circumstance means I never have to read another permission prompt about them.

Helper scripts

Source: claude/bin/.

Five small scripts, each doing exactly one thing.

bin/project-root.sh returns the git repo root, falling back to $PWD outside a working tree.

bin/project-name.sh returns a slug-safe project identifier used in scratch artifact filenames. Lowercased, leading dots stripped, non-alphanumeric replaced with dashes, collapsed dashes, trimmed. $HOME becomes home. / becomes root. Empty becomes unknown. The slug stability is what makes "the most recent plan for this project" a reliable thing to ask for.

bin/git-base.sh prints the base branch for the current checkout. Detection order: explicit argument, upstream tracking branch, remote HEAD, common defaults (main, master, develop, trunk). Used by /write:release-notes and elsewhere to compute "commits unique to this branch."

bin/detect-stack.sh emits the compact stack report consumed by inject-context.sh. Detects JS/TS (with framework, package manager, Node version), Python (with framework, in ., backend/, server/, api/), Ruby (with Rails detection), Rust, and monorepo signals (pnpm workspaces, Turbo, Nx, Lerna).

bin/run-checks.sh detects and runs the project's typecheck, lint, format-check, and tests. Each section is independent; failures are reported, not aborted. It is the script /flow:test and /flow:review shell out to.

These are all intentionally boring. They are the parts of "context Claude needs about this project" that should never be regenerated by the agent itself. Boring shell scripts produce stable, slug-safe output. Stable output is what makes scratch artifact naming work, which is what makes /flow:resume work, which is what makes the whole flow recoverable when context runs out mid-task.

Scratch artifacts and the project boundary

The whole flow is held together by a naming convention for artifacts written to ~/.claude/scratch/:

~/.claude/scratch/<kind>-<project-name>-<scope-slug>-<YYYYMMDD-HHMM>.md

kind is preflight, plan, review, feature, retro, etc. project-name is the output of project-name.sh. scope-slug is the task slug or, for some kinds, omitted.

Any command that needs "the most recent X" filters by current project name:

ls -t ~/.claude/scratch/<kind>-<project-name>-*.md | head -1

Never read across projects. If no artifact exists for the current project, run the predecessor command first.

This is what makes the flow durable. A plan written for project A in the morning is still findable by /flow:resume in project A in the afternoon, even after a half-dozen unrelated sessions in other projects in between. The naming convention is the bridge between sessions.

The cost argument, restated

Add it up: a CLAUDE.md that pre-loads the contract. A flow namespace that gates work behind preflight, plan, implement, test, review. An audit namespace that loads heavy checklists only when invoked. A meta namespace for shaping fuzzy work into structured input. A write namespace routed to Haiku for transformation tasks. Skills loaded on demand instead of bundled into the system prompt. A <repo-context> block injected once per session and cached per project. Effort tags that map to model selection. Hooks that block the destructive operations that cost the most to undo. A permission split that lets the agent move on safe work and stop on dangerous work. Scratch artifacts that survive across sessions.

Every one of those is a markdown file, a shell script, or a JSON entry. None of it is a framework. None of it is a vendor primitive. The whole thing is the kind of structure any senior engineer would recognize from a well-run open source project, applied to the agent instead of to a new hire.

Yes, all of this spends tokens. It also prevents the much larger token spend of correcting an under-context, over-confident agent that drifted, hallucinated, or did the wrong thing in the right file. And it prevents the largest cost of all, the one that does not show up on any token meter: my time spent re-steering, re-explaining, and rolling back work that should not have happened.

The constraint was never knowledge. The constraint, once you let an agent into your editor, is discipline at runtime. Discipline does not scale through willpower. It scales through tooling. The dotfiles are what that scaling looks like for me. Yours will look different. The point is that you should have one.

I made a related argument about planning a while back: AI removed the time constraint that used to prevent proper architectural work upstream. This is the downstream version of the same argument. Once planning is cheap, runtime discipline becomes the next thing worth engineering.

Source for everything in this article: github.com/ku5ic/dotfiles/tree/main/claude. MIT licensed. Copy what is useful, ignore what is not, and tell me what you would change.

Accessibility-first looks different from accessibility-compliant

Sinisa Kusic — Sat, 11 Apr 2026 09:00:00 +0000

Passing an axe-core audit is not the same thing as designing for accessibility. The outputs can look identical. The process that produced them is not.

Most component libraries retrofit accessibility. The ARIA roles get added, the keyboard navigation gets wired, the contrast ratios get verified. It passes. But the architecture was not designed around the constraint. It was designed first, then adjusted to meet it.

nuka-ui was built with WCAG 2.2 AA as a hard requirement from the first commit. Not a goal. A constraint. That distinction is in the README. This article is what that sentence means in practice: nine decisions from the codebase where accessibility as a non-negotiable constraint produced an outcome that a retrofit would not.

1. The `hidden` attribute instead of conditional rendering

The default React pattern for a dropdown is {open && <SelectContent />}. It is clean, idiomatic, and wrong for an accessible combobox.

The SelectTrigger has aria-controls pointing to the listbox ID. If the listbox is conditionally rendered, aria-controls references an element that does not exist when the dropdown is closed. The ARIA 1.2 spec technically permits this, but it creates a second problem: SelectItem components register their labels on mount so the trigger can display the selected option's label. If the listbox is not in the DOM, that registration never happens. The trigger has no label data on first render.

The fix is hidden={!open} on the listbox. Always in the DOM, removed from the accessibility tree when not needed, aria-controls always resolves.

<div
  role="listbox"
  id={listboxId}
  hidden={!open}
  aria-hidden={!open}
>
  {children}
</div>

This decision cascades. Because the listbox is always mounted, the label registry must exist before the listbox is visible. SelectItem registers via useLayoutEffect into a Map stored in a ref. A registryVersion state counter increments on each registration, included in a useMemo dependency so SelectTrigger re-renders when items register.

One accessibility requirement. Three implementation consequences. The simpler approach would have worked visually. It would not have worked for screen readers.

2. `aria-controls` and `aria-expanded` are not redundant

SelectTrigger carries both aria-controls and aria-expanded. They answer different questions.

aria-expanded tells the user whether the popup is currently open. aria-controls tells the user which element this control manages. Both are required by the ARIA combobox pattern. Together they allow screen readers to announce the relationship between the trigger and the listbox without the user exploring the DOM. Removing either one degrades the experience even if the visual interface is correct.

The third ARIA attribute on the trigger is aria-activedescendant. When keyboard navigation highlights an option, this attribute points to that option's ID. Focus stays on the trigger. The screen reader announces which option is highlighted.

<button
  role="combobox"
  aria-haspopup="listbox"
  aria-expanded={ctx.open}
  aria-controls={ctx.listboxId}
  aria-activedescendant={ariaActiveDescendant}
/>

One test from the suite worth noting:

it("aria-activedescendant is undefined when no option is highlighted", () => {
  renderSelect();
  expect(screen.getByRole("combobox")).not.toHaveAttribute(
    "aria-activedescendant",
  );
});

The test checks for undefined, not empty string. aria-activedescendant="" is invalid. The attribute must be absent when nothing is highlighted. TypeScript strictness helps: the value is typed as string | undefined, and undefined attributes are not rendered to the DOM.

3. `nameFrom: author` and the accessible name fallback chain

role="combobox" has nameFrom: author in the ARIA spec. This means the visible text inside the trigger does not contribute to the accessible name. A screen reader will not announce the displayed value unless an explicit accessible name is provided.

This surprises developers who test visually. The trigger displays the selected value. It looks labelled. It is not labelled from the screen reader's perspective.

SelectTrigger handles this with a fallback chain:

If the trigger is inside a FormField, the Label component provides aria-labelledby pointing to the label's ID. This takes priority and aria-label is omitted.
If no FormField is present, SelectTrigger derives aria-label from: the selected option label (from the registry), then the placeholder prop, then a hardcoded fallback of "Select".

const ariaLabel = ariaLabelledBy
  ? undefined  // aria-labelledby from FormField takes over
  : (displayLabel ?? placeholder ?? "Select");

const ariaLabelledBy = formCtx.labelId || undefined;

The fallback to "Select" is a last resort that ensures no combobox ships without an accessible name, even if the consumer forgets to provide a label or placeholder. This chain exists because of a specific ARIA rule about this specific role. You only design it if you know the rule before you start.

4. Skeleton's hardcoded `aria-hidden` that cannot be overridden

Most components in nuka-ui accept spread props, including arbitrary ARIA overrides. Skeleton deliberately does not allow aria-hidden to be removed.

Skeleton is purely visual decoration. It conveys no information. Loading state announcements belong on the parent container via aria-busy="true", not on the skeleton elements. If a consumer passes aria-hidden={false}, they create a situation where a screen reader announces a meaningless animated rectangle as content.

The enforcement mechanism is prop ordering. aria-hidden="true" is placed after the ...props spread:

const Skeleton = React.forwardRef<HTMLDivElement, SkeletonProps>(
  ({ className, shape, ...props }, ref) => {
    return (
      <div
        ref={ref}
        {...props}
        aria-hidden="true"  // after spread: cannot be overridden
        className={cn(skeletonVariants({ shape }), className)}
      />
    );
  },
);

The correct pattern puts aria-busy on the container:

<div aria-busy="true" aria-label="Loading posts">
  <Skeleton shape="text" className="h-4 w-3/4" />
  <Skeleton shape="text" className="h-4 w-1/2" />
</div>

Most component libraries give consumers maximum flexibility on the assumption they know what they are doing. The tradeoff is that consumers can also do the wrong thing. Skeleton has one job. The API reflects that.

5. Toast live region urgency tied to intent

Toast uses role="status" with aria-live set dynamically based on intent. Default, success, and warning toasts use aria-live="polite". Danger toasts use aria-live="assertive".

This is not a visual distinction. It changes when and how a screen reader interrupts the user.

aria-live="polite" waits for the user to finish what they are doing, then announces. aria-live="assertive" interrupts immediately. A confirmation toast ("Profile saved") should not interrupt a user who is mid-sentence in a form. A danger toast ("Payment failed") should.

<div
  role="status"
  aria-live={toastItem.intent === "danger" ? "assertive" : "polite"}
  aria-atomic="true"
/>

The tests that enforce the split:

it("has aria-live=assertive for danger intent", () => {
  render(<Toast toast={{ ...baseToast, intent: "danger" }} onDismiss={onDismiss} />);
  expect(screen.getByRole("status")).toHaveAttribute("aria-live", "assertive");
});

it("has aria-live=polite for success intent", () => {
  render(<Toast toast={{ ...baseToast, intent: "success" }} onDismiss={onDismiss} />);
  expect(screen.getByRole("status")).toHaveAttribute("aria-live", "polite");
});

Most toast implementations use one aria-live setting for everything. The distinction here is tied directly to the semantic meaning of intent, which is also used to drive visual styling. The accessibility behavior and the visual behavior are derived from the same prop, which means they stay in sync.

6. Banner's required `aria-label` enforced at the TypeScript level

Banner uses role="region". A region landmark without an accessible name is worse than no landmark: screen reader users navigating by landmarks encounter an anonymous region with no context for what it contains.

The fix is obvious: require aria-label. The interesting part is how nuka-ui enforces it.

Rather than documenting the requirement or adding a runtime warning, aria-label is required at the TypeScript type level. BannerProps uses Omit to strip the optional aria-label from React.HTMLAttributes and re-declares it as required:

export interface BannerProps
  extends Omit<React.HTMLAttributes<HTMLDivElement>, "aria-label">,
    BannerVariantProps {
  "aria-label": string;  // required, not optional
  onDismiss?: () => void;
  action?: React.ReactNode;
}

A consumer who omits aria-label gets a TypeScript error at build time, not a failed audit at review time. The accessibility requirement became a compile-time contract.

This is distinct from Alert, which uses role="alert". Alert is an assertive live region for urgent, transient feedback. Banner is a persistent contextual landmark. The semantic distinction between the two is reflected in the APIs: Alert has no aria-label requirement because its role carries the identity. Banner does, because role="region" does not.

7. Tooltip vs. Popover: the semantic boundary in the API

Tooltip content has pointer-events-none and role="tooltip". Popover content has role="dialog" and receives focus on open.

These are not stylistic choices. They reflect a fundamental ARIA distinction between two types of supplemental content.

role="tooltip" is for non-interactive supplementary information. Triggered by hover and focus. The trigger describes itself with aria-describedby. Focus stays on the trigger. role="dialog" is for interactive regions. Triggered by click. Focus moves into the panel on open.

The structural difference:

// Tooltip: focus stays on trigger, content is non-interactive
const hover = useHover(context, { delay: { open: delay, close: 0 } });
const focus = useFocus(context);
const role = useRole(context, { role: "tooltip" });
// trigger gets aria-describedby, content has pointer-events-none

// Popover: focus moves into panel on open
const click = useClick(context);
const role = useRole(context, { role: "dialog" });
// trigger gets aria-expanded + aria-controls
// PopoverContent focuses first focusable child on open

The PopoverContent focus management:

React.useEffect(() => {
  if (ctx.open) {
    const frame = requestAnimationFrame(() => {
      const focusable = contentRef.current?.querySelector<HTMLElement>(
        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
      );
      if (focusable) {
        focusable.focus();
      } else {
        contentRef.current?.focus();
      }
    });
    return () => cancelAnimationFrame(frame);
  }
}, [ctx.open]);

The requestAnimationFrame is necessary because the portal has just been added to the DOM and layout has not completed. Attempting focus() synchronously inside useEffect is unreliable.

One additional constraint from WCAG 1.4.13: Tooltip opens on focus with no delay. The hover open has a configurable delay (default 600ms). Focus-triggered content must be immediate because the user has already made an explicit navigation action. Applying the hover delay to focus-open would violate that criterion.

The compound component pattern enforces the semantic separation structurally. A consumer cannot accidentally put interactive content inside a Tooltip because the content element has pointer-events-none. The boundary is not just documented. It is built in.

8. RadioGroup roving tabindex: one tab stop, arrow key navigation

RadioGroup implements the roving tabindex pattern. Only one radio in the group is in the tab order at a time (tabindex="0"). All others have tabindex="-1". Arrow keys move between radios and shift the tabindex="0".

This is the correct keyboard interaction model for radio groups per the ARIA Authoring Practices Guide. Tab navigates between form controls. Arrow keys navigate within a group. A group with three radios should cost the user one Tab key press, not three.

case "ArrowDown":
case "ArrowRight":
  e.preventDefault();
  moveFocus("next");
  break;
case "ArrowUp":
case "ArrowLeft":
  e.preventDefault();
  moveFocus("prev");
  break;
case "Home":
  e.preventDefault();
  moveFocus("first");
  break;
case "End":
  e.preventDefault();
  moveFocus("last");
  break;

The test that verifies Tab does not cycle within the group:

it("Tab does not cycle within the group", () => {
  renderGroup({ defaultValue: "green" });
  const radios = screen.getAllByRole("radio");
  const focused = radios.find((r) => r.getAttribute("tabindex") === "0");
  const unfocused = radios.filter((r) => r.getAttribute("tabindex") === "-1");
  expect(focused).toBeDefined();
  expect(unfocused).toHaveLength(2);
});

The visual radio indicator uses sr-only on the native <input type="radio"> rather than display: none or visibility: hidden. The native input remains in the accessibility tree and receives focus. The visual ring is a custom <span aria-hidden="true"> that mirrors the state. Hiding the input entirely would break keyboard navigation. This is the kind of decision that only comes up if you are thinking about accessibility before you start writing styles.

9. The color token rule: adjust lightness only, never chroma or hue

This one is about the design token system, not component code. It is one of the most direct examples of how the accessibility constraint changed an architectural decision.

nuka-ui uses oklch() for all color tokens. An oklch() value has three components: L (lightness), C (chroma), H (hue). Contrast ratio is determined by luminance, which is primarily a function of lightness.

When a color token fails a contrast check, the rule is: adjust L only. Never adjust C or H.

Adjusting chroma or hue to fix contrast changes the color. You get something that passes the checker but is no longer the color you chose. Fixing contrast by adjusting lightness keeps the hue and saturation intent intact.

The primary accent is oklch(44% 0.043 257): hue 257 (a blue-grey direction), chroma 0.043 (intentionally low for a muted slate aesthetic), lightness 44%. That lightness value produces 7.74:1 contrast on white, which is WCAG AAA. The lightness was chosen to clear that bar. The hue and chroma were never touched for contrast reasons.

This rule only works cleanly in oklch(). In hsl(), saturation and lightness interact in non-perceptually-uniform ways. Equal changes in L do not produce equal perceived changes in lightness across hues. oklch() is perceptually uniform: adjusting L produces consistent perceived results regardless of hue. The color space was chosen in part because it makes the accessibility constraint easier to enforce consistently.

The actual cost of the constraint

These are not exotic edge cases. Every dropdown, every loading state, every notification system, every color token in any component library runs into exactly these decisions. The difference is when you encounter them.

If accessibility is a constraint from the start, you design the registry pattern before you wire up the combobox because you know you will need it. You make aria-label required on Banner before any consumer uses the component. You choose oklch() before you write the first token because you know you will need to adjust contrast without changing color identity.

If accessibility is a retrofit, you discover these things in an audit and patch them. The patches are usually correct. But the architecture was not designed around them. Some of the decisions above cannot be cleanly retrofitted because they affect the component API or the token system structure. By the time you find them, you already have consumers.

nuka-ui's README says WCAG 2.2 AA is "a hard constraint, not a goal." This article is what that sentence costs.

The live Storybook is at https://ku5ic.github.io/nuka-ui/.
Source is at https://github.com/ku5ic/nuka-ui.

The Constraint Was Never Knowledge

Sinisa Kusic — Thu, 09 Apr 2026 07:52:39 +0000

There is a category of work that every experienced engineer knows matters and almost nobody does consistently. Not because they lack the skill. Not because they do not value it. Because the deadline is already here.

Modeling state before writing a line of it. Stress-testing an architecture before committing to it. Understanding a system before modifying it. The preflight work. The thinking that separates a codebase that holds from one that becomes someone else's archaeology project six months later.

This is the work that creates The Janitor Pattern when it gets skipped. And it gets skipped constantly, not out of laziness or ignorance, but because time was the binding constraint. There was never enough of it to think before acting.

That constraint is largely gone now. Most teams have not noticed what that actually means.

What AI Actually Unlocks

The dominant narrative around AI-assisted development is about throughput. Write code faster. Generate boilerplate. Autocomplete your way through implementation. That is real, but it is the least interesting part of what changed.

The more significant unlock is cognitive. When implementation is fast, the bottleneck shifts back to where it always belonged: decisions. What are we building and why. What state actually needs to exist. Where the boundaries go. What happens when requirements change.

These are not questions that get easier with faster typing. They get easier with time and focused thinking. AI did not make senior engineers faster at coding. It gave them back the time to actually do the architectural work they were already qualified to do but never had runway for.

That is a different claim than most people are making, and it has different implications.

The Seniority Multiplier

There is a mistake a lot of organizations are making right now.

They noticed that a junior developer with AI tooling can produce output that looks closer to senior work than it used to. That part is true. The gap in raw implementation quality has narrowed.

What they missed is the more important implication: a senior engineer with the same tools can produce output closer to five or ten seniors working without them. That is not a marginal improvement. That is a structural change in what one person can accomplish.

The reason is not code generation. A junior with AI increases coding throughput. A senior with AI improves the entire decision system behind the code.

That means defining the right problem before it gets expensive. Cutting bad scope before it ships. Choosing architecture that survives contact with production. Directing AI toward useful output instead of accepting confident noise. Catching wrong assumptions before they compound into something expensive. Keeping long-term maintainability intact while still moving fast.

None of that is something AI does on its own. It requires the judgment to know what questions to ask, recognize a wrong answer when you see one, and understand the tradeoffs well enough to make real decisions rather than defer to whatever the tool suggests.

The cost of building fast in the wrong direction is higher now, not lower, because the speed is higher. A team generating confident, well-structured code aimed at the wrong problem ships a very polished failure. That failure arrives faster than it used to.

That is why the value of genuine seniority did not go down when AI tooling arrived. In most real-world contexts, it went up.

The Workflow

A common objection to structured workflows is that they slow you down. The opposite is true once the system is in place. Output speed increases because there is no time lost to wrong assumptions, scope creep, or rework caused by starting before the problem was understood. The quality bar stays high by default rather than by heroic effort. And the dividends compound: the longer you use it, the more the constraint system knows about your codebase, the less friction each new task carries. The first task is the most expensive. The fiftieth is fast and clean.

The workflow follows a strict phase sequence: preflight, plan, implement, verify, review. Each phase is a named command. None are optional. None can be skipped. The sequence is the discipline.

But the sequence is only half of it. The other half is what the AI knows before the first command runs.

The workflow in the Battleship project is built on two layers of encoded knowledge. First, CLAUDE.md, the engineering standards document that defines every architectural constraint: layer contracts, state design rules, coordinate handling, TypeScript requirements, accessibility rules, testing strategy. Second, a set of skills in .claude/skills/ that encode domain expertise for specific concerns: react-architecture for layer separation and state design, wcag-react for accessibility implementation patterns, vitest-react for testing strategy. The skills load automatically in the right context. The AI does not re-discover these rules each session. They are written down, versioned, and available every time.

This is the part most AI workflow descriptions miss. The commands are the trigger. The standards document and skills are the constraint system. Without them, the workflow is a prompting pattern. With them, it is a system.

Preflight is the first phase and the most important one. The command instructs the AI to read CLAUDE.md in full, search the existing codebase for relevant types, utilities, and logic, identify the correct layer for each piece of work, check for duplication, and state the delta: one sentence per file to be created or modified. If it cannot state the delta clearly, the scope is not clear enough. Stop and ask.

No code is generated in this phase. That constraint is deliberate.

This step works in two directions at once. When the preflight report matches your mental model, you have a verified shared baseline before a single line changes. When it surfaces something you had not fully articulated, an existing utility you had forgotten, an ambiguous layer placement, an assumption you had not examined, you learn something about your own system. Both outcomes are useful. Neither is accidental. The surface area that comes up unexpectedly is exactly where bugs live and refactors go wrong.

Plan produces a reviewable artifact before any implementation begins. Not a vague description. A concrete specification. Every new type with its name, shape, and rationale. Every new function with its signature, layer placement, purity, and test strategy. Every state change with what gets persisted, what gets derived, and why. Every component with its props interface and what it emits. Accessibility impact. Risk flags. One sentence per file to be created or modified.

The plan is a checkpoint, not a suggestion. It requires explicit approval before anything is written. If the plan is wrong, you catch it here, before it is encoded in code that needs to be undone.

Implement writes the approved code, one complete file at a time. No scope expansion. No reinventing what already exists. The approved plan is the boundary.

Verify runs before human review, not as part of it. The command runs through a checklist: architecture boundaries, TypeScript correctness, component composition rules, accessibility compliance, test coverage, CI simulation. Architecture pass, TypeScript pass, accessibility pass, tests pass: each is an explicit gate. If anything fails, it gets fixed before the handoff. The AI does not ask for review with known violations.

Review surfaces the implementation with decisions, tradeoffs, and anything requiring human judgment explicitly flagged. Things noticed during implementation but out of scope for the current change go here as deferred observations rather than silently expanding the diff.

The framing from the project documentation captures it precisely: the same discipline you would apply working with a capable but unsupervised junior engineer. No implementation before the design is agreed. No review request before verification passes. No unexplained decisions in the final output.

Most problems in software do not come from writing bad code. They come from starting before the problem was understood.

Here is what a task prompt actually looks like. This is the document used to implement the CLI runner in the Battleship project. It carries both the specification and the execution instructions. The AI workflow section tells the AI exactly which commands to run and in what order, so the full phase sequence is encoded in the prompt itself:

Task: Implement CLI runner

Context: The engine layer is pure (state, action) => state with no React dependency. A terminal runner should consume it directly -- same reducers, same services, same types -- with zero changes to existing code. This validates that the layer boundaries are real.

Pre-task decisions (do not re-open):

No React imports anywhere in src/cli/
No game rules in the CLI -- only I/O, rendering, and driving the engine
LineReader interface abstracts Node's readline to avoid importing Node types under the vite/client type scope
No colors, no ANSI formatting, no AI shot delay -- terminal output is synchronous, the delay serves no purpose
No placement phase -- both modes use generateRandomLayout
No tests for src/cli/ -- all meaningful logic is covered by engine and service tests

Files to create (4):

src/cli/
  index.ts      -- entry point, mode and difficulty menus, readline lifecycle
  loop.ts       -- game loops for single-player and vs-computer modes
  renderer.ts   -- pure string rendering, board grids, shot results, game-over messages
  input.ts      -- coordinate parser, readline prompt loop, LineReader interface

Files to modify (2):

tsconfig.cli.json -- confirm CLI entry point is correctly configured
docs/ARCHITECTURE.md -- add CLI section documenting consumer pattern and AI delay omission

Types:

LineReader interface in input.ts: { question(prompt: string, cb: (answer: string) => void): void; close(): void } -- abstracts readline, no Node type import required
No new domain types -- all existing types from engine/, services/, types/ used as-is

Functions:

renderBoard(boardState: BoardState, label: string): string -- pure string function, no side effects, unit testable
parseCoordinateInput(input: string, boardSize: number): Coordinate | null -- pure, returns null on invalid input
runSinglePlayerLoop(rl: LineReader, difficulty: Difficulty): Promise<void> -- async, drives engine reducer directly
runVsComputerLoop(rl: LineReader, difficulty: Difficulty): Promise<void> -- async, same pattern

State: No new state. CLI drives engine reducers as plain functions: state = reducer(state, action).

Accessibility impact: None -- terminal only.

Required AI workflow:

/cmd-preflight -- read CLAUDE.md, search for existing engine reducers, service functions, and types relevant to this task. Confirm src/cli/ does not exist yet. Run npx tsc -p tsconfig.json --noEmit, npm test, npm run lint. Do not proceed if anything is failing.
/cmd-plan -- produce the full implementation plan covering types, function signatures, file list, and the ARCHITECTURE.md update. Wait for explicit approval before writing any code.
/cmd-implement -- implement in this order: input.ts, renderer.ts, loop.ts, index.ts, then update docs/ARCHITECTURE.md. One complete file at a time. No scope expansion.
/cmd-verify -- confirm zero React imports in src/cli/, no domain logic duplicated from services, TypeScript clean, all existing tests still passing.
/cmd-review -- surface decisions, tradeoffs, and the AI delay omission explicitly. Flag anything requiring sign-off.

Risk flags:

crypto.randomUUID may not be available in all Node versions -- confirm or use Math.random fallback
AI shot delay is intentionally omitted -- document explicitly so a future reader does not add it back

Testing plan: No CLI-specific tests. Engine, services, and renderer pure functions are covered by existing and new unit tests. renderer.ts and input.ts are testable in isolation if needed later.

Acceptance criteria:

npm run cli starts the game
Both single-player and vs-computer modes work end to end
Difficulty selection works
Shot input parses correctly, rejects invalid input with a message
Game over is detected and reported
Zero changes to engine/, services/, utils/, types/, or constants/
src/cli/ has no React imports
docs/ARCHITECTURE.md updated with CLI section

Do not:

Do not import React anywhere in src/cli/
Do not duplicate any rule logic from services/
Do not add the AI shot delay
Do not add a placement phase
Do not commit -- stop after review approval

This document is what gets approved before a line of code is written. The AI implements against it. The scope is fixed. What comes out the other end is a single, reviewable, purposeful commit, not a 40-file diff with no clear narrative.

Atomic prompts produce atomic commits. The git history stays readable. Reviews stay tractable. Not as a side effect of the workflow. As a structural outcome of defining scope before touching code.

This is what speed with quality actually looks like. Not heroics, not shortcuts. A repeatable system.

What This Looks Like in Practice

The Battleship project I recently published was a direct application of this workflow. The goal was not to build a game. It was to demonstrate what disciplined frontend architecture looks like when you actually have time to think before writing code.

The state logic lives in a pure engine layer: plain TypeScript, no React imports, no framework dependency. The hook is wiring only. The CLI runner, whose full task prompt appears in the workflow section above, is the proof that the boundaries are real. The same engine, the same reducers, the same services, consumed by a Node terminal process with zero changes to domain code. A different output layer consuming the same logic without modification.

But the more telling artifact is not the code. It is docs/ARCHITECTURE.md, a document that explains every significant decision in the codebase, every alternative that was considered, and the reasoning behind each choice. It includes a "Key Discussion Points" section that anticipates the questions a technical reviewer would ask and answers them before they are asked. It exists because the workflow created space for that kind of thinking before any code was written.

That document does not get written under normal deadline pressure. Not because the engineer is less capable, but because there is never time. The constraint was never knowledge. It was time.

That is the workflow. Not "AI writes the code." AI handles the implementation details while I spend the recovered time on the decisions that actually determine whether the system will survive.

The Honest Caveat

The tools do not give you judgment. They give you time to use the judgment you already have.

For engineers who were already doing the thinking but running out of runway, that is a genuine and significant unlock. That constraint is gone.

For everyone else, it is faster output. Which is useful, but it is not the same thing, and it will not produce the same results.

The difference shows up six months later, when one codebase is still being extended cleanly and another has become someone's full-time archaeology project.

The Janitor Pattern

Sinisa Kusic — Tue, 07 Apr 2026 08:31:29 +0000

There is a role that does not appear in any job description but exists on almost every frontend team. You know it when you are living it. You spend more time navigating someone else's decisions than making your own. Every new feature requires archaeology. Every bug fix risks destabilizing something three layers removed. You are not building anymore. You are maintaining the illusion that the codebase is still under control.

This is the Janitor Pattern. And it is not caused by bad developers.

It is caused by a structural assumption that gets made early, often before the first line of code is written, and almost never gets questioned: that the frontend is a UI layer. A skin over the real system. Something you bolt on at the end, staff with whoever is available, and optimize last if at all.

That assumption is wrong. And the codebase you inherit six months later is the proof.

How the Assumption Takes Hold

It rarely starts as a conscious decision. It starts as a staffing model.

The backend engineers get senior architects. They get ADRs, design reviews, and ownership over the data layer. The frontend gets whoever is left, or whoever was cheapest, or whoever interviewed well enough to clear the bar for "can ship components." The implicit message is clear even when the explicit message is not: this part does not require serious engineering.

From there, the assumption compounds. No architectural investment means no architectural standards. No standards means every engineer makes their own local decisions. Local decisions, made independently over time, produce a system with no coherent shape. State leaks across boundaries that should not share state. Components grow to accommodate every use case that ever touched them. A component that was written to render a data table gradually absorbs filtering logic, then sorting state, then a network call, then an inline error handler, until it is four hundred lines long and nobody can confidently change it without running the full application to see what breaks. Business logic migrates into the render tree because there is nowhere else to put it and nobody with the authority to put it somewhere better. The codebase becomes a record of every compromise that was made under pressure, and none of the intentions that preceded them.

Leadership looks at the result and concludes that frontend is just messy by nature. It is not. It is messy because no one was given the mandate, the time, or the authority to keep it otherwise.

What It Actually Costs

The first cost is velocity, and it compounds in a way that does not show up cleanly on any roadmap.

Early on, the team ships fast. The codebase is small, everyone knows where everything is, and there is no meaningful technical debt because there is not yet enough code to have debt. Leadership sees the speed and attributes it to the team. What they are actually seeing is the absence of consequences. The debt is being taken on, not yet being repaid.

Six months later, the same features take twice as long. A year later, they take four times as long. But the team is also larger now, which obscures the signal. The productivity loss per engineer is invisible because it is distributed across more engineers. What leadership perceives as a scaling problem, we need to hire more, is actually an architectural problem: the system is resisting change because it was never designed to accommodate it.

The second cost is engineer quality. Senior engineers tolerate janitor work for a while. They do not tolerate it indefinitely. The ones who leave are almost never the ones who cause the mess. They are the ones who recognize it, who tried to address it, and who eventually concluded that the organization had no interest in addressing it with them. What remains tends toward the engineers who either do not see the problem or have stopped caring. Neither produces a better codebase.

The third cost is invisible and therefore the most dangerous: the features you do not build. Every hour spent managing accumulated complexity is an hour not spent on the product. No one tracks this. It does not appear in sprint velocity or quarterly reports. It exists only as a gap between what the team could have shipped and what it actually shipped, and leadership usually fills that gap with explanations that have nothing to do with the real cause.

Frontend Is a System

The framing of "frontend" as a UI layer is not just organizationally convenient. It is technically incorrect.

A modern frontend application manages state, enforces business rules, handles asynchronous coordination, defines data contracts with backend services, implements security boundaries in the form of auth flows and guarded routes, and owns the full error surface that users ever actually see. It makes rendering decisions, caching decisions, and navigation decisions. In a sufficiently complex product, the frontend state machine is as sophisticated as anything running on the server.

Treating that as a "layer" is not a simplification. It is a category error.

The same engineering discipline that applies to backend systems applies here: clear separation of concerns, explicit data flow, bounded ownership, and components that do one thing well. The difference is that on the backend, these principles are treated as table stakes. On the frontend, they are treated as optional, or worse, as overhead.

SOLID is not a backend concept. A component that renders a form, validates input, manages submission state, handles error display, and fires analytics events is violating the single responsibility principle just as clearly as any god object in a Java service layer. It is harder to test, harder to change, and harder to reason about. The fact that it is written in JSX rather than Java does not make the violation less real.

KISS applies too. Not in the reductive sense of "write simple code," but in the sense of resisting the pull toward abstraction before abstraction has earned its complexity budget. Frontend codebases are full of "flexible" systems that no one uses flexibly, generic components that handle twelve variants when they needed to handle two, and configuration-driven rendering logic so abstracted that adding a new case requires reading three files before writing one line.

YAGNI is where frontend most consistently goes wrong. The instinct to generalize too early, to build the reusable version before the requirements are even stable, produces abstractions that are wrong in ways you cannot see until you try to use them. The cost of premature abstraction in a UI codebase is not just the code that was written. It is the constraints that code imposes on every decision that comes after it.

Component design, specifically, benefits from a discipline most frontend teams never formalize: keep components as dumb as possible for as long as possible. A component that receives props and renders output is easy to test, easy to compose, and easy to change. A component that also manages its own network state, its own business logic, and its own error recovery is none of those things. The only state a component should own by default is the state that is genuinely local to its rendering, whether a dropdown is open, whether a tooltip is visible. Everything else belongs somewhere else, managed by something whose job is to manage it.

This is not a new idea. It is not even a frontend idea. It is what engineering discipline looks like when it is applied consistently. The problem is not that frontend engineers do not know this. It is that the organizations they work in do not create the conditions for it.

What Disciplined Frontend Architecture Looks Like

So what does the alternative actually look like? Not as a set of principles, but as working code you can open and read.

I built a Battleship game as a public project specifically to demonstrate what frontend architecture looks like when the same standards applied to backend systems are applied to the frontend without compromise. The game itself is not the point. The architecture is.

The domain layer, hit detection, sunk-ship resolution, turn management, game-over detection, lives in pure TypeScript functions under engine/ and services/. No React imports anywhere in that layer. The same reducers that power the browser UI also drive a standalone CLI runner that you can invoke with npm run cli. That is not a demo added afterward. It is proof the layer boundaries are real: a second consumer in a completely different runtime environment, Node terminal versus browser DOM, works without changing a single line of domain code. If the domain had leaked React, the CLI would not compile.

State is minimal by design. Each game hook persists only what cannot be derived from other state: the shots map and the last shot result. Everything else, whether a cell is hit, whether a ship is sunk, whether the game is over, is computed via useMemo from those two facts. There is one source of truth per fact. The alternative, persisting derived values alongside the raw state, creates a second source of truth that must be kept consistent with the first. When those two diverge, and they will, the UI renders incorrect state. Deriving is consistent by construction.

Shot state transitions are atomic. Firing a shot must update the shots map and the last result together. Two useState calls would create a window between the first and second update where the component has inconsistent state: the shot is recorded but the result is still the previous one, or vice versa. An aria-live region reading during that window announces the wrong result. A single useReducer dispatch eliminates the window entirely. One dispatch, one new state object, no intermediate renders.

When a second game mode was added, it required a new engine module, a new hook, and a new wiring component. No existing rule logic was touched. Services, utilities, and the original single-player engine were extended, not rewritten. That is the practical payoff of clear layer boundaries: new requirements have a predictable place to go, and change is local rather than global.

Components are dumb by default. The Board component knows how to render a grid and manage keyboard navigation. It does not know what a ship is, what a shot is, or what the rules are. It could render a Minesweeper grid without changing its implementation. The only components that call hooks are the two wiring components at the top of the game tree, and those components contain no logic of their own. This is not a heroic constraint. It is what components look like when someone decided early what they are for.

None of this required a new framework, a state management library, or a methodology. It required deciding, before the first component was written, that the frontend was a system with the same expectations applied to any other system, and that those expectations would be enforced.

A production codebase is harder. The requirements are less clear, the team is larger, the deadlines are real. But the failure mode is not that production constraints make architecture impossible. The failure mode is that no one was asked to do it, or given the authority to enforce it, or protected from the pressure to skip it.

What Needs to Change

For engineering leadership, the starting point is recognizing that the staffing model is the architecture.

If you staff the frontend with engineers who are not expected to own the architecture, no architecture will be owned. If you do not create review processes that include frontend design decisions alongside backend ones, frontend design will not be reviewed. If you treat frontend performance, frontend accessibility, and frontend code quality as secondary concerns to be addressed "after we ship," they will remain secondary concerns indefinitely, because there is always something else to ship.

The investment required is not enormous. It is a senior engineer with genuine ownership and the authority to make and enforce architectural decisions. It is design review that includes the frontend. It is the same expectation of discipline that you already apply to the systems you have decided matter.

For senior frontend engineers, the work is not just building better systems. It is making the cost of bad systems legible to the people who control the conditions under which systems are built. That means tracking the time lost to architectural debt explicitly, not absorbing it silently into estimates. It means framing refactoring work in terms of shipping velocity, not code quality, not because code quality does not matter, but because the argument has to land somewhere that registers. It means being willing to push back on the framing that frontend is inherently messy, because that framing is false and accepting it makes the problem permanent.

The Janitor Pattern persists because it is self-obscuring. The people creating the conditions for it rarely see the consequences directly. The engineers absorbing the consequences rarely have the standing to name the cause. Breaking that loop requires both sides to be honest about what is actually happening.

The frontend is not a UI layer. It is a system. It deserves to be treated like one.

Why I separated `variant` from `intent` in my component API

Sinisa Kusic — Mon, 06 Apr 2026 10:09:16 +0000

Every component library starts the same way. You add a Button. It needs a primary style and a danger style, so you reach for a variant prop. Simple enough.

Then someone needs a ghost button that also signals danger. You add variant="ghost-danger". Then outline-success. Then link-warning. Then secondary-danger. Each new combination feels reasonable in isolation. Six months later you have a prop that accepts seventeen strings, half of which your consumers will never discover because nothing in the type system points them there.

This is not a tooling problem. It is a modeling problem. The variant prop is doing two unrelated jobs, and conflating them is what causes the explosion.

Two orthogonal concerns

When you look at what variant is actually encoding in most button APIs, it is carrying two distinct signals:

Visual weight: how much attention the component demands. Primary buttons are loud. Ghost buttons are quiet. Outline sits between them. This is a presentation decision.

Semantic meaning: what the action communicates. Danger means destructive. Success means confirmation. Warning means proceed with caution. This is a communication decision.

These are orthogonal axes. A ghost button can be dangerous. An outline button can confirm success. There is no inherent relationship between how loud a button is and what it means. Cramming both signals into a single prop forces a false coupling that grows more expensive with every variant you add.

The fix is to give each concern its own prop.

The split

In nuka-ui, my open-source React component library built on Tailwind v4, the API separates these into two independent props:

A note on the project itself. I built nuka-ui because I kept repeating the same patterns across every project I started, personal, hobby, showcase, whatever. Rebuilding accessible, production-ready components from scratch every time is a real burden, and I got tired of it. The library exists to solve that repetition once, with accessibility and solid UX baked in from the start rather than bolted on later. It is not on npm yet. Navigation and Composites are the remaining pieces before the first publish.

variant controls visual weight: primary, secondary, outline, ghost, link
intent controls semantic meaning: default, danger, success, warning

Every combination is valid. The consumer API looks like this:

<Button variant="primary" intent="default" />
<Button variant="ghost" intent="danger" />
<Button variant="outline" intent="success" />
<Button variant="secondary" intent="warning" />

Compare that to the flat approach:

<Button variant="ghost-danger" />
<Button variant="outline-success" />
<Button variant="secondary-warning" />

The flat approach is not unreadable. The problem is discoverability and scale. A consumer looking at variant's type has no way to know which combinations exist, which are intentional, and which ones you simply never got around to building. The two-prop model makes the full space explicit and uniform. Every variant works with every intent. There are no gaps.

How CVA implements the intersection

Separating the props does not make the styling simpler. It makes it honest. You still need to define what every combination looks like. That work is done through CVA's compoundVariants:

const buttonVariants = cva(baseClasses, {
  variants: {
    variant: {
      primary: [],
      secondary: [],
      outline: [],
      ghost: [],
      link: [],
    },
    intent: {
      default: "",
      danger: "",
      success: "",
      warning: "",
    },
  },
  compoundVariants: [
    {
      variant: "primary",
      intent: "default",
      className: [
        "bg-[var(--nuka-accent-bg)]",
        "text-[var(--nuka-text-inverse)]",
        "hover:bg-[var(--nuka-accent-bg-hover)]",
      ],
    },
    {
      variant: "primary",
      intent: "danger",
      className: [
        "bg-[var(--nuka-danger-base)]",
        "text-[var(--nuka-text-inverse)]",
        "hover:brightness-90",
      ],
    },
    {
      variant: "ghost",
      intent: "danger",
      className: [
        "text-[var(--nuka-danger-text)]",
        "hover:bg-[var(--nuka-danger-bg)]",
      ],
    },
    // one entry per variant x intent combination
  ],
  defaultVariants: {
    variant: "primary",
    intent: "default",
    size: "md",
  },
})

5 variants multiplied by 4 intents gives you 20 compound variant entries for Button alone. You write all 20 explicitly. That is the cost of a complete, deliberate API, and it is a one-time authoring cost. Once they are written, the intersection is fully covered. Adding a consumer use case requires no library changes, just passing the two props you already have.

TypeScript enforces the contract at compile time:

interface ButtonProps extends ButtonVariantProps {
  variant?: "primary" | "secondary" | "outline" | "ghost" | "link"
  intent?: "default" | "danger" | "success" | "warning"
}

Invalid prop values do not survive a build. The type system reflects the actual API surface, not a historical accident of how variants accumulated.

What you gain at scale

The pattern compounds across a library. In nuka-ui it applies to Button, Alert, Badge, Tag, Code, Input, and Checkbox. Each component defines its own variant and intent axes and handles the intersections through compound variants. The mental model is consistent everywhere. A consumer who understands how Button works understands how Alert works.

Adding a new intent, say info, requires adding N compound variant entries per component, where N is the number of that component's variants. It is more work than adding a single flat variant string, but the scope is bounded and predictable. You know exactly what needs to be done, and you cannot accidentally miss a combination because the grid is explicit.

Tradeoffs, and when not to apply this

The verbosity is real. Twenty compound variant entries per component is a lot of lines. If your library is small and your variant space is stable, the flat approach is less overhead and probably fine. This pattern earns its cost at scale, when the alternative is a variant prop with an ever-growing string union that no one can hold in their head.

Consumers also have to understand two props instead of one. For most senior engineers this is a non-issue. The separation is intuitive once named. For a component library targeting less experienced consumers, the additional concept may need more documentation investment.

The pattern also does not apply universally. Banner in nuka-ui uses intent alone. There is no variant prop because Banner has one visual weight. Applying the full grid to a component with a single presentation mode would be mechanical pattern application, not design. The question to ask is whether the component genuinely has independent visual weight and semantic axes. If it does not, use the simpler model.

Two alternatives worth naming explicitly, because I considered both before landing here:

Flat variants are simpler to implement initially. The explosion problem only becomes painful as the library grows, which is exactly when you have the least appetite to refactor the API.

CSS data attributes (data-intent="danger") avoid prop surface area but lose TypeScript type safety and make the API implicit. The props approach is more explicit and more tool-friendly.

Where to see it in practice

The full implementation is in the nuka-ui repository at https://github.com/ku5ic/nuka-ui. The live Storybook at https://ku5ic.github.io/nuka-ui shows every variant and intent combination across all components. If you want to follow along as the library moves toward its first npm publish, starring the repo is the easiest way to keep up with progress.

Most component API problems are modeling problems in disguise. This one just happens to be easy to see once you know where to look.