# Repository Guidelines

## Project Structure & Module Organization
`kokage-ui` is a Python package using a `src/` layout.

- `src/kokage_ui/`: library code (core FastAPI integration, HTML elements, DaisyUI components, CRUD, auth, storage, etc.).
- `tests/`: pytest suite, organized as `test_<feature>.py` (for example, `test_components.py`, `test_crud.py`).
- `examples/`: runnable FastAPI sample apps (`hello.py`, `todo.py`, `dashboard.py`).
- `docs/`: MkDocs source content (`guide/`, `examples/`, `api/`).
- `site/`: generated documentation output; do not edit by hand.
- `pyproject.toml`: dependencies, build backend, Ruff, and pytest configuration.

## Build, Test, and Development Commands
- `uv sync --extra dev --extra docs`: install project + development/doc tooling.
- `uv run pytest`: run the full test suite.
- `uv run pytest tests/test_components.py -k Card`: run a targeted subset while iterating.
- `uv run ruff check .`: lint and static style checks.
- `uv run ruff format .`: auto-format Python code.
- `uv run uvicorn examples.hello:app --reload`: run a local example app.
- `uv run mkdocs serve`: preview docs locally.
- `uv build`: build distribution artifacts via Hatchling.

## Coding Style & Naming Conventions
- Follow Python 3.11+ conventions with explicit type hints on public APIs.
- Use 4-space indentation and keep lines within Ruff’s configured `line-length = 120`.
- Naming: `snake_case` for modules/functions/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants.
- Keep component constructors readable and keyword-driven when many optional args exist.
- Keep changes focused; avoid unrelated refactors in feature/fix PRs.

## Testing Guidelines
- Testing stack: `pytest` + `pytest-asyncio` (`asyncio_mode = auto`).
- Add or update tests for every behavior change, especially HTML rendering and FastAPI route integration.
- Prefer descriptive test names like `test_card_with_actions` and mirror module scope in test files.
- No enforced coverage percentage is configured; contributors are expected to provide regression tests for modified behavior.

## Commit & Pull Request Guidelines
- Match existing history style: short, imperative, lower-case commit subjects (for example, `add admin page generation`, `theme switch`).
- Keep one logical change per commit and keep the subject concise (about 72 chars or less).
- PRs should include: change summary, why it is needed, tests run, and any docs/example updates for user-facing changes.
- Include screenshots or rendered HTML snippets when UI output changes, and link related issues when applicable.
