ContextQMD
Back to Lobehub

React Component Writing Guide

.agents/skills/react/SKILL.md

2.2.04.9 KB
Original Source

React Component Writing Guide

Styling

ScenarioApproach
Most casescreateStaticStyles + cssVar.* (zero-runtime, module-level)
Simple one-offInline style attribute
Truly dynamic (JS color fns like readableColor/chroma)createStyles + token — last resort

Component Priority

  1. src/components — project-specific reusable components
  2. @lobehub/ui/base-ui — headless primitives (Select, Modal, DropdownMenu, Popover, Switch, ScrollArea…)
  3. @lobehub/ui — higher-level components (ActionIcon, Markdown, DragPage…)
  4. Custom implementation — last resort; never reach for antd directly

If unsure about available components, search existing code or check node_modules/@lobehub/ui/es/index.mjs.

Common @lobehub/ui Components

CategoryComponents
GeneralActionIcon, ActionIconGroup, Block, Button, Icon
Data DisplayAvatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip
Data EntryCodeEditor, CopyButton, EditableText, Form, FormModal, Input, SearchBar, Select
FeedbackAlert, Drawer, Modal
LayoutCenter, DraggablePanel, Flexbox, Grid, Header, MaskShadow
NavigationBurger, Dropdown, Menu, SideNav, Tabs

Layout

Use Flexbox and Center from @lobehub/ui. See references/layout-kit.md for full props and examples.

  • Use gap instead of margin for spacing between flex children
  • Use flex={1} to fill available space
  • Nest Flexbox for complex layouts; set overflow: 'auto' for scrollable regions

For SPA pages, use react-router-dom, NOT next/link.

tsx
// ❌ Wrong
import Link from 'next/link';

// ✅ Correct
import { Link, useNavigate } from 'react-router-dom';

Access navigate from stores: useGlobalStore.getState().navigate?.('/settings');

Desktop File Sync Rule

Files with a .desktop.ts(x) variant must be edited in sync. Drift causes blank pages in Electron.

Base file (web)Desktop file (Electron)
desktopRouter.config.tsxdesktopRouter.config.desktop.tsx
componentMap.tscomponentMap.desktop.ts

After editing any .ts/.tsx: glob for <filename>.desktop.{ts,tsx} in the same directory. If found, apply the equivalent sync-import change.

Routing Architecture

Route TypeUse CaseImplementation
Next.js App RouterAuth pagessrc/app/[variants]/(auth)/
React Router DOMMain SPAdesktopRouter.config.tsx + .desktop.tsx (pair)

Router utilities:

tsx
import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';
element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
element: redirectElement('/settings/profile');
errorElement: <ErrorBoundary />;

Common Mistakes

MistakeFix
Using next/link in SPAUse react-router-dom Link
Using antd directlyUse @lobehub/ui/base-ui first, then @lobehub/ui
createStyles for static stylesUse createStaticStyles + cssVar
Editing only desktopRouter.config.tsxMust edit both .tsx and .desktop.tsx
Using margin for flex spacingUse gap prop on Flexbox
Accessing zustand store without selectorUse selectors to access store data (see zustand skill)
Text or icon-text actions built with Flexbox/Text + onClickUse Button type={'text'} size={'small'} with icon when needed