Client Components
Developmentclient-componentsClient Components is an Agent Skill for development published in the ParabolInc/parabol repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Reference conventions for React client components — Tailwind CSS, UI primitives (Dialog, Tooltip, Menu), constants, HTML sanitization, and component design patterns. Use when building or reviewing UI components in packages/client.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ParabolInc/parabol/blob/HEAD/.claude/skills/client-components/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/client-components, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
packages/client conventions
Styling
- All new components must use Tailwind CSS — do not use emotion (
styled,cssfrom@emotion/styled/@emotion/react). - Biome enforces Tailwind class sort order (
lint/nursery/useSortedClasses). After modifying a file, runpnpm exec biome check --write <file>to auto-fix. Do not usepnpm biome check --write— thebiomescript already includescheck, so it would expand tobiome check check --writeand fail. - Promote shared classes to the parent. When two or more sibling elements share the same Tailwind class, move it to their common parent instead of repeating it. Inherited properties (
font-*,text-*,capitalize,leading-*,color) cascade naturally; structural properties (flex,w-*,p-*) usually stay on the element they control.
UI primitives (modals, dialogs, popovers, tooltips, menus)
Use the radix-ui based components in packages/client/ui/:
| Use case | Components |
|---|---|
| Modal / dialog | Dialog, DialogContent, DialogTitle, DialogActions, DialogOverlay, DialogClose from ui/Dialog/ |
| Alert/confirm dialog | AlertDialog and sub-components from ui/AlertDialog/ |
| Tooltip | Tooltip, TooltipTrigger, TooltipContent from ui/Tooltip/ |
| Dropdown menu | Menu, MenuItem, MenuContent etc. from ui/Menu/ |
| Select | Select, SelectContent, SelectItem etc. from ui/Select/ |
Do NOT use DashModal (packages/client/components/Dashboard/DashModal.tsx) — it is deprecated.
Dialog open state can be managed with useDialogState from ui/Dialog/useDialogState.tsx, or passed as isOpen/onClose props to Dialog. Prefer always rendering the Dialog and controlling via isOpen rather than conditionally mounting it.
Constants
- Do not add new values to
constEnums.ts(packages/client/types/constEnums.ts) — it is deprecated. - Add new constants to
packages/client/utils/constants.tsas plainexport constvalues.
HTML Sanitization
- Wrap all external HTML with
sanitizeExternalHtml()beforedangerouslySetInnerHTML. Content from external sources (Jira, GitHub, GitLab, Azure DevOps, Linear, user reflections) must be sanitized viasanitizeExternalHtml()frompackages/client/utils/sanitizeExternalHtml.ts. It uses DOMPurify with a hook that forces links totarget="_blank" rel="noopener noreferrer"and blocks<style>tags.
// Good
<div dangerouslySetInnerHTML={{__html: sanitizeExternalHtml(descriptionHTML)}} />
// Bad — XSS risk
<div dangerouslySetInnerHTML={{__html: descriptionHTML}} />
Component Size
- Target under 100 LOC per component. If a component is approaching 100 lines, look for self-contained sections (a form section, a list item, a panel) to extract into their own files.
- Hard limit: 300 LOC. A component that exceeds 300 lines must be split — no exceptions.
React Component Design
- Use
onPointerDowninstead ofonMouseDown+onTouchStart. The unified pointer API handles mouse, touch, and pen. - Prevent unnecessary re-renders:
useMemofor expensive computationsuseCallbackfor event handlers passed to child components- Early returns in
useEffectwhen values haven't changed (e.g.if (cellValue !== value))
- Lazy
useStateinitialization for hot-path components:useState(() => expensiveComputation())notuseState(expensiveComputation()). The thunk runs only on mount, not every render. - Provide clear user feedback. Forms need submit buttons or auto-save — don't rely on implicit Enter-to-save without visual cues.
UI/UX Patterns
- Autocomplete behavior: Allow Tab and Enter to complete suggestions. Show a visual preview of what will be completed (inline ghost text or bold matching).
- Stable tag/label colors: Assign colors when tags are created and persist them. Don't generate colors from the current text on every keystroke.
- Destructive actions need explicit confirmation. Use clear labels like "Delete Permanently" not just "Delete".
- Clear role naming: prefer simple names like "Team Lead" and "Member" over "Member team".
- Validate and limit input sizes — set
maxLengthon all input fields. Prevent users from pasting megabytes of text into cells.
Dependencies & Package Management
- Consolidate package versions in the root
package.json. Don't install the same package in multiplepackage.jsonfiles — this causes version conflicts (e.g. TipTap extensions with different versions on server vs client).
Code Organization
- Use descriptive file names. Avoid generic names like
data.ts— prefertableOps.ts,transforms.ts, etc. - Kebab-case for HTML/CSS attributes. Use
data-is-databasenotdata-isDatabase. - Consistent ordering: CHANGELOG entries in reverse chronological order (newest first).
Testing Stripe
brew install stripe/stripe-cli/stripeand thenstripe loginto get the port forwarder up and running- Use
stripe listen --forward-to https://localhost:3000/stripe --skip-verifyto forward Stripe events to your local server.