hoop / webapp_v2
CLAUDE.md848 starsChanged 24 days agoMITView on GitHub
React 19 + JavaScript (no TypeScript) · Vite · Mantine v8 (sole styling — no Tailwind) · Zustand · Axios · React Router v7 · lucide-react. Setup and details: README.md. One product: the gateway. hoop start control-plane runs the same gateway and UI. - Route wrappers. modes/gateway.jsx exports { Page, Guard, Home, Onboarding, CatchAll }. Page is the shell of a React page (layout/GatewayPage: auth gate + Layout + PageLayout), Guard a React route without the shell. Home, Onboarding and…
In this repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- sidecar/CLAUDE.mdCLAUDE.md
- webapp/CLAUDE.mdCLAUDE.md
- build-ticketSkill
- evidenceSkill
- gcp-marketplace-publishSkill
- shapeSkill
- support-agentSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
36 rules. About 0 are common, 9 are distinctive, and 27 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
27
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Test: npm test (vitest; the session fixtures in test/fixtures/sessions come from npm --prefix ../webapp run fixtures:sessions)
- Very specific: line 57
Sidecar features are always on: Every gateway serves sidecars, so the Sidecars pages, nav and palette items and the sidecar traffic of a …
- Very specific: line 120
One generation counter per resource: when a store's state has more than one async writer, so a late response cannot restore what a newer …
- Very specific: line 149
Check COMPONENTS.md first — the component you need may already exist.
- Very specific: line 150
If it doesn't exist, create a wrapper in src/components/[Name]/index.jsx that imports the Mantine primitive internally and re-exports a …
- Very specific: line 152
Update COMPONENTS.md with usage examples after creating the wrapper.
- Very specific: line 170
When something in pages/[Page]/components/ starts getting reused outside the page, graduate it to src/components/ (and update …
- Very specific: line 186
Use @/ alias for absolute imports from src (e.g., import { useAuthStore } from '@/stores/useAuthStore')
- Distinctive: line 190
Use Mantine components exclusively.
- Distinctive: line 191
Use Mantine's built-in props for styling (size, variant, color, etc.)
- Very specific: line 192
Icons: Use lucide-react exclusively.
- Distinctive: line 201
Keep components small and focused
- Very specific: line 202
JSX text with variables: always use template strings or plain strings — never HTML entities (', ", etc.) and never mix bare text …
- Very specific: line 215
When a page must react to a change made elsewhere (a sidecar checked in, a record changed), subscribe with useLiveEvent.
- Very specific: line 259
Do NOT use @mantine/notifications — the dependency has been removed from the project (it produced a completely different visual from v1 and …
- Very specific: line 264
Do NOT show snackbars through the CLJS bridge (clojureDispatch('show-snackbar', ...)) — the CLJS Toaster only exists while the CLJS tree is …
- Very specific: line 291
Check token: If no token in localStorage, redirect to /login (saves current URL)
- Very specific: line 292
Fetch user: If token exists, fetch user data from /api/users/me
- Distinctive: line 293
Validate user: If user data is empty/invalid, clear token and redirect to login
- Distinctive: line 305
When React needs to trigger a CLJS re-frame action (e.g., navigate to a CLJS-owned route, open a CLJS modal):
- Very specific: line 307
Never call
window.hoopDispatchdirectly from a component: Always wrap it in a Zustand store method. - Very specific: line 308
Put the wrapper in the most relevant existing store, or create a stores/useBridgeStore.js for cross-cutting concerns.
- Very specific: line 363
When a Mantine component (NavLink, Button, Drawer, Badge…) needs styles specific to one context, create a wrapper component that owns all …
- Distinctive: line 397
When Mantine's built-in props and theme tokens are not enough for a visual requirement:
- Very specific: line 398
Create a dedicated component in src/components/ (not inline in the page).
- Very specific: line 399
Use Component.extend() in src/components/[Name]/theme.js for global defaults.
- Distinctive: line 400
Use a CSS Module scoped to that component for complex selectors only.
- Distinctive: line 401
Never add global CSS or unscoped styles.
- Distinctive: line 407
NEVER hardcode design values in CSS Modules: Every spacing, color, font size, radius, and line-height value must reference a Mantine CSS …
- Very specific: line 461
Never use raw names like c="dark" or c="light" — those palettes are not defined in theme.js and silently fall back to Mantine defaults.
- Very specific: line 463
When adding a new palette or changing primaryColor, re-verify c="dimmed" contrast in DevTools.
- Very specific: line 474
DO NOT change the Mantine import to styles.css (without .layer) — that reintroduces the cascade bug.
- Very specific: line 481
Do NOT remove the disableCLJSCSS() call in ClojureApp's cleanup.
- Very specific: line 482
Do NOT switch to <style>@import url(...) layer(...)</style> — it works in theory but @import is processed serially by the CSS parser, …
- Very specific: line 491
If it still doesn't apply and layers.css is imported, inspect the rule in DevTools and confirm it's inside @layer mantine — if not, the …
- Very specific: line 513
Before implementing any behavior (mobile nav, modals, transitions, keyboard handling, etc.), check how it works in the original app first …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.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
Hoop WebApp V2 - Development Guidelines
Stack
React 19 + JavaScript (no TypeScript) · Vite · Mantine v8 (sole styling — no
Tailwind) · Zustand · Axios · React Router v7 · lucide-react. Setup and
details: README.md.
Commands
- Development (recommended):
npm run dev:full— Vite + shadow-cljs together; ports, proxy and HMR caveats inREADME.md - Development (Vite only):
npm run dev - Build:
npm run build - Lint:
npm run lint - Test:
npm test(vitest; the session fixtures intest/fixtures/sessionscome fromnpm --prefix ../webapp run fixtures:sessions) - Preview production:
npm run preview
Project Structure
src/
├── components/ # Presentational components (receive props, no business logic)
├── layout/ # App shell
├── modes/ # Route wrappers (gateway.jsx), ByRuleTraffic, the agents flag
├── features/ # Complex features (e.g., CommandPalette)
├── stores/ # Zustand global stores (cross-route state)
├── services/ # Axios API calls (one file per domain)
├── hooks/ # Reusable custom hooks
├── utils/ # Pure utility functions
├── pages/ # Route-based pages (each route = folder)
│ ├── [Page]/
│ │ ├── index.jsx # Page component
│ │ ├── <TabName>.jsx # Tab bodies / top-level page slices (siblings of index)
│ │ ├── components/ # Reusable components scoped to this page (≥2 consumers)
│ │ ├── sections/ # Page-specific decomposition (single consumer, not "components")
│ │ ├── store.js # Local store (only if state is page-specific)
│ │ └── [SubPage]/
│ │ └── index.jsx
├── App.jsx # Root component + providers
├── Router.jsx # The route table
└── main.jsx # Entry pointRouting, gates and roles
One product: the gateway. hoop start control-plane runs the same gateway and UI.
- Route wrappers.
modes/gateway.jsxexports{ Page, Guard, Home, Onboarding, CatchAll }.Pageis the shell of a React page (layout/GatewayPage: auth gate + Layout + PageLayout),Guarda React route without the shell.Home,OnboardingandCatchAllare the ClojureScript leaves/,/onboarding/*and/*. OnlyRouter.jsxreads them. - Guardrail and masking rules have one form each.
pages/Guardrails/Create/GuardrailForm.jsxandpages/Features/DataMasking/Create/DataMaskingForm.jsxwrite both halves of a rule (the agent fields andsidecar_spec); an option one engine does not run carries aRuleSupportTag(utils/ruleSupport.js). Only the analyzer keepsGateway*Form/Sidecar*Formsiblings, picked per rule with<ByRuleTraffic>inRouter.jsx. - Sidecar features are always on. Every gateway serves sidecars, so the Sidecars
pages, nav and palette items and the sidecar traffic of a rule carry no gate. The
agents product follows
agentsEnabled()(modes/agents.js, theexperimental.agentsflag). Off,GatewayProtectedRouteturns/, the agent onboarding and every path a nav or palette entry flags withAGENTS_FLAG(modes/agentPaths.js), sub-paths included, into the landing by role (pages/Home) on every route change, and the CLJS app does not move the URL while it is parked (routes/navigate!). Flag a new agent page ingatewayNav.jsand its URL closes too. - Auth is one gate.
components/ProtectedRoute(token,/userinfo,/serverinfo, flags,adminOnly,role,licenseFeature).GatewayProtectedRouteadds the agents swap. - Roles.
/userinforeportsrole. A role is a reserved group name;standardis the absence of one and is never stored as a group. The group names come from/serverinfo(admin_role_name,approver_role_name), never a literal. Gate a route with<Page role={ROLE_APPROVER}>and a nav or palette item withrole:;hasRoleinutils/roles.jsis the single decision and admin passes every gate. This gates pages, not data: the route's own middleware ingateway/api/server.gois the authority on what a request returns.
Architecture Rules
Stores (Zustand)
- Global stores (
src/stores/): State consumed by multiple pages (auth, user, resources, connections, agents, UI) - Local stores (
src/pages/[Page]/store.js): State that only exists in that specific page (form wizard steps, local filters) - Access store state outside React with
useStore.getState()
Services (Axios)
- Base instance in
services/api.jswith auth interceptor and 401 handling - One file per domain:
services/agents.js,services/resources.js, etc.
A service returns the raw Axios promise. No .then, no response.data, no
defaulting — the store unwraps. services/agents.js is the shape to copy:
// ✅ services/agents.js
export const agentsService = {
list: () => api.get('/agents'),
create: (data) => api.post('/agents', data),
}
// consumed in useAgentStore
const { data } = await agentsService.list()
// ❌ unwrapping inside the service
list: () => api.get('/agents').then((r) => r.data ?? []),The store is where status, headers and defaulting belong, and a service that unwraps forces a rewrite the day a caller needs a header or a status. 10 of the 34 service files still unwrap; they predate the rule and are not a licence to add an eleventh. Touching one is the moment to fix it.
Who owns a request
The store owns the request: its loading flag, its error, and its cancellation. A page asks for an id and renders what comes back.
A page may import a service directly — 39 do, and routing a one-shot probe
through a store is worse, not better. What a page must not do is hand-roll
loading/error state for a resource a store already owns. A call that stays out
of the store on purpose: Sidecars/Setup/sections/WaitingStep.jsx polls every
3s. In a global store that re-renders every subscriber, for state that dies when
the wizard closes.
One generation counter per resource when a store's state has more than one
async writer, so a late response cannot restore what a newer one replaced.
useSidecarStore carries listRequestId and selectedRequestId; each fetch
takes the next number and commits only while it is still current. A superseded
list response still clears loading — the request it belonged to is over
either way, and leaving the flag set strands the page on a loader.
Reset session-scoped stores on logout, from the store's own side:
useAuthStore.subscribe((state, prev) => {
if (prev.isAuthenticated && !state.isAuthenticated) useMyStore.getState().reset()
})Module state outlives a logout — nothing on that path reloads the tab — so the
next user in the same tab sees the previous one's data until the first fetch
answers. Subscribing from this side keeps the dependency pointing the right way
and avoids the cycle a call from useAuthStore would create. Live examples:
useNativeAccessStore, useSidecarStore.
Components — Component Library Strategy
Every UI primitive is wrapped. We own every component — even a Button, a Table, a TextInput. App code never imports these directly from Mantine; it always imports from @/components/. This gives us:
- A single place to change the visual behaviour of any primitive across the whole app
- A Storybook-ready inventory: every component in
src/components/is a candidate for a story - Portability: if we ever replace Mantine, only the wrapper internals change, not the app
How to apply this rule:
- Check
COMPONENTS.mdfirst — the component you need may already exist. - If it doesn't exist, create a wrapper in
src/components/[Name]/index.jsxthat imports the Mantine primitive internally and re-exports a styled, opinionated version. - The wrapper owns all
classNames,styles, and default props. Call sites stay clean. - Update
COMPONENTS.mdwith usage examples after creating the wrapper.
Scope:
src/components/= Reusable across the whole app. No direct Mantine imports at call sites for any component that has a wrapper.src/pages/[Page]/components/= Reusable within the page (≥2 consumers, or a clear candidate to graduate to the globalsrc/components/). May still import Mantine directly if no wrapper exists yet and it's too specific to generalise.src/pages/[Page]/sections/= Single-consumer page decomposition. A file that exists only to keep a tab/page body small. Not a "component" — don't put it incomponents/. Example:pages/Roles/Configure/sections/MetadataFieldsInput.jsxis rendered by exactly one tab; it lives insections/. Acomponents/SecretFieldrendered by multiple renderers lives incomponents/.- Tabs / top-level page slices live at the page root next to
index.jsx(e.g.pages/Roles/Configure/CredentialsTab.jsx). They're not reusable and not decomposition — they're the page itself, sliced for readability. - Before creating a new component, check
COMPONENTS.md— it catalogs every existing component, hook, store, and service with usage examples.
The reusability bar — what makes something a "component"?
| Where it lives | What it is | Examples |
pages/[Page]/<X>.jsx | A tab body or top-level slice of the page | CredentialsTab.jsx, DetailsTab.jsx, ConfigureHeader.jsx |
pages/[Page]/sections/ | Decomposition, single consumer, not reusable | SidecarMirrorView.jsx, MetadataFieldsInput.jsx |
pages/[Page]/components/ | Reusable within the page (≥2 consumers) | SecretField/, ToggleSection.jsx, ReviewSection.jsx |
src/components/ | Reusable across the whole app | Button, TextInput, Table |
When something in pages/[Page]/components/ starts getting reused outside the page, graduate it to src/components/ (and update COMPONENTS.md).
Layout
src/layout/= App shell infrastructure (Layout, Header, Sidebar, PageLayout, EmptyState)- These are not generic reusable components, but structural elements that define the app shell
Features
src/features/= Complex features with multiple interconnected components (e.g., CommandPalette)- Features can have their own internal structure with pages, components, and utilities
Pages
- Each page is a folder. Sub-pages are sub-folders.
- Shared files for a page and its sub-pages live at the page's root folder.
- Entry point is always
index.jsx.
Imports
- Use
@/alias for absolute imports from src (e.g.,import { useAuthStore } from '@/stores/useAuthStore') - Group: external libraries first, then
@/imports, then relative imports
UI Components
- Use Mantine components exclusively. No custom CSS unless absolutely necessary.
- Use Mantine's built-in props for styling (size, variant, color, etc.)
- Icons: Use
lucide-reactexclusively. Do NOT use@tabler/icons-reactor any other icon library.import { TriangleAlert, Plus, Trash2 } from 'lucide-react'
Code Style
- JavaScript only (no TypeScript)
- Functional components with hooks
- Named exports for stores, default exports for page components
- Keep components small and focused
- JSX text with variables: always use template strings or plain strings — never HTML entities (
',", etc.) and never mix bare text with JSX expressions.// ❌ Wrong <Text>'{name}' cannot be undone.</Text> <Text>Hello {name}!</Text> // ✅ Correct <Text>{`'${name}' cannot be undone.`}</Text> <Text>{'Hello ' + name + '!'}</Text>
Real-time updates — use useLiveEvent, never a new stream or socket
When a page must react to a change made elsewhere (a sidecar checked in, a
record changed), subscribe with useLiveEvent. The browser holds one shared
connection to GET /api/events/stream: one tab streams and passes events to the
others. It opens with the first subscriber and closes when the last page
unmounts. Do not open an EventSource, a websocket or a new fetch stream for
this.
import { useLiveEvent } from '@/hooks/useLiveEvent'
import { LIVE_EVENTS } from '@/services/liveEvents'
useLiveEvent(LIVE_EVENTS.SIDECAR_CHECKED_IN, (event) => {
if (event.id === sidecar.id) refreshSidecar(sidecar.id)
}, enabled)Rules:
- An event is
{ type, id }and carries no data. Read the resource again through its store or service. - A new type is added in both places: the gateway constant
(
gateway/liveevents) andLIVE_EVENTS. - A page that must not miss an event keeps a slow poll: the stream is best effort (one replica, no replay, reconnects after 3-8s).
- Users: the sidecar setup wizard (
pages/Sidecars/Setup), approval notifications (features/ApprovalNotifications) and the sidebar pending approvals count (layout/Sidebar/usePendingApprovalsCount).
Snackbars / Toasts — use showSnackbar, never Mantine notifications
The legacy CLJS app shows toasts through sonner at the top-right of the screen.
The React side uses the same library (sonner) through a thin wrapper at
src/utils/snackbar.jsx, rendered by src/components/Snackbar/Toast.jsx (a
one-to-one port of the legacy toast), so users see one consistent toast style
across CLJS and React routes.
import { showSnackbar } from '@/utils/snackbar'
showSnackbar({ level: 'success', text: 'Connection enabled.' })
showSnackbar({ level: 'error', text: 'Failed to update.', description: err.message })
showSnackbar({ level: 'info', text: 'Heads up.' })Rules:
- Do NOT use
@mantine/notifications— the dependency has been removed from the project (it produced a completely different visual from v1 and broke parity). Do not re-add it. - The
<Toaster>is mounted once atsrc/App.jsx. Do not add additional Toaster instances. - The wrapper accepts the same
{ level, text, description }shape as the CLJS:show-snackbarevent so the mental model stays identical on both sides. - Do NOT show snackbars through the CLJS bridge (
clojureDispatch('show-snackbar', ...)) — the CLJS Toaster only exists while the CLJS tree is mounted, so toasts fired from React-only routes would be silently lost. Always useshowSnackbarfrom@/utils/snackbar.
Authentication Flow
Overview
Authentication follows the same logic as the original webapp (ClojureScript):
- Supports local auth (email/password) and IDP/OAuth providers
- Token stored in localStorage as
jwt-token(not justtoken) - Token can come from cookies (
hoop_access_token) or query params (?token=xxx) - The gateway renews the token in the
X-New-Access-Tokenresponse header;api.jsand the SSE clients store it, as CLJS does. SenduseAuthStore.getState().getToken(), never the store'stoken(the sign-in's, kept to detect an account change) - On 401, redirects to login
- Saves current URL before redirect for post-auth navigation
Key Files
stores/useAuthStore.js- Token management, cookie/query param handlingservices/auth.js- Login/logout API callsservices/api.js- Axios interceptor for auth header and 401 handlingcomponents/ProtectedRoute.jsx- Route protection wrapper;GatewayProtectedRoute.jsxadds the agents swappages/Auth/Login/- Login page (detects auth method from gateway)pages/Auth/Register/- Local auth signup formpages/Auth/Signup/- IDP org setup (post-OAuth)pages/Auth/Callback/- OAuth login callbackpages/Auth/SignupCallback/- OAuth signup callback → redirects to/signup
Auth Flow
- Check token: If no token in localStorage, redirect to
/login(saves current URL) - Fetch user: If token exists, fetch user data from
/api/users/me - Validate user: If user data is empty/invalid, clear token and redirect to login
- 401 Handling: On any API 401 response, save URL, clear token, redirect to login
- OAuth Callback: On
/auth/callback, extract token from cookie/query, save to localStorage, redirect to saved URL or home - OAuth Signup: On
/signup/callback, extract token, redirect to/signupfor org setup
Environment Variables
Env vars (VITE_API_URL, SEGMENT_WRITE_KEY, API_URL, VITE_CLJS_URL): see the table in README.md (Environment Variables).
Re-frame Interop (CLJS ↔ React)
See CLJS_PATTERNS.md for the complete CLJS → React mapping (state, HTTP, lifecycle, routing, Tailwind → Mantine, and how to find CLJS source files).
When React needs to trigger a CLJS re-frame action (e.g., navigate to a CLJS-owned route, open a CLJS modal):
- Never call
window.hoopDispatchdirectly from a component. Always wrap it in a Zustand store method. This makes it trivial to swap the underlying mechanism when the CLJS side is eventually removed. - Put the wrapper in the most relevant existing store, or create a
stores/useBridgeStore.jsfor cross-cutting concerns.
// ✅ Correct — store owns the bridge call
// stores/useUIStore.js
openLegacyModal: (modalName) => {
window.hoopDispatch(['modal->open', modalName])
}
// ❌ Wrong — component reaches directly into CLJS
window.hoopDispatch(['modal->open', 'some-modal'])Styling hierarchy — follow this order, never skip levels
1. Mantine style props — always first. Cover the vast majority of cases.
<Box mih="100%" p="md" maw={400} w="90%" h="100vh" />
<Text c="dimmed" fz="sm" fw={600} ta="center" />
<Stack gap="lg" align="center" />2. Component.extend() in src/components/[Name]/theme.js — for global defaults that apply to every instance of a component. Imported and assembled in src/theme.js.
// src/components/NavLink/theme.js
export const NavLinkTheme = NavLink.extend({
defaultProps: { radius: 'sm' },
styles: { label: { fontWeight: '600' } },
})3. CSS Module with var(--mantine-*) only — only when Mantine props cannot express the rule (pseudo-elements, [data-*] selectors, :hover with complex targets). See CSS Modules section below.
Never use
// ❌ style={{}} — always forbidden
<Box style={{ borderRadius: 8, color: '#3e63dd', padding: '8px 16px' }} />
// ❌ styles={{}} on instances — code smell: move it to Component.extend() in theme
<NavLink styles={{ label: { fontWeight: 600 } }} />
<AppShell styles={{ navbar: { transition: 'width 200ms ease' } }} />style={{}} and styles={{}} on instances generate inline styles on the DOM, bypass the theme, and scatter visual decisions across the codebase. If you find yourself reaching for either, step back:
- Simple value? → use a Mantine prop
- Repeated across instances? → move to
Component.extend() - Complex selector? → CSS Module with
var(--mantine-*)
Accepted exceptions for styles={{}}:
- Mantine
Transitionanimation spread:style={transitionStyles} - Structural shell slots (AppShell, Drawer) where
classNamesloses to Mantine's own CSS specificity — usestyleswith constants defined at the top of the file, never with raw hardcoded values inline
Wrapping Mantine components with context-specific styles
When a Mantine component (NavLink, Button, Drawer, Badge…) needs styles specific to one context, create a wrapper component that owns all the visual decisions. Never scatter classNames or styles props across call sites.
Where the wrapper lives — reusability decides
| The wrapper is used… | Put it in… | Example |
| Across the whole app | src/components/ | StatusBadge used in Sessions, Agents, Resources |
| Only inside one layout section | src/layout/[Section]/ | SidebarNavLink only used in the Sidebar |
| Reused by ≥2 consumers inside one page | src/pages/[Page]/components/ | SecretField/ rendered by multiple credential renderers |
| Only one consumer inside one page | src/pages/[Page]/sections/ | MetadataFieldsInput.jsx rendered by exactly one tab |
src/components/ is for truly reusable components. A component whose styles are hard-coded for a specific context (dark sidebar, data table, modal shell) is NOT reusable — even if it wraps a generic Mantine component. Keep it co-located with the context it serves. And a file that exists only to break up a long tab body isn't a component at all — put it in sections/.
Rules
- Apply all styles inside the wrapper via
classNames={{}}pointing to a co-located CSS Module. Never passstyles={{}}on instances. - Expose semantic props (
danger,blocked,profileItem) so call sites stay declarative and free of CSS class logic. - The CSS Module is the single source of truth for that component's appearance — one file to read, one file to change.
// ✅ Correct — wrapper owns classNames, call site stays clean
<SidebarNavLink danger label="Log out" onClick={onLogout} />
// ❌ Wrong — styling leaks into the call site
<NavLink
styles={{ root: { color: 'rgba(255,120,120,0.85)' } }}
classNames={{ root: classes.navLink }}
label="Log out"
onClick={onLogout}
/>Styled Components
When Mantine's built-in props and theme tokens are not enough for a visual requirement:
- Create a dedicated component in
src/components/(not inline in the page). - Use
Component.extend()insrc/components/[Name]/theme.jsfor global defaults. - Use a CSS Module scoped to that component for complex selectors only.
- Never add global CSS or unscoped styles.
CSS Modules — mandatory rule
CSS Modules are allowed only for complex selectors that Mantine props cannot express (pseudo-elements, :nth-child, etc.).
NEVER hardcode design values in CSS Modules. Every spacing, color, font size, radius, and line-height value must reference a Mantine CSS variable so the theme remains the single source of truth.
Available Mantine CSS variables (set by the theme in src/theme.js):
/* Spacing. The theme's own scale carries an `Alt` suffix; Mantine's five
defaults stay alongside it, so both spellings resolve and they are NOT the
same size. There is no --mantine-spacing-xxl: that one silently resolves to
nothing and the rule using it is dropped.
theme: xsAlt=4px smAlt=8px mdAlt=16px lgAlt=24px xlAlt=32px xxlAlt=48px xxxlAlt=64px
Mantine: xs=10px sm=12px md=16px lg=20px xl=32px */
var(--mantine-spacing-xsAlt | smAlt | mdAlt | lgAlt | xlAlt | xxlAlt | xxxlAlt)
var(--mantine-spacing-xs | sm | md | lg | xl)
/* Colors come from the theme. A surface is a component (Paper variant,
Divider, Alert, CodeSnippet) whose theme sets its color; a CSS Module names
no color unless it draws a one-off effect. Where no component fits, use the
role tokens below, never gray-N (the gray scale starts at Radix step 3;
CLJS_PATTERNS.md has the mapping). */
var(--hoop-surface-subtle | muted | strong | raised)
var(--hoop-border-subtle | divider)
var(--hoop-terminal-bg | text)
/* Font sizes — xs=12px sm=14px md=16px lg=18px xl=20px */
var(--mantine-font-size-xs | sm | md | lg | xl)
/* Line heights */
var(--mantine-line-height-xs | sm | md | lg | xl)
/* Border radius — xs=4.5px sm=6px md=9px lg=12px xl=18px */
var(--mantine-radius-xs | sm | md | lg | xl)
/* Semantic colors, never a shade number: outside src/components and
src/theme.js, test/themeColors.test.js fails on --mantine-color-{name}-{0-9}
(also built: `${name}.6`), a hex or an rgb(). A one-off effect says
`theme-exception: <why>` in its comment. */
var(--mantine-color-{name}-filled) /* solid fill */
var(--mantine-color-{name}-light) /* light variant bg */
var(--mantine-color-{name}-light-color) /* light variant text */
var(--mantine-primary-color-filled | light | light-color)
var(--mantine-color-text | dimmed | body)/* ❌ Wrong — hardcoded values leak out of the theme */
.label { font-size: 12px; margin-bottom: 8px; color: #3e63dd; }
/* ✅ Correct — always reference the theme */
.label { font-size: var(--mantine-font-size-xs); margin-bottom: var(--mantine-spacing-sm); color: var(--mantine-color-dimmed); }Text color — use Mantine tokens, not raw names
- For secondary text use
c="dimmed". The--mantine-color-dimmedvariable is set intheme.jscssVariablesResolver()to Radix slate11 (#60646c, ~5.7:1 on white — passes WCAG AA). Body text is--mantine-color-text= slate12 (#1c2024). - Never use raw names like
c="dark"orc="light"— those palettes are not defined intheme.jsand silently fall back to Mantine defaults. For near-black text simply omit the prop to inheritvar(--mantine-color-text);gray.9is#4d4d60(a mid slate), not near-black. - On dark navy surfaces (
--brand-navy), never color text with the gray scale — it is calibrated for light backgrounds. Use the--hoop-on-navy-*tokens (theme.js);EnterpriseBannerandSelectionCardkeep their own tones insidesrc/components. - When adding a new palette or changing
primaryColor, re-verifyc="dimmed"contrast in DevTools.
CSS Layers — do not disable
- The project loads Mantine via
@mantine/core/styles.layer.css(notstyles.css) and declares layer order insrc/layers.css:@layer mantine, app; mantineholds Mantine's built-in component CSS.appis declared but left empty — CSS Modules stay outside any named layer, which gives them the highest precedence in the cascade.- Without this, Mantine's internal classes (
.mantine-Accordion-item, etc.) compete with your CSS Module classes at equal specificity, and bundle import order decides the winner. Layers make CSS Modules win deterministically. - Practical consequence: when you add a new CSS Module that targets a Mantine slot via
classNames={{}}, you do NOT need!importantor doubled selectors (.foo.foo {}). - DO NOT change the Mantine import to
styles.css(without.layer) — that reintroduces the cascade bug.
CLJS stylesheet isolation
The legacy CLJS app (/webapp) ships its own stylesheet (/css/site.css, Tailwind + Radix). ClojureApp.jsx loads it as a regular <link rel="stylesheet" data-cljs-css> on mount, and on unmount toggles link.disabled = true. Remounts re-enable the same <link> — the browser keeps the parsed stylesheet in memory, so there is no re-fetch and no flash of unstyled content. This is why the CLJS CSS does NOT need a @layer legacy wrap: while a React-only route is rendered, the CLJS stylesheet is disabled and its rules do not enter the cascade at all.
Rules:
- Do NOT remove the
disableCLJSCSS()call in ClojureApp's cleanup. Without it, Tailwind/Radix rules leak into every React page as soon as the user visits a CLJS route once. - Do NOT switch to
<style>@import url(...) layer(...)</style>— it works in theory but@importis processed serially by the CSS parser, producing a visible FOUC on mount and unpredictable timing on unmount.
Symptom — "my CSS Module does nothing on a Mantine component"
Debug checklist:
- Is the CSS Module imported in the JSX? (Vite only bundles it if there's
import classes from './X.module.css'.) - Are classes applied via
classNames={{ slot: classes.foo }}, notclassName? Internal slots of Mantine components ignoreclassName. - Is the slot name correct? Check the "Styles API" section of the Mantine component's docs.
- Does the CSS Module name a color? It must not: colors come from the component's theme or the role tokens in
theme.js(the sidebar's Figma alpha overlays are--hoop-nav-*, white tones on the brand navy are--hoop-on-navy-*).test/themeColors.test.jsfails on a shade or a literal outsidesrc/componentsandsrc/theme.js. - If it still doesn't apply and
layers.cssis imported, inspect the rule in DevTools and confirm it's inside@layer mantine— if not, thestyles.layer.cssimport was broken.
Reference Implementation
pages/Agents/is the reference page showing the full pattern: store + service + list page + create page
Required reading — do this before every task
Read these files at the start of every session, before writing any code:
CONTEXT_MIGRATION.md— architecture, shell/bridge contracts, routing split, migration status. Required for any work in this repo.CLAUDE.md(this file) — coding rules, styling hierarchy, component strategy.COMPONENTS.md— catalog of every existing component, hook, store, and service. Check before creating anything new.
Additionally, for specific task types:
- Migrating a CLJS page to React → also read
MIGRATION_CHECKLIST.mdandCLJS_PATTERNS.md - Building UI or adding a component →
COMPONENTS.mdis mandatory (already listed above) - Any behavior that exists in the original app → read the CLJS source first under
../webapp/src/webapp/and replicate it; do not invent patterns the original already has
Skipping these reads is the leading cause of regressions: wrong column structure, invented UI that diverges from the original, components duplicated instead of reused, and styling that bypasses the theme.
Migration Rule
This project is a migration of ../webapp/ (ClojureScript) to React — not a greenfield build.
Before implementing any behavior (mobile nav, modals, transitions, keyboard handling, etc.),
check how it works in the original app first (../webapp/src/webapp/). Replicate the behavior
using Mantine/React equivalents. Do not invent new patterns when the original already has one.
When migrating a page, follow MIGRATION_CHECKLIST.md — it covers every step from reading the CLJS source to updating the routing table, including verification against the original behavior.
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.

