---
name: frontend-conventions
description: Use for creating, modifying, moving, or reviewing React frontend code anywhere in packages/*, including Workshop pages, gatekeeper management apps, shared UI, components, hooks, forms, interactions, styling, accessibility, and frontend tests.
title: frontend-conventions
canonical_url: https://skilld.dev/gh/cloudflare/cloudflare-os/frontend-conventions
last_updated: 2026-10-03T16:30:13.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install cloudflare/cloudflare-os/frontend-conventions`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/frontend-conventions`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/cloudflare/cloudflare-os/frontend-conventions) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/frontend-conventions`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/frontend-conventions --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/frontend-conventions --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Frontend Conventions

Apply these conventions to the Workshop SPA, gatekeeper management SPAs, and `@gadgets/ui`.
Package-level `AGENTS.md` files add product-specific rules but do not replace this guidance.

## Ownership And Organization

Organize code by product ownership before implementation type. Feature directories own product
behavior and may contain components, hooks, tests, and utilities that change for the same reason.

Start directories flat. Do not introduce `components/`, `hooks/`, `helpers/`, or `tests/`
subdirectories merely to classify files. Introduce a responsibility-named subsystem directory only
when several files form a coherent unit or the flat directory becomes difficult to scan.

Use PascalCase filenames for components and camelCase filenames for hooks and non-component
modules. Colocate `*.test.ts(x)` files with their subject. Feature organization does not replace
the one-component-per-file model.

Keep product behavior with its product even when another feature consumes it. Promote code only as
high as its ownership requires:

- Code shared within one feature belongs at the nearest common feature directory.
- Feature-independent code shared across unrelated areas of one app may live in that app's
  `components/` or `hooks/` directory.
- Runtime UI shared by independent frontends belongs in `@gadgets/ui`.
- Do not merge components merely because they look similar. Avoid generic prop-heavy abstractions
  that erase domain behavior.

## Components And Hooks

Create a separate component when it owns meaningful state, effects, interactions, accessibility
behavior, or reusable responsibility; represents a distinct UI concern; or obscures its parent's
main flow. Keep small stateless render helpers private until they develop an independent concern.

Extract a hook when it owns a coherent behavior or external synchronization lifecycle, not simply
to shorten a file. Keep code together when an extracted child would mostly forward markup or depend
on the parent's refs, setters, and synchronization callbacks.

Prefer named arrow-function components and hooks. Type props directly rather than using `React.FC`.
Give wrappers such as `memo` and `forwardRef` stable DevTools names.

## Component APIs

Represent props that are valid only together as an object or discriminated union. A controlled
value requires a change callback; otherwise expose an uncontrolled initial value. Do not copy a
controlled prop into local state with an Effect.

Name callbacks `on<Action>` and pass domain values rather than React setters or browser events.
Add `children`, slots, variants, `className`, DOM passthrough, and imperative refs only for current
callers, not speculative reuse.

Use context for genuinely application-wide values such as authentication, theme, and toasts. Pass
instance-specific feature data and actions through props.

## Kumo And Styling

Use Kumo components and semantic tokens by default. Check Kumo and `@gadgets/ui` before creating a
control or interaction pattern. A shared Gadgets component should compose Kumo behavior, not merely
rename or restyle a primitive.

Do not add custom color literals, arbitrary Tailwind colors, feature-local token systems, or local
replacements for Kumo surfaces, borders, text, status, focus, and interaction tokens unless the user
explicitly requests them. Existing legacy colors are not precedent.

Tailwind is appropriate for structure, spacing, sizing, positioning, responsive behavior, and
typography. Use custom CSS only for technical behavior Kumo and utilities cannot express. Global
Kumo token theming is an application-level decision and must not be changed during ordinary feature
work.

When Kumo is unsuitable, identify the concrete behavioral or accessibility gap before introducing
a shared abstraction.

## React

Treat Effects as synchronization with external systems, not as derived-state machinery or a way to
sequence user interactions. Calculate render data during render, keep state near its owner, prefer a
component `key` for identity resets, and use `useSyncExternalStore` for suitable external stores.

Effects that fetch or subscribe must clean up stale work and remain correct when restarted. Avoid
chains of Effects and do not synchronize two pieces of React state when one can be derived.

Do not add `useMemo` or `useCallback` without a concrete identity or performance need. Preserve
keyboard behavior, focus management, accessible names, announcements, and mouse/touch/hybrid input
parity. RPC stubs must follow the disposal and React state rules in the root `AGENTS.md`.

## Comments

Prefer names and types that communicate intent. Comments should explain non-obvious constraints,
security or performance reasons, and deliberate departures from conventions. Do not narrate the
next line. Remove or update comments when their constraint changes.

## Tests

Tests should protect observable behavior, product rules, accessibility, state transitions, races,
and failure paths. Do not test React, JavaScript, Kumo, or another framework's own behavior merely
for coverage. Avoid assertions coupled only to implementation details or trivial passthrough.

Behavior-preserving moves should keep tests unchanged apart from imports. Add focused coverage only
when an extraction exposes important previously untested logic.
