# UX Notes — defapp

Last updated: 2026-07-22

## Documentation viewer UX

The main documentation entrypoint is `defapp.docs.php`, located at the defapp
app root next to the `docs/` folder.

### Layout

- Index view:
  - Displays one card per known doc from the `$docManifest` array.
  - Each card shows:
    - Title
    - File path (e.g., `docs/SPEC.md`)
    - Purpose
    - “Use when” guidance
    - Status badge: present, stub, or not generated yet.
- Detail view:
  - Shows the selected doc’s title and purpose.
  - Renders the Markdown content using `renderMarkdownLite()` into HTML.
  - Provides a “Back to index” link for navigation.

### Status badges

Doc status is computed from the actual file on disk:

- present — file exists and is not a stub.
- stub — file exists and contains “Stub for”.
- not generated yet — file does not exist; user should run `newapp.sh init-defapp`.

Badges are rendered consistently using `statusBadge()` so we don’t duplicate
badge markup in the UI.

### Purpose and “Use when”

Every doc in `$docManifest` requires:

- `purpose` — concise sentence describing what the doc is for.
- `useWhen` — short guidance on when to read or update it.

These fields are UX content, not just metadata. They are written for humans and
should be updated whenever a doc’s role changes.

## Wizards concept

A wizard in defapp means a guided multi-step flow that helps users complete a
goal without dumping everything at once.

### Wizard principles

- One wizard = one goal.
- Each step is small, explicit, and testable.
- Wizards display what they are doing, which files they touch, and how to verify
  success.
- Wizards favour clear, incremental progress over complex one-shot commands.

### Wizard examples (future)

- `init-defapp` wizard:
  - Step-by-step initialization of a new defapp instance.
  - Generates core docs and verifies they exist.
- “Create new doc” wizard:
  - Adds a new entry to `$docManifest`.
  - Generates a stub Markdown file.
  - Reminds the user to define `purpose` and `useWhen`.

All wizards should log their actions in `PROJECT_LOG.md` and, when behaviour
changes, in `CHANGELOG.md`.