← Development guidelines

Code · Architecture · UX

Project design guide template

Download editable Markdown

Template edition: 3.2.0

Revised: 2026-10-25

Guideline content by Lucas Vitti, licensed under CC BY 4.0. See scope and attribution.

Use this template to document how a project works, why it is structured that way, and what each page or form is for. Keep it in the project's dedicated documentation folder, normally docs/project-design.md, and adapt it to real evidence. Replace placeholders; mark unknowns and proposed choices explicitly. The examples are illustrative and do not describe an audited application's implementation. Use the separate change plan template for approval before implementation and the version journal template for each release's full technical outcome, paired with the separate user changelog template for practical user effects.

Project scope and ownership

Architecture and data flow

Describe the system boundary, its users, and external systems. Then identify the applications, workers, and data stores inside the boundary. Link an editable diagram if it improves understanding; label responsibilities and relationships and explain the diagram in text. Add component detail where necessary, rather than generating every C4 level automatically.

Code structure and implementation choices

Repeat a short record for each significant feature/module. Link to real source locations and symbols; do not copy entire files into the guide.

Use the existing project's vocabulary. A short coherent implementation does not need extra layers solely to fill this section. Keep function-level invariants beside the code; explain broader design rationale here.

Internal parameter register

Follow DOC-09. Keep this section as the canonical register for a small project or link docs/parameters.md from here and from each change plan. Record internal policy and behavior values, including unnamed literals and configuration fallbacks, in terms the project owner can understand. Reuse authoritative configuration, schema, and design-token references instead of maintaining competing lists.

Do not copy credentials or secret values. Cover all planned parameters in a new project; in existing work, declare the actual coverage and staged legacy backlog. A code search alone does not establish completeness. Parameter documentation is a product decision aid; it does not automatically require an administration screen, environment variable, or higher limit.

Example upload limit record

Fictional example only; these values, paths, and outcomes are not verified facts about an existing application.

Modularity plan and review

Apply ARCH-07 through ARCH-13 within the approved change plan and update this current-state record at completion. In an audit, record the observed structure, violations, and proposed boundaries without changing application code.

Working architecture baseline

Keep this proportional to the application. A small script does not need web layers, and an empty directory tree is not a working baseline.

UX structure and shared conventions

Describe the main user journeys, navigation and resource scope, shared components and tokens, content conventions, and accessibility behavior. Record how forms, lists, dialogs, errors, pending work, and unsaved changes behave consistently. Link the shared specifications from individual page records and state exceptions locally.

For each chosen UX pattern, record the problem it solves, applicable UX/VIS rule IDs, implementation choice, tradeoff, and how the result was checked. Avoid unexplained claims such as "modern design" or "Gestalt compliant."

Page and form inventory

List each route or native screen ID and each independently actionable form, including dialogs and drawers. Give each a stable record ID and a link to its details. Reused forms can share a record with all entry points listed. Index labels must say what the user accomplishes, not just name a database entity.

Keep the inventory current as screens are added, removed, or repurposed. For existing projects, identify uncovered screens explicitly rather than implying full coverage.

Page or form record

Repeat this record for each inventory entry. Combine short fields or link shared specifications to keep records readable; use "not applicable" with a reason where appropriate.

Example client consultation page

Illustrative proposed design, not a claim about existing code or verified user behavior.

Example client registration form

Illustrative child record for the preceding example.

Significant decision record

Use one short record for a consequential architecture, code, security, or UX choice. Use separate files when useful; otherwise stable headings in the guide are sufficient. Adapted from architecture decision records, extended here to UX and implementation choices.

An accepted decision and an implemented result are different statuses. Keep implementation evidence in the linked guide/page record. Do not invent approval or retroactively claim an undocumented choice was deliberate.

Maintenance and review

Before implementation, provide the architecture and UX change plan and obtain explicit approval for its revision and scope under DOC-07. Record existing approval when it already covers the work; obtain renewed approval for material departures. As part of the same change, reconcile the current design guide with implementation, update links and examples, and finish both changelogs, checking that version, dates, audience, and availability agree. Preserve the approved plan and decision history; remove or mark obsolete current-state instructions. Before deployment, present the outcome and evidence and confirm authorization covers the release and target. Have a reader follow setup or task instructions with safe local data when relevant.

Use Diátaxis to distinguish procedural guidance from factual reference and design explanations. Create a tutorial only when there is a learning need. Publish generic patterns freely when authorized, but keep credentials, real personal data, exploitable findings, and private infrastructure details out of public documentation. Audit-only sessions record proposed corrections in their report and do not edit the project.

References: Diátaxis, C4, and architecture decision records.