Lucas Vitti / Engineering referenceUse in an AI session

How to use this standard

Apply the relevant rules to new work and the areas you change. Assess existing debt separately; this document does not authorize a wholesale rewrite. Choose the smallest design that makes the behavior clear, correct, and verifiable.

  • MUST marks an applicable baseline requirement. A conflicting project requirement needs an explicit resolution, not a silent exception.
  • SHOULD marks the usual choice. Record a reason when a material departure improves the project.
  • MAY marks an optional technique. A listed pattern is not permission to add an unrequested feature.
  • Scope comes first. Follow the current task and applicable repository instructions. These house rules do not override higher-priority platform instructions or explicit user decisions. Resolve material conflicts before the affected action; continue independent authorized work.
  • Read-only means read-only. In an audit, collect evidence and recommendations. Do not edit application code, install packages, run migrations, restart services, or deploy. Local reports and isolated checks may be appropriate within the authorized scope.
  • Publication is separate. This standard does not grant permission to publish, change production, manage accounts, or send messages. Use authorization already provided by the user; do not add approval steps for routine work already authorized.
  • Document first. For development work, provide a saved architecture and UX change plan and obtain explicit approval for its identified scope before implementation. Deploy only with authorization covering the release and target. An existing approval covering the same plan and release remains valid; silence and an AI's own decision are not approval. Follow DOC-07 and keep both changelogs required by DOC-08.

For a reproducible task, use a versioned edition, read the full applicable sections, and state the version used. A link alone does not load its contents into an AI session. If access is unavailable, request a local copy rather than claiming to have read it.

Each numbered rule has six concrete examples: three DOs and three DON'Ts. Examples illustrate the rule within the stated context; they do not create features or requirements outside the authorized task. The web page reveals examples on request, while the downloadable Markdown includes them in full.

Architecture and modularization

  • ARCH-01 · Give each responsibility a home. MUST. Organize around recognizable product features. Keep entry-point wiring, interaction handling, business rules, storage, and external integrations distinguishable. A route, window, or component should not become the entire application.
    Examples for ARCH-01 · 3 DOs and 3 DON'Ts

    DO

    • Keep invoice calculations in a billing module and HTTP parsing in the route.
    • Put customer lookup, editing, and validation in a recognizable customer feature.
    • Let the application entry point assemble dependencies and start the service.

    DON’T

    • Add exports, authentication, scheduling, and rendering to one growing server file.
    • Let a window's click handler implement database access and tax policy.
    • Organize every feature into anonymous helper files with no clear responsibility.
  • ARCH-02 · Make boundaries real. MUST. Define inputs, outputs, dependencies, state ownership, and side effects. Moving pieces of one giant function into separate files or partial classes does not by itself reduce coupling.
    Examples for ARCH-02 · 3 DOs and 3 DON'Ts

    DO

    • Pass an explicit order and pricing policy into the quote operation.
    • Define whether a storage adapter returns missing, failed, or found results.
    • Give a queue module ownership of its jobs and cancellation behavior.

    DON’T

    • Split one function across files that still mutate the same global variables.
    • Have a repository read the selected UI row from a global component.
    • Require callers to know which undocumented initialization sequence makes a module work.
  • ARCH-03 · Prefer useful simplicity. SHOULD. Extract a module for a cohesive rule, repeated policy, external dependency, lifecycle, or test boundary. Avoid speculative frameworks, generic utilities that collect unrelated code, and mandatory layers around trivial operations. Microservices are not a default solution to a large file.
    Examples for ARCH-03 · 3 DOs and 3 DON'Ts

    DO

    • Extract a payment-provider adapter when provider failures need independent handling.
    • Keep a small pure formatter as a function when no class lifecycle is needed.
    • Separate a cohesive import operation when it needs focused verification.

    DON’T

    • Create six forwarding layers around a single configuration lookup.
    • Introduce microservices solely because an application file has become long.
    • Build a universal workflow engine for one known business operation.
  • ARCH-04 · Keep shared policy consistent. MUST. Centralize genuinely shared authorization, validation, configuration, and external-client behavior. Keep intentionally different business policies distinct. Do not force superficially similar workflows into one abstraction.
    Examples for ARCH-04 · 3 DOs and 3 DON'Ts

    DO

    • Reuse the same ownership check for download and export endpoints.
    • Centralize environment parsing so workers and the web service agree.
    • Keep retail and wholesale discount policies separate when their rules differ.

    DON’T

    • Copy authorization checks into routes and let their conditions drift.
    • Merge unrelated approval policies just because both contain a status field.
    • Configure retry behavior independently in every call to the same provider.
  • ARCH-05 · Own state and lifecycle explicitly. MUST. Identify request, session, process, persisted, and disposable state. Keep imports free of unexpected startup work. Define who creates and disposes of processes, streams, timers, locks, connections, and temporary files.
    Examples for ARCH-05 · 3 DOs and 3 DON'Ts

    DO

    • Cancel a screen's pending request when that screen is disposed.
    • Open a database pool at service startup and close it at shutdown.
    • Associate a draft with its user and resource instead of a shared process variable.

    DON’T

    • Start background jobs merely by importing a utility module.
    • Keep every user's mutable selection in one server-wide singleton.
    • Create timers or temporary files without defining who cleans them up.
  • ARCH-06 · Refactor incrementally. MUST. Protect important behavior before extraction. Move one complete feature at a time, preserve its contract, and verify it. A behavior change, migration, or dependency upgrade must be identified separately from structural cleanup.
    Examples for ARCH-06 · 3 DOs and 3 DON'Ts

    DO

    • Capture current invoice totals before extracting the calculation module.
    • Move one complete feature and verify its existing external contract.
    • Describe a necessary data migration separately from file reorganization.

    DON’T

    • Rename API fields during a supposedly behavior-preserving extraction.
    • Reorganize all features at once without a way to isolate regressions.
    • Upgrade the framework and alter permissions inside an undocumented cleanup.

A useful dependency direction is interaction → application operation → domain rule or storage/integration boundary. Use the language and framework's idioms; do not create empty layers to reproduce a diagram. File length is a review signal, not proof of good or bad design. ARCH-09 makes acting on that signal mandatory.

Modularization and code splitting

Human-maintained source must stay understandable in parts. A maintainer should be able to find a feature, explain a file's responsibility, and change a business rule without reading the entire application. Apply ARCH-07 through ARCH-10 to implementation work; audits record violations and recommendations without changing code.

  • ARCH-07 · Split source by responsibility. MUST. Do not deliver a multi-feature application as one handwritten file or keep adding unrelated responsibilities to an existing file. Give each source file one cohesive purpose. Keep application startup and page composition thin; extract substantial interaction handling, business policies, storage access, and integrations into named modules when they have separate reasons to change. Split large UI screens into meaningful components and operations. Co-located markup, styles, and behavior for one cohesive component are valid framework conventions. Use real imports/interfaces rather than numbered file fragments, concatenated scripts, or shared mutable globals. A generated deployment bundle may be one file; its maintained source must remain modular. Small single-purpose scripts may stay in one file.
    Examples for ARCH-07 · 3 DOs and 3 DON'Ts

    DO

    • Keep app.ts responsible for wiring and move invoice calculations, persistence, and screen behavior into their appropriate modules.
    • Split a growing Clients screen into a list component, a form component, and focused application operations when their responsibilities diverge.
    • Maintain readable source modules even when the build emits one minified JavaScript bundle.

    DON’T

    • Append billing, user administration, background jobs, and HTML generation to a single server.js file.
    • Replace a giant file with part1.js and part2.js that still depend on the same undocumented global state.
    • Treat comment banners or collapsed editor regions as a substitute for module boundaries.
  • ARCH-08 · Decide module boundaries before growing a feature. MUST. Before implementing a new feature or materially expanding one, record a boundary contract in its approved plan: affected files/modules, responsibility, public operations and result/failure shapes, state and data owner, side effects, allowed dependencies, and explicitly prohibited dependencies. Identify who may write owned data and how other features request changes through public operations. Reuse a suitable existing home; create a module for a distinct responsibility and export only what callers need. Keep domain policy independent of UI/transport details and prevent new dependency cycles or cross-feature access to private internals. Review wide callback lists, dependency bags, shared mutable state, and access to another feature's storage; explicit injection alone does not establish a sound boundary. Do not create a file for every small function, empty forwarding layers, or a new service merely to increase the file count. Reconcile the source map with the final implementation without silently rewriting the approved plan.
    Examples for ARCH-08 · 3 DOs and 3 DON'Ts

    DO

    • In the approved import plan, identify parsing, validation, and persistence responsibilities, public operations, failure shapes, and the owner of imported records.
    • Record that pricing accepts order data and returns a quote; explicitly prohibit UI imports and direct writes to another feature's tables.
    • Give a customer feature only the search and registration capabilities it needs, keeping related internal helpers private.

    DON’T

    • Start a new feature by adding it to whichever existing file is easiest to open, without checking that file's responsibility.
    • Inject hundreds of unrelated callbacks through one context object and claim the shared application knowledge has been removed.
    • Have billing and customer modules import each other's private mutable state, creating a dependency cycle.
  • ARCH-09 · Resolve oversized files and functions. MUST. Review every new or changed handwritten source file exceeding 300 nonblank, non-comment-only lines and every function or method exceeding 50 such lines. Count the entire touched file/function, not just added lines, with the project's language-aware tool and documented counting convention. Before marking the work complete, either extract cohesive responsibilities or record a scoped exception under the audit/exception format: exact file/symbol, measured size, why it remains cohesive, alternatives considered, owner, and a concrete revisit trigger. These are house review thresholds, not universal quality limits. Mixed responsibilities still require correction below the thresholds. Existing larger files touched for a narrow fix may receive a documented deferred-extraction exception; do not expand the task into an unrelated rewrite. Generated/vendor files, lockfiles, and data-only fixtures are excluded from numerical checks; list exclusions and keep authored generators and executable logic in scope. Never compress statements, remove useful comments, or mislabel authored code as generated to evade review. Different project thresholds require an explicit documented project decision under the normal conflict/exception rules.
    Examples for ARCH-09 · 3 DOs and 3 DON'Ts

    DO

    • Review a touched 430-line controller and extract its distinct export workflow before declaring the feature complete.
    • For a cohesive 62-line parser, record its measured size, why splitting harms clarity, alternatives, owner, and the change that will trigger another review.
    • For a narrow fix in a legacy 1,600-line file, record the full file size and a scoped deferred-extraction exception instead of claiming the new 12 lines make it compliant.

    DON’T

    • Ignore a 2,000-line module because this change adds only five lines.
    • Compress statements onto fewer lines or remove explanatory comments to pass a size check.
    • Approve a 200-line file containing authentication, tax calculation, UI rendering, and unrelated scheduled jobs merely because it is below 300 lines.
  • ARCH-10 · Make modularity a completion check. MUST. Use the existing check workflow for size review and executable dependency restrictions where supported: prohibited imports, private cross-feature access, and cycles. Document the scope, command, and narrow exceptions; verify the boundary checker detects a known prohibited dependency in an isolated fixture or equivalent safe check. A warning alone is not a completed review. If suitable automation is unavailable, record the manual inventory, limitations, owner, and revisit trigger. Inspect runtime coupling, hidden shared state, wide dependency lists, and cohesion as well; passing import and line-count checks does not establish these. For each new or materially changed boundary, demonstrate a relevant change scenario or test substitute that isolates an implementation detail without changes to unrelated features. Also verify affected behavior, contracts, and failure paths; substitutes do not prove a real integration works. Report the resulting source map, size dispositions, checks, and unresolved findings. Unresolved applicable requirements prevent completion unless explicitly resolved under the exception policy. In an audit, report findings and acceptance criteria without making fixes.
    Examples for ARCH-10 · 3 DOs and 3 DON'Ts

    DO

    • Run size and dependency checks, confirm an isolated forbidden-import fixture fails, and link the resolved size exceptions in the handover.
    • Test invoice behavior using a controlled storage substitute, then verify the real adapter's contract separately, including failures.
    • When suitable automation is unavailable, document the manual dependency inventory, shared-state review, limitations, responsible owner, and revisit trigger.

    DON’T

    • Call the work complete while unresolved oversized-source warnings remain unexplained.
    • Disable dependency checks across the repository or exclude all dynamic imports without disclosing the gap.
    • Claim isolated architecture because imports are acyclic while features still share mutable global state and require changes across the application.

Example of a source layout for a client feature with distinct UI, policy, and persistence responsibilities. Adapt the names and boundaries to the actual stack; do not create empty files to reproduce this tree.

src/
  app.ts                         application wiring
  features/clients/
    ClientList.tsx               consultation UI and composition
    ClientForm.tsx               registration and edit interaction
    client-policy.ts            business rules and validation policy
    client-repository.ts        persistence boundary on the server
    client-routes.ts            HTTP and authorization boundary on the server

This tree describes logical source locations across the relevant application packages; server modules must not enter the browser bundle. In a smaller feature, fewer files can express the same boundaries. A single app.js containing all screens, SQL, authorization, export logic, and timers fails ARCH-07 even if comment banners divide it into sections. Renaming it to part1.js, part2.js, and part3.js while sharing the same globals also fails.

For JavaScript/TypeScript projects already using ESLint, these rule settings illustrate the numerical review gate. Merge them into the existing configuration, parser, source scope, and exception process; this is not a complete configuration or a requirement to install ESLint in every stack. Apply the gate to touched source during staged adoption while recording existing debt.

rules: {
  "max-lines": ["error", {
    max: 300, skipBlankLines: true, skipComments: true
  }],
  "max-lines-per-function": ["error", {
    max: 50, skipBlankLines: true, skipComments: true
  }]
}

The defaults above are house choices. ESLint documents configurable file-size checks and function-size checks; neither proves architectural quality. See the TypeScript module guide for language-level imports and exports. Source modularization and runtime bundle splitting solve different problems: use lazy loading when delivery/performance needs justify it, and do not treat extra downloaded chunks as evidence of readable source.

Architecture baselines and reusable starters

Start with the smallest structure that expresses the real responsibilities. For a small multi-feature application, one deployable application with cohesive feature modules is a useful default. Logical boundaries do not require separate services, a particular framework, or one universal folder tree. A starter supplies examples and checks; each project still needs its own approved architecture and UX plan.

  • ARCH-11 · Demonstrate the baseline with a working feature. MUST. Before expanding a new application, document its architecture baseline in the approved plan and implement one small representative feature through its real interaction, application behavior, required persistence/integration, and failure feedback. Include relevant tests, setup instructions, and links from the source map so later work has an executable example to follow. Identify which boundaries, lifecycle owners, and UX choices it demonstrates and which risks remain unproven. Keep the baseline proportional: a small script may need only its input, operation, and output. For an existing application, map the current structure and select an existing representative feature; improve it incrementally within approved scope. Empty folders, diagrams, and a passing health endpoint alone do not demonstrate a multi-feature application's boundaries.
    Examples for ARCH-11 · 3 DOs and 3 DON'Ts

    DO

    • For a new client app, demonstrate one approved registration flow through the form, authorization, business operation, storage, and visible failure handling.
    • In an existing application, document a working import feature as the reference and improve its boundaries in a scoped, behavior-preserving change.
    • For a small command-line tool, demonstrate its input validation, operation, output, and failure exit without adding unused web layers.

    DON’T

    • Create empty domain, services, and adapters folders and declare the architecture established.
    • Treat a health endpoint as proof that authorization, persistence, and user workflows are correctly separated.
    • Rewrite every existing feature to match a new starter before verifying one representative path.
  • ARCH-12 · Keep external details behind narrow contracts. MUST. Where an external dependency needs independent testing, failure handling, or expected replacement, define an application-facing contract for the required capability and keep provider, database, filesystem, framework, or SDK details in the implementing adapter. Translate external data and errors at that boundary; make unsupported capabilities and behavioral differences explicit. Assemble implementations at a clear composition point and supply only the operations each consumer needs. Preserve authoritative authorization, transaction integrity, cancellation, and resource ownership across the boundary. Verify the application with controlled substitutes and the real adapter with suitable integration or contract checks. Record why simpler direct use is sufficient where no meaningful boundary is needed; do not wrap every function, invent a second production provider, or promise that different technologies are interchangeable without evidence.
    Examples for ARCH-12 · 3 DOs and 3 DON'Ts

    DO

    • Let a report operation depend on a narrow document-store contract while a file adapter handles paths, serialization, and filesystem errors.
    • Supply a model-generation capability at startup, translate provider errors in its adapter, and explicitly report an unsupported streaming mode.
    • Test payment policy with a controlled provider substitute and check the real adapter in a safe integration environment before claiming compatibility.

    DON’T

    • Pass an HTTP request, database SDK client, and browser selection into a reusable pricing rule.
    • Wrap every pure formatter in a factory, interface, registry, and adapter despite having no separate responsibility to isolate.
    • Hide failed writes or lost transaction guarantees behind an adapter that always returns success.
  • ARCH-13 · Version reusable starters deliberately. SHOULD. When a working structure is worth reusing, maintain a minimal, stack-appropriate starter containing a representative feature, boundary checks, safe configuration examples, documentation, and necessary run/test commands. Version it independently from applications and record its source/version and chosen options in each adopting project. Distinguish generated files from project-owned code. Validate generation with disposable fixtures; when updating a starter, review the resulting changes and migrations without overwriting application work. Add a generator only when recurring work justifies it. A template is not permission to add unused services, deployment infrastructure, patterns, or dependencies.
    Examples for ARCH-13 · 3 DOs and 3 DON'Ts

    DO

    • Publish a small starter with a working feature, safe fixtures, dependency checks, and documented setup, then record starter version 1.2.0 in an adopting project.
    • Generate a disposable sample to check the starter and review an upgrade diff before applying it to project-owned modules.
    • Keep a documented reference example until repeated, stable setup work justifies a generator.

    DON’T

    • Copy the newest starter over an existing application and overwrite its feature code or approved architecture choices.
    • Include a queue, container cluster, model provider, and background worker in every project whether they are needed or not.
    • Change a published starter without a new version and leave adopting projects unable to identify their baseline.

An illustrative boundary contract for client registration names registerClient(actor, input) as the public operation, the client feature as the owner of registration rules and writes, and a storage contract as its permitted persistence dependency. It prohibits importing DOM controls or another feature's private database implementation. Startup supplies the chosen adapter. Verification covers valid registration, denied access, duplicates, and persistence failure. The same contract belongs in the project design guide and is referenced from the change plan rather than copied into competing documents.

Ports and adapters can isolate application behavior from external technology but add maintenance costs. Dependency injection separates assembly from use; it does not make an oversized dependency list cohesive. Tools such as dependency-cruiser can enforce declared JavaScript/TypeScript import restrictions. Use stack-appropriate mechanisms and verify their actual coverage, including aliases, re-exports, or dynamic loading where relevant.

Readability, naming, and comments

  • READ-01 · Write for the next reader. MUST. Use meaningful domain names and consistent terminology. Short indices are fine in small loops; product concepts should not require decoding abbreviations. Follow language conventions and avoid compressing independent operations onto one line.
    Examples for READ-01 · 3 DOs and 3 DON'Ts

    DO

    • Name a value outstandingBalance when it represents unpaid money.
    • Use the same term subscription across the UI, domain model, and documentation.
    • Place validation, transformation, and persistence on separate readable statements.

    DON’T

    • Name unrelated domain objects data1, obj2, and tmpFinal.
    • Call one concept customer in one module and subscriber elsewhere without a distinction.
    • Compress a payment workflow into a chain of side-effecting expressions.
  • READ-02 · Make names truthful. MUST. A mock must not secretly contact production. A read operation must not silently migrate data. Distinguish live providers, demo fixtures, previews, saved results, and published artifacts in names and behavior.
    Examples for READ-02 · 3 DOs and 3 DON'Ts

    DO

    • Make DemoCustomerProvider return synthetic records without network access.
    • Call a function saveAndPublish when it performs both actions.
    • Name a generated preview distinctly from the published document.

    DON’T

    • Let MockProvider silently use real credentials when fixtures are missing.
    • Have getSettings write defaults into production storage without disclosure.
    • Label cached results live when they have not been refreshed.
  • READ-03 · Keep control flow legible. SHOULD. Use guard clauses where they clarify the main path. Break long expressions and mixed-language templates into understandable units. Prefer ordinary composition over clever indirection.
    Examples for READ-03 · 3 DOs and 3 DON'Ts

    DO

    • Return early for an invalid request before the main processing path.
    • Name an intermediate condition when a long expression obscures its meaning.
    • Move a substantial HTML template out of a business calculation.

    DON’T

    • Nest success logic six conditions deep when early exits would clarify it.
    • Use nested ternaries to combine authorization, pricing, and error selection.
    • Hide ordinary branching behind a custom metaprogramming mechanism.
  • READ-04 · Explain reasons beside the code. SHOULD. Comments explain constraints, invariants, compatibility, or deliberate failure policies. Use short adjacent comments when possible. Keep a longer docstring or block when a public contract or algorithm genuinely requires it.
    Examples for READ-04 · 3 DOs and 3 DON'Ts

    DO

    • Explain that a retry preserves the first assignment to prevent duplicate allocation.
    • Document why a legacy date format remains necessary for a partner contract.
    • Use a fuller docstring when an algorithm's assumptions are essential to safe use.

    DON’T

    • Write increment counter above an obvious counter increment.
    • Add decorative comment banners before every small helper.
    • Remove an important invariant explanation merely to make comments shorter.
  • READ-05 · Keep comments accurate. MUST. Update comments with behavior. Remove obsolete instructions, decorative banners, obvious narration, and debugging stories. Move extended rationale to a short design note. Do not impose a comment-per-function quota.
    Examples for READ-05 · 3 DOs and 3 DON'Ts

    DO

    • Update the timeout comment when changing the actual timeout policy.
    • Move a lengthy architectural debate into a linked decision record.
    • Delete an obsolete workaround note after its underlying workaround is removed.

    DON’T

    • Leave a comment claiming offline behavior above a network request.
    • Keep a chat transcript describing failed debugging attempts inside a function.
    • Generate identical boilerplate comments just to meet a comment quota.
  • READ-06 · Keep diffs focused. SHOULD. Use the existing formatter and conventions. Avoid unrelated mass formatting or cosmetic renaming during a functional change. Do not rename persisted keys or API fields merely to improve internal style.
    Examples for READ-06 · 3 DOs and 3 DON'Ts

    DO

    • Format the changed file using the repository's existing settings.
    • Keep an internal variable rename separate from a database-column migration.
    • Limit a bug-fix diff to the affected behavior and necessary documentation.

    DON’T

    • Reformat the entire repository while fixing one validation bug.
    • Rename persisted JSON keys because the new names look cleaner.
    • Replace established naming conventions with personal preferences during unrelated work.

An example of a useful comment:

// Keep the first assignment; retries must not overwrite an earlier decision.
if (assignments.has(customerId)) return;

Contracts, configuration, and failures

  • CON-01 · Identify external contracts. MUST. Document API shapes, serialized keys, environment variables, command-line flags, role behavior, file formats, and version conventions. Make compatibility changes intentional and explain migration needs.
    Examples for CON-01 · 3 DOs and 3 DON'Ts

    DO

    • Document the accepted date format and time-zone interpretation of an API field.
    • Identify consumers before renaming an exported CSV column.
    • Describe how existing users migrate when a command-line flag changes.

    DON’T

    • Change a stored status value without checking existing records and clients.
    • Treat an environment variable used by deployment as a private implementation detail.
    • Return a new response shape while leaving the API reference unchanged.
  • CON-02 · Load configuration deliberately. MUST. Define precedence and validate required values. Distinguish missing, empty, invalid, inherited, and explicitly overridden values. Use project-relative or injected paths instead of personal machine paths. Local development must not silently select production data.
    Examples for CON-02 · 3 DOs and 3 DON'Ts

    DO

    • Validate required configuration at startup and explain which value is missing.
    • Distinguish an explicitly empty override from an absent setting.
    • Resolve fixture paths relative to the project or an injected data directory.

    DON’T

    • Fall back to a production database when local configuration is missing.
    • Hardcode a developer's home directory into a shared application.
    • Let web and worker processes apply different undocumented configuration precedence.
  • CON-03 · Report outcomes truthfully. MUST. Pending is not saved; generated is not delivered; unavailable is not zero. Do not silently replace live data with demo data or report success after a required write fails.
    Examples for CON-03 · 3 DOs and 3 DON'Ts

    DO

    • Show Saving until the required server write is confirmed.
    • Report that a report was generated but delivery failed.
    • Display unavailable when the provider cannot return a measurement.

    DON’T

    • Show Saved after catching and ignoring a persistence error.
    • Replace failed live results with demo records without disclosure.
    • Display zero sales when the data source could not be reached.
  • CON-04 · Define recovery. MUST. Specify success, partial completion, timeout, cancellation, retry, and cleanup for external work. Bound retries and deadlines. Handle expected errors specifically; retain useful diagnostics without leaking secrets.
    Examples for CON-04 · 3 DOs and 3 DON'Ts

    DO

    • Set a deadline and bounded retry policy for a provider request.
    • Record which batch items succeeded so failed items can be retried safely.
    • Remove temporary output when cancellation leaves an incomplete export.

    DON’T

    • Retry a failing external request forever in the background.
    • Catch every error and return an unexplained empty collection.
    • Restart an entire non-idempotent batch after only its final step fails.
  • CON-05 · Preserve integrity. MUST. Use transactions or equivalent atomic operations for business changes that must succeed together. Handle concurrent edits, duplicate requests, and partial writes deliberately. Make audit failures visible and recoverable.
    Examples for CON-05 · 3 DOs and 3 DON'Ts

    DO

    • Commit an inventory reservation and its business record in one transaction.
    • Use a version check to detect conflicting edits to the same record.
    • Use an idempotency mechanism for a payment request that may be retried.

    DON’T

    • Mark an order complete before its required inventory update succeeds.
    • Silently overwrite another user's newer edits.
    • Hide a failed audit write when the operation requires durable attribution.

Ten application security tenets

  • SEC-01 · Least privilege and explicit trust. MUST. Use established authentication and cryptographic mechanisms. Give users, services, and credentials only necessary access. Fail closed when required security configuration is missing.
    Examples for SEC-01 · 3 DOs and 3 DON'Ts

    DO

    • Give a reporting service read access only to its required data.
    • Use the framework's maintained password-hashing and authentication mechanisms.
    • Refuse startup when required signing configuration is absent.

    DON’T

    • Give every service the same unrestricted database account.
    • Invent a custom password cipher for account storage.
    • Disable authentication automatically when its configuration cannot be loaded.
  • SEC-02 · Authorization on every protected action. MUST. Check the actor, resource, and action on the server, including ownership, tenant/repository boundaries, downloads, and batch operations. A hidden button or authenticated session is not an authorization policy. Public access must be intentional.
    Examples for SEC-02 · 3 DOs and 3 DON'Ts

    DO

    • Check resource ownership again when serving a direct file download.
    • Verify every requested item in a batch operation belongs to the permitted scope.
    • Enforce a role change on subsequent protected server operations.

    DON’T

    • Authorize editing solely because the Edit button was hidden from other roles.
    • Allow an authenticated user to fetch any record by changing its identifier.
    • Check the first batch item and assume all remaining items are permitted.
  • SEC-03 · Verified identity and attribution. MUST. Derive authoritative actor, owner, and approver fields from verified identity. Do not trust client-supplied names or identity headers outside their defined trust boundary.
    Examples for SEC-03 · 3 DOs and 3 DON'Ts

    DO

    • Set the audit actor from the verified session identity.
    • Validate proxy identity headers only within the configured trusted-proxy boundary.
    • Derive the effective workspace from verified membership and the requested resource.

    DON’T

    • Accept approvedBy from an arbitrary request body as authoritative attribution.
    • Trust an internet-supplied user header without verifying its source.
    • Treat a client-supplied owner name as proof of ownership.
  • SEC-04 · Validate input at boundaries. MUST. Validate type, shape, size, length, allowed values, pagination, and upload characteristics. Treat files, manifests, remote responses, and model output as untrusted data. Reject malformed input predictably.
    Examples for SEC-04 · 3 DOs and 3 DON'Ts

    DO

    • Reject a negative quantity before it reaches order processing.
    • Bound upload size and validate the file characteristics the feature accepts.
    • Validate a model-generated action against the allowed schema before considering execution.

    DON’T

    • Assume a dropdown prevents callers from submitting unsupported values.
    • Load an unbounded import file entirely into memory.
    • Execute instructions found inside an uploaded manifest as trusted application commands.
  • SEC-05 · Safe output and resource access. MUST. Encode for the output context. Restrict URL schemes and destinations where external fetching is allowed. Resolve and validate filesystem boundaries, including symlinks where relevant. Limit file and network access to the intended feature.
    Examples for SEC-05 · 3 DOs and 3 DON'Ts

    DO

    • Render untrusted notes as text using the framework's safe output mechanisms.
    • Constrain imported file paths to the intended directory after resolution.
    • Validate redirect destinations as well as initial URLs in a restricted fetcher.

    DON’T

    • Insert customer text directly into raw HTML.
    • Let a download filename resolve outside the authorized storage boundary.
    • Allow a public URL-preview feature to fetch unrestricted internal service addresses.
  • SEC-06 · Safe queries and commands. MUST. Parameterize database values, allowlist dynamic identifiers, and pass subprocess arguments without constructing shell commands from untrusted text. Bound query and process execution.
    Examples for SEC-06 · 3 DOs and 3 DON'Ts

    DO

    • Bind a customer identifier as a database query parameter.
    • Map requested sort fields to a fixed set of allowed column identifiers.
    • Launch a subprocess with separate validated arguments and a deadline.

    DON’T

    • Concatenate search text into SQL syntax.
    • Pass user input through an interpolated shell command.
    • Assume parameterized values also make arbitrary table names safe.
  • SEC-07 · Secret protection. MUST. Keep credentials out of repositories, browser bundles, images, URLs, and logs. Use scoped server-side secret configuration, rotation, and revocation. Examples contain placeholders. Do not build custom encryption schemes.
    Examples for SEC-07 · 3 DOs and 3 DON'Ts

    DO

    • Keep provider credentials in scoped server-side configuration.
    • Use placeholders in documentation and redact secrets in diagnostics.
    • Revoke and replace an exposed credential through the authorized process.

    DON’T

    • Embed a private service token in a browser JavaScript bundle.
    • Commit a real environment file to make setup easier.
    • Put reusable access credentials into a link's query string.
  • SEC-08 · Session lifetime and revocation. MUST. Enforce expiry on the server and define how logout, password reset, account deactivation, and role changes invalidate access. Use appropriate cookies and CSRF protections where applicable; define CORS intentionally. Avoid reusable credentials in query strings.
    Examples for SEC-08 · 3 DOs and 3 DON'Ts

    DO

    • Reject an expired session on the server even when the browser retains its cookie.
    • Define how account deactivation invalidates existing access.
    • Apply appropriate cookie attributes and CSRF protection to cookie-authenticated writes.

    DON’T

    • Implement logout only by clearing the screen while credentials remain reusable.
    • Trust an old token's role indefinitely after permission revocation.
    • Treat a permissive CORS configuration as a substitute for authentication.
  • SEC-09 · Bounded work and maintained dependencies. MUST. Cap caches with eviction, queues, concurrency, request bodies, expensive actions, and external-call duration. Apply rate limiting where abuse would matter. Use supported runtimes and review dependency advisories and lockfiles.
    Examples for SEC-09 · 3 DOs and 3 DON'Ts

    DO

    • Bound simultaneous imports and reject excess work predictably.
    • Give a cache an eviction policy and a maximum size.
    • Review dependency advisories and plan updates for unsupported runtimes.

    DON’T

    • Keep every response forever in an unbounded process map.
    • Allow any request to launch unlimited expensive background jobs.
    • Treat a committed lockfile as proof that dependencies have no vulnerabilities.
  • SEC-10 · Evidence and recovery. MUST. Log meaningful security events without sensitive payloads, preserve actor attribution, and test access and failure boundaries. Minimize collected personal data, document retention, and support recovery from damaged or incomplete state.
    Examples for SEC-10 · 3 DOs and 3 DON'Ts

    DO

    • Log access denial with the actor and resource identifiers needed for investigation.
    • Test recovery from an interrupted write using disposable data.
    • Collect only personal fields the feature actually needs and define their retention.

    DON’T

    • Log full credential-bearing request bodies for easier debugging.
    • Claim recovery works because a backup file merely exists.
    • Remove actor attribution from security events to simplify the logging schema.

Detailed reference: OWASP authorization guidance. These tenets are a house baseline, not a claim of security certification.

Developer setup and IDE readiness

  • DEV-01 · Keep canonical source identifiable. MUST. Document the repository and project root. Include authored source, dependency declarations, applicable lockfiles, and configuration examples. Generated deployment bundles are not a substitute for source.
    Examples for DEV-01 · 3 DOs and 3 DON'Ts

    DO

    • Identify the repository and application root in the README.
    • Keep authored source and dependency declarations alongside applicable lockfiles.
    • Document which generated folders can be recreated and how.

    DON’T

    • Treat a minified deployment bundle as the only maintained source.
    • Leave developers guessing which of several copied folders is authoritative.
    • Store required build configuration only on one person's machine.
  • DEV-02 · Support a clean local setup. MUST. Document runtime/tool versions, installation, run, debug, test, and check commands. Use synthetic fixtures and disposable data. Explain required external services and available local substitutes.
    Examples for DEV-02 · 3 DOs and 3 DON'Ts

    DO

    • Document the supported runtime and a complete first-run sequence.
    • Provide synthetic fixtures and a disposable local database where appropriate.
    • Explain which integrations can be replaced by local substitutes.

    DON’T

    • Require production credentials merely to start the development interface.
    • Document install dependencies without naming the supported installation workflow.
    • Rely on an unrecorded global tool version for successful builds.
  • DEV-03 · Make editor use practical. SHOULD. Support ordinary VS Code navigation and debugging for suitable stacks, and native Visual Studio solution/project files where appropriate. Add tasks or launch settings when useful. The project must remain manageable through documented commands rather than one editor's hidden state.
    Examples for DEV-03 · 3 DOs and 3 DON'Ts

    DO

    • Provide useful VS Code debug settings for a supported web stack.
    • Maintain native Visual Studio project files for a suitable desktop application.
    • Document commands that work independently of a particular editor session.

    DON’T

    • Require undocumented clicks in one developer's editor to build the project.
    • Commit launch settings that contain personal secrets or absolute home paths.
    • Force a Visual Studio solution onto a stack that does not benefit from it.
  • DEV-04 · Make checks consistent. MUST. Provide appropriate formatting, linting, type checking, and behavior-test workflows. A developer should be able to hit a breakpoint in a meaningful operation and run its checks without production credentials.
    Examples for DEV-04 · 3 DOs and 3 DON'Ts

    DO

    • Expose the relevant lint, type, and behavior checks through documented commands.
    • Make a meaningful local operation reachable with a debugger breakpoint.
    • Run required checks using fixtures that do not depend on production access.

    DON’T

    • Declare checks complete after running only the formatter.
    • Require a live customer account to exercise ordinary local validation.
    • Let the documented test command succeed while executing no relevant checks.
  • DEV-05 · Provide a short source map. SHOULD. Explain entry points, feature locations, shared policies, external dependencies, and state ownership. Include a small domain glossary when useful. A maintainer should not need previous AI conversations to understand the project.
    Examples for DEV-05 · 3 DOs and 3 DON'Ts

    DO

    • Point maintainers from invoice behavior to the actual billing module.
    • Explain which service owns a background job's lifecycle.
    • Define domain terms that have a special meaning in the project.

    DON’T

    • Use see previous AI chat as the only explanation of a feature.
    • Copy the entire file tree without explaining responsibilities.
    • Keep a source map pointing to paths removed in a refactor.

Deployment on a shared VPS

These requirements apply when deployment or operations are in scope. They describe the target pattern; they do not authorize server changes during an audit.

  • DEP-01 · Separate environments and privileges. MUST. Keep development, staging where available, and production configurations/data distinct. Isolate project credentials, database access, storage, and runtime identities. Run application work without unnecessary root privileges.
    Examples for DEP-01 · 3 DOs and 3 DON'Ts

    DO

    • Give each application its own scoped runtime credentials.
    • Keep development fixtures separate from production records.
    • Run the application under a service identity with only necessary privileges.

    DON’T

    • Share a root database credential across unrelated projects.
    • Point a staging import job at production storage by default.
    • Run ordinary request processing as root merely for convenience.
  • DEP-02 · Minimize public exposure. MUST. Route public web traffic through the intended HTTPS entry point. Keep internal databases and management interfaces restricted. Review IPv4, IPv6, container publishing, and firewall behavior together. Do not assume a container is a complete security boundary.
    Examples for DEP-02 · 3 DOs and 3 DON'Ts

    DO

    • Expose the intended HTTPS entry point and restrict internal services.
    • Verify IPv6 exposure as well as IPv4 when reviewing service bindings.
    • Check how container-published ports interact with host firewall rules.

    DON’T

    • Publish the database port globally because the database is containerized.
    • Assume an IPv4 firewall rule also restricts every IPv6 listener.
    • Expose an administration interface without its intended access boundary.
  • DEP-03 · Use one documented release workflow. MUST. Map a source revision to a reproducible build and identifiable release. Separate build, release configuration, and runtime. Keep secrets and persistent data outside replaceable release files; do not patch production as the source of truth.
    Examples for DEP-03 · 3 DOs and 3 DON'Ts

    DO

    • Build an artifact from an identifiable source revision.
    • Inject environment-specific configuration separately from the compiled application.
    • Document the release workflow another maintainer can repeat.

    DON’T

    • Patch a running production file and leave the repository behind.
    • Bake deployment secrets into an image layer.
    • Store uploaded user files inside a replaceable release directory.
  • DEP-04 · Identify releases immutably. MUST. Record the commit, version, artifact/image identity, configuration requirements, and migration version. A mutable latest tag alone is insufficient. Retain the prior usable release according to a stated retention policy.
    Examples for DEP-04 · 3 DOs and 3 DON'Ts

    DO

    • Record the commit and immutable artifact identity in the release record.
    • Keep the previous usable release for the documented rollback period.
    • Associate a deployment with its required schema version.

    DON’T

    • Record only latest and assume it always refers to the same artifact.
    • Overwrite a published version with different content under the same identifier.
    • Delete the previous release before checking the replacement's health.
  • DEP-05 · Plan rollback and migrations. MUST. Document health checks, smoke checks, graceful shutdown, restart ownership, and rollback. Treat schema/data rollback separately from application rollback. Test risky migrations against representative disposable data and provide a recovery path.
    Examples for DEP-05 · 3 DOs and 3 DON'Ts

    DO

    • Check application health and a representative operation after deployment.
    • Test a risky migration against representative disposable data.
    • Document when application rollback also requires data recovery.

    DON’T

    • Assume starting an older binary reverses every database migration.
    • Let two supervisors repeatedly restart the same failing process.
    • Terminate active work without a documented shutdown or recovery policy.
  • DEP-06 · Operate within limits. MUST. Define resource limits, timeouts, log rotation, and actionable monitoring so one project cannot easily exhaust the host. Assign backup responsibility and retention; keep protected copies outside the failure domain and verify restoration separately from backup creation.
    Examples for DEP-06 · 3 DOs and 3 DON'Ts

    DO

    • Set resource limits so a batch job cannot consume the whole VPS.
    • Rotate logs and alert on actionable service failures.
    • Keep protected backups outside the host failure domain and test restoration.

    DON’T

    • Allow logs to grow until the shared filesystem is full.
    • Keep the only recovery copy beside the live data on the same disk.
    • Treat a successful backup upload as evidence that restoration was tested.
  • DEP-07 · Keep the pattern proportionate. SHOULD. Use a consistent container or process-supervisor convention appropriate to the stack. Document domains, ports, storage, service ownership, and deployment commands privately. Do not introduce orchestration complexity without a concrete need.
    Examples for DEP-07 · 3 DOs and 3 DON'Ts

    DO

    • Use the team's documented supervisor for a small standalone service.
    • Record service ownership, ports, and storage in private operations documentation.
    • Introduce orchestration only when an actual operational requirement justifies it.

    DON’T

    • Add a cluster platform solely to host one simple personal application.
    • Use a different undocumented release convention for every project.
    • Put private deployment topology into a public generic guidelines page.

Reference: The Twelve-Factor App: build, release, run. Publishing and rollback must stay within the user's authorized task.

UX and interface patterns

Use the patterns that serve the actual task. House presentation defaults are starting points, not reasons to override an established product design or add features.

  • UX-01 · Start with the user's task. MUST. Make the current page, object, scope, and next action understandable. Prefer a dominant work area over a dashboard or card grid added by habit.
    Examples for UX-01 · 3 DOs and 3 DON'Ts

    DO

    • Show the selected project and the document currently being edited.
    • Put the scheduling workspace first when scheduling is the screen's main task.
    • Make the next useful action recognizable from the current state.

    DON’T

    • Replace a working editor with decorative metric cards.
    • Hide the active account while allowing account-scoped actions.
    • Give unrelated promotional content more prominence than the user's task.
  • UX-02 · Match screen structure to purpose. SHOULD. Collections help find records; detail pages explain one object; editors expose inputs and results; settings group related choices; utilities bring input/output forward. Separate administration from everyday work where useful.
    Examples for UX-02 · 3 DOs and 3 DON'Ts

    DO

    • Use a searchable collection view to help users locate existing records.
    • Give substantial editing work a dedicated area for inputs and results.
    • Group related configuration in a settings surface.

    DON’T

    • Make every screen a dashboard regardless of its purpose.
    • Scatter a single object's details across unrelated summary cards.
    • Place account administration controls in an everyday task toolbar without need.
  • UX-03 · Keep navigation and scope clear. MUST. Distinguish global and resource-specific actions. Show the active project/account/resource. Use links for navigation and buttons for actions. Support useful deep links, Back, and an accessible narrow-screen navigation alternative.
    Examples for UX-03 · 3 DOs and 3 DON'Ts

    DO

    • Show which workspace a permission change will affect.
    • Use a link for a record destination that supports navigation and Back.
    • Provide an understandable navigation alternative at narrow widths.

    DON’T

    • Make a global delete action look like a selected-row action.
    • Use a navigation link that silently performs a write.
    • Hide all navigation on mobile without another way to reach destinations.
  • UX-04 · Use restrained, readable hierarchy. SHOULD. Use consistent typography, spacing, components, and semantic color tokens. Do not use color alone for meaning. Light is the house starting theme; offer deliberate dark/system choices only when relevant, and verify all supported themes. Density and branding depend on the product.
    Examples for UX-04 · 3 DOs and 3 DON'Ts

    DO

    • Reuse the established spacing and typography tokens across screens.
    • Pair warning color with a clear label or icon and accessible text.
    • Check text and control contrast in every supported theme.

    DON’T

    • Invent a new button style for every page.
    • Use red and green alone to communicate failure and success.
    • Add a dark theme without checking dialogs, fields, and disabled states.
  • UX-05 · Name actions by their effect. MUST. Distinguish save, preview, publish, export, restore, and delete. Show the version, destination, audience, or record scope when consequential. Do not require confirmation for every ordinary save.
    Examples for UX-05 · 3 DOs and 3 DON'Ts

    DO

    • Label a draft write Save draft and a public release Publish.
    • Show the target project before a consequential import.
    • State whether Export includes selected rows or the filtered result set.

    DON’T

    • Use OK for an action that permanently removes a record.
    • Call a preview action Publish when no publication occurs.
    • Ask for confirmation after every ordinary reversible field save.
  • UX-06 · Write useful interface text. SHOULD. Use plain labels and concise instructions that help a decision or recovery. Keep stack traces, implementation details, and long explanations in appropriate operator/help surfaces. Avoid placeholder-only labels and unexplained icons.
    Examples for UX-06 · 3 DOs and 3 DON'Ts

    DO

    • Use a visible label explaining what a field contains.
    • Explain a failed connection with a recovery action the user can take.
    • Give an unfamiliar icon a meaningful accessible name and visible help when needed.

    DON’T

    • Use placeholder text as the only field label.
    • Display a raw stack trace as the main explanation of a form error.
    • Label an action Process without explaining its effect.
  • UX-07 · Make forms recoverable. MUST. Associate labels with inputs, show required formats, validate accessibly, preserve input on failure, and prevent duplicate submission. Show persistent actionable errors and accessible asynchronous feedback. Password/credential values need special handling.
    Examples for UX-07 · 3 DOs and 3 DON'Ts

    DO

    • Keep valid entries when one field fails validation.
    • Associate an error with its field and make it discoverable by keyboard.
    • Prevent another submission while the same save is pending.

    DON’T

    • Clear the entire form after a recoverable server failure.
    • Show errors only in a toast that disappears before it can be read.
    • Let repeated clicks create duplicate records.
  • UX-08 · Make tables usable. SHOULD. Use identifiable rows, units, meaningful sorting, and resizable columns where appropriate. Resolve filtering and CSV-export requirements from existing project decisions; ask only when genuinely undecided and material. Define export and selection scope explicitly. Sort the whole result set, preserve relevant settings across pages, and distinguish no records from no matches.
    Examples for UX-08 · 3 DOs and 3 DON'Ts

    DO

    • Sort the complete result set before applying pagination.
    • Show clear row identity and units for numeric columns.
    • Preserve useful sorting and filtering when moving between result pages.

    DON’T

    • Sort only the currently visible page while implying a global order.
    • Export all records when the control promises selected records.
    • Show the same empty message for no data and no filter matches.
  • UX-09 · Preserve editing context. MUST. Display unsaved, saving, saved, and failed states truthfully. Keep drafts, focus, selection, and scroll position through recoverable updates. Detect conflicts where collaborative editing is supported. Preview must not imply publication.
    Examples for UX-09 · 3 DOs and 3 DON'Ts

    DO

    • Keep a draft visible when saving fails.
    • Detect a conflicting edit before overwriting another user's changes.
    • Preserve the selection and scroll position through a recoverable refresh.

    DON’T

    • Show Saved before the write completes.
    • Reset an editor to the top whenever background data updates.
    • Treat opening a preview as permission to publish it.
  • UX-10 · Expose progress and partial results honestly. MUST. Model loading, empty, success, error, permission-denied, and unavailable-service states. Long work needs suitable progress, cancellation/retry when supported, and a clear result. Do not invent percentages or claim completion before verification.
    Examples for UX-10 · 3 DOs and 3 DON'Ts

    DO

    • Show completed and failed counts for a partially successful import.
    • Use an indeterminate indicator when actual completion percentage is unknown.
    • Offer cancellation or retry when the operation genuinely supports it.

    DON’T

    • Animate a fabricated percentage unrelated to actual work.
    • Show a success banner while required background processing is still pending.
    • Represent a service outage as an empty result set.
  • UX-11 · Use dialogs deliberately. SHOULD. Keep a dialog focused on one decision. Manage initial focus, keyboard dismissal where appropriate, and focus return. Use a full page for substantial work. For destructive actions, explain the affected scope and offer undo when practical.
    Examples for UX-11 · 3 DOs and 3 DON'Ts

    DO

    • Use a short confirmation dialog for one consequential decision.
    • Restore focus to the triggering control when a dialog closes.
    • Move a substantial multi-step editor to a page.

    DON’T

    • Put an entire administration application inside a confirmation modal.
    • Leave keyboard focus on controls hidden behind an active dialog.
    • Ask Delete? without identifying the affected object or scope.
  • UX-12 · Connect data to evidence. MUST when presenting data. Identify units, time period, filters, source, and uncertainty. Distinguish missing from zero. Offer a suitable text/table alternative to charts. Make details inspectable without exposing private information.
    Examples for UX-12 · 3 DOs and 3 DON'Ts

    DO

    • Label a revenue chart with its currency and reporting period.
    • Explain when an estimate is based on incomplete data.
    • Provide a suitable table or textual interpretation alongside an important chart.

    DON’T

    • Compare values from different periods without identifying the difference.
    • Display missing measurements as zero.
    • Expose private source records merely to make a chart drill-down available.
  • UX-13 · Keep AI assistance accountable. MUST when using AI. Distinguish suggestions from accepted changes. Show the scope, evidence, and limitations needed to assess output. Do not treat model text as trusted code, credentials, or authorization to act.
    Examples for UX-13 · 3 DOs and 3 DON'Ts

    DO

    • Mark an AI-generated revision as a suggestion until it is accepted.
    • Show the evidence and scope needed to assess an automated recommendation.
    • Validate generated actions against the application's actual permissions and contracts.

    DON’T

    • Treat a model's approval message as user authorization.
    • Run generated code automatically because it appears syntactically valid.
    • Present an unsupported AI guess as a verified system fact.
  • UX-14 · Implement accessibility. MUST. Use semantic controls, accessible names/states, keyboard operation, visible focus, adequate contrast, zoom/reflow, and appropriate touch targets. Target WCAG 2.2 AA for web work and platform-appropriate accessibility for native apps. Verify actual interactions; an automated scan alone is insufficient.
    Examples for UX-14 · 3 DOs and 3 DON'Ts

    DO

    • Use native controls with accessible names and visible keyboard focus.
    • Check zoom and narrow layouts with realistic long labels.
    • Verify important workflows with keyboard navigation as well as automated checks.

    DON’T

    • Make a clickable decorative container the only way to submit a form.
    • Remove focus outlines without an equally clear replacement.
    • Claim accessibility compliance solely because one automated scan passed.
  • UX-15 · Assign scroll ownership. SHOULD. Prefer one vertical scroll owner for a page. Avoid nested scrollers; use sibling editor panes in a non-scrolling shell where necessary. Keep navigation/actions reachable without obscuring content. Section or paginate long collections rather than shrinking essential text; adapt the layout at small sizes and zoom.
    Examples for UX-15 · 3 DOs and 3 DON'Ts

    DO

    • Let a long settings page use one main vertical scroll area.
    • Use sibling editor panes inside a shell that does not also scroll.
    • Keep important actions reachable without covering focused content.

    DON’T

    • Give each card a vertical scrollbar inside a scrolling page.
    • Shrink text to fit a large table into an arbitrary fixed-height box.
    • Allow a fixed toolbar to cover the field currently receiving keyboard focus.
  • UX-16 · Declare one main intent per page or form. MUST. Before designing or materially changing a page, screen, or form, record its intended user, one primary task, and observable successful outcome in the project design guide. Use a concrete verb and object: find a client, register a client, edit a price, or monitor scheduled runs. "Manage clients" is too broad when it disguises unrelated consultation, creation, and administration tasks. Size, placement, content, and action emphasis must serve that declared intent. One intent can require multiple controls or steps; a monitoring page can contain several indicators serving one monitoring task.
    Examples for UX-16 · 3 DOs and 3 DON'Ts

    DO

    • Document the client-list intent as finding and opening an existing client.
    • Give a registration form the outcome of creating one valid client.
    • Treat search and sorting as supporting controls for consultation.

    DON’T

    • Describe a page as manage everything without defining a user outcome.
    • Combine consultation and an always-expanded registration workspace by habit.
    • Interpret one intent as a requirement to remove necessary supporting controls.
  • UX-17 · Keep separate tasks subordinate. MUST. Put secondary tasks on their own page or reveal them on request through a collapsed section, side panel, or focused dialog. Keep the entry action discoverable without permanently displaying a competing form or work area. Search, filters, sorting, help, and validation may remain visible when they directly support the primary task. A client-list page therefore prioritizes finding existing clients and exposes registration through New client. Document where each secondary task opens and how users return with context preserved. Do not interpret this rule as hiding errors, necessary instructions, permissions, or critical status.
    Examples for UX-17 · 3 DOs and 3 DON'Ts

    DO

    • Open registration only after New client is selected.
    • Keep optional advanced settings collapsed until requested.
    • Return from a secondary operation with the original search context preserved.

    DON’T

    • Place a full creation form above every record collection.
    • Hide critical validation errors to make the primary area look cleaner.
    • Make a secondary task discoverable only through an unexplained icon.
  • UX-18 · Choose the secondary surface deliberately. SHOULD. Use a dedicated page for substantial forms, multi-step work, deep linking, or long-lived drafts; a dialog for a short bounded task; a side panel when consulting the underlying record materially helps; and a collapsed section for optional supporting detail. On small screens, change the surface when needed to retain usability. Use an in-application dialog rather than a separate browser popup by default. Preserve input on failure, handle unsaved changes, provide an explicit exit, and restore focus and relevant list context. A proposed simultaneous multi-task workspace needs a documented workflow justification and resolution under the exception rules before the affected implementation.
    Examples for UX-18 · 3 DOs and 3 DON'Ts

    DO

    • Use a page for a long form that needs a bookmarkable draft.
    • Use a focused dialog for a short bounded rename operation.
    • Use a side panel when comparing with the underlying record materially helps.

    DON’T

    • Choose a modal solely because creating a route takes more implementation work.
    • Open a separate browser popup for ordinary in-application editing.
    • Keep a cramped desktop drawer unchanged on a narrow screen.

These house rules apply progressive disclosure to task separation; they do not claim that one primary task is a universal research law. Reference: NN/g on progressive disclosure.

Accessibility reference: W3C Understanding WCAG 2.2. This is a quality target, not a certification statement.

Interaction hierarchy and nesting

Keep the active task understandable without requiring users to track several competing layers of navigation, scrolling, selection, or task focus. Structural containment is normal: a sidebar, page, form, and field can each have a clear role. The problem is nesting another interaction mechanism that repeats or competes with its parent's job. Component reuse and database hierarchy are not reasons to reproduce that hierarchy in the interface.

  • UX-19 · Avoid competing nested interactions. MUST. Use one clear owner for each interaction within the active task. Do not place a tab group inside another tab's content, stack an application dialog over another dialog, or create independently scrolling page sections inside an already scrolling work area. Avoid recursive accordions and embedded management workspaces that make users operate the same task at several levels. Replace the extra layer with a dedicated destination, a sequential step, a flat section, or a control with a distinct supporting purpose. Bounded text inputs and code editors can scroll when necessary; sibling work panes may scroll in a non-scrolling shell under UX-15. They must not become another page-level workspace. Normal document structure and clearly scoped global navigation remain valid.
    Examples for UX-19 · 3 DOs and 3 DON'Ts

    DO

    • Replace nested tab groups with clear destinations and one local content selector.
    • Move from one dialog step to the next without stacking active dialogs.
    • Keep one page-level scroll owner or explicitly separated sibling work panes.

    DON’T

    • Put tabs inside a selected tab and require both selections to understand the page.
    • Open a management modal that launches another management modal.
    • Embed a separately scrolling CRUD workspace inside another scrolling workspace.
  • UX-20 · Distinguish navigation from controls. MUST. Identify what each control changes: destination, content section, result subset, representation, or a selected object. Use links for destinations, a single local tab level for related panels when justified, labeled filters for narrowing one result set, and suitable view controls for changing its representation. State the affected scope, preserve relevant context, and expose active filters and their reset. Renaming nested tabs as pills, buttons, or dropdowns does not resolve the problem if they still select successive workspaces. Do not flatten unrelated categories into one ambiguous tab strip merely to remove a level.
    Examples for UX-20 · 3 DOs and 3 DON'Ts

    DO

    • Use a labeled Type filter to narrow records in the same queue.
    • Use destination links when each choice opens a different workflow.
    • Use a view control when switching the same records between table and grid.

    DON’T

    • Rename nested tabs as pills while keeping the same nested workspace behavior.
    • Mix statuses, object types, and destinations in one unlabeled selector.
    • Hide active filters so an apparently missing record cannot be explained.
  • UX-21 · Review interaction depth before styling. SHOULD. In the page record, map navigation levels, active task surface, selection scope, and scroll owners. Explain why each control is necessary for the declared page intent. Walk through a representative task on desktop, narrow layouts, and keyboard input; check Back, close/cancel, retained state, and focus return. Remove layers that duplicate another control's role. Prefer headings and spacing over decorative containers within containers when the inner boundary has no meaning. A proposed departure from UX-19 needs resolution under the existing exception rules; a library's ability to nest components is not a justification.
    Examples for UX-21 · 3 DOs and 3 DON'Ts

    DO

    • Map navigation, task surfaces, selection, and scrolling before choosing components.
    • Walk through Back and cancellation with keyboard and narrow-screen layouts.
    • Remove an inner container whose border and controls add no meaningful scope.

    DON’T

    • Accept recursive accordions simply because the component library supports them.
    • Review only colors while users must track several competing control layers.
    • Use the database's nesting depth as the default interface navigation structure.

Example: a queue with a top tab row for Items and Capsules and a second tab row for All, Approvals, Contributions, and Feedback has two layers to interpret. If the second row selects subsets of the same list, use a labeled Type filter with an explicit all-items state. If it opens distinct workflows, give those workflows their own destinations. Keep one main content area and preserve the current query when returning. Determine the actual behavior before choosing the replacement; a screenshot cannot establish whether a control filters data or opens another workspace.

The no-nesting requirement is a house design rule, not a claim that every nested component violates accessibility standards. For the behavior and semantics of a single tab group, see the W3C tabs pattern and GOV.UK tabs guidance.

Project documentation and design decisions

Every project adopting this edition needs a maintained design guide covering code structure, architecture, UX intent, and significant pattern choices. Keep it with the source and link it from the README. A small project can start with one concise document; larger projects can use an index linking focused documents. The goal is enough context for another human or AI session to continue safely without reconstructing earlier conversations.

  • DOC-01 · Maintain a canonical guide in a dedicated folder. MUST. Keep architecture, UX, change plans, decisions, technical version journals, and user changelogs in a dedicated documentation folder inside the project workspace, separate from application source and build output. Reuse an established documentation root; otherwise use docs/, with project-design.md, plans/, and releases/ as needed. Link the folder's index from the project README and keep it under the project's version control. Identify the adopted guidelines edition, documentation owner, applicable source revision or release, and review date. Distinguish current implementation, accepted design, proposals, and known gaps. Chat history is not the canonical record. Keep private project details in the appropriate private repository and outside public build artifacts; public guidelines contain generic rules and examples only.
    Examples for DOC-01 · 3 DOs and 3 DON'Ts

    DO

    • Keep the design guide, plans, and version journals in the project's docs folder and link its index from the README.
    • Reuse an established documentation folder and record the adopted guideline edition and reviewed revision there.
    • Keep a proposed redesign separate from current behavior and exclude private project documents from public build output.

    DON’T

    • Keep the only architecture plan in a chat transcript or a temporary directory outside the project workspace.
    • Publish private deployment details inside a generic public standard.
    • Scatter competing design documents among application modules with no canonical documentation index.
  • DOC-02 · Explain code and architecture. MUST. Document the product boundary, users and external systems, applications and data stores, important data flows and trust boundaries, and operational assumptions. Map features to real source locations, entry points, module responsibilities, dependencies, state ownership, contracts, and relevant checks. Name the code and architecture patterns actually used, explain why they fit, and identify consequential alternatives and tradeoffs. Link authoritative schemas, API definitions, setup instructions, and runbooks instead of copying them. Do not invent layers or label a codebase with a pattern it does not implement.
    Examples for DOC-02 · 3 DOs and 3 DON'Ts

    DO

    • Map a user action through the responsible module to storage and external services.
    • Explain why an integration adapter owns provider-specific error handling.
    • Link authoritative API schemas and describe important trust boundaries.

    DON’T

    • Call the architecture clean without identifying responsibilities and dependencies.
    • Copy API definitions into several guides that can drift independently.
    • Describe layers that do not exist in the actual source.
  • DOC-03 · Keep a page and form inventory. MUST. Give every page, native screen, and independently actionable form a stable record. Identify its route or screen ID, user and permission scope, primary intent and success condition, supporting controls, secondary tasks and their destinations, entry/exit behavior, and relevant UI states. Include dialogs and drawers as linked child records; a form used on several pages may share one record with its entry points listed. Reuse common state/accessibility specifications by reference and record local differences. Map the record to its code, applicable UX/VIS patterns, decisions, and verification evidence. This is the reference for evaluating whether the screen serves its intended purpose.
    Examples for DOC-03 · 3 DOs and 3 DON'Ts

    DO

    • Give each route or native screen a stable page record with one main intent.
    • Link a reusable registration form to all its documented entry points.
    • Record navigation, states, scope, code locations, and acceptance evidence together.

    DON’T

    • Document only top-level menus and omit independently actionable dialogs.
    • Use a screenshot as the entire specification of a form's behavior.
    • Claim complete page coverage while known screens have no inventory entries.
  • DOC-04 · Record consequential decisions. MUST. For choices affecting architecture, code boundaries, contracts, security, or UX task structure, write a short decision record with an ID, status, date, context, options, chosen approach, reason, consequences, and affected records. Include rejected alternatives only when they explain a meaningful tradeoff. Preserve superseded records and link the replacement; an AI proposal is not an accepted product decision. Minor styling choices can remain in a component or page record. Do not create a separate decision file for every small edit.
    Examples for DOC-04 · 3 DOs and 3 DON'Ts

    DO

    • Record why registration uses a separate page instead of a permanent inline form.
    • Retain a superseded storage decision and link its replacement.
    • Include costs and rejected alternatives when explaining a significant choice.

    DON’T

    • Mark an AI proposal accepted without the relevant decision authority.
    • Delete old rationale when a consequential decision changes.
    • Create a separate formal decision record for every spacing adjustment.
  • DOC-05 · Keep documentation in the work loop. MUST. Read applicable documentation before work and follow the DOC-07 plan and approval sequence. Reconcile the current design guide with the actual result in the same change while preserving the approved plan revision and decision history. Review affected links, diagrams, examples, page records, and contracts when code or UX changes. Verify documented commands safely and record any checks not run. Do not silently rewrite intended behavior to excuse a defect or claim verification from a screenshot alone. Include documentation impact, plan/approval references, and both DOC-08 changelogs in the handover.
    Examples for DOC-05 · 3 DOs and 3 DON'Ts

    DO

    • Read the approved plan and page intent before changing available actions.
    • Update current design records and the version journal with the implementation while retaining the approved plan revision.
    • Verify a setup instruction safely and disclose any step not exercised.

    DON’T

    • Rewrite the approved plan after implementation to disguise an unapproved behavior change.
    • Leave module links pointing at files removed by the same refactor.
    • Claim a keyboard workflow was tested after reviewing only a screenshot.
  • DOC-06 · Write for a specific reader need. SHOULD. Keep setup and task instructions separate from factual reference and explanations of design rationale. Use descriptive headings, short paragraphs, concrete examples, a glossary when needed, and links to a single source of truth. Prefer editable diagrams with labeled relationships and readable text equivalents when diagrams clarify the system. Explain decisions and constraints rather than narrating every function. Avoid empty template sections, duplicated specifications, long generated prose, and rigid document-length or comment quotas.
    Examples for DOC-06 · 3 DOs and 3 DON'Ts

    DO

    • Give setup instructions a concise sequence and link deeper rationale separately.
    • Use a labeled architecture diagram with a readable textual explanation.
    • Explain a project-specific term once and reuse it consistently.

    DON’T

    • Generate empty documentation folders simply to imitate a framework.
    • Narrate every function instead of explaining consequential design choices.
    • Duplicate the same changing contract in a tutorial, guide, and reference.

Use established documentation patterns proportionately:

  • Diátaxis: distinguish tutorials for learning, how-to guides for accomplishing a task, reference for facts, and explanation for understanding. Apply the distinction where useful without creating four empty folders. See the Diátaxis introduction.
  • C4: start with system context and application/data-store views; add component detail only where it helps. C4's term "container" denotes an application or data store, not necessarily a Docker container. There is no requirement to produce all four levels for every project. See the C4 model.
  • Decision records: retain the rationale and consequences of significant choices in short linked records. The same lightweight approach can cover code and UX decisions as a house extension of architecture decision records. See Michael Nygard's architecture decision record approach.

Start from the project design guide template or its editable Markdown copy. File names and folder arrangements are examples; equivalent existing documentation satisfies the requirement when it covers the same information and stays discoverable.

Adoption and audit scope. Apply these requirements to new projects and relevant authorized changes after adoption. For an existing project, inventory missing documentation and agree on staged coverage; do not rewrite every screen or backfill every decision during an unrelated task. For audit-only work, document findings and proposed page intents in the local report, distinguishing inference from an owner-confirmed objective. Do not modify project documentation or application behavior under an audit-only authorization.

Document first approval and version journals

  • DOC-07 · Provide a plan and obtain approval before implementation. MUST. For each development change, save and present an identifiable architecture and UX plan in the project's documentation folder before implementation. Cover the intended version and scope, current behavior and proposed outcome, module boundaries and contracts, state/lifecycle and security impact, page/form intent and interaction choices, verification, deployment, and recovery. For a small fix or documentation change, use a short plan and state why architecture or UX is unaffected rather than inventing work. Obtain explicit approval from the user or designated decision authority for that plan revision and scope; record who approved, when, and the message or record establishing it. An already approved plan covering the same work remains valid; do not ask again for unchanged scope. Material changes to behavior, architecture, UX, or rollout require an updated plan and renewed approval before the affected work. Before deploying, present the implemented outcome, verification, and both changelogs, and confirm deployment authorization covers that release and target. Plan approval alone is not deployment authorization, but one explicit approval may cover both. Silence, a successful check, or an AI marking its own plan accepted is not approval. Read-only audits may produce reports and proposed plans without starting implementation or deployment.
    Examples for DOC-07 · 3 DOs and 3 DON'Ts

    DO

    • Save a checkout change plan covering payment boundaries, page intent, failure states, and verification; present revision 2 and record the user's approval before implementation.
    • For a typo release, provide a short plan stating architecture and UX are unaffected; reuse an explicit approval that already covers the correction and that release's publication.
    • When an approved dialog becomes a multi-step workflow, revise the UX plan and obtain approval for that change; present results and the journal before the authorized deployment.

    DON’T

    • Implement first and generate an architecture and UX plan afterward as if it had guided the work.
    • Mark a plan approved because the AI likes it, tests pass, or the user has not responded.
    • Deploy an unapproved release or target because permission was given only to implement the design.
  • DOC-08 · Keep technical and user changelogs for every version. MUST. Maintain two distinct, indexed release histories in the project's dedicated documentation folder, under version control. Use the same version identity in both; record dates and actual release/availability status consistently. Start both records during planning, then reconcile them with the delivered result. Cover feature, fix, refactor, and documentation-only versions. Reuse established equivalent paths; otherwise use docs/releases/<version>.md for the technical journal and docs/CHANGELOG-USERS.md for the user history, linked from docs/README.md. The technical journal retains the full existing requirement: what changed, why, observable before/after effects, source revision or artifact identity, preceding version, approved plan and decisions, architecture/code/configuration changes, parameter changes, verification results and limitations, compatibility/migration impact, deployment status and target, and rollout/recovery instructions. Keep sensitive operational details in the appropriate private documentation. The user changelog explains what changed FOR users in their product's language. Include relevant new capabilities, changed workflows, new or renamed controls, moved or removed pages, corrected behavior, changed limits or permissions, and required user actions. Use actual interface labels, say where moved functionality can now be found, and explain replacements or loss of functionality when something is removed. State who is affected and any rollout or availability restriction that changes the reader's next action. Omit empty categories. For a release with no user-visible change, retain a version entry saying so plainly; do not manufacture a benefit. Describe user-relevant security changes without exposing sensitive implementation details. Both records must agree on facts and availability. Do not present proposed, approved, implemented, or verified work as already available to users. A commit list, copied technical notes, internal parameter names, or vague claims such as "various improvements" do not satisfy the user changelog. Preserve published entries in both histories; make later corrections explicit through dated addenda or a new version. Never erase an earlier narrative or rewrite a planned feature as previously shipped. Public user notes must not expose private technical links, identifiers, credentials, or operational evidence. An accessible technical-detail link may be included when appropriate to the audience.
    Examples for DOC-08 · 3 DOs and 3 DON'Ts

    DO

    • Keep routing, module, and regression-test details in the technical journal; tell users: "On Clients, choose 'New client' to open the registration form. The client list now occupies the main page."
    • Record a validated per-file limit change from 20 MiB to 64 MiB in the technical journal, including effective enforcement and evidence; tell users: "You can now attach files up to 64 MiB each." If the release is still pending, label that availability explicitly in both records.
    • Keep a pure internal refactor in both histories: explain the boundary changes and verification technically, and write "No user-visible changes in this version" for users. Preserve earlier entries and append dated corrections when needed.

    DON’T

    • Copy "ASSET_MAX_BYTES updated; routes modularized" into user notes or claim "better performance" without evidence of a user-visible improvement.
    • Write "navigation improved" when a page was removed or a button moved, leaving users without the old location, new destination, replacement, or required action.
    • Mark an unverified rollout available, omit a version because only internal code changed, or replace previous notes with the newest version.
  • DOC-09 · Make internal parameters explicit before implementation. MUST. During planning, inventory all internal hardcoded parameters that determine behavior or policy, including unnamed literals and defaults used when configuration is absent. Keep a canonical register in the project's documentation folder, normally docs/parameters.md, and link it from the architecture/UX plan and design guide. For each parameter, document its plain-language purpose; identifier or literal and source location; current and proposed value with exact unit and scope; enforcement points and effective constraints; fixed or configurable status, override mechanism and precedence; allowed range/validation and invalid-value behavior; rationale, owner, and approval status; user-visible effect; consequences of changing it; and verification evidence or planned boundary checks. Separate source defaults from observed environment values and proposals from approved, implemented, and deployed values. Present the register and unresolved policy choices for review with the plan under DOC-07. Confirm whether each value should stay fixed or be configurable; documenting it neither authorizes a change nor requires adding a setting. Reconcile the register with code and relevant deployment configuration before completion, and record changed values and their practical effects in the version journal. A variable name, constant list, or code comment alone does not satisfy this rule.
    Examples for DOC-09 · 3 DOs and 3 DON'Ts

    DO

    • Before planning an upload change, explain 'maximum bytes per file' beside UPLOAD_MAX_BYTES, record the exact byte value and MiB conversion, locate every enforcement point, and mark unknown proxy limits for verification.
    • Document an unnamed 30000 timeout as 30 seconds, including its source, affected operation, cancellation behavior, rationale or unknown rationale, fixed/configurable decision, approval state, and planned failure check.
    • Keep docs/parameters.md linked from the plan, inventory defaults and overrides across reviewed layers, then reconcile actual values and journal their user effects; list legacy coverage gaps with an owner instead of claiming the whole project was checked.

    DON’T

    • Tell the owner only 'raise ASSET_MAX_BYTES' or list constant names without explaining the current limit, exact unit, user impact, reason, and consequences of changing it.
    • Treat a grep for uppercase constants as a complete inventory while ignoring inline validators, retry counts, feature defaults, frontend limits, and stricter infrastructure constraints.
    • Silently turn every constant into an environment variable, copy secret values into the register, or mark a proposed 64 MiB limit deployed before approval, implementation, and effective-path verification.

Parameter coverage. Include size/count limits, quotas, timeouts, retry and concurrency policies, batch/page sizes, retention, cache lifetimes, feature defaults, thresholds, scoring weights, accepted formats/values, fixed endpoints/paths, and behavior-setting UI defaults or timings. Cover backend, frontend, workers, and first-party build/deployment code; review defaults embedded in expressions and validators as well as named constants. Link existing authoritative configuration or design-token references instead of duplicating them; cosmetic values may be grouped in a style reference. Language syntax, loop indices, and mathematical identities are not policy parameters. Generated/vendor internals need not be exhaustively catalogued, but external or infrastructure limits that constrain the effective behavior must be identified with their source and verification status. Keep secrets out of the register: document the secret reference and purpose, never its value.

Coverage and evidence. New projects start with a complete register of planned parameters and reconcile it with the implementation. For existing projects, state the reviewed source revision, directories and search/manual-review method, exclusions, and remaining gaps; inspect all parameters affecting the planned change, including interacting limits across layers. A search for uppercase constants is a discovery aid, not proof of completeness. Track legacy coverage gaps with an owner and next review scope, without expanding an unrelated task or claiming unreviewed areas comply. In audit-only work, report the inventory and gaps without changing code. Describe a file-size limit as "maximum bytes accepted per uploaded file" before its internal name, specify whether MB or MiB is meant, and check whether a proxy or another route imposes a smaller effective limit.

A compact documentation layout is shown below. Reuse the existing project's equivalent paths and create only records that have content. The design guide describes the current system; plans describe intended changes and approvals; technical journals describe the full delivered result; user changelogs explain its practical effect. Decisions explain consequential choices and may live in the guide until separate records are useful.

docs/
  README.md                 index and adopted guideline edition
  project-design.md         current architecture, boundaries, and UX inventory
  parameters.md             internal parameters, defaults, limits, and coverage
  plans/1.4.0.md             architecture and UX plan with approval record
  releases/README.md        version history index
  releases/1.4.0.md         technical changes, evidence, compatibility, deployment
  CHANGELOG-USERS.md        user-facing changes by version and availability

Use the project design template, change plan template, technical version journal template, and user changelog template. Each has an editable Markdown download. These documents support decisions; completing a template never substitutes for user approval or behavior verification.

Visual perception and grouping

Use perceptual principles to make purpose, relationships, and action scope easier to recognize. Gestalt is the broader account of how people perceive organized wholes; the principles below are design aids, not seven independent features to implement. Apply them to the user's task and existing design system. A visual style or screenshot alone cannot prove usability.

  • VIS-01 · Whole-screen coherence. SHOULD. Establish the page's purpose, main work area, and action hierarchy before styling individual components. Give emphasis according to task importance; avoid unrelated controls competing for attention. Example: in an editor, keep the document central and distinguish Save from secondary export options. Review: can a reviewer identify what they are editing and the likely next action without inspecting every card? A dashboard may need several equally important areas; do not invent a single primary action when none exists.
    Examples for VIS-01 · 3 DOs and 3 DON'Ts

    DO

    • Make the document the dominant area of a writing screen.
    • Give the current task's action clearer emphasis than unrelated utilities.
    • Group several monitoring indicators around one clearly stated monitoring objective.

    DON’T

    • Give every card, badge, and button the same strong visual emphasis.
    • Add a dashboard above a form without a task-related reason.
    • Invent a primary action on a read-only monitoring page just for symmetry.
  • VIS-02 · Figure and ground. SHOULD. Make foreground content, controls, and overlays distinguishable from their surroundings through appropriate contrast, spacing, surfaces, and boundaries. Example: a dialog has a recognizable edge and a subdued backdrop without making its text faint. Review: inspect text, fields, focus, and selected states against their actual backgrounds in supported themes. Use the accessibility requirements in UX-14; a shadow alone does not establish adequate contrast or keyboard focus.
    Examples for VIS-02 · 3 DOs and 3 DON'Ts

    DO

    • Make a dialog's surface and boundary distinguishable from its backdrop.
    • Check field and text visibility against their actual theme backgrounds.
    • Use a visible focus treatment that remains clear on selected controls.

    DON’T

    • Rely on a faint shadow as the only boundary of an ambiguous control.
    • Reduce foreground text contrast merely to make the background look subtle.
    • Assume a selected state remains visible after changing the surface color.
  • VIS-03 · Similarity. SHOULD. Give elements with the same role consistent shape, typography, spacing, and interaction treatment. Make meaningfully different states or effects distinguishable. Example: equivalent primary actions share a component style; a destructive action has an explicit label and an appropriate distinct treatment. Review: compare the same action across screens and check for controls that look equivalent but behave differently. Do not rely on color alone or give every button equal visual weight.
    Examples for VIS-03 · 3 DOs and 3 DON'Ts

    DO

    • Reuse a consistent style for equivalent Save actions.
    • Distinguish destructive actions through explicit wording and appropriate visual treatment.
    • Use the same badge convention for the same status across screens.

    DON’T

    • Give identical-looking controls substantially different effects without explanation.
    • Change the visual meaning of a status color from page to page.
    • Make every action look primary regardless of its role.
  • VIS-04 · Proximity. SHOULD. Keep labels, help, errors, and actions close to the content they describe or affect. Make spacing within a group smaller than spacing between unrelated groups. Example: with a compatible spacing scale, a label might sit 8 px from its input while field groups are separated by 24 px; these are illustrative values, not universal thresholds. Review: after wrapping and mobile reflow, is each label or error still visibly attached to the correct field, and is a row action clearly local rather than global? See NN/g on proximity.
    Examples for VIS-04 · 3 DOs and 3 DON'Ts

    DO

    • Keep a field's label and error closer to it than to neighboring fields.
    • Separate unrelated form groups using the established spacing scale.
    • Keep row-level actions visibly associated with their affected row on mobile.

    DON’T

    • Place a field error nearer the next input than its own input.
    • Move a group heading away from its content during responsive reflow.
    • Position a row action beside global controls without clarifying its scope.
  • VIS-05 · Continuity. SHOULD. Use consistent alignment and a logical sequence to guide the eye through related information. Keep visual order aligned with reading direction, document order, and keyboard navigation. Example: an import flow presents source, options, preview, and execution in a clear sequence. Review: follow the task visually and with the keyboard at wide and narrow widths; look for unexplained jumps and detached actions. Do not force a left-to-right sequence on languages or workflows that require a different order.
    Examples for VIS-05 · 3 DOs and 3 DON'Ts

    DO

    • Align related fields so their sequence is easy to follow.
    • Keep visual order consistent with document and keyboard order.
    • Present import source, options, preview, and execution in an understandable progression.

    DON’T

    • Use CSS reordering that makes keyboard focus jump unpredictably across the screen.
    • Detach the next-step action from the current task flow.
    • Force left-to-right progression where the interface language requires another reading direction.
  • VIS-06 · Closure. SHOULD. Use implied visual boundaries only when the object or grouping remains recognizable. Closure concerns perceiving a complete form from incomplete visual information; it is not a general instruction to remove detail. Example: whitespace and alignment may group a summary without a border around every item. Review: can a reader still recognize the group and every available action? Keep necessary labels, field boundaries, status, and instructions explicit. Border removal is optional; restore a boundary when it clarifies meaning. See NN/g on closure.
    Examples for VIS-06 · 3 DOs and 3 DON'Ts

    DO

    • Use whitespace to group a recognizable summary without boxing every line.
    • Retain a boundary when removing it makes an input hard to recognize.
    • Check that a simplified icon remains recognizable at its actual display size.

    DON’T

    • Remove field labels and expect users to infer their meaning.
    • Treat closure as permission to hide required instructions.
    • Eliminate all borders even when adjacent groups become ambiguous.
  • VIS-07 · Common fate. SHOULD when motion is already useful. Elements that move together can communicate a shared operation or relationship. Example: selected rows moving as a group during reordering should retain their visible selection and move coherently. Review: does motion match the actual affected set, and does the same relationship remain clear when motion is reduced or absent? Prefer static selection, labels, and status when sufficient; do not add animation to satisfy this principle. Respect reduced-motion preferences and preserve a non-motion explanation. See W3C guidance on interaction animation, which describes an AAA criterion beyond this standard's AA baseline.
    Examples for VIS-07 · 3 DOs and 3 DON'Ts

    DO

    • Move selected rows coherently when the user reorders them as a group.
    • Keep selection labels visible when movement is reduced or disabled.
    • Use static status when motion adds no necessary explanation.

    DON’T

    • Animate every card solely to demonstrate the common-fate principle.
    • Move unrelated objects together and imply they share an operation.
    • Make motion the only way to understand which records were affected.

Applying these directions in an AI session. For relevant interface work, the assistant should name the user's task, identify the groups and action scopes, and choose the few principles that address an actual problem. Translate each choice into a component, layout, spacing, state, or behavior decision using existing design tokens. Inspect the rendered result with representative content, narrow layouts, keyboard operation, and relevant states. Record which checks were performed and unresolved ambiguity; a claim such as "Gestalt applied" is insufficient evidence. A screenshot supports visual observations but cannot establish keyboard behavior, accessible names, or motion preferences. Request user feedback when discoverability remains uncertain.

Example implementation brief: "For this settings form, group account fields separately from notification fields. Keep each label, helper, and error with its input and place Save with the settings it affects. Use the existing spacing scale, with larger gaps between groups than within them. Preserve those relationships on mobile and in the error state. Reuse the established primary-button style. Explain the grouping choices and verify the rendered layout and keyboard order."

These are compatible recommendations, not new mandatory adoption gates. Existing accessibility, security, truthful-state, and task-scope requirements still apply. During an audit, use these checks to document observed ambiguity and acceptance criteria without redesigning the application.

Common interaction scenarios

  • Settings: identify whether a setting is personal, project-wide, or global; show effective values and save state; distinguish stored from successfully tested configuration.
  • Login and recovery: separate signed-out, expired-session, invalid-credential, and service-unavailable states. Preserve recoverable work across reauthentication without exposing it to the wrong account.
  • First access and identity: distinguish display name, account identity, and permissions. Enforce required onboarding on the server where it controls access.
  • People and permissions: show roles in the correct resource scope; distinguish role assignment from membership and ownership. Explain the effect of revocation. Enforce the same rules in the API.
  • Restricted actions: distinguish missing permission from missing prerequisites. Provide useful recovery without revealing protected data.
  • Invitations and offboarding: model pending, accepted, expired, revoked, and removed states as applicable. Recheck access on the server and make outstanding-session behavior explicit.
  • Integrations and credentials: show connection state, scope, last verification, and actionable failures. Never reveal a stored secret merely to prove it exists.
  • Runs, schedules, and notifications: show the time zone, next run, actual status, and result when supported. Keep notification preferences explicit. Do not add background work merely because a pattern exists.

Verification and definition of done

  • QA-01 · Verify observable behavior. MUST. Test important business rules, authorization, failure paths, and likely regressions. Use realistic fixtures and temporary data. Tests should not simply restate the implementation or assert arbitrary file lengths/private helper names.
    Examples for QA-01 · 3 DOs and 3 DON'Ts

    DO

    • Test that a user cannot retrieve another workspace's protected record.
    • Verify a business calculation with meaningful input and expected outcomes.
    • Exercise a failed external write using controlled disposable fixtures.

    DON’T

    • Assert a private helper's name as proof of correct behavior.
    • Test only a successful path after changing permission handling.
    • Treat an arbitrary file-length limit as a functional regression test.
  • QA-02 · Match checks to the change. MUST. Run required project checks and relevant tests. UI work needs appropriate interaction, keyboard, viewport, long-content, and theme checks. Compilation alone is not evidence that an interface works. Small documentation changes need review and link checks, not an invented application test suite.
    Examples for QA-02 · 3 DOs and 3 DON'Ts

    DO

    • Check keyboard interaction and narrow layouts after changing a dialog.
    • Run focused behavior checks and required project checks for a logic change.
    • Review content and links for a documentation-only update.

    DON’T

    • Claim a UI works merely because the application compiles.
    • Create an application test suite solely for a corrected documentation sentence.
    • Repeat unrelated expensive checks after the relevant checks pass without new cause.
  • QA-03 · Keep evidence honest. MUST. Report what passed, failed, was not applicable, or was not tested. Separate known baseline warnings from new problems. Do not claim full coverage or a complete audit from a limited sample.
    Examples for QA-03 · 3 DOs and 3 DON'Ts

    DO

    • State that local checks passed while live-provider behavior was not exercised.
    • Separate pre-existing warnings from failures introduced by the change.
    • Describe the sampled audit scope and its evidence limits.

    DON’T

    • Report a complete security audit after reviewing only selected source files.
    • Mark a skipped check as passed.
    • Claim a deployment succeeded because an upload command was started.
  • QA-04 · Finish the handover. MUST. Explain the outcome, affected contracts, validation, remaining limitations, and whether anything was deployed. Update relevant setup instructions, source maps, examples, and comments.
    Examples for QA-04 · 3 DOs and 3 DON'Ts

    DO

    • Explain what changed, why, and which checks support the result.
    • Identify migration or compatibility requirements in the handover.
    • State the deployed version or clearly say that work remains local.

    DON’T

    • Finish with done while leaving a known deployment failure unexplained.
    • Omit a changed external contract from the release notes.
    • Leave another maintainer dependent on an unpublished AI conversation to continue.

A change is ready when its approved plan matches the implemented scope, the affected responsibilities remain understandable, security and data boundaries are preserved, relevant checks support the result, and another developer can continue from the dedicated documentation folder. Complete applicable ARCH-07 through ARCH-13 reviews, including size dispositions, boundary evidence, and a working reference feature where required. Reconcile the DOC-09 parameter register with the implemented values, effective constraints, and user-visible behavior; identify coverage gaps explicitly. Use structural checks for dependency policy and behavior tests for observable outcomes. Finish the technical journal with honest verification and deployment status, and the user changelog with practical effects and matching availability. Deployment requires authorization covering the release and target under DOC-07. Remaining debt is explicit rather than hidden behind a successful build.

Audit and exception format

Auditors collect and explain; implementation remains a separately scoped task. Every finding should include an ID, project/module, category, priority, confidence, exact evidence, observed behavior, impact, recommendation, acceptance criteria, relative effort, dependencies, and limitations. Separate confirmed defects, architectural preferences, and unresolved product-policy questions.

For a material exception, record the rule ID, scope, reason, consequences, compensating measures where relevant, owner, and revisit condition. A developer preference cannot silently waive an explicit user requirement. Existing debt does not authorize unrelated changes. Avoid numeric quality scores that imply precision the evidence does not support.

Versioning and adoption

This public reference uses semantic versions. Version 1.0.0 is the first public-ready edition. The revision date identifies this edition, not a claim that a website has already been deployed.

  • MAJOR: changes that break an established contract, tighten mandatory behavior incompatibly, or require a changed adoption policy.
  • MINOR: compatible additions, optional patterns, and guidance that preserve existing requirements.
  • PATCH: corrections, wording, examples, or links without changing the meaning of requirements.
  • Preserve released editions and changelog entries. Do not rewrite an older edition under the same version. Use stable rule IDs; record replacements/deprecations rather than quietly changing their meaning.
  • The stable page points to the current edition. Versioned paths identify exact editions. Pin the version for reproducible work and record it in the project source map or task handover.
  • Review new editions before adoption; do not silently apply changed requirements halfway through a task. New guidance governs relevant future work, while legacy debt is tracked deliberately.

License and attribution

Guideline content by Lucas Vitti, licensed under CC BY 4.0. See scope and attribution. This license covers the guideline material only; it does not license your applications. Please link the attribution to https://lucas.mat.br where reasonably practicable. The license notice explains scope, exclusions, and suggested credit.

Instruction for a development session

Copy this instruction and provide the page URL or attach its Markdown edition. Fill in the requested task; do not assume the URL is reachable until publication has been verified.

Reusable session instruction
Read Lucas Vitti's Development Guidelines, version 3.2.0, at:
https://lucas.mat.br/development-guidelines/versions/3.2.0/guidelines.md

Guideline material by Lucas Vitti (https://lucas.mat.br), licensed under CC BY 4.0: https://creativecommons.org/licenses/by/4.0/
Scope and attribution: https://lucas.mat.br/development-guidelines/versions/3.2.0/license.html
This licenses guideline content only; application licenses remain separate.

Also read the applicable repository instructions and project documentation.
Confirm which edition you actually read and apply the relevant requirements.
If the page is inaccessible, ask for the Markdown copy; do not claim to have read it.
Respect the task's scope and existing authorization. Audit-only tasks remain read-only.
Identify material conflicts or justified exceptions before the affected work.
Keep independent authorized work moving. Do not add features just to satisfy a pattern.
Before implementation, save and present an architecture and UX plan in the project's dedicated documentation folder, normally docs/.
Include the DOC-09 parameter register: all internal hardcoded behavior/policy values and configuration defaults, plain-language effects, exact values/units, source and enforcement, overrides, rationale, change impact, approval, and checks. Declare coverage and gaps.
Obtain explicit approval for its identified revision and scope; record the approver, date, and approval reference. Reuse approval covering unchanged scope.
Revise the plan and obtain renewed approval for material scope changes before the affected work.
Apply ARCH-07 through ARCH-13: define public boundary contracts, data/state ownership, allowed and prohibited dependencies, and keep handwritten source cohesive.
Demonstrate a new application's baseline through a small working feature; adopt incrementally for an existing application.
Use narrow external contracts and justified adapters; verify dependency restrictions and a relevant change-isolation scenario.
Record the source/version of any reusable starter, distinguish generated and project-owned files, and review upgrades.
Review touched files over 300 code lines and functions over 50; extract cohesive units or record a scoped exception before completion.
Report the final source map, size-review dispositions, dependency review, and relevant behavior checks.
For an audit, provide evidence-based findings and acceptance criteria without making fixes.
For interface work, translate relevant visual principles into concrete choices and verify the rendered result.
For new or materially changed pages/forms, document one main intent and where secondary tasks open.
Maintain the project design guide, source map, page inventory, approved plans, decisions, full technical version journals, and separate user changelogs in the dedicated documentation folder.
For every version, keep the full technical journal with evidence, compatibility impact, and honest release/deployment status. Also write a separate user changelog explaining practical changes, moved/removed controls or pages, fixes, affected users, and required actions in product language.
Use matching version identities, dates, and actual availability in both records. For internal-only releases, retain a user entry saying "No user-visible changes in this version." Preserve both histories and append dated corrections.
Reconcile parameter documentation with implementation and effective deployment constraints; explain changed limits/defaults in the journal without claiming proposals are deployed.
Before deployment, present the result and both changelogs and confirm authorization covers the release and target; plan approval alone does not authorize deployment.
An existing explicit approval may cover both plan and deployment; never infer approval from silence or the AI's own decision.
Avoid competing nested interactions; distinguish navigation, filters, view controls, task surfaces, and scroll owners.

Task: [describe the requested work and constraints]

A repository may keep this reference in its agent-instruction file, along with essential local rules for offline use. A local copy should record its version; never depend solely on a link that the session may be unable to fetch.