# Template overrides

A filesystem theme can replace any core view. This is the developer-level escape hatch that panel settings deliberately do not provide.

## How resolution works

When a view is rendered, the theme manager looks for the theme's override first and falls back to the core view when it is absent. A theme therefore overrides only what it cares about.

```
public/themes/{theme}/views/{name}.php   ← used when present
app/views/{name}.php                     ← fallback
```

See [Theme resolution](../07-internals/THEME-RESOLUTION.md).

## Overridable views

| View | Page |
|---|---|
| `home` | Home feed |
| `question` | Question detail |
| `ask` | Ask form |
| `topics` | Discussion listing |
| `topic` | Discussion detail |
| `taxonomy` | Category and tag pages |
| `search` | Search results |
| `contact` | Contact form |
| auth views | Sign-in, registration, recovery |
| account views | Profile and account settings |
| `layouts/app` | The page shell |
| header/footer partials | Shell fragments |

## The contract

An override receives the same variables the core view receives. If the core view is given `communityFeed`, `feedFilter`, `currentUser` and `widgetsHtml`, the override gets exactly those.

Do not assume a variable that the core view does not receive; a core change will break your theme silently. Read the core view before overriding it.

## Safety

- Path traversal cannot escape the theme directory. A view name is resolved inside the theme root, and nothing outside it can be loaded.
- A missing override falls back safely; it never emits a warning or a blank page.
- Overrides are PHP files installed over the filesystem, never uploaded through the browser.

## Practical guidance

- Override the smallest unit that achieves your goal. Overriding `layouts/app` to change one card means inheriting every future shell fix by hand.
- Prefer tokens and layout presets over an override when they can express the change. See [Appearance tokens](APPEARANCE-TOKENS.md).
- Escape every value you render. An override is application code and carries the same obligations.
- Use the URL helpers for every link. A theme that hard-codes `/admin` or a domain breaks on a subdirectory install.
