onyx-foss / web
AGENTS.md320 starsChanged 8 days agoMITView on GitHub
Standards for web/ and desktop/. Every Opal component and layout has a README.md beside it. Read that README instead of guessing props. Use, in priority order: Never import from web/src/components/. It is legacy and being deleted. The one exception is createLogoIcon in src/components/icons/icons.tsx. - Admin and settings pages: SettingsLayouts.{Root,Header,Body} from @opal/layouts. - Icon + title + description: Content or ContentAction from @opal/layouts. Empty states and error pages: IllustrationContent. - Buttons: Button from @opal/components. No raw <button>. - Inputs: Opal or…
1 other project uses a version of this.
Adopted by
Most recently taken up by
- onyx-dot-app/onyxword for word, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 1
- onyx-dot-app/onyx★ 33k100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- backend/AGENTS.mdAGENTS.md
- documentation/AGENTS.mdAGENTS.md
- mobile/AGENTS.mdAGENTS.md
- docs-writingSkill
- feature-mapSkill
- merge-dependabot-prsSkill
- onyx-craft-devSkill
- onyx-dev-stackSkill
- playwright-e2e-testsSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
17 rules. About 0 are common, 4 are distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 4
Read that README instead of guessing props.
- Distinctive: line 8
Use, in priority order:
- Very specific: line 14
Never import from web/src/components/.
- Very specific: line 54
Size props default to
"md": when the prop type is SizeVariants from @opal/types or a subset of it. - Very specific: line 56
Padding over margin: Use a component's padding prop before wrapping it in a <div>.
- Very specific: line 66
Open popups inside the click: Call window.open("about:blank") in the event handler, then set its location after the await.
- Very specific: line 69
All navigation goes through
@opal/navigation: Never import next/navigation or next/link outside it, and never write window.location or … - Very specific: line 86
Put the props interface (FooProps) in the same file as the component.
- Very specific: line 94
No hard-coded user-facing strings under src/.
- Very specific: line 103
Run python3 tools/i18n/check_copy_changes.py --base origin/main from the repository root to check a branch.
- Distinctive: line 106
Use ICU for arguments and plurals.
- Very specific: line 107
Use title case for English setting titles: field labels and the titles of settings sections and cards (Include Pull Requests, Categories to …
- Very specific: line 122
Add a typed key to OpalStrings in web/lib/opal/src/strings.tsx, with an English default in defaultOpalStrings right below.
- Very specific: line 126
Read it in the component with useOpalStrings() from @opal/strings.
- Very specific: line 130
Add the key under opal.<component>.<name> in en.json and every other locale file.
- Distinctive: line 132
Never hard-code a user-facing string inside an Opal component, and never import next-intl there — the contract keeps Opal host-agnostic …
- Very specific: line 141
Run an e2e test with cd web && bun run playwright <TEST_NAME>.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Frontend Standards
Standards for web/ and desktop/. Every Opal component and layout has a README.md beside it.
Read that README instead of guessing props.
Where components come from
Use, in priority order:
web/lib/opal/src/(@opal/*): the design system.web/src/refresh-components/: production components not yet in Opal.web/src/sections/(feature composites; entity cards insections/cards/) andweb/src/layouts/.
Never import from web/src/components/. It is legacy and being deleted. The one exception is
createLogoIcon in src/components/icons/icons.tsx.
- Admin and settings pages:
SettingsLayouts.{Root,Header,Body}from@opal/layouts. - Icon + title + description:
ContentorContentActionfrom@opal/layouts. Empty states and error pages:IllustrationContent. - Buttons:
Buttonfrom@opal/components. No raw<button>. - Inputs: Opal or refresh-components. No raw
<input>,<textarea>, or<select>. - Text:
Textfrom@opal/componentswithfontandcolorprops. No naked text nodes. For text that shows a tooltip when cut, setmaxLinesandoverflowTooltip. - Icons: only
@opal/icons. Neverlucide-reactorreact-icons. If an icon is missing, import it from Figma with the Figma MCP tool and add it tolib/opal/src/icons/. - Hover-reveal:
Hoverablefrom@opal/core. If you must hand-write it, addno-hover:opacity-100so touch devices still show the item. @opal/coreprimitives (Interactive,Disabled) build components. App code does not use them.- Layout:
Sectionfrom@opal/layouts, never a<div>/<span>withflex,inline-flex,grid,items-*,justify-*orgap-*(oxlintopal/no-layout-div).Content,ContentAction,Card,InputHorizontal/InputVerticalandDividercover the rest. - On
Section, set spacing and size with props:gap={n},padding={n},width,height. Section setsgapandpaddingas inline styles, sop-*,px-*andgap-*classes are silently ignored (oxlintopal/no-section-utility-classes). Use margin classes for asymmetric spacing.
oxlint enforces the import, icon and raw-element rules. Files that broke them when the rules
landed are in the design-system baseline in .oxlintrc.json, where they only warn. Files with
layout divs when opal/no-layout-div landed are in the layout baseline. Remove a file
from the baseline once it is clean. Never add one. opal/no-replaced-refresh-import warns on each
refresh-components import that Opal replaces. Migrate a file to Opal when you edit it. The
.agents/hooks/opal_migrate_on_edit.py hook reports these problems to the agent after each edit.
Rules with a reason
- No
dark:Tailwind modifier. The tokens already define both themes, and overrides break dark mode. OnlycreateLogoIconmay use it. - No built-in Tailwind colors (
bg-gray-100,text-blue-600). Use the token classes:text-0X,background-neutral-0X,background-tint-0X,border-0X,action-selection-0X,action-danger-0X,status-{info,success,warning,error}-0X,theme-*. Tokens live inweb/lib/shared/tokens/. - Text props accept markdown. Type any prop rendered as visible text (
title,description,label) asstring | RichStrfrom@opal/typesand render it withText. Callers opt in withmarkdown()from@opal/utils. Plain strings are never parsed. - Size props default to
"md"when the prop type isSizeVariantsfrom@opal/typesor a subset of it. - Padding over margin. Use a component's
paddingprop before wrapping it in a<div>. If a library component has no such prop, add one to the component instead of adding a wrapper. - Inputs sit 1rem from their container's edge. Build the 1rem from two 0.5rem steps, not from
absolute positioning:
- Give the container 0.5rem, for example
Modal.Body padding={2}. - A naked input (no card around it): wrap it in
InputPadder, which adds the other 0.5rem. PutInputDividerbetween naked groups. - A covered input: to group inputs visually, put them in a white, borderless
<Card padding={2}>. The card adds 0.5rem, and the input's own 0.5rem internal padding adds the rest. Do not wrap inputs inside the card inInputPadder.
- Give the container 0.5rem, for example
- Open popups inside the click. Call
window.open("about:blank")in the event handler, then set itslocationafter theawait. Popup blockers and the desktop app block awindow.openthat runs after anawait. - All navigation goes through
@opal/navigation. Never importnext/navigationornext/linkoutside it, and never writewindow.locationor call the router's orhistory'spush/replace/back.useNavigation()givesgo,linkTo,clampedBack,refresh,prefetch,loadandreload;NavLinkreplacesnext/link;usePathname,useSearchParams,useParams,redirectandnotFoundare re-exported from it;loadPageis for code outside a component;useAppPosition()from@/lib/navigation/hookscovers/apppositions.gowrites the URL at once and then asks Next for the page, so the tabs and the page's loader (PendingRoute) follow the click;clampedBack(fallback)never leaves the app. A static internalhrefis banned too: spreaduseNavigation().linkTo(…)or useNavLink. oxlintnavigation/no-naked-navigationenforces this. - Data fetching:
useSWR, on the client, inside the component that needs the data, with a loader while pending. Do not fetch at the top of the page and pass data down.
Style
- Absolute imports only:
@/forsrc/,@opal/for Opal. No../paths. - Components are
functiondeclarations, not arrow functions. - Put the props interface (
FooProps) in the same file as the component. Put shared types in a co-locatedtypes.ts.interfaces.tsis the old name; rename it when you touch one. - Class names:
cnfrom@opal/utils, never template strings. - Hooks: feature hooks go in
web/src/lib/<feature>/hooks.ts. UI hooks with no app knowledge go in Opal.web/src/hooks/is the last resort.
i18n (next-intl)
- No hard-coded user-facing strings under
src/. The oxlint rulei18n/no-raw-jsx-textfails on them. UseuseTranslations("<namespace>")on the client orawait getTranslations(...)on the server. web/src/i18n/messages/en.jsonis the source of truth. When you add or change a key, add your best translation to every other locale file in that directory. Missing or extra keys failtypes:check. ICU shape must match across locales (src/i18n/__tests__/catalog.test.ts).- The
i18n-copy-changespre-commit hook requires each changed English message to have a changed translation in every locale. It uses the pre-commit range base when supplied. Otherwise, it checks working edits against HEAD or clean checkouts against HEAD^. Main push checks use the push event’s previous commit. The hook does not assess translation quality. Runpython3 tools/i18n/check_copy_changes.py --base origin/mainfrom the repository root to check a branch. - Keys are stable identifiers:
<namespace>.<section>.<element>.<role>in camelCase, for examplesettings.appearance.colorMode.title. Rewording the English never changes the key. - Use ICU for arguments and plurals. Never concatenate translated fragments.
- Use title case for English setting titles: field labels and the titles of settings sections and
cards (
Include Pull Requests,Categories to Index). Keep articles, short conjunctions and prepositions in lowercase, except as the first or last word. Do not change brand or acronym casing (GitHub,API). Use sentence case for placeholders, descriptions, messages and errors. A placeholder prompts the action and does not repeat the field's title (Add a display name, notDisplay name). A change in letter case only needs no new translation; thei18n-copy-changeshook ignores it. - Dates and numbers:
useFormatteranduseLocale, not hard-coded"en-US". - New styles use logical properties (
ms-,pe-,start-) instead ofml-,pr-,left-.
Opal i18n
Opal has no next-intl. A label an Opal component renders itself (a built-in placeholder, empty
state, aria-label — anything not passed in by the caller) rides the OpalStrings contract:
- Add a typed key to
OpalStringsinweb/lib/opal/src/strings.tsx, with an English default indefaultOpalStringsright below. Prefix component-scoped keys with the component name (comboBoxNoOptions,keyValueDuplicateKey). A string with arguments is a function-valued entry ((count) => string). - Read it in the component with
useOpalStrings()from@opal/strings. - Map it in
web/src/i18n/OpalStringsBridge.tsxfrom theopal.*catalog namespace (t("comboBox.noOptions")) — the bridge wraps the app inlayout.tsxand feeds Opal the host translations. - Add the key under
opal.<component>.<name>inen.jsonand every other locale file.
Never hard-code a user-facing string inside an Opal component, and never import next-intl there — the contract keeps Opal host-agnostic while the app supplies real translations.
Tests
- Craft: keep one test file per source file. Group related cases with section comments and scoped
describeblocks. - Component tests (Jest + React Testing Library):
web/tests/README.md. - E2E (Playwright):
web/tests/e2e/README.mdholds the hard rules (Page Object Model, locator priority). - Run an e2e test with
cd web && bun run playwright <TEST_NAME>. Do not usebunxornpx; they can fetch an unpinned Playwright. ods type-coverage typescript --checktype-checksweb/and gates type coverage (the share of identifiers whose type is notany, tests excluded). Eachas Tor<T>xcast and eachx!non-null assertion also counts as uncovered, exceptas constandas unknown. Coverage must not drop below the floors inweb/.type-coverage-baseline.yaml. Thetypescript-checkpre-commit hook runs it. After you removeanytypes, casts or non-null assertions, raise the floors withods type-coverage typescript --update.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

