# Code Review Guidelines

Before marking any task as done, verify every applicable section below.

## Code Quality

- **Biome**: run `bun qc` and confirm zero errors. Do not suppress or ignore lint rules without justification.
- **TypeScript**: run `bun qts` and confirm zero type errors. All exported functions and types must have explicit type annotations (`isolatedDeclarations` is enabled).
- **Formatting**: 4-space indentation, 100-character line width, multiline JSX attributes. Run `bun qa` to auto-fix if needed.
- **Unused imports**: Biome warns on unused imports — remove them before committing.
- **Unused code**: do not leave behind dead code, commented-out blocks, or `console.log` statements.

## Components

- **Mantine first**: use Mantine components (`Box`, `Text`, `Group`, `Stack`, etc.) over raw HTML elements. Use `<Box>` instead of `<div>`.
- **Props interface**: extend `BoxProps` or the appropriate Mantine component props type. Export the props interface alongside the component.
- **Prop spreading**: spread remaining props (`...rest`) onto the root element so consumers can pass through Mantine attributes.
- **clsx**: use `clsx` from `@src/helpers/clsx` (the project's own implementation), not the npm `clsx` package.
- **Return type**: use `ReactNode` for function declarations or `FC<Props>` for arrow functions — match the convention of surrounding code.

## Styling

- **SCSS modules**: styles go in `style.module.scss` next to the component. Import as `import classes from "./style.module.scss"`.
- **dashesOnly**: access class names as `classes.myClass`, never `classes["my-class"]`.
- **Dynamic values**: use Mantine's `__vars` prop to pass CSS custom properties for dynamic size/color — not inline styles.
- **Design tokens**: reference Mantine tokens (`--mantine-color-*`) and SurrealDB tokens (`--surreal-*`). Do not hardcode color hex values in SCSS unless defining a new token.
- **Light/dark theme**: any color that differs between themes must use `@include light { ... }` and `@include dark { ... }` mixins. Verify the component looks correct in both color schemes.
- **Responsive**: use the breakpoint mixins (`@include sm-and-up`, `@include md-and-down`, etc.) instead of raw `@media` queries.
- **No global styles**: do not add styles to `global.scss` or `variants.scss` unless defining a new design token. Component styles belong in SCSS modules.

## Exports

- **Re-export from index**: new components, hooks, helpers, or types must be re-exported from `src/index.ts`. Missing re-exports break the public API.
- **Explicit type exports**: use `export type` for type-only exports (required by `isolatedDeclarations` and `verbatimModuleSyntax`).

## Storybook

- **Story exists**: every primitive component must have a corresponding story in `src/stories/primitives/`. Mantine-themed component demos go in `src/stories/mantine/`.
- **CSF3 format**: stories must use Component Story Format 3 with a typed `meta` default export and `StoryObj` named exports.
- **Title convention**: use the correct prefix (`Primitives/`, `Mantine/`, `Catalog/`, or `Playground/`) in the story `title`.
- **No providers in stories**: do not wrap stories in `MantineProvider` — this is handled globally by `.storybook/preview.tsx`.
- **Shared arg types**: reuse `size` and `icon` from `src/stories/arg-types/` instead of redefining them.

## Testing

- **Tests pass**: run `bun run test:unit` and `bun run test:e2e` and confirm all tests pass. Do not skip or disable tests without justification.
- **Markdown parser**: changes to `src/lib/markdown/` must include tests. Markdown tests live under `tests/unit/MarkdownEditor`, `tests/unit/MarkdownViewer`, and `tests/unit/MarkdownConformance`; run `bun run test:unit` (and `bun run test:e2e` for the parity suites) to verify. Update snapshots only when the change is intentional.
- **Snapshot review**: if snapshots are updated, verify the diff reflects the intended change — not unrelated side effects.

## Dependencies

- **Justify new packages**: new external dependencies require justification. Prefer small helper functions over adding utility packages.
- **Peer vs direct**: UI framework dependencies (React, Mantine, CodeMirror, Slate) are peer dependencies — never add them to `dependencies`.
- **Package manager**: use `bun` exclusively. Do not use npm, yarn, or pnpm commands. Do not commit `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`.

## Generated Files

- **Do not edit**: `src/constants/icons.ts` is auto-generated by `bun run icons`. Never edit it manually.
- **Do not edit**: `bun.lock` is managed by Bun. Do not manually modify it.
- **Do not commit**: `dist/`, `node_modules/`, `storybook-static/`, and `.tgz` files are gitignored.

## Security

- **No secrets**: credentials, tokens, and API keys must not appear in source code, console logs, or error messages.
- **No `.env` files**: do not commit `.env` or any environment variable files.

## Build Compatibility

- **ES2022 target**: do not use syntax or APIs that require a target newer than ES2022.
- **Tree-shaking**: the package is marked `"sideEffects": false`. Ensure new modules do not introduce top-level side effects outside of style imports.
- **CSS layer**: all component CSS is wrapped in `@layer surreal` at build time. Do not add `@layer` directives in SCSS modules — the Vite plugin handles this.

## Hooks

- **useStable**: the return value of `useStable` is a stable reference — do not include it in React dependency arrays. Biome enforces this automatically.
- **useExhaustiveDependencies**: Biome enforces exhaustive deps at error level. Do not suppress this rule; fix the dependency array instead.

## Skip

- Formatting and linting auto-fixes (enforced by `bun qa` / `bun qau`).
- Biome-excluded files: `.vscode/`, `.github/`, `.storybook/`, `src/constants/icons.ts`, `dist/`, `*.js`.
