Plasmic

This is a set of rules that outlines the best practices and architecture principles to create Plasmic-compatible code:

Plasmic-Specific Guidelines

- Build reusable components for Plasmic Studio, not pages
- Pass as much UI work as possible to Plasmic Studio
- For repeatable components, use string/number props over slots
- Use slot components for images when possible; apply default styles with ".element image" selectors
- Use DataProvider only when exposing data to Plasmic Studio is necessary
- Use the Plasmic state feature if you need to listen to or propagate changes

Component Registration

- Register all components in plasmic-host.tsx
- Import components at the top of the file
- Use registerComponent with proper configuration (see Plasmic docs)
- Set appropriate name and displayName
- Use importPath with @/ prefix only in codegen mode (if loader library is absent)
- Provide default values for required props
- Add descriptive comments for each prop
- By default, registerComponent includes a className prop for root styles (do not add it explicitly)

Props Configuration

- Use type: "class" for all className props (never "string")
- For eventHandler props, include argTypes: []
- Use these types for props:
  - "string" for text
  - "number" for numbers
  - "boolean" for toggles
  - "imageUrl" for images
  - "array" for collections
  - "eventHandler" for callbacks
  - "slot" for customizable content
  - "class" for styles

Naming Conventions

- PascalCase: Components, Types, Interfaces
- kebab-case: directories, file names (e.g., auth-wizard, user-profile.tsx)
- camelCase: variables, functions, methods, hooks, props
- UPPERCASE: environment variables, constants
- Prefix event handlers with 'handle' (e.g., handleClick)
- Prefix booleans with verbs (e.g., isLoading, hasError)
- Prefix custom hooks with 'use' (e.g., useAuth)
- For style props, use suffix ClassName (e.g., titleClassName)
- For event handlers, use prefix on (e.g., onClick)

Styling Guidelines

- Use CSS modules (e.g., ComponentName.module.css)
- Design mobile-first and responsively
- Include hover states and transitions for interactive elements
- Add fallback styles for missing content (e.g., no-image state)
- Ensure color contrast accessibility
- Maintain consistent spacing
- Define CSS variables for theme colors and spacing
- Use Plasmic's registerToken/tokens for CSS variable integration
- Pass className for root element to allow Studio style customization
- Use classnames feature to allow Studio to override/modify child styles
- Allow initial CSS in UI components for Studio users to extend

Data & State Handling

- Use DataProvider only when exposing data to Studio is needed (in case if user would need to render something using the data, like a repeatable component, or if the component itself is created to fetch the data)
- Transform data inside the component as needed
- Define states in registration when needed, with correct valueProps/onChangeProps/variableType
- When using data sources (like fetching data from remote database) - use data fetching components, look up supabase example repository to see how it's done

Common Mistakes to Avoid

- Do not create pages; only reusable components
- Do not use type: "string" for className props (use "class")
- Do not use slots for repeatable components populated from data
- Do not forget argTypes: [] for eventHandler props
- Do not forget providesData: true when using DataProvider
- Do not add className prop again in registration
- Do not use app router features without confirming project structure
- Use "dynamic" clause to load registered components that rely on heavy front-end dependencies (like google maps, etc.)