## Contributor

- Yura (for Base airdrop participation)

### Navigation policy

> Note: We generally do not change the global navigation (top-level tabs) or sidebar sections unless there is a clear, broadly beneficial need. Contributions should focus on improving existing pages and adding new pages within current sections.

### Section purpose and placement

- **Quickstart**: End-to-end setup to first success. Keep concise and current.
- **Concepts**: Explanations of components, architecture, and design philosophy.
- **Guides**: Step-by-step, action-oriented tutorials for specific tasks.
- **Examples**: Complete, runnable examples demonstrating real-world usage.
- **Technical Reference**: API/method/component specs with parameters and return types.
- **Contribute**: Information for contributors and process updates.

#### Cookbook scope

- The `cookbook/` section hosts use case-focused guides and patterns, not product-specific documentation.
- Prefer cross-cutting solutions that illustrate how to build on Base across tools and scenarios.

> Warning: Avoid subsection proliferation:
> - Put all guides at the same level within the Guides section.
> - Organize Reference by component/feature, not per use case.
> - Use cross-links instead of adding new structural layers.

## Style and formatting

### Writing style

1. Be concise and consistent; use active voice and second person.
2. Focus on the happy path; mention alternatives briefly where relevant.
3. Use explicit, descriptive headings and filenames.
4. Maintain consistent terminology; introduce abbreviations on first use.

### AI-friendly content

- Use clear, explicit language and link related pages directly.
- Prefer bulleted lists for options/steps when not sequential.
- Name and reference libraries and tools explicitly.
- Use semantic, readable URLs and avoid ambiguous abbreviations.

> Checklist:
> - Would a Large Language Model understand and follow this content?
> - Can an engineer copy, paste, and run the examples as-is?

### Mintlify formatting

- Start main sections with H2 (`##`) and subsections with H3 (`###`).
- Use fenced code blocks with language and optional filename.
- Wrap images in `<Frame>` and include `alt` text.
- Use callouts for emphasis: `<Note>`, `<Tip>`, `<Warning>`, `<Info>`, `<Check>`.
- For procedures, prefer `<Steps>` / `<Step>`.
- For alternatives, use `<Tabs>` / `<Tab>`.
- For API docs, use `<ParamField>`, `<ResponseField>`, and request/response examples.

### Code examples

- Provide complete, runnable examples with realistic data.
- Include proper error handling and edge cases.
- Specify language and filename when helpful.
- Show expected output or verification steps.

## Third-party guides policy

> Warning: We generally do not accept guides that primarily document a third-party product. Exceptions require a clear Base-focused use case and a tight integration with Base products. Simply deploying on Base or connecting to Base Account/Base App is not sufficient.

If your goal is to increase discoverability of your product, please request inclusion on the Base Ecosystem page instead. See the instructions for [updating the Base Ecosystem page](https://github.com/base/web?tab=readme-ov-file#updating-the-base-ecosystem-page).

## Review checklist (before submitting a PR)

- [ ] Fits within existing structure (no new top-level sections)
- [ ] Minimal, necessary subsections only
- [ ] Consistent terminology; abbreviations introduced on first use
- [ ] Code examples are complete, runnable, and validated
- [ ] Cross-links to related guides/examples/references are included
- [ ] Uses Mintlify components and heading hierarchy correctly
- [ ] Accessible images with descriptive `alt` text and frames
- [ ] AI-friendly: explicit, link-rich, and easy to follow

## Submission process

1. Create a PR to `https://github.com/base/docs` with your changes.
2. Include a clear description of the change and impacted pages.
3. Request review from the docs team.
4. Address feedback and iterate.
5. Once approved, changes will be merged and published.

## Publishing changes

The core team will review opened PRs. The SLA is 2 weeks, generally on a first-come, first-served basis outside of urgent changes. 

## Storybook for UI components

See `storybook/README.md` for details on local Storybook and component docs.