wonder-blocks frontend-rules.instructions.md

Wonder Blocks Design System - Frontend Rules

This file provides frontend development instructions for the Wonder Blocks design system.

Technology Stack

• Language: TypeScript (Strict mode enforced)
• Framework: React (Functional Components and Hooks)
• Styling: Aphrodite (aphrodite) for CSS-in-JS with Wonder Blocks tokens (@khanacademy/wonder-blocks-tokens)
• State Management: Local state (useState) and React Context API (useContext)
• Data Fetching: There should be no data fetching in the design system UI components
• Routing: Design system components with link functionality should also support React-Router routes
• Testing: Jest, React Testing Library (RTL), @testing-library/user-event, Storybook
• Package Manager: pnpm

Coding Conventions

File & Export Naming

• Use kebab-case for files and directories (e.g., activity-button.tsx, utils.ts)
• Test files: *.test.ts(x)
• Storybook files: *.stories.tsx
• PascalCase for React components and types (e.g., Button, type ButtonProps)
• camelCase for functions, variables, hooks (e.g., getButtonProps, useButtonFunctionality)

TypeScript

• Use strict mode
• Define clear interfaces/types. Use type for props and state, interface for shared structures where appropriate
• Use utility types (Partial, Omit, Pick, Readonly, etc.)
• Use the satisfies operator for type-safe object literals
• Prefer type-only imports: import type {...} for types
• Avoid any; use unknown or specific types instead

React

• Imports: Always use import * as React from "react" (required for JSX transformation)
• Use functional components and hooks (useState, useEffect, useContext, useCallback, useMemo)
• Define explicit Props types with object destructuring. Pass complex objects/callbacks with stable references (useCallback, useMemo) if they are dependencies of effects or memoized children
• Keep component state minimal. Lift state up when necessary
• Provide stable key props for lists (use item IDs if available)
• Build complex UI by composing smaller Wonder Blocks when possible
• Use React.forwardRef when components need to expose DOM refs
• Extract reusable logic into custom hooks (e.g., useFieldValidation, useIsMounted from @khanacademy/wonder-blocks-core)
• Event Handlers: Internal handlers prefixed with handle (e.g., handleClick), callback props prefixed with on (e.g., onClick)
• Don't use React.FC<Props>, use (props: Props) => instead
• Avoid creating new class components