Forem: venkatesh m

jsx-a11y has 36 rules. None of them catch these 6 patterns.

venkatesh m — Mon, 13 Apr 2026 14:10:56 +0000

The Bug That Passed Lint

I was building a menu component. The trigger had aria-haspopup="menu". The content panel had role="dialog". Every element was individually valid. jsx-a11y gave zero warnings. The component rendered correctly. Keyboard navigation worked.

Then I tested with VoiceOver.

The trigger announced: "Actions, button, menu popup." The user expects a menu — arrow keys to navigate between items, no Tab key needed. What they got was a dialog with Tab navigation. Visually identical. Functionally identical for sighted users. Completely wrong for screen reader users. The trigger promised a menu. The content delivered a dialog.

jsx-a11y didn't catch this because it can't. It visits one JSX element at a time. It sees attributes on that element. It cannot see the parent, the sibling, or the child. The aria-haspopup="menu" was valid. The role="dialog" was valid. The mismatch between them is invisible to any tool that checks elements in isolation.

This is not a jsx-a11y bug. It's a structural limitation. Element-level analysis cannot validate relationships.

What Element-Level Linting Misses

jsx-a11y has 36 active rules. Every one answers the same type of question: "Does this element have the right attributes?" Does this <img> have alt? Does this <button> have content? Does this element with onClick have a keyboard handler?

These are important checks. They catch real bugs. But the accessibility failures that survive to production are rarely about missing attributes on a single element. They're about how elements relate to each other.

Six patterns. Each one passes jsx-a11y. Each one breaks for screen reader or keyboard users.

1. Dialog without `aria-modal="true"`

// Passes jsx-a11y. Breaks screen reader navigation.
<div role="dialog">
  <h2>Confirm deletion</h2>
  <p>Are you sure?</p>
</div>

Without aria-modal="true", screen readers allow virtual cursor navigation outside the dialog. A VoiceOver user presses the down arrow and starts reading the page behind the modal overlay. They're interacting with content that's visually obscured. The dialog looks modal. It isn't.

What the user expects	What happens
Virtual cursor stays inside dialog	Virtual cursor reads page behind dialog
Escape closes, focus returns to trigger	Escape may or may not work
"Confirm deletion, dialog" announced	"dialog" announced, no context

The fix is aria-modal="true". One attribute. jsx-a11y doesn't check for it because the attribute belongs to the relationship between the dialog and the page — not to the dialog element alone.

2. `aria-haspopup` with an invalid value

// Passes jsx-a11y. Silently broken.
<button aria-haspopup="dropdown">Open</button>

The ARIA spec allows seven values for aria-haspopup: menu, listbox, tree, grid, dialog, true, false. That's it. "dropdown" is not one of them. Neither is "tooltip" or "popup" or "select."

Browsers don't throw errors on invalid ARIA values. They silently treat them as false. The popup is never announced. The user clicks the button, something appears on screen, and the screen reader says nothing about it. The popup is invisible to assistive technology.

This isn't hypothetical. I've seen aria-haspopup="tooltip" in production codebases from developers who reasonably assumed the value should describe what appears. The spec disagrees. The browser silently drops it.

3. Interactive elements inside a tooltip

// Passes jsx-a11y. Keyboard users can never reach the link.
<div role="tooltip">
  <a href="/help">Learn more</a>
</div>

Tooltips disappear on blur. A keyboard user cannot Tab into a tooltip because the moment focus leaves the trigger, the tooltip closes. The link inside it is unreachable. A mouse user can click it. A keyboard user cannot. A screen reader user cannot.

If you need interactive content in a popup, use role="dialog" with a focus trap. Tooltips are for text-only content — labels, descriptions, keyboard shortcuts. Putting a button or link inside one creates a feature that exists for mouse users and doesn't exist for everyone else.

4. Accordion trigger outside a heading

// Passes jsx-a11y. Invisible to heading navigation.
<div>
  <button aria-expanded="true" aria-controls="panel-1">
    Section title
  </button>
</div>
<div id="panel-1">Panel content</div>

Screen reader users navigate pages by headings. In NVDA, pressing H jumps to the next heading. In VoiceOver, using the rotor filtered to headings gives an outline of the page. Accordion sections are page structure — they should appear in that outline.

Without a heading wrapper, the accordion section is invisible to heading navigation. The user has to read the entire page sequentially to find it. The fix is one element:

<h3>
  <button aria-expanded="true" aria-controls="panel-1">
    Section title
  </button>
</h3>

The WAI-ARIA Accordion Pattern specifies this explicitly. jsx-a11y doesn't check it because the heading requirement is about the relationship between the trigger and its ancestor — not about the trigger element itself.

5. `role="menuitem"` on a `<button>`

// Passes jsx-a11y. Double announcement in some screen readers.
<button role="menuitem">Edit</button>

<button> has an implicit role of "button." Adding role="menuitem" overrides it at the ARIA level, but NVDA with Firefox announces both: "button, menuitem, Edit." The user hears two conflicting roles for the same element. Is this a button or a menu item? The double announcement creates confusion about what the element does and how to interact with it.

The correct pattern for menu items:

<div role="menuitem" tabIndex={-1}>Edit</div>

No implicit role conflict. One announcement. Programmatically focusable via roving tabindex. This is what the WAI-ARIA Menu Button Pattern specifies. jsx-a11y doesn't flag the conflict because the conflict is between the element's implicit role and its explicit role — a relationship, not an attribute.

6. Dialog without an accessible name

// Passes jsx-a11y. "dialog" announced with no context.
<div role="dialog" aria-modal="true">
  <h2>Confirm deletion</h2>
  <p>This action cannot be undone.</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

When this dialog opens, VoiceOver announces: "dialog." That's it. The user doesn't know what the dialog is about until they navigate through its contents. Compare with:

<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Confirm deletion</h2>
  ...
</div>

Now VoiceOver announces: "Confirm deletion, dialog." The user knows the purpose immediately. The difference is aria-labelledby pointing to the heading — a relationship between two elements.

Why This Gap Exists

ESLint rules operate on AST nodes. When jsx-a11y visits a JSXOpeningElement, it receives the attributes of that element. It can check if role is valid. It can check if aria-label exists. It cannot walk up to the parent and check if the parent is a heading. It cannot walk down to the children and check if any of them are focusable.

Some of these checks are structurally possible within ESLint's visitor pattern. You can walk the parent chain by following the parent property that ESLint sets on every AST node. You can inspect children through the JSXElement.children array. jsx-a11y doesn't do this — its rules are designed to be fast, single-element checks. The performance trade-off is reasonable for a plugin with 12 million weekly downloads.

But the consequence is that composition-level accessibility bugs — the ones where every element is individually correct but the combination is wrong — pass lint and ship to production.

What Microsoft Built (and Didn't Build)

Microsoft ships eslint-plugin-fluentui-jsx-a11y for their FluentUI component library. It checks that FluentUI-specific components have the right ARIA attributes — a DialogBody needs a DialogTitle, an accordion header needs an accessible name.

It's a good plugin. It's also tied to FluentUI. It doesn't check that a generic <button aria-haspopup="menu"> connects to a panel with role="menu". It doesn't check that a <div role="tooltip"> doesn't contain interactive children. The composition problem in framework-agnostic React code was still unsolved.

eslint-plugin-a11y-enforce

I built a plugin that checks these relationships. 10 rules, divided into two categories.

Component pattern rules validate ARIA relationships in compound components — Dialog, Menu, Accordion, Tooltip:

dialog-requires-modal — role="dialog" must have aria-modal="true"
dialog-requires-title — role="dialog" must have aria-labelledby or aria-label
haspopup-role-match — aria-haspopup must be a valid ARIA value
tooltip-no-interactive — role="tooltip" must not contain focusable children
accordion-trigger-heading — accordion triggers must be inside headings
menuitem-not-button — role="menuitem" should not be on <button> elements

General interaction rules catch common patterns every developer writes:

focusable-has-interaction — tabIndex={0} requires a keyboard handler
input-requires-label — form inputs must have accessible labels (placeholder is not a label)
radio-group-requires-grouping — radio buttons must be inside <fieldset> or role="radiogroup"
no-positive-tabindex — tabIndex greater than 0 breaks natural tab order

How the rules work

The composition rules use ancestor traversal — walking up the AST's parent chain to check if an element's ancestor has the right role or tag name. For accordion-trigger-heading, when the visitor encounters a <button> with aria-expanded, it walks up the parent chain looking for <h1>-<h6> or role="heading". For tooltip-no-interactive, when the visitor encounters a focusable element, it walks up looking for role="tooltip".

This is stateless — no mutable flags like insideTooltip = true that would break with nested components, conditional rendering, or interleaved elements. Each check walks the tree from the current node, every time. The trade-off is performance (O(n*d) where d is tree depth), but for the file sizes ESLint processes, this is negligible.

What the error messages say

Every error message explains three things: what is wrong, why it matters for the user, and how to fix it. Not "violation" — a specific audio experience.

Tooltip (role="tooltip") must not contain interactive elements. Tooltips are non-interactive by design. Users cannot Tab to content inside a tooltip because it disappears on blur. If you need interactive content in a popup, use a Popover or Dialog instead.

If a developer reads this message and still doesn't understand the issue, the message failed, not the developer.

Install

npm install --save-dev eslint-plugin-a11y-enforce

// eslint.config.js (ESLint 9+)
import a11yEnforce from 'eslint-plugin-a11y-enforce';

export default [
  a11yEnforce.configs.recommended,
];

ESLint 8 is also supported via legacy config.

Use both jsx-a11y and a11y-enforce. They complement each other. No rule overlap. jsx-a11y checks elements. a11y-enforce checks relationships.

Design Decisions

Zero runtime dependencies. The plugin uses only ESLint's built-in AST APIs. No aria-query, no axe-core, no axobject-query. The full rule set is 1,065 lines of TypeScript.

Educational over terse. Every rule's error message explains the user impact, not just the spec violation. Developers who understand why a rule exists are less likely to disable it.

Conservative on spreads. <div role="dialog" {...props}> fires the rule even though the spread might contain aria-modal. Static analysis cannot see through spreads. If you set role statically, set aria-modal statically too.

Single recommended preset. All 10 rules as errors. No recommended/strict split until real-world usage data justifies one. If a rule fires, it's a real problem.

What This Doesn't Catch

Static analysis has limits. This plugin cannot verify that aria-labelledby points to an element that actually exists — that requires cross-file or runtime analysis. It cannot check that a focus trap is implemented correctly — that's behavior, not structure. It cannot validate screen reader announcement order — that varies by browser and AT combination.

For rendered DOM testing, use @axe-core/react in development. For real-world validation, test with an actual screen reader. Linting catches the structural errors. Testing catches the behavioral ones. Both matter.

Why This Matters Now

Accessibility enforcement is accelerating. The European Accessibility Act started enforcement on June 28, 2025, across all 27 EU member states. In the US, over 5,000 ADA digital accessibility lawsuits were filed in 2025 across federal and state courts — up from roughly 4,000 in 2024 (UsableNet 2025 Year-End Report). In India, the Supreme Court declared digital access a fundamental right under Article 21 in April 2025, and SEBI mandated WCAG compliance for the entire financial sector in July 2025.

Your linter should catch these before they ship. jsx-a11y catches the element-level issues. a11y-enforce catches the composition-level issues. Install both.

npm: eslint-plugin-a11y-enforce
GitHub: vmvenkatesh78/eslint-plugin-a11y-enforce

10 rules. 207 tests. Zero dependencies. ESM + CJS. ESLint 8 and 9.

From 3 components to 8: what actually changes when a design system scales

venkatesh m — Thu, 02 Apr 2026 14:54:26 +0000

When flintwork had 3 components (Button, Dialog, Tabs), every component was its own island. Each one had its own hooks, its own keyboard handling, its own focus management. The code worked but nothing talked to anything else.

When it grew to 8 (adding Menu, Select, Popover, Accordion, Tooltip), the codebase went through a structural shift I didn't plan for. Patterns emerged that only become visible when you have enough components to compare.

This is about what those patterns are and why they matter more than any individual component.

Four components that are secretly the same thing

Dialog, Popover, Menu, and Select look completely different to a user. Different triggers, different content, different interaction models. But internally they all do the same three things when they open:

Trap focus inside the content
Close when you click outside
Close when you press Escape

The code is identical:

// All four components do exactly this in their Content component:
useFocusTrap(contentRef, { enabled: isOpen });
useClickOutside(contentRef, () => onOpenChange(false));

useEffect(() => {
  const handleEscape = (event: KeyboardEvent) => {
    if (event.key === 'Escape') {
      event.stopPropagation();
      onOpenChange(false);
    }
  };
  document.addEventListener('keydown', handleEscape);
  return () => document.removeEventListener('keydown', handleEscape);
}, [onOpenChange]);

The behavioral difference between these four components lives entirely in their ARIA layer:

Component	role	aria-modal	aria-haspopup	Trigger
Dialog	`dialog`	`true`	`dialog`	Opens only
Popover	none	none	`dialog`	Toggles
Menu	`menu`	none	`menu`	Toggles
Select	`listbox`	none	`listbox`	Toggles

A screen reader user experiences Dialog and Popover as completely different things. But the code that powers them is the same three hooks composed the same way. The ARIA attributes are the differentiator, not the behavior.

This is something you can't see with 3 components. You need at least 4 overlapping patterns before the shared shape becomes obvious.

The decision I'm most glad I made early

Every hook is internal. Consumers never call useFocusTrap directly. They use <Dialog.Content> which calls it internally.

This seemed like a small decision at the time. With 8 components, it turned out to be the most important architectural choice in the system. Here's why:

When I needed to change how useFocusTrap handles initial focus placement, I changed one file. If consumers were calling useFocusTrap directly, that's a breaking change to a public API. With internal hooks, it's an implementation detail that no consumer code depends on.

The compound component API is the public contract. The hooks are the private implementation. This boundary is what lets the system evolve without breaking consumers.

When not to share: typeahead

Menu and Select both support typeahead search. Type a character and focus jumps to the first item that starts with that character. Same 500ms buffer timeout, same textContent matching logic.

The obvious move is to add typeahead to useRovingTabIndex since both Menu and Select already use it. I didn't.

Typeahead is specific to menu and listbox patterns. Tabs use roving tabindex but don't have typeahead. A toolbar would use roving tabindex but wouldn't have typeahead either. Adding it to the generic hook would pollute a behavior primitive with pattern-specific logic.

Instead, typeahead is a keydown handler directly in MenuContent and SelectContent. Both implementations are structurally identical. If a third component needs typeahead, that's when it gets extracted into useTypeahead.

Two instances is coincidence. Three is a pattern. Don't extract at two.

The Portal positioning tradeoff

Every component that renders floating content (Popover, Menu, Select, Tooltip) needs positioning. The obvious choice is to bundle @floating-ui/react and handle it internally.

I deliberately didn't. flintwork provides Portal for stacking context escape but leaves positioning to the consumer. The consumer can use CSS, @floating-ui/react, or whatever they want.

This was the hardest scope decision because it increases the barrier to entry. A consumer has to bring their own positioning. But the alternative is coupling the entire library to a specific positioning dependency that may not match the consumer's existing setup.

The compromise: the docs site shows a recommended pattern using CSS position: fixed with container refs. It works for the common case. If someone needs viewport-aware collision detection, they add @floating-ui/react themselves.

Not every library needs to solve every problem. Knowing where to draw the scope boundary is as important as what you include.

Accordion broke the pattern

Every component up to Accordion shared a simple context model: Root provides state, children consume it. One level of context.

Accordion needs two levels. The root tracks which panels are open (an array of values). Each item tracks whether that specific item is open. An AccordionItem needs to know its own open state AND whether it should be open based on the root's selection model (single vs multiple).

// Root context: which panels are open
const AccordionContext = createContext<{
  value: string[];
  onToggle: (itemValue: string) => void;
  type: 'single' | 'multiple';
}>();

// Item context: is THIS panel open
const AccordionItemContext = createContext<{
  isOpen: boolean;
  value: string;
}>();

AccordionItem reads from root context to determine its state and provides item context to its children (Trigger and Content). The Trigger doesn't need to know about the root's selection model. It only needs isOpen and toggle from its item context.

This two-level context pattern didn't exist in the system until Accordion forced it. It's the kind of structural change that only surfaces when you're actually building components, not when you're designing the architecture upfront.

What I'd tell someone starting a design system

Start with 3 components. Ship them. Use them. Then build 5 more.

The architecture you design upfront for 3 components will be wrong for 8. That's fine. The hooks you write for Dialog will turn out to be the same hooks you need for Popover. But you won't see that until Popover exists. The context model that works for Tabs will need a second level for Accordion. But you won't know that until Accordion forces the change.

The goal of v1 isn't to design the perfect system. It's to build enough components that the shared patterns become visible. Then you refactor toward those patterns. That's how the architecture emerges rather than being imposed.

flintwork's source is on GitHub and the docs are live at flintwork.vercel.app if you want to see how this looks in practice.

eslint-plugin-bad-vibes: I built a linter that enforces the worst frontend practices

venkatesh m — Thu, 02 Apr 2026 14:09:54 +0000

This is a submission for the DEV April Fools Challenge

What I Built

An ESLint plugin with 6 rules that enforce the worst frontend practices with deadpan corporate error messages. Real AST visitors. Real tests. Completely useless output.

Every rule is something I have heard suggested in an actual code review, standup, or Slack thread. Not as a joke. As a genuine engineering opinion delivered with confidence by someone who has never opened a screen reader.

The rules:

Rule	What it enforces
`no-semantic-html`	Flags `<button>`, `<nav>`, `<main>`. Demands `<div>`.
`no-alt-text`	Flags any `<img>` that has an `alt` attribute.
`prefer-positive-tabindex`	Errors on `tabIndex={0}`. Requires `tabIndex={100}` minimum.
`no-aria-allowed`	Flags every `aria-*` attribute as "invisible complexity."
`prefer-inline-styles`	Flags `className`. CSS class names are "indirection."
`no-keyboard-handlers`	Flags `onKeyDown`/`onKeyUp`. Keyboard users are "statistically insignificant."

The error messages are the actual payload. Each one reads like it was copy-pasted from an internal engineering standards document written by someone who has strong opinions about "developer velocity" but has never tabbed through their own product.

Example:

Error: Keyboard handler "onKeyDown" detected. Internal analytics confirm
that keyboard-only navigation represents a statistically insignificant
portion of our user base (estimated <3%, though we have not actually
instrumented this). Supporting keyboard interactions doubles the
interaction surface area of every component, increasing testing burden
and bug surface. Focus engineering effort on the primary input modality
(pointer). Keyboard support is tentatively scheduled for the accessibility
sprint (TBD, see backlog).

If any of these rules made you think "wait, we actually do that" -- that is the point.

Demo

Install it. Run it on your codebase. Watch it flag every good practice you have.

npm install eslint-plugin-bad-vibes --save-dev

// eslint.config.js
import badVibes from 'eslint-plugin-bad-vibes';
export default [badVibes.configs.recommended];

Then run npx eslint src/ and marvel at how much of your codebase is "correct" by bad-vibes standards.

Here's what happens when you run it on a React component:

The recommended config sets all 6 rules to error because bad practices deserve the same enforcement rigor as good ones.

Code

vmvenkatesh78 / eslint-plugin-bad-vibes

ESLint plugin that enforces the worst frontend practices with corporate confidence. 6 rules, 38 tests, zero value.

eslint-plugin-bad-vibes

A production-grade ESLint plugin that enforces the worst frontend practices with the confidence of a principal engineer who has never opened a screen reader.

6 rules. 38 tests. Zero value delivered.

Please do not use this.

Why

Every codebase has unwritten rules that make it worse. This plugin makes them written, enforceable, and blocking in CI.

Born from years of reading code reviews that said things like "do we really need ARIA here?" and "can we just use a div?" This plugin answers: yes. Always. To everything.

Install

npm install --save-dev eslint-plugin-bad-vibes

You won't, but the infrastructure supports it.

Usage

// eslint.config.js
import badVibes from 'eslint-plugin-bad-vibes';

export default [
  badVibes.configs.recommended,
];

All 6 rules ship as errors because bad practices deserve the same enforcement rigor as good ones.

Rules

`no-semantic-html`

Flags <button>, <nav>, <main>, <header>, <footer>, <aside>…

View on GitHub

6 rules, 38 tests, zero dependencies. TypeScript strict mode. ESM + CJS dual build. The engineering is real. The rules are not.

How I Built It

This uses the same AST visitor infrastructure as an actual ESLint plugin I am building, eslint-plugin-a11y-enforce, which catches real accessibility composition errors. Same Rule.RuleModule typing, same JSXOpeningElement traversal, same helper utilities for attribute extraction and element classification.

The stack: TypeScript, tsup for dual CJS/ESM builds, vitest for testing, ESLint's RuleTester for rule validation. Every rule uses proper AST analysis, not string matching or regex.

Writing the error messages was the hardest part. They had to sound exactly corporate enough that you believe someone wrote them unironically. The prefer-positive-tabindex message about "higher-revenue elements should receive lower tabIndex values for earlier focus" came from an actual conversation I overheard. The no-keyboard-handlers message about the "accessibility sprint (TBD, see backlog)" is in every company's Jira right now.

I used Google AI Studio to brainstorm increasingly absurd corporate justifications for each bad practice, then edited them down to the ones that were funny specifically because they sounded plausible. The best satire is indistinguishable from the thing it satirizes.

Prize Category

Community Favorite -- because I want this to be the plugin that makes people laugh, then uncomfortably realize their codebase would pass half these rules.

Best Google AI Usage -- Google AI Studio helped generate the corporate doublespeak for the error messages. The best ones came from prompting Gemini with "write a serious engineering justification for removing all ARIA attributes from a component library" and watching it produce text that was disturbingly close to things I have read in real PRs.

I Built an MCP Server That Lets Designers Change CSS From a Notion Table

venkatesh m — Sat, 14 Mar 2026 20:49:14 +0000

This is a submission for the Notion MCP Challenge

What I Built

A designer opens a Notion table. Changes a color reference. An AI agent reads the change, validates it against every other token in the system, generates new JSON files, runs the build pipeline, and writes "synced" or "error" back to the same Notion row. The CSS output updates. The designer never leaves Notion.

This is flintwork-token-sync — an MCP server that turns Notion into a design token editor for flintwork, a design system I built from scratch with a three-tier token architecture (global → semantic → component), headless React components, and WAI-ARIA compliance.

The problem it solves

Design token handoff is broken. A designer changes a color in Figma. Someone copies the hex value into a JSON file. They typo it. Or they reference a token that was renamed last sprint. Or they change the light theme but forget the dark theme. The build succeeds because JSON doesn't validate intent — and the wrong color ships to production.

The fix is not more process. It's making the source of truth editable by designers with validation that catches errors before they reach code.

How it works

Four Notion databases mirror the three tiers of the token system, plus an audit log:

Global Tokens — 93 raw palette values. Every color, spacing value, font size, and shadow in the system. Each row is a token with its name, value, type, and sync status.

Semantic Tokens — 96 intent mappings across light theme, dark theme, and typography. color.text.primary references {color.gray.900} in light mode and {color.gray.50} in dark mode. A designer changing the primary text color edits one cell. Both themes stay consistent because the architecture enforces it.

Component Tokens — 64 component-specific bindings. button.primary.bg references {color.interactive.default}. The designer doesn't need to know the hex value — they work at the intent level.

Build Log — Every sync recorded. Timestamp, result, token counts, errors. The complete audit trail.

When a designer edits a token value in Notion, they tell Claude: "Sync my design tokens." Claude orchestrates two MCP servers:

Notion MCP (remote) — reads token data from the four databases, writes sync status and build log entries back
flintwork-token-sync MCP (local) — validates all 253 tokens, generates JSON files, runs the build pipeline that produces CSS custom properties

The sync validates everything before writing anything. If a designer references {color.purple.999} and that token doesn't exist, the sync stops. No JSON generated. No CSS changed. The error appears in the Notion row's Error column: "Unresolved reference: {color.purple.999} does not match any known token." The designer sees it immediately, fixes it, syncs again.

Five MCP tools

Tool	What it does
`sync_tokens`	Full pipeline: read → validate → generate JSON → build CSS → write status back
`validate_tokens`	Read and validate only — preview errors before committing
`diff_tokens`	Compare Notion state against files on disk — see what would change
`build_tokens`	Run the CSS build on existing JSON files
`get_token_summary`	Current state: counts, status breakdown, errors

The diff tool is what makes this practical for a real workflow. Before syncing, the designer asks "What changed?" and sees exactly which tokens were modified and what the old and new values are. No surprises.

What makes this different from a Notion API integration

This is not a script that calls the Notion API. It's a custom MCP server that Claude Desktop connects to alongside Notion MCP. The AI agent orchestrates both servers — reading from one, processing through the other, writing results back. The MCP protocol is the connective tissue, not a wrapper.

The validation is real. It checks:

Token name format (dot-separated alphanumeric)
Color values (hex format, transparent, none)
Dimension values (px, rem, unitless for line-height)
Font weights (numeric only)
Reference resolution (does the referenced token exist?)
Circular references (A references B references A)

The build is real. The generated JSON feeds into flintwork's token build pipeline, which resolves cross-tier references and outputs CSS custom properties with full theme support. A single [data-theme="dark"] attribute swap on the root element switches every color in the system.

Video Demo

Watch the demo →

Show us the code

vmvenkatesh78 / flintwork-token-sync

MCP server that syncs design tokens between Notion and flintwork's token pipeline.

flintwork-token-sync

MCP server that syncs design tokens between Notion databases and flintwork's token pipeline. Designers edit tokens in Notion, an AI agent validates and builds them into CSS.

Architecture

Claude Desktop
    ├── Notion MCP (remote) — reads/writes Notion workspace
    └── flintwork-token-sync MCP (local) — validates, generates, builds

Claude orchestrates both MCP servers. It reads token state from Notion via Notion MCP, calls this server's tools to validate and build, and writes results back to Notion via Notion MCP.

MCP Tools

Tool	What it does
`sync_tokens`	Full pipeline: read → validate → generate JSON → build CSS → write status + build log
`validate_tokens`	Read and validate only — check for errors before committing
`diff_tokens`	Compare Notion state against JSON files on disk — preview what would change
`build_tokens`	Run the build pipeline on existing JSON files
`get_token_summary`	Read current state from Notion — counts, status breakdown, errors

Notion Databases

…

View on GitHub

Key files:

src/core/sync.ts — The orchestrator. Single source of truth for the read → validate → generate → build → write-status pipeline. Both the MCP server and CLI call this function.
src/core/validate.ts — Token validation. Hex format, reference resolution, circular reference detection, token name format. Pure functions, no Notion dependency.
src/core/diff.ts — Compares Notion state against JSON files on disk. Normalizes values (arrays to comma-separated, numbers to strings) for accurate comparison.
src/core/generate-json.ts — Transforms Notion rows into flintwork-compatible JSON. Groups by category, theme, and component. Handles font weights as numbers, font families as arrays.
src/mcp-server/server.ts — Five MCP tools registered with the MCP SDK. Each tool is a thin wrapper around core functions.
src/core/build-log.ts — Writes audit trail entries to the Build Log database after every sync.

The design system it syncs to: flintwork — headless React components (Button, Dialog, Tabs) with compound component API, full WAI-ARIA compliance, and 190 tests.

Architecture:

Claude Desktop
    ├── Notion MCP (remote)
    │   └── reads/writes 4 Notion databases
    └── flintwork-token-sync MCP (local)
        ├── validate_tokens    → hex, refs, cycles, names
        ├── diff_tokens        → compare Notion vs disk
        ├── sync_tokens        → full pipeline
        ├── build_tokens       → run CSS build
        └── get_token_summary  → current state
                ↓
        flintwork/src/tokens/ (JSON files)
                ↓
        flintwork/dist/tokens/tokens.css (CSS output)

Tests: 59 tests covering validation (token names, all value types, reference resolution, circular detection), JSON generation (file grouping, value formatting, all three tiers), and diff (added, removed, modified, unchanged, normalization).

How I Used Notion MCP

Notion MCP is not a backend for this project. It's the entire interface. There is no dashboard, no separate UI, no frontend. The designer works in Notion. The AI agent works through Notion MCP.

Reading tokens: Claude reads all four databases through Notion MCP. Each token is a row with properties — Name (title), Value/Reference (text), Type/Theme/Component (select), Status (select), Last Synced (date), Error (text). The MCP server normalizes these into typed objects for validation.

Writing status: After every sync, the tool writes back to each changed row. Successful sync → Status: "synced", Last Synced: timestamp, Error: cleared. Validation failure → Status: "error", Error: specific message. The designer sees the result in the same table they edited, without switching tools.

Build log: Every sync writes a new row to the Build Log database — timestamp, result, token counts per tier, errors. The designer can open the Build Log and see the complete history of every sync.

Diff preview: Before syncing, the designer can ask Claude "What changed?" Claude reads the current Notion state via MCP and compares it against the JSON files on disk. The diff shows exactly which tokens were added, removed, or modified with before/after values.

Why MCP, not just the Notion API: The same validation and build logic is available as a CLI (npm run cli sync) for CI pipelines and scripts. But the MCP interface is what makes it accessible to designers. They don't run terminal commands. They talk to Claude in a chat window. Claude handles the orchestration — reading from Notion MCP, calling the custom MCP server for validation and build, writing results back through Notion MCP. Two MCP servers, one AI agent, bidirectional flow.

Optimized write-back: The initial implementation wrote status to all 253 rows on every sync (~88 seconds at Notion's rate limit). This exceeded Claude Desktop's MCP tool call timeout. The fix: only write back to rows whose status actually changed. A typical sync after one designer edit writes 1 row instead of 253.

Headless Components Are Useless Without a Styling Strategy

venkatesh m — Fri, 13 Mar 2026 03:10:32 +0000

Most headless component libraries stop at behavior. They give you a Dialog that traps focus and a Tabs component with roving tabindex, then tell you to "bring your own styles."

That's where most side projects stop too. The headless primitives work. The README says "unstyled." And the components sit in a repo that nobody wants to actually use — because now the consumer owns all the CSS, and without a token system driving it, the visual consistency depends entirely on discipline.

The gap isn't behavior. It's the bridge between behavior and presentation. How do you add a visual layer on top of headless primitives without welding the two together? How do you let the token pipeline drive every color, every spacing value, every border radius — while keeping the styled layer thin enough that replacing it doesn't mean rewriting the component?

That's what Phase 3 of flintwork solves. And the answer turned out to be surprisingly small.

The Two-Layer Architecture

Every component in flintwork exists as two things:

A headless primitive that owns behavior — state management, keyboard interactions, focus trapping, ARIA attributes. Zero styling. Outputs plain HTML with the right attributes and event handlers. This is what Articles 1 and 2 covered.

A styled wrapper that owns presentation — colors, spacing, typography, borders, shadows. Consumes the primitive, adds a single data attribute, and ships a CSS file that targets that attribute. The wrapper is so thin it's almost trivial. That's the point.

// Headless — behavior only, no opinions
import { Button } from 'flintwork/primitives';

// Styled — behavior + token-driven visuals
import { Button } from 'flintwork';
import 'flintwork/styles/button.css';

The consumer picks which layer they want. Teams that need full visual control use the primitive and write their own CSS. Teams that want a working design system out of the box use the styled export. Both share the same accessibility and keyboard behavior because that lives in the primitive, not the styles.

The exports field in package.json maps each import path to the correct file — TypeScript types, ESM, CJS, and CSS all resolved per path. flintwork/styles/button points to a single CSS file. A consumer who only uses Button doesn't load Dialog or Tabs CSS. Tree-shaking at the CSS level, not just the JavaScript level.

Why Not CSS-in-JS, CSS Modules, or Tailwind?

Every CSS strategy has a runtime or tooling cost. CSS-in-JS adds JavaScript to your bundle that runs on every render. CSS Modules require a bundler plugin — your consumer's build pipeline has to support them. Tailwind needs its own build step and a config file.

The styled layer uses plain CSS files with data attribute selectors. No runtime. No bundler plugin. No config. The consumer imports a .css file and the styles apply. If their bundler can handle CSS imports (every modern bundler can), it works.

The selectors target data attributes that the headless primitive already emits:

[data-fw-button] { /* base structure */ }
[data-fw-button][data-variant="primary"] { /* primary colors */ }
[data-fw-button][data-size="md"] { /* medium sizing */ }
[data-fw-button]:hover { /* hover state */ }

The primitives emit data-variant, data-size, data-state, data-loading, aria-disabled — all the state the CSS needs to respond to. The styled layer doesn't inject any JavaScript. It reads what the primitive already outputs.

In DevTools, you see data-variant="primary" on the element and [data-variant="primary"] in the stylesheet. Self-documenting. No generated class names, no hash suffixes, no layer of indirection between what you see in the DOM and what you see in the CSS.

The CSS Pattern That Killed Repetition

A button has four variants (primary, secondary, danger, ghost), three sizes (sm, md, lg), and multiple states (hover, active, focus, disabled, loading). That's potentially dozens of selector blocks, each repeating the same property declarations with different values.

The first approach I tried was direct:

[data-variant="primary"] {
  background: var(--fw-button-primary-bg);
  color: var(--fw-button-primary-text);
  border-color: var(--fw-button-primary-border);
}

[data-variant="primary"]:hover {
  background: var(--fw-button-primary-bgHover);
  color: var(--fw-button-primary-text);
  border-color: var(--fw-button-primary-border);
}

[data-variant="secondary"] {
  background: var(--fw-button-secondary-bg);
  color: var(--fw-button-secondary-text);
  border-color: var(--fw-button-secondary-border);
}

/* repeat for every variant × every state */

It works. But the background, color, and border-color declarations repeat in every block. Add a fifth variant and you're writing the same three lines again. Add a property — say box-shadow — and you're editing every variant block.

The pattern that fixed this: declare the structure once, let variants swap values.

/* Structure — declared once, never repeated */
[data-fw-button] {
  background: var(--_bg);
  color: var(--_text);
  border: 1px solid var(--_border);
  padding: var(--_py) var(--_px);
  font-size: var(--_fs);
}

/* Variants only assign values to the intermediates */
[data-variant="primary"] {
  --_bg: var(--fw-button-primary-bg);
  --_text: var(--fw-button-primary-text);
  --_border: var(--fw-button-primary-border);
}

[data-variant="primary"]:hover {
  --_bg: var(--fw-button-primary-bgHover);
}

[data-variant="secondary"] {
  --_bg: var(--fw-button-secondary-bg);
  --_text: var(--fw-button-secondary-text);
  --_border: var(--fw-button-secondary-border);
}

The --_ prefix marks these as component-private intermediate variables. They're not part of the token system — consumers never reference --_bg directly. They're internal wiring that connects the token pipeline to the CSS declarations.

The base selector says what properties a button uses. The variant selectors say which token values fill those properties. Adding a fifth variant is one block of variable assignments — no structural changes to the base.

The hover block for primary is a single line. It only overrides --_bg because the text and border don't change on hover. In the direct approach, you'd repeat all three properties just to change one.

This is the same principle as the token architecture itself: separate what something is from how it's configured.

The Styled Wrapper Is Almost Nothing

Here's the entire styled Button component:

export const Button = forwardRef(
  <T extends ElementType = 'button'>(
    props: StyledButtonProps<T>,
    ref: React.Ref<Element>,
  ) => {
    return (
      <ButtonPrimitive
        ref={ref}
        data-fw-button=""
        {...props}
      />
    );
  },
);

One attribute: data-fw-button="". That's the only thing the styled layer adds. Everything else — the variant prop, the size prop, loading state, disabled state, aria attributes, keyboard handlers, polymorphic as prop — passes straight through to the primitive.

The CSS file targets [data-fw-button]. Without the CSS import, this component renders identically to the headless primitive. The attribute is inert until the stylesheet loads.

Dialog follows the same pattern but only wraps the sub-components that produce visible DOM:

Dialog          → pass-through (no DOM, pure context)
Dialog.Trigger  → pass-through (renders consumer's child)
Dialog.Portal   → pass-through (createPortal wrapper)
Dialog.Overlay  → adds data-fw-dialog-overlay
Dialog.Content  → adds data-fw-dialog-content + size prop
Dialog.Title    → adds data-fw-dialog-title
Dialog.Description → adds data-fw-dialog-description
Dialog.Close    → pass-through (renders consumer's child)

Five of eight sub-components pass through untouched. The styled layer only touches what has pixels on screen.

Tokens Drive Everything

Every value in the CSS comes from the token pipeline. Not a single hardcoded color, spacing value, or font size in any stylesheet.

The resolution chain from the first article is what makes this work:

button.json:     button.primary.bg = {color.interactive.default}
light.json:      color.interactive.default = {color.blue.500}
colors.json:     color.blue.500 = #217CF5

→ CSS output:    --fw-button-primary-bg: #217CF5
→ Button CSS:    --_bg: var(--fw-button-primary-bg)
→ Rendered:      background: #217CF5

Switch to dark mode — swap data-theme="dark" on the root element — and the semantic layer remaps color.interactive.default to color.blue.400 (#4C97FF). The component CSS doesn't change. The token pipeline resolves the new chain. Every button on the page updates.

The styled layer doesn't know about themes. It doesn't know about light or dark. It references token custom properties, and the token pipeline handles the rest. That separation is what makes theme switching a single attribute change instead of a stylesheet swap.

What Went Wrong During the Build

Object.assign mutated the primitive. The compound component pattern uses Object.assign(Root, { Trigger, Content, ... }) to create the dot-notation API. When the styled wrapper did Object.assign(DialogPrimitive, { Content: StyledContent }), it replaced Dialog.Content globally — including for consumers importing from flintwork/primitives. A consumer using the headless layer would silently get styled sub-components.

The fix: create a new root function instead of mutating the imported primitive.

// Wrong — mutates the primitive
export const Dialog = Object.assign(DialogPrimitive, { ... });

// Right — new object, primitive untouched
function StyledDialogRoot(props) {
  return <DialogPrimitive {...props} />;
}
export const Dialog = Object.assign(StyledDialogRoot, { ... });

This is the kind of bug that doesn't show up in tests because tests import from one entry point. It shows up in production when two teams import from different entry points in the same app.

Polymorphic typing collapsed. The styled Button wraps the primitive Button, which supports <Button as="a" href="...">. But React.ComponentPropsWithoutRef<typeof ButtonPrimitive> doesn't thread the generic through — TypeScript collapses it to the default 'button' case and href becomes a type error.

The fix: re-declare the full polymorphic type on the styled wrapper. Same pattern as the primitive — generic T extends ElementType, Omit<ComponentPropsWithoutRef<T>, keyof OwnProps>. The styled layer can't inherit polymorphic types automatically. It has to re-establish them.

CSS files don't copy themselves. tsup compiles TypeScript. It does not touch CSS files. After tsup runs, dist/styled/button.css doesn't exist even though package.json exports point to it. Added an onSuccess hook in the tsup config that copies CSS files to dist/ after every build.

What I'd Build Next

Scroll lock on Dialog. When the dialog opens, the page behind it should stop scrolling. Right now it doesn't. The fix is straightforward — set overflow: hidden on document.body when the dialog mounts, restore on unmount. Deferred because it's a CSS concern, not a behavior concern, and the focus trap already prevents keyboard scrolling. Mouse wheel scrolling on the overlay is the gap.

CSS animations. The overlay and content both appear and disappear instantly. A fade-in on the overlay and a scale-in on the content would make the transitions feel finished. The styled layer already has data-state="open" and data-state="closed" attributes from the primitive — CSS transitions can target those without any JavaScript changes. The animation is purely a presentation concern, which is exactly what the styled layer is for.

More components. Three components prove the architecture. Ten components prove it scales. Tooltip, Select, Popover, Menu, Accordion — each one follows the same pattern: headless primitive with hooks, thin styled wrapper with data attributes, CSS file with intermediate variables, component tokens in JSON. The first component took days. Each subsequent one takes hours. That ratio is the return on the architectural investment.

This is Part 3 of the Building flintwork series. Part 1 covers the token pipeline. Part 2 covers the headless primitives and accessibility. The full source is on GitHub.

Your Dialog Has role='dialog'. That Doesn't Make It Accessible.

venkatesh m — Fri, 06 Mar 2026 13:51:13 +0000

The Attribute Isn't the Behavior

Open any component library's Dialog implementation. You'll find role="dialog" and aria-modal="true" on the content panel. Check the box, ship it, call it accessible.

Now try using it with a keyboard.

Open the dialog. Press Tab. Where does focus go? If it goes behind the dialog to the page content, the dialog isn't accessible — a keyboard user is now interacting with elements they can't see, behind a modal overlay. Press Tab twelve more times. If focus never wraps back to the first element inside the dialog, it's not trapped. Press Escape. If the dialog doesn't close and return focus to the button that opened it, a keyboard user is stranded.

role="dialog" tells a screen reader "this is a dialog." It doesn't trap focus. It doesn't handle Escape. It doesn't restore focus on close. It doesn't prevent clicks outside from reaching the page behind. It's a label, not a behavior.

The gap between "has the right ARIA attributes" and "actually works for someone using a keyboard or screen reader" is where most component libraries cut corners. Not out of malice — out of complexity. A fully accessible modal dialog requires a focus trap with tabbable element detection, click-outside dismissal that doesn't false-positive on drag events, Escape key handling that doesn't leak to parent components, focus restoration to the trigger element, and initial focus placement with a priority chain. That's five independent behaviors converging on one component.

I built all of it from scratch for flintwork — a headless design system where the primitives handle behavior and accessibility with zero styling. No Radix import, no Headless UI dependency. Every hook, every edge case, hand-written and tested.

Here's what that taught me.

What a Screen Reader Actually Hears

While studying existing implementations — reading the WAI-ARIA authoring practices alongside Radix's source code — I spent time with VoiceOver on macOS testing dialog behavior. The difference between a properly built dialog and a half-built one is immediately obvious — not visually, but audibly.

A properly built dialog trigger announces: "Open settings, button, dialog popup." Three pieces of information from three attributes: the text content, the element role, and aria-haspopup="dialog" telling the user that activating this button will open a dialog.

When the dialog opens, VoiceOver announces: "Settings, dialog. Update your preferences." The title comes from aria-labelledby pointing to the dialog's heading. The description comes from aria-describedby. Without aria-labelledby, VoiceOver just says "dialog" — no context, no purpose. The user has to navigate around inside the dialog to figure out what it's for.

When the user presses Escape, the dialog closes and VoiceOver announces: "Open settings, button." Focus returned to the trigger. The user is back where they started. Without focus restoration, the user lands on <body> or the first focusable element on the page — they've lost their place entirely.

Every ARIA attribute is an audio experience. Once you hear the difference, writing aria-labelledby stops being a spec compliance checkbox and starts being "the thing that makes the dialog announce its purpose."

The Problem With Monolithic Components

A single-component Dialog looks clean at first:

<Dialog
  triggerText="Open"
  title="Confirm"
  onConfirm={handleConfirm}
/>

Then requirements arrive. Custom trigger? Add a renderTrigger prop. Form content? Add children. Multiple action buttons? Add footer. Two close buttons? Now you need renderFooter. Twelve props later, half of them render functions, and you still can't put the close button where you want it.

Compound components solve this with composition:

<Dialog open={open} onOpenChange={setOpen}>
  <Dialog.Trigger>
    <button>Open settings</button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>Settings</Dialog.Title>
      <Dialog.Description>
        Update your preferences.
      </Dialog.Description>
      <Dialog.Close>
        <button>Done</button>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog>

The consumer controls the structure. The compound components handle the behavior. Dialog.Trigger automatically gets aria-haspopup="dialog" and aria-expanded. Dialog.Content automatically gets role="dialog" and aria-modal="true". The consumer doesn't think about ARIA. They get it for free.

Seven sub-components, but the complexity concentrates in one. Dialog.Content is where all three behavioral hooks converge — useFocusTrap for Tab cycling, useClickOutside for dismissal, and the Escape key handler. Every other sub-component either provides context, renders a portal, or attaches a click handler. Content does the heavy lifting.

Building the Focus Trap

The focus trap is the hardest piece. It's also the piece that makes the dialog actually accessible versus just labeled as accessible.

What "Tabbable" Means

Before you can trap focus, you need to know what focus can land on. The list is longer than most developers expect:

<a href>, <button> (not disabled), <input> (not disabled, not type="hidden"), <select> (not disabled), <textarea> (not disabled), <summary>, [tabindex="0"], <iframe>, <audio controls>, <video controls>, [contenteditable].

But matching the selector isn't enough. An element that matches button:not(:disabled) can still be untabbable if it or an ancestor has display: none, if it has visibility: hidden, if it's inside a closed <details> element (except the <summary>), if it has [inert] or lives inside an [inert] ancestor, or if it has tabindex="-1" (focusable via .focus() but skipped by Tab).

Each of those is a filter that runs on every candidate. The tabbable query re-runs on every Tab press — no caching — because content inside the dialog can change while it's open. A form that conditionally reveals a field, a loading state that resolves to a button, an error message with a retry link.

One early bug: <details> was in the selector, but <details open> matched alongside its <summary> child, returning three elements where the DOM only had two interactive ones. The fix was removing details from the selector entirely — <summary> is the interactive element users Tab to, <details> is just the container.

The Trap Lifecycle

Activation. Focus moves into the dialog. Priority chain: a specific element if provided → an element with [data-autofocus] → the first tabbable element → the container itself.

Active. Tab on the last element wraps to the first. Shift+Tab on the first wraps to the last. If focus somehow escapes — screen reader virtual cursor, programmatic focus change — a focusin guard pulls it back.

Deactivation. Focus returns to whatever was focused before the dialog opened. Usually the trigger button.

useEffect(() => {
  if (!enabled) return;
  const container = containerRef.current;
  if (!container) return;

  previouslyFocused.current = document.activeElement as HTMLElement;
  placeInitialFocus();

  document.addEventListener('keydown', handleKeyDown, true);
  document.addEventListener('focusin', handleFocusIn, true);

  return () => {
    document.removeEventListener('keydown', handleKeyDown, true);
    document.removeEventListener('focusin', handleFocusIn, true);
    const toRestore = previouslyFocused.current;
    if (toRestore?.isConnected) {
      toRestore.focus();
    }
  };
}, [enabled]);

No requestAnimationFrame. An earlier version used rAF under the assumption that React might not have committed the portal to the DOM by the time the effect runs. This was wrong — useEffect fires after the browser has painted. The container and its children are guaranteed to exist. The rAF added unnecessary async complexity and broke under test frameworks with fake timers. Removing it simplified both the implementation and the tests.

The Tab Cycling Logic

function handleKeyDown(event: KeyboardEvent) {
  if (event.key !== 'Tab') return;
  const container = containerRef.current;
  if (!container) return;

  const tabbable = getTabbableElements(container);
  if (tabbable.length === 0) {
    event.preventDefault();
    return;
  }

  const active = document.activeElement as HTMLElement;
  const first = tabbable.at(0) ?? null;
  const last = tabbable.at(-1) ?? null;

  // Focus is outside the container entirely — pull it back in
  if (!container.contains(active)) {
    event.preventDefault();
    first?.focus();
    return;
  }

  if (event.shiftKey && active === first) {
    event.preventDefault();
    last?.focus();
  } else if (!event.shiftKey && active === last) {
    event.preventDefault();
    first?.focus();
  }
}

The key insight: you only need to intercept Tab at the boundaries and when focus has escaped. When focus is on the last element and the user presses Tab, prevent the default and focus the first. When focus is on the first and the user presses Shift+Tab, focus the last. The !container.contains(active) check handles the case where focus escaped via screen reader virtual cursor before the focusin guard fired. Everywhere else, the browser's native Tab behavior works correctly within the container.

Building useClickOutside

Clicking outside the dialog should close it. Simple concept, subtle implementation.

Why mousedown, not click. A click event fires after mouseup. If a user presses inside the dialog, drags outside, and releases, a click fires outside the dialog. The dialog would incorrectly dismiss. mousedown captures intent at the moment of press. Same logic applies to touchstart for mobile.

Why capture phase. The listener uses addEventListener('mousedown', handler, true). Capture fires before the event reaches child elements. If a child inside the dialog calls stopPropagation(), a bubble-phase listener on document would never see the event. Capture guarantees the check runs regardless.

The handler ref pattern. The handler is stored in a ref so the effect doesn't re-attach listeners when the handler changes. The ref always holds the latest function — no stale closures — and the consumer doesn't need to memoize their callback with useCallback.

const handlerRef = useRef(handler);
handlerRef.current = handler;

Roving Tabindex: Why Arrow Keys Matter

A tab bar with five triggers, all with tabindex="0", requires pressing Tab five times to get past it. Roving tabindex solves this. Only the active trigger gets tabindex="0". All others get tabindex="-1". Tab enters, lands on the active trigger, next Tab exits. Arrow keys move between triggers.

The hook handles orientation awareness (horizontal tabs ignore ArrowUp/Down, vertical menus ignore ArrowLeft/Right), loop wrapping, disabled item skipping, and Home/End keys.

The part that surprised me was bridging focus and selection. When the hook moves focus to a new tab trigger, onActiveChange fires. The callback reads document.activeElement.dataset.value and updates the selected tab — making arrow keys both move focus AND select. This is automatic activation, the WAI-ARIA default.

useRovingTabIndex(listRef, {
  orientation,
  loop: true,
  onActiveChange: () => {
    const focused = document.activeElement as HTMLElement;
    const value = focused?.dataset.value;
    if (value) onValueChange(value);
  },
});

This works because .focus() is synchronous — document.activeElement updates immediately. But it's the kind of assumption that breaks silently if someone later makes the hook async. That's a comment in the code now.

The Compound Component Wiring

Dialog and Tabs both use the same pattern. The root is a pure context provider — no DOM output. Sub-components read from context. Object.assign enables dot notation:

export const Dialog = Object.assign(DialogRoot, {
  Trigger: DialogTrigger,
  Portal: DialogPortal,
  Overlay: DialogOverlay,
  Content: DialogContent,
  Title: DialogTitle,
  Description: DialogDescription,
  Close: DialogClose,
});

Both components support controlled and uncontrolled usage via a useControllable hook. The mode detection checks value !== undefined. Not value !== null. Not !!value. Specifically undefined. This matters because null is a valid controlled value — the parent is explicitly saying "nothing selected right now." false is a valid controlled value — a dialog that's closed. 0 is a valid controlled value — a tabs component where the first tab is selected by index. The only signal that a component is uncontrolled is when the parent never passed value at all. In React, an omitted prop is undefined. Every other falsy value is an intentional choice by the consumer.

For Tabs, triggers and panels are linked by a string value prop — not by index. Indices break when you reorder tabs, conditionally render them, or add them dynamically. Strings survive structural changes. The ARIA cross-references (aria-controls on triggers, aria-labelledby on panels) are derived deterministically from a base id:

function getTriggerId(baseId: string, value: string) {
  return `${baseId}-trigger-${value}`;
}

function getPanelId(baseId: string, value: string) {
  return `${baseId}-panel-${value}`;
}

No registration system where components mount and register their ids. No mount-order dependency — the trigger doesn't need to render before the panel for the ids to exist. Pure derivation from baseId + value. Both functions live in the context file and are called by Trigger (to set aria-controls={getPanelId(...)}) and Panel (to set aria-labelledby={getTriggerId(...)}).

The ARIA You Don't See

Every ARIA attribute is a real audio experience. This stopped being abstract after testing with VoiceOver.

On the trigger:

Attribute	What the user hears
`aria-haspopup="dialog"`	"dialog popup" after the button label
`aria-expanded`	"expanded" / "collapsed"
`aria-controls`	Used for virtual cursor navigation

On the dialog panel:

Attribute	What the user hears
`role="dialog"`	"dialog"
`aria-modal="true"`	Constrains virtual cursor to dialog
`aria-labelledby`	Reads the title text on open
`aria-describedby`	Reads description after title

On tabs:

Element	What the user hears
`role="tablist"` + `role="tab"`	"Account, tab 1 of 3"
`aria-selected`	"selected"
`tabindex="0"` on panel	Tab from tablist lands on panel content

The tabindex="0" on the panel is easy to miss but important. After selecting a tab with arrow keys, pressing Tab should land on the panel content — not skip to some other focusable element elsewhere on the page. The panel itself needs to be a tab stop.

None of this is visible. All of it is load-bearing.

What Broke Along the Way

Three things broke in ways I didn't expect.

jsdom doesn't do layout. The focus trap's visibility check used el.offsetParent === null — the standard browser approach. jsdom doesn't implement offsetParent. It's always null. Every element was being filtered out as "hidden." The fix was replacing offsetParent with a getComputedStyle ancestor walk checking for display: none.

jsdom lies about tabIndex. In a real browser, a <button> without an explicit tabindex attribute has tabIndex === 0. In jsdom, it returns -1. A check like if (el.tabIndex < 0) return false silently filters out every button and input. The fix: only check el.tabIndex when el.hasAttribute('tabindex'). If the element matched the focusable selector, trust the selector.

React 18 vs 19 context syntax. The root component used <DialogContext value={context}> — React 19 syntax. React 18 requires <DialogContext.Provider value={context}>. Without .Provider, context is null and every compound component throws. A one-line fix, but Tabs used .Provider from the start — lesson learned.

What I'd Do Differently

Scroll lock. When the dialog opens, the page behind it should stop scrolling. I deferred this because the headless primitive shouldn't own the implementation — scroll lock involves document.body style manipulation that varies by browser and layout. But the primitive should at least provide a hook or callback for consumers to attach their own. That API gap is the first thing I'd add.

aria-describedby pointing to nothing. If the consumer renders Dialog.Content without Dialog.Description, aria-describedby still points to the generated id. Screen readers handle broken id references gracefully — they ignore them. But it's not clean. A v2 would conditionally add aria-describedby only when Description is mounted, which means a registration mechanism between Content and Description. I chose the simpler approach for v1.

Animation support. The compound component pattern gives consumers direct access to Overlay and Content, so they can animate with CSS transitions or any library. But there's no onExitComplete callback — no way to tell the primitive "don't unmount yet, the exit animation is still running." Solving this cleanly requires either a render-even-when-closed prop or an animation-aware state machine. Both add complexity. I'd solve it before shipping to npm.

var() chains in the token output. This carries over from the token pipeline article. When the styled layer wraps these headless primitives with token-driven CSS, the flat hex values in the generated output mean every semantic change requires a rebuild. var() chains would cascade at runtime. For a published design system, that's the right trade-off — and the first thing I'll revisit in Phase 3.

All three primitives, the hooks that power them, and 173 tests are in the flintwork repo. The next phase is a styled layer that consumes these primitives and applies token-driven CSS — connecting the design token pipeline to the components that use them.

The thing I keep coming back to: accessibility isn't a feature you add to components. It's the architecture of the component. The focus trap isn't a wrapper around the dialog — it's what makes the dialog a dialog. The roving tabindex isn't an enhancement to the tab bar — it's what makes keyboard navigation usable. When you build the behavior layer first, the accessibility comes with it. When you build the visual layer first and add accessibility later, it never quite fits.

130 Shades of Gray: Building a Design Token Pipeline That Killed Our Color Chaos

venkatesh m — Sun, 01 Mar 2026 14:09:48 +0000

The Codebase That Had 130 Grays

I spent four years working in a production codebase that had 130 gray variables. I actually counted them once.

Someone needs a border color, creates $gray-v1. Someone else needs a slightly darker background,doesn't find the right gray in the file — or can't tell which of 130 is correct — creates $gray-v2. Four years of that across 5 product modules and this is what you get:

$gray-v12: #6B7280;
$gray-v13: #6E7581;
$gray-v14: #707682;
$gray-v38: #4A5163;
$gray-v39: #4B5264;
$gray-v47: #5C6370;
$gray-v89: #3D4450;

Seven variables. Can you tell them apart by hex value? We couldn't either. $gray-v38 and $gray-v39 differ by one hex digit. They were used on different screens for the same purpose — disabled text. Created six months apart by two different developers who had no way of knowing the other one existed.

And the grays weren't even the worst part — the utility classes were.

.FontSm14GrayV52 {
  font-size: 14px;
  color: $gray-v52;
}

.FontRg16GrayV23 {
  font-size: 16px;
  color: $gray-v23;
}

.BgGrayV7Pd12 {
  background-color: $gray-v7;
  padding: 12px;
}

Font size, color, and gray version baked into one class name. Need the same gray at a different font size? New class. Same font size, different gray? Another class.

Now imagine a designer updates the disabled text color from #6B7280 to #8B95A5. Go find every gray variable that was being used as disabled text. Not labeled as disabled text — just happening to be that hex value, or one digit away from it, scattered across 130 numbered variables and 200+ utility classes. Good luck.

Nobody built this mess on purpose. There was no architecture to prevent it. What was missing wasn't discipline — it was a system.

Why This Happens

The instinct is to blame developers. Better naming conventions. Stricter code review. More discipline.

We tried all of that. It doesn't work — not at scale, not over time.

Here's what actually happens. A developer needs a color for disabled text. They open the variables file, see 80 grays with names like $gray-v52 and $gray-v61, and have no way to know which one is "the disabled text gray." Nothing in the name tells them. Nothing in the system maps intent to value. So they pick one that looks close enough, or they create a new one. Both choices are rational. Both make the problem worse.

Code review doesn't catch this because the reviewer is looking at the same meaningless variable names. They can verify that a gray was used. They can't verify it was the right gray. There's no source of truth to check against.

Naming conventions help for about six months. Then the team grows, the conventions drift, someone joins who never read the doc, and you're back to $gray-v131.

The problem isn't that developers make bad choices. It's that the system they're working in makes the right choice invisible. You can't consistently pick the correct gray if nothing in the codebase defines what "correct" means.

The Three-Tier Model

Take one gray: #6B7280. In the old system, that hex value could live in $gray-v12 or $gray-v47 or a utility class or hardcoded inline. No meaning attached, no intent captured. Just a color floating in a file somewhere.

In a token system, that same gray passes through three layers before it ever reaches a component.

Tier 1 — Global tokens. These are the raw palette. Every color, every spacing value, every font size your system supports. Named by what they are, not what they do.

{
  "color": {
    "gray": {
      "500": { "$value": "#6B7280" },
      "600": { "$value": "#4B5563" },
      "700": { "$value": "#374151" }
    }
  }
}

color.gray.500 is a fact. It's a gray. It's the 500 weight in your scale. It says nothing about where it goes or why it exists. That's intentional — global tokens are the raw material, not the decisions.

Tier 2 — Semantic tokens. This is where intent enters the system. Semantic tokens don't define colors — they define purposes and point to a global token.

{
  "color": {
    "text": {
      "primary": { "$value": "{color.gray.700}" },
      "secondary": { "$value": "{color.gray.500}" },
      "disabled": { "$value": "{color.gray.500}" }
    },
    "border": {
      "default": { "$value": "{color.gray.500}" }
    }
  }
}

Now #6B7280 has meaning. It's color.text.secondary. It's color.text.disabled. It's color.border.default. Three different purposes, same underlying value — and that relationship is explicit, not accidental.

Remember the designer changing the disabled text color? In the old system, that was an archaeology project across 130 variables. Here, you update color.text.disabled to point to color.gray.600 instead of color.gray.500. One change. Every disabled text element in the product updates. Nothing else is affected.

Tier 3 — Component tokens. These bind semantic tokens to specific component surfaces.

{
  "button": {
    "text": {
      "disabled": { "$value": "{color.text.disabled}" }
    }
  },
  "input": {
    "text": {
      "disabled": { "$value": "{color.text.disabled}" }
    }
  }
}

A developer building a button never picks a gray. They use --fw-button-text-disabled. They don't need to know it resolves to color.text.disabled, which resolves to color.gray.500, which resolves to #6B7280. The chain exists, but the developer at the end of it just sees a name that tells them exactly what it's for.

This is what it looks like when the system makes the right choice the only choice. There's no wrong gray to pick because developers aren't picking grays. They're picking intentions — --fw-button-text-disabled, --fw-input-border-default, --fw-card-bg-primary — and the token pipeline resolves those intentions to actual values.

And here's where theming comes in for free. The entire resolution chain above is your light theme. Your dark theme is a second set of semantic mappings pointing to different global tokens:

{
  "color": {
    "text": {
      "disabled": { "$value": "{color.gray.400}" }
    }
  }
}

Same component tokens. Same developer API. Different underlying values. Swap a single attribute on the root element:

<div data-theme="dark">
  <!-- every component re-resolves automatically -->
</div>

No separate stylesheet. No conditional logic in components. The architecture handles it.

The Build

The full pipeline is in the flintwork repo if you want every line. Here I'll walk through the parts that do the actual work.

The input is a folder of JSON files organized by tier — global/ for the raw palette, semantic/ for theme mappings, component/ for component-level bindings. The output is CSS files with custom properties scoped to data-theme attributes. One build script, no Style Dictionary, no runtime dependencies.

Flattening nested tokens.

Token files are nested JSON following the W3C Design Tokens format. A token has a $value — everything else is a group container. The first step is flattening that tree into a flat map of dot-notation paths to values:

function flattenTokens(
  group: TokenGroup,
  prefix: string = ''
): FlatTokenMap {
  const map: FlatTokenMap = new Map();

  for (const [key, value] of Object.entries(group)) {
    if (key.startsWith('$')) continue; // skip metadata

    const path = prefix ? `${prefix}.${key}` : key;

    if (isTokenValue(value)) {
      map.set(path, value.$value);
    } else if (typeof value === 'object' && value !== null) {
      const nested = flattenTokens(value as TokenGroup, path);
      for (const [nestedPath, nestedValue] of nested) {
        map.set(nestedPath, nestedValue);
      }
    }
  }

  return map;
}

{ color: { gray: { 500: { $value: "#6B7280" } } } } becomes Map { "color.gray.500" => "#6B7280" }. Keys starting with $ are W3C metadata ($type, $description) and get skipped — they're documentation, not output.

Resolving references.

The core problem: tokens point to other tokens. {color.text.disabled} points to {color.gray.500} which points to #6B7280. The resolver follows those chains using regex replacement, so a single value can contain multiple references:

function resolveValue(
  value: string | number | string[],
  lookups: FlatTokenMap[],
  depth: number = 0
): string {
  if (Array.isArray(value)) return value.join(', ');
  if (typeof value === 'number') return String(value);
  if (depth > 10) {
    throw new Error(
      `Circular reference detected while resolving: ${value}`
    );
  }
  if (!value.includes('{')) return value;

  return value.replace(/\{([^}]+)\}/g, (_, refPath: string) => {
    for (const lookup of lookups) {
      const resolved = lookup.get(refPath);
      if (resolved !== undefined) {
        return resolveValue(resolved, lookups, depth + 1);
      }
    }
    throw new Error(`Unresolved token reference: {${refPath}}`);
  });
}

The function handles three value types — arrays for font family stacks that get joined with commas, numbers that pass through as strings, and string values that might contain references. The depth guard at 10 catches circular references instead of blowing the call stack. The throw on unresolved references is deliberate — I want the build to fail loudly if a token points to nothing. A silent fallback means a missing color in production that nobody catches until a user reports it. Fail at build time, not at render time.

The lookups parameter is an array of flat token maps, searched in order. The build passes [componentTokens, semanticTokens, typographyTokens, globalTokens] so component-level overrides resolve before falling back to semantic, then global.

The order encodes the architecture.

CSS output.

Token paths convert to custom properties with a --fw- prefix to avoid collisions in consumer apps. color.text.primary becomes --fw-color-text-primary. The theme scoping is straightforward — light tokens go under :root, dark tokens go under [data-theme="dark"]:

:root {
  --fw-color-text-primary: #374151;
  --fw-color-text-disabled: #6B7280;
  --fw-button-text-disabled: #6B7280;
}

[data-theme="dark"] {
  --fw-color-text-primary: #F9FAFB;
  --fw-color-text-disabled: #9CA3AF;
  --fw-button-text-disabled: #9CA3AF;
}

The pipeline generates a combined tokens.css plus separate light.css and dark.css for consumers who only need one theme. Three files, 213 tokens resolved, light and dark themes ready. The whole build runs in about 40ms.

Theme Switching in Practice

The old codebase never had dark mode. Now I understand why — imagine adding it:

.card {
  background: $gray-v3;
  color: $gray-v71;
}

.dark-mode .card {
  background: $gray-v88;
  color: $gray-v14;
}

That's one component. Now multiply it across every surface, every text style, every border and background in the product. Each one needs a .dark-mode override block. Each one requires someone to pick the right gray from a list of 130. Nobody was willing to start that project. I don't blame them.

With tokens, dark mode already exists. Not because I built it separately — because the architecture makes it free:

.card {
  background: var(--fw-color-surface-primary);
  color: var(--fw-color-text-primary);
}

No override block. The component references intentions, not values. Switch one attribute on the root:

<div data-theme="dark">
  <!-- every token re-resolves automatically -->
</div>

Same component code. Same custom property names. Different values underneath. No stylesheet swap, no JavaScript toggling classes on individual elements, no new CSS files.

Dark mode went from "a project nobody wanted to touch" to a single attribute change. That's the difference between having a system and not having one.

What I'd Do Differently

If I rebuilt this pipeline tomorrow, two things would change immediately.

Token validation before resolution. Right now a typo in a JSON file passes silently. $valeu instead of $value, a hex code like #6B728 with five digits — the pipeline won't catch it until something downstream breaks or the CSS output looks wrong. For a solo project with 213 tokens, I can eyeball the output. For a team where five people are editing token files in the same sprint, this is the first thing that breaks. A JSON schema validation step before resolution even starts — checking that every token has a valid $value, that hex codes are well-formed, that references point to paths that actually exist — would catch these at the source instead of at the symptom.

Flat values vs. var() chains. The pipeline resolves every reference to its final value. --fw-button-text-disabled outputs #6B7280, not var(--fw-color-text-disabled). I chose this because flat values are easier to debug — you inspect an element and see the actual color, not a chain of three custom property references. But the tradeoff is real. If a semantic token changes, I rebuild and every downstream value updates. A var() chain would let that cascade at runtime without a rebuild. For a shipped design system with consumers who import your CSS, the var() approach is probably the right call. I went with flat values because I was optimizing for "can I see what's happening in DevTools" during development. I'd revisit that decision before publishing to npm.

Both of these are solvable. Neither required rearchitecting anything — they're additive improvements to a pipeline that already works. The gaps are at the edges, not the foundation.

I built this pipeline for flintwork, not for that codebase. But everything I learned about what breaks — and why — came from four years of living inside a system without one. That's the thing about building a system from scratch: you have to know exactly what the absence of one costs.

The second article in this series — on building the headless primitives that consume these tokens — is now live.

I replaced our chaotic WhatsApp sports groups with a zero-login web app

venkatesh m — Fri, 27 Feb 2026 14:11:03 +0000

This is a submission for the DEV Weekend Challenge: Community

The Community

Every Friday around 5 PM, my WhatsApp groups light up.

"Cricket tomorrow 7 AM anyone?"
"I'm in"
"Me too"
"Where?"
"Same place bro"
"How many people?"
...17 unread messages later...
"So are we playing or not?"

I live in Chennai, India, where pickup cricket, basketball, and badminton are a daily thing. But the coordination happens through scattered WhatsApp groups where messages get buried under memes, nobody confirms until game time, you never know how many people are actually coming, and plans fall apart because "only 4 people confirmed."

There's no single place to see what's happening, who's in, and whether there's space. This app is for every person who's ever rage-scrolled a WhatsApp group trying to figure out if the game is still on.

What I Built

pickup — a web app for organizing pickup sports games with zero friction.

The flow:

Create a game — pick a sport (cricket, basketball, badminton, football), set time, place, and max players
Share the link — one-tap WhatsApp share with a pre-filled message
People join — tap the link, type your name, done. Under 10 seconds.

No login. No app download. No sign-up form. Someone taps a link in their WhatsApp group and they're in.

Key features:

Support for 5 sport types with smart defaults (22 for cricket, 10 for basketball, etc.)
Real-time player list — everyone sees who joins/leaves instantly via WebSocket subscriptions
WhatsApp-first sharing with Web Share API and clipboard fallback
Short, readable game URLs (/game/k7m3px) instead of UUID soup
Live progress bar showing spots filled
"My Games" page tracking games you've created or joined
Fully mobile-responsive — tested at 375px because that's where 90% of users will be

The deliberate no-auth decision: The target user taps a WhatsApp link on their phone. Any login wall — even "Sign in with Google" — kills the flow. The cost of a fake name joining is low. The cost of friction is high. I use sessionStorage for game-session identity and localStorage for cross-session tracking. Not bulletproof, but the right tradeoff for pickup games with 10-22 people.

Demo

Live app: getpickup.vercel.app

Home page — zero-friction landing

Browse — look through games and join the one you're excited in and share with others to have your gang over

Create a game — 30 seconds to set up

Have a look through at the games you have created, who's joined and let more people know by sharing the link

Try it yourself — create a game, copy the link, open it in an incognito tab, and join as a different player. Watch the player list update in real-time.

Code

vmvenkatesh78 / pickup

Organize pickup sports games in seconds. No login, no app download — just create, share, and play.

pickup 🏐

The simplest way to organize and join pickup sports games. No login. No app download. Just create, share, and play.

Built for the DEV Weekend Challenge — "Build for Your Community"

The problem

Coordinating pickup sports happens through scattered WhatsApp groups where messages get buried, nobody confirms until game time, and plans fall apart at the last minute. There's no single place to see what's happening, who's in, and whether there's space.

The solution

Create a game in 30 seconds, share the link on WhatsApp, and people join with just their name. Live player count, auto-close when full, and a browse page to discover games nearby.

Features

Create a game — pick a sport, set time/place/max players, get a shareable link
Join with zero friction — no login, no signup, just your name
Real-time player list — see who's in and how many spots are left, live
WhatsApp…

View on GitHub

Project structure highlights:

src/lib/api.ts — all Supabase queries and real-time subscriptions
src/lib/utils.ts — share codes, date formatting, WhatsApp sharing
src/pages/GamePage.tsx — the core experience with real-time player updates
supabase/schema.sql — database schema with RLS policies
ARCHITECTURE.md — full technical documentation

How I Built It

Tech stack:

Layer	Choice	Why
Framework	React + TypeScript	Type safety with fast iteration
Build	Vite	Instant HMR, zero config
Styling	Tailwind CSS v4	Utility-first, mobile-first
Backend	Supabase	Postgres + REST API + real-time subscriptions in one service
Hosting	Vercel	One-click deploy from GitHub

Real-time: the feature that makes it click

When someone joins or leaves, every person viewing the game page sees the change instantly. I subscribe to Postgres changes on the players table filtered by game_id, and re-fetch the full player list on any event:

const channel = supabase
  .channel(`game-${gameId}-players`)
  .on(
    'postgres_changes',
    {
      event: '*',
      schema: 'public',
      table: 'players',
      filter: `game_id=eq.${gameId}`,
    },
    async () => {
      const { data } = await supabase
        .from('players')
        .select('*')
        .eq('game_id', gameId)
        .order('joined_at', { ascending: true });
      if (data) callback(data);
    }
  )
  .subscribe();

Re-fetching the full list on every change isn't the most efficient approach, but for max 22 players it's completely fine and way simpler than merging individual row events.

Share codes over UUIDs

Game URLs use 6-character codes (k7m3px) instead of UUIDs. Ambiguous characters (0/O, 1/l/I) are stripped out. Around 700 million combinations — more than enough.

Edge cases I caught

Stale sessions — if your player record was deleted but sessionStorage still says "joined," the page detects the mismatch and resets
Game full race condition — client-side count check before the insert catches most simultaneous joins
Double-submit — useRef locks prevent spam-clicking from firing multiple API calls

What I'd build next

OTP phone verification for spam prevention
Waitlist with auto-promote when someone leaves
Recurring games ("Every Saturday 7 AM at Marina Beach")
Push notifications an hour before game time

The constraint of a weekend made this product better, not worse. "Should I add auth?" became "Does my user need auth to get value?" — and the answer was no.

If you're in Chennai (or anywhere with pickup sports), give it a try: getpickup.vercel.app 🏏🏀🏸

Forem: venkatesh m

jsx-a11y has 36 rules. None of them catch these 6 patterns.

The Bug That Passed Lint

What Element-Level Linting Misses

1. Dialog without aria-modal="true"

2. aria-haspopup with an invalid value

3. Interactive elements inside a tooltip

4. Accordion trigger outside a heading

5. role="menuitem" on a <button>

6. Dialog without an accessible name

Why This Gap Exists

What Microsoft Built (and Didn't Build)

eslint-plugin-a11y-enforce

How the rules work

What the error messages say

Install

Design Decisions

What This Doesn't Catch

Why This Matters Now

From 3 components to 8: what actually changes when a design system scales

Four components that are secretly the same thing

The decision I'm most glad I made early

When not to share: typeahead

The Portal positioning tradeoff

Accordion broke the pattern

What I'd tell someone starting a design system

eslint-plugin-bad-vibes: I built a linter that enforces the worst frontend practices

What I Built

Demo

Code

vmvenkatesh78 / eslint-plugin-bad-vibes

ESLint plugin that enforces the worst frontend practices with corporate confidence. 6 rules, 38 tests, zero value.

eslint-plugin-bad-vibes

Why

Install

Usage

Rules

no-semantic-html

How I Built It

Prize Category

I Built an MCP Server That Lets Designers Change CSS From a Notion Table

What I Built

The problem it solves

How it works

Five MCP tools

What makes this different from a Notion API integration

Video Demo

Show us the code

vmvenkatesh78 / flintwork-token-sync

MCP server that syncs design tokens between Notion and flintwork's token pipeline.

flintwork-token-sync

Architecture

MCP Tools

Notion Databases

How I Used Notion MCP

Headless Components Are Useless Without a Styling Strategy

The Two-Layer Architecture

Why Not CSS-in-JS, CSS Modules, or Tailwind?

The CSS Pattern That Killed Repetition

The Styled Wrapper Is Almost Nothing

Tokens Drive Everything

What Went Wrong During the Build

What I'd Build Next

Your Dialog Has role='dialog'. That Doesn't Make It Accessible.

The Attribute Isn't the Behavior

What a Screen Reader Actually Hears

The Problem With Monolithic Components

Building the Focus Trap

What "Tabbable" Means

The Trap Lifecycle

The Tab Cycling Logic

Building useClickOutside

Roving Tabindex: Why Arrow Keys Matter

The Compound Component Wiring

The ARIA You Don't See

What Broke Along the Way

What I'd Do Differently

130 Shades of Gray: Building a Design Token Pipeline That Killed Our Color Chaos

The Codebase That Had 130 Grays

Why This Happens

1. Dialog without `aria-modal="true"`

2. `aria-haspopup` with an invalid value

5. `role="menuitem"` on a `<button>`

`no-semantic-html`