# Repository Guidelines

## Project Structure & Module Organization
- `src/components/ui/*`: Atomic UI components (Radix/ShadCN-based). Each component should have a `*.stories.tsx` file next to it.
- `src/components/layout/*`: Reusable layout containers (Page, Heading, Header, ViewHeader, ErrorPage).
- `src/components/features/*`: Higher-level, opinionated components (e.g., PostShareModal, SourceTabs).
- `src/hooks/*`: Custom React hooks.
- `src/lib/utils.ts`: Shared utilities (class merging, formatting, chart helpers).
- `src/providers/*` and `src/ShadeApp.tsx`: Context + app wrapper that scopes styles to `.shade`.
- `src/assets/*`: Logos and custom icon SVGs (icons auto-exported via `Icon`).
- `test/unit/*`: Vitest tests. `test/unit/utils/test-utils.tsx` provides a `render` helper.
- Build artifacts: `es/` (compiled ESM) and `types/` (generated `.d.ts`). Storybook config lives in `.storybook/`.

## Build, Test, and Development Commands
- `yarn build` — Type declarations + Vite library build to `es/`.
- `yarn test` — Type-checks then runs Vitest with coverage.
- `yarn test:unit` / `yarn test:types` — Run unit tests or TS type-checks only.
- `yarn lint` — ESLint for source and tests (`tailwindcss` plugin enabled).
- `yarn storybook` — Run Storybook locally. `yarn build-storybook` — static export.

## Coding Style & Naming Conventions
- React + TypeScript. Prefer composable components over heavy prop configuration.
- Filenames: ShadCN-generated files keep kebab-case; component identifiers use `PascalCase`.
- Functions/vars: `camelCase`. Keep file-scoped components in the same file.
- Always forward and merge `className` with `cn(...)`. Use CVA for variants when useful.
- Tailwind is scoped via `.shade`; dark mode uses `.dark`. Follow ESLint and `tailwindcss/*` rules.

## Component API Patterns
- Prefer compound subcomponents for multi‑region components (e.g., `Header.Title`, `Header.Meta`, `Header.Actions`) instead of many props.
- Keep parts small and focused; attach them as static properties and export as named exports.
- Expose Radix/HTML props where sensible; always include `className` and merge with `cn(...)`.
- Demonstrate each part in Storybook stories (e.g., “With actions”, “With meta”).

## Adding New Components
- Prefer ShadCN first: search for an equivalent and add via `npx shadcn@latest add <component>`. Follow the guardrails above to avoid accidental overwrites.
- Location & exports: place new UI components under `src/components/ui` and export them from `src/index.ts`.
- Storybook: add a sibling `*.stories.tsx` file with an overview (what/why) and stories showing different use cases/variants (sizes, states, important props).
- Implementation: forward `className` and merge with `cn(...)`; use CVA for variants where appropriate.
- Verification: `yarn lint`, `yarn test`, plus `yarn storybook` to visually validate stories before opening a PR.
- **Important**: Always run `yarn lint` after making changes to fix any ESLint errors and warnings before committing.

## Testing Guidelines (TBD)
We are finalizing a formal testing strategy.

Interim expectations:
- Use the existing setup (Vitest + Testing Library + jsdom) when adding tests.
- Location/patterns: `test/unit/**/*.(test).(ts|tsx|js)`; use `test/unit/utils/test-utils.tsx`’s `render` when a wrapper is needed.
- For new UI components, prioritize comprehensive Storybook stories; add focused unit tests where they provide real value (e.g., hooks, utils, logic-heavy parts).
- No strict coverage threshold yet; run `yarn test` locally to ensure the suite passes.

## Commit & Pull Request Guidelines
- Commit messages are the release notes. Follow this structure:
  - 1st line: ≤ 80 chars, past tense, start with one of: Fixed/Changed/Updated/Improved/Added/Removed/Reverted/Moved/Released/Bumped/Cleaned.
  - 2nd line: blank.
  - 3rd line: magic word + absolute issue URL (e.g., `ref https://linear.app/...` or `closes ...`).
  - 4th+: explain the “why”/context behind the change.
- Gotchas: don’t use `ref:` (colon) — magic word must be followed by a space; Linear requires full URLs.
 - Dependency bumps: focus the message on resulting user‑visible changes (no need to list which internal packages changed).
- PRs: describe changes, link issues, add screenshots/gifs for UI changes, and update/add stories.

## Storybook Documentation for New Components
Refer to “Adding New Components” for the process. Story content should:
- Include a short overview (what the component does and primary use case).
- Demonstrate key variants and states (sizes, disabled/loading, critical props).
- Be minimal but representative; prefer CVA variants/props over ad‑hoc class overrides.
 - Avoid obvious technical implementation details (e.g., which libraries are used). Prefer one‑line guidance per story explaining when to use that variant/size/state.

## Notes for Contributors (and Agents)
- Do not rename ShadCN-generated files purely for casing.
- Use the `@` alias for internal imports (e.g., `@/lib/utils`).
- When changing tokens/config, verify Storybook and a library build still succeed.
- When adding new components to Shade, always look for a ShadCN/UI equivalent and if it exists add it using `npx`.

## ShadCN Component Installation Guardrails
- Never overwrite existing Shade components during `npx shadcn@latest add <name>` prompts. Choose “No” when asked to overwrite.
- Always work on a fresh branch and commit a clean baseline before running the installer so you can easily revert: `git checkout -b chore/shadcn-add-<name>`.
- If a component already exists in `src/components/ui`, generate the new version in a temporary workspace (scratch repo), then manually diff and port only the desired changes into the existing Shade file.
- After integrating, run `yarn lint`, `yarn test`, and verify in Storybook before merging.