docs: ban Radix in agent instructions, add missing CLAUDE.md symlinks

[adamleithp]

Problem

Agents keep writing new UI with @radix-ui/themes — Box, Flex, Text — because ~500 files in the repo already do and nothing in the instruction files told them not to. Every one of those is new legacy to migrate later. The one file that did say "use quill, not Radix" (features/canvas/AGENTS.md) hedged it as a preference.

Two of the three feature guides were also invisible to Claude: canvas/AGENTS.md and browser-tabs/AGENTS.md had no CLAUDE.md symlink beside them, and inbox/ had the content in CLAUDE.md with no AGENTS.md — inverted from the root convention.

Changes

Docs only — no source, dependency, or lint-config changes.

Root AGENTS.md gains a ## UI Components section stating the ban outright: no @radix-ui/* import in any file, ever, with no "matching the surrounding code" exception. It carries two lookup tables agents can act on directly:

• Layout primitives → plain elements + Tailwind. <Flex align="center" gap="2"> → <div className="flex items-center gap-2">; also Box, Grid, Section, Container, ScrollArea, Heading, Code, VisuallyHidden, Link.
• Everything else → its @posthog/quill equivalent (Text, Button, Input/Textarea, Select, Switch, Tooltip, Dialog, DropdownMenu, …), verified against quill's actual export surface as used in this repo.

It also sets the replace-as-you-go expectation — migrate what your diff touches, leave the file no more Radix-dependent than you found it, no drive-by rewrites of untouched files — and spells out two carve-outs so the rule doesn't get over-applied:

• The Radix CSS variables (text-(--gray-12), --radius-2) are the token layer, not components. They stay.
• The app-level and test <Theme> root stays pending a separate migration.

Reinforced everywhere else an agent reads instructions:

• features/canvas/AGENTS.md — "not Radix" preference hardened into a ban, with the swap spelled out.
• features/browser-tabs/AGENTS.md — new "Components & styling" section.
• features/inbox/AGENTS.md — note in UI Architecture + a "Things to Avoid" bullet.
• docs/conventions.md — its canonical component example was itself teaching <Box>; that's now a <div>, plus a pointer to the new section and a clarification on the CSS-variable line.
• .claude/skills/storybook-stories/SKILL.md — its <Theme> mention now says explicitly that the root provider is the sanctioned exception, not license to use Radix components.

Symlinks. Feature guides now follow the root convention (content in AGENTS.md, CLAUDE.md symlinked beside it): added the missing symlinks for canvas/ and browser-tabs/, and flipped inbox/ (git mv CLAUDE.md AGENTS.md + symlink). Root AGENTS.md documents the convention so new guides get the symlink too.

Enforcement is a natural follow-up but deliberately not in this PR — a Biome noRestrictedImports entry for @radix-ui/* would fail on the ~500 existing files until they're migrated, so it needs its own sequencing.

How did you test this?

Nothing to run — the diff is 6 markdown files and 3 symlinks. Verified by inspection:

• Symlinks resolve and are committed as git mode 120000, not copied content.
• Relative links to AGENTS.md#ui-components resolve from each file's depth, and the anchor matches the new heading.
• The quill column of the mapping table is checked against the symbols actually imported from @posthog/quill across packages/ and apps/, so no row points at a component that doesn't exist.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

---

Generated by Claude Code

[trunk-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[greptile-apps]

Prompt To Fix All With AI

### Issue 1
AGENTS.md:233-237
**Radix ban contradicts carve-outs**

The unconditional ban on every `@radix-ui/*` import conflicts with the later instructions to retain the Radix Theme roots and token stylesheet. Qualify the ban wherever it is stated so agents do not remove sanctioned imports from `ThemeWrapper.tsx`, Storybook, existing themed tests, or `globals.css`, causing avoidable visual regressions and corrective work.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs: ban Radix in agent instructions, a..." | Re-trigger Greptile}

[greptile-apps]

Radix ban contradicts carve-outs

The unconditional ban on every @radix-ui/* import conflicts with the later instructions to retain the Radix Theme roots and token stylesheet. Qualify the ban wherever it is stated so agents do not remove sanctioned imports from ThemeWrapper.tsx, Storybook, existing themed tests, or globals.css, causing avoidable visual regressions and corrective work.

Context Used: Do not attempt to comment on incorrect alphabetica... (source)

Knowledge Base Used: @posthog/ui shared UI package

Prompt To Fix With AI

This is a comment left during a code review.
Path: AGENTS.md
Line: 233-237

Comment:
**Radix ban contradicts carve-outs**

The unconditional ban on every `@radix-ui/*` import conflicts with the later instructions to retain the Radix Theme roots and token stylesheet. Qualify the ban wherever it is stated so agents do not remove sanctioned imports from `ThemeWrapper.tsx`, Storybook, existing themed tests, or `globals.css`, causing avoidable visual regressions and corrective work.

**Context Used:** Do not attempt to comment on incorrect alphabetica... ([source](https://app.greptile.com/review/custom-context?memory=instruction-0))

**Knowledge Base Used:** [`@posthog/ui` shared UI package](https://app.greptile.com/posthog-org-19734/-/custom-context/knowledge-base/posthog/code/-/docs/ui-package.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!