general

Wonder Blocks Design System

Technology Stack

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

Coding Conventions & Style

1. File Naming

• ✅ Use kebab-case for files and directories (e.g., activity-button.tsx, utils.ts)
• ✅ Test files: *.test.ts(x)
• ✅ Storybook files: *.stories.tsx

2. Export Naming

• ✅ PascalCase for React components and TSX types/interfaces (e.g., Button, type ButtonProps)
• ✅ camelCase for functions, variables, hooks (e.g., getButtonProps, useButtonFunctionality)

3. TypeScript

• ✅ Use strict mode
• ✅ Define clear interfaces/types (colocated or in types.ts). 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 when you want both type checking and type inference
• ✅ Prefer type-only imports where applicable: import type {...} for types
• ❌ Avoid any; use unknown or specific types instead

4. React

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