Canonical frontend conventions for frontend/. Most are mechanically enforced. Deep how-to: ../../guides/frontend.md.
| Pattern | Rule | Enforcement |
|---|---|---|
| Colors | Theme classes only: bg-theme-*, text-theme-* |
hardcoded-color-check.sh + pattern-validation.sh |
| Navigation | Flat structure — no submenus | pattern-validation.sh |
| Actions | ALL in PageContainer — none in page content | review |
| State | Global notifications only — no local success/error | review |
| Imports | Path aliases for cross-feature: @/shared/, @/features/; an extension's own tree via its alias (@system/) |
pattern-validation.sh (extension trees, public and private; three or more ../ fails) + convert-relative-imports.sh (on-demand fixer, core only) |
| Logging | No console.* at any level — use import { logger } from '@/shared/utils/logger' |
console-log-check.sh + pattern-validation.sh (both via scripts/list-console-sites.sh) |
| Types | No any — proper TypeScript types required |
no-any-type-check.sh + pattern-validation.sh |
This row used to cite scripts/convert-relative-imports.sh as the enforcement.
That script is real and useful, but it never enforced anything, for three
separate reasons — and each one alone is enough:
- Nothing fails on it. No hook, gate or CI step runs it. The only caller is
the
/cleanup allskill (.claude/skills/cleanup/SKILL.md:38), which a person invokes on demand and which rewrites files rather than failing. - It cannot see an extension. It hardcodes
SRC_ROOT="frontend/src", so it never descends intoextensions/*/frontend/src. - It cannot emit the alias this row is about. Its output alphabet is
@/shared/and@/features/only (scripts/convert-relative-imports.sh:68-83); there is no branch that can ever produce@system/.
It stays the right tool for converting core by hand. The row now also cites the scan that actually fails a build.
With no gate reaching them, the system extension had drifted to 61 imports climbing three or more directories, across 30 files (IMP-003653cb5634).
Three climbs is the threshold. ../../types stays inside a feature and reads as
local; ../../../ has already left it, and that is the form that breaks on a
move — silently, because TypeScript resolves whatever the new path lands on and
a file moved one level can start importing a different module that still
type-checks.
The scan covers PUBLIC and private extension frontends. An earlier draft
covered public trees only, justified by the rule that a tracked core file may not
name a private extension — true, and already solved by the SPLIT LEDGER the
console-log and core-purity guards use: known debt is grandfathered per file with
a count in .claude/hooks/deep-relative-import-baseline.txt, and private paths go
in the gitignored .local.txt sibling beside it. Excluding them would have left
125 of the 128 offending files fleet-wide unguarded.
The ledger is a ratchet in BOTH directions. A listed file that grows fails; a
listed file that shrinks, is fixed or is deleted fails too, so an entry cannot
outlive the debt it describes. A missing tracked baseline fails closed. Only
single-quoted from '...' is matched; a double-quoted or dynamic import()
form is a known, accepted gap.
The rule is every console level, not just log. It used to be log/debug/info
only, in three places that each kept their own copy of the pattern, so console.warn
and console.error accumulated for the life of the tree while every guard reported
clean (IMP-1f4b84af602c).
scripts/list-console-sites.sh is now the single definition of what counts; the edit
hook and the pattern-validation.sh check both call it. Sites that already existed are
grandfathered in two ledgers — .claude/hooks/console-log-baseline.txt (tracked, core
and public extensions) and .claude/hooks/console-log-baseline.local.txt (gitignored,
private extensions, whose paths must not reach the public mirror).
If the gate fails with "N new console call(s)", the fix is the logger, not the ledger. Regenerate the ledgers only when you have legitimately REMOVED sites:
bash scripts/generate-console-log-baseline.shEntries are path|source line, one per occurrence, so a third copy of an
already-grandfathered line is still a new site.
Frontend MUST use permissions ONLY — NEVER roles for access control:
// ✅ CORRECT
currentUser?.permissions?.includes('users.manage')
// ❌ FORBIDDEN
currentUser?.roles?.includes('admin')
user.role === 'manager'Backend: current_user.has_permission?('name') — NEVER permissions.include?() (returns objects). Advisory nudge: permission-not-roles-check.sh. The principle stays in the core because it is a security boundary; the hook is a backstop, not the source of truth.
Extensions compose into the platform through featureRegistry — routes, nav
items, settings tabs, channels, component slots. State is the same shape of
seam, via injectReducer from @/shared/services.
An extension that defines a Redux slice must register its reducer, or the slice
exists nowhere and every selector reading it gets undefined. That is not
hypothetical: an extension shipped a complete slice mounted in no store, and it
went unnoticed only because nothing rendered the components that would have
thrown on first render.
// extension register() — beside the featureRegistry calls
import { injectReducer } from '@/shared/services';
import billingReducer from '@myext/shared/slices/billingSlice';
export function register(): void {
injectReducer('billing', billingReducer);
featureRegistry.registerRoutes('myext', [ /* ... */ ]);
}Type it from the extension side — core must never name an extension, so it
exposes an empty, augmentable ExtensionState that declaration merging fills:
// beside the slice
declare module '@/shared/services' {
interface ExtensionState {
billing: BillingState;
}
}Three properties worth understanding rather than working around:
- Ordering is already safe.
register()runs synchronously at module load (extensionLoader's eager glob), and runtime extensions are awaited inindex.tsx— both before the first render. A reducer injected fromregister()is present before anything selects it. RootStateappliesPartial<>to extension state, deliberately. Slices genuinely do not exist untilregister()runs, and a runtime extension that exceeds the boot timeout registers after the first render. So read with?.and a fallback. Asserting the slice is present would type-check and then throw — the exact failure this seam replaced.injectReduceris idempotent. Re-registering a key is a no-op, so HMR and a double-invokedregister()cannot reset live slice state.
Do NOT create a second store inside an extension. Two stores means two sources of truth, and breaks devtools and cross-cutting selectors.
Covered by frontend/src/shared/services/injectReducer.test.ts.