# Source comment policy

SLASHED source CSS and generated bundles are implementation artifacts, not the primary API documentation surface.

## Rule

Keep comments in `core/*.css`, `optional/*.css`, and generated `dist/*.css` limited to:

- concise file headers with the module path, layer, purpose, prefix/API surface, and load-scope facts when useful;
- short section/category separators that identify what the following block contains;
- tooling directives that are required for linters or processors;
- machine-readable metadata comments when a repository script still consumes them to generate documentation.

Do not keep long-form API notes, recipes, browser-history explanations, token catalogs, or consumer-facing examples in source CSS. Move that information to the documentation files under `docs/` instead.

## Documentation homes

Use these files for material removed from source comments:

| Subject | Documentation target |
| --- | --- |
| Architecture and layer decisions | `docs/architecture.md` |
| Token API and token behavior | `docs/tokens.md`, `docs/token-index.md`, `docs/llm-guide.md` |
| Classes and class taxonomy | `docs/classes.md`, `docs/layout.md`, `docs/macros.md` |
| Components | `docs/components.md` |
| States, motion, and theming | `docs/states.md`, `docs/motion.md`, `docs/theming.md` |
| Migration or compatibility notes | `docs/migration.md` |

When a CSS change affects public tokens or classes, update the relevant documentation and review `docs/llm-guide.md` as required by `CLAUDE.md`.