v1.8-module-brief-template

Module Brief Template

Define reusable app parts before building them.

Why this exists

SiteFactory is a reusable local library of app components, modules, miniapps, templates and interface building blocks.

The module brief helps ensure every new reusable part has a clear purpose, reuse case, state model, preview path and build check before work starts.

Module identity

Define the name, type and reason for the reusable part.

MODULE_NAME

Use lowercase kebab-case for files, folders and preview paths.

MODULE_TYPE

Examples: component, module, miniapp, template, workspace, panel, view.

MODULE_PURPOSE

State the specific job this reusable part should do.

REUSE_CASE

Describe where this should be copied or adapted later.

STATUS

Use shared status words such as draft, prototype, preview, working, live, archived or blocked.

Usage definition

Define the actual reuse boundary before building.

USE_WHEN

List the situations where this reusable part is a good fit.

DO_NOT_USE_WHEN

Name the cases where this part would create the wrong abstraction.

INPUTS

List required content, data, settings or user input.

OUTPUTS

List what the module shows, stores, emits or creates.

USER_ACTIONS

List expected clicks, typing, toggles, uploads or review actions.

STATE_NEEDS

State whether the part is static, localStorage-based, server-backed or not yet decided.

Technical shape

Prefer plain HTML, CSS and vanilla JavaScript first. Avoid dependencies and backend services unless the brief proves they are needed.

FILES_REQUIRED

List the minimum HTML, CSS and optional JavaScript files.

HTML_STRUCTURE

Use semantic HTML with clear section comments and stable ids.

CSS_REQUIREMENTS

Use clear class names from NAMING.md and keep styles portable.

JS_REQUIREMENTS

Use vanilla JavaScript only when behavior is required.

DATA_STORAGE

Document static data, localStorage keys, file inputs or future storage needs.

DEPENDENCIES

Default to none. Add one only when it clearly reduces real complexity.

Preview definition

Keep canonical source and browser preview copy separate.

CANONICAL_SOURCE_PATH

Canonical source belongs in /templates or /projects.

PREVIEW_COPY_PATH

Preview copy belongs under projects/sitefactory-test/public/template-previews or project-previews.

PREVIEW_URL

Use a browser URL that works locally and on Cloudflare.

BUILD_CHECK

Run npm run build in projects/sitefactory-test and confirm preview output is included.

Preview folders must follow the Preview Access Rule: include index.html, use relative CSS and JavaScript links, work locally, and appear in build output.

Reuse rules

Use this checklist before building a reusable part.

  • small enough to copy
  • clear names
  • no hidden dependencies
  • no hardcoded machine paths
  • works outside Astro
  • documented state behavior
  • registry update planned

Done criteria

Define what completion means before implementation starts.

WHAT_COUNTS_AS_DONE

List the concrete state where the part is usable.

WHAT_COUNTS_AS_NOT_DONE

List missing work that should block calling it complete.

KNOWN_LIMITATIONS

Name the limits of the current version.

NEXT_VERSION_IDEA

Capture possible future improvements without adding them now.

Copy-friendly module brief

Copy this block before creating a new reusable module, miniapp or template.

MODULE_NAME:
MODULE_TYPE:
MODULE_PURPOSE:
REUSE_CASE:
USE_WHEN:
DO_NOT_USE_WHEN:
INPUTS:
OUTPUTS:
USER_ACTIONS:
STATE_NEEDS:
FILES_REQUIRED:
DATA_STORAGE:
CANONICAL_SOURCE_PATH:
PREVIEW_COPY_PATH:
PREVIEW_URL:
DEPENDENCIES:
DONE_CRITERIA:

Example brief

A small example for a reusable review panel.

MODULE_NAME:
review-panel

MODULE_TYPE:
module

MODULE_PURPOSE:
A reusable panel for reviewing whether a project, template or miniapp is ready to move forward.

REUSE_CASE:
Use inside dashboards, project workspaces, template reviews and agent-readable docs.

STATE_NEEDS:
Static in v0.1. Could become interactive later.

FILES_REQUIRED:
review-panel.html
review-panel.css

Common mistakes

These mistakes make the library harder to reuse and maintain.

  • building a module without a reuse case
  • mixing component/module/miniapp naming
  • adding JavaScript before needed
  • storing canonical source only in public preview
  • forgetting registry update
  • forgetting build check
  • making modules too specific too early