docs(desktop): ban Radix in agent instructions - #76809
Merged
Merged
Conversation
Agents keep reaching for `@radix-ui/themes` because the surrounding code does and nothing told them not to. Make the ban explicit everywhere an agent reads instructions. Root AGENTS.md gains a "UI Components" section: no `@radix-ui/*` import, ever; layout primitives (Box/Flex/Grid/Section/Container) become `div`s with Tailwind; everything else maps to its `@posthog/quill` equivalent. Replace Radix in the code you touch rather than matching it. Two carve-outs are spelled out so the rule isn't over-applied — the Radix CSS variables (`--gray-*`, `--radius-*`) stay, and the app/test `<Theme>` root stays pending a separate migration. Also reinforced in the feature guides (canvas, browser-tabs, inbox), in docs/conventions.md — whose canonical component example was itself teaching `<Box>` — and in the storybook-stories skill. Feature guides now follow the root convention: content in AGENTS.md with a CLAUDE.md symlink beside it, so Claude picks them up. Adds the missing symlinks for canvas and browser-tabs, and flips inbox (CLAUDE.md became AGENTS.md + symlink). Docs only — no source or lint-config changes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DEM8aVRU7GGbWjMssYYoTf
charlesvien
added
the
skip-agent-review
|
😎 Merged successfully - details. |
2 tasks
github-actions
Bot
added
docs
Contributor
|
Reviews (1): Last reviewed commit: "docs: ban Radix in agent instructions, a..." | Re-trigger Greptile |
charlesvien
enabled auto-merge (squash)
August 3, 2026 17:14
![stamphog[bot]](https://avatars.githubusercontent.com/in/3000332?s=60&v=4){kind=small}
There was a problem hiding this comment.
Docs-only change adding Radix-ban guidance across desktop AGENTS.md/skill files; content matches file extensions, no risky territory, no unresolved concerns.
- 👍 on the PR from greptile-apps[bot], hex-security-app[bot].
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✓ | no deny categories matched |
| size | ✓ | 0L, 0F substantive, 108L/6F incl. docs/generated/snapshots — within ceiling |
| tier | ✓ | T0 auto-approve: T0-deterministic (108L, 6F, single-area, docs) |
| stamphog 2.0.0b4 | .stamphog/policy.yml @ b929e92 · reviewed head 28b3b3e |
Member
Author
|
/trunk merge |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Ports PostHog/code#4064. Agents keep writing new desktop UI with
@radix-ui/themesbecause ~500 files already do and no instruction file said not to. Every new usage is more legacy to migrate.Changes
Docs only, under
products/desktop/:AGENTS.mdgains a## UI Componentssection banning@radix-ui/*imports outright, with lookup tables (layout primitives todiv+ Tailwind, everything else to its@posthog/quillequivalent), the replace-as-you-go expectation and two carve-outs (Radix CSS variables and the root<Theme>provider stay).docs/conventions.mdand the storybook-stories skill.The source PR also added
CLAUDE.mdsymlinks for the feature guides; those already exist in the monorepo so that part was dropped. The inbox guide had diverged here (Responder/finding terminology), so its two additions were re-applied on top of the monorepo version.How did you test this code?
N/A, markdown only. Verified the relative links still resolve at the same depth under
products/desktop/.Automatic notifications
Docs update
N/A
🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Claude ported this from PostHog/code#4064 at @charlesvien's direction using /porting-code-prs, applying the source patch with
git am --directory=products/desktop/to keep the original commit authorship. One add/add conflict in the inbox guide was resolved by keeping the monorepo side and re-applying the PR's two additions.