Skip to content
Agon ĀtriumAgon Ātrium

Source code

Open source page

Frontend guidance

  • Read component contracts for reusable behavior and theming for visual changes.
  • Use Alpine’s CSP build, named providers, Alpine Router, Bootstrap SCSS, Vite, and Yarn. Alpine owns interaction. Do not initialize Bootstrap JavaScript on the same controls.
  • Follow coding standards for all maintained JavaScript, configuration, tests, source headers, and formatting ownership.
  • Provide a dedicated guide in docs/components/ for each reusable component, including a copyable integration example, settings, lifecycle, and consumer responsibilities. Keep the index and working showcase synchronized.
  • Document every callable with its own directly attached multiline JSDoc, including anonymous callbacks, arrow functions, test bodies, fixtures, empty functions, methods, constructors, and lifecycle hooks. Include a clear purpose, a blank line before tags, typed and described parameters, return contracts, and stable thrown failures. Enclosing documentation never substitutes for a callback’s own block.
  • Use multiline braced control flow. Allow compact arrays, objects, destructuring, named exports, function parameters, and arguments when readable. Expand long or complex expressions consistently and forbid trailing commas in every JavaScript list. Keep spaces inside nonempty array brackets and object braces. Separate independent control-flow statements, function declarations, and multiline variable declarations with an empty line. Keep else, catch, and finally attached to their owning chain. A terminal action followed by return may remain a single exit sequence.
  • Keep complete import declarations on one line, including multiple named bindings and aliases. Keep short named exports compact and allow long exports to wrap. Enforce the import convention with the repository ESLint gate. Place multiline explanatory comments above imports.
  • Scope ESLint globals by execution environment. Browser modules must not inherit Node globals. Node ES modules use globals.nodeBuiltin. Grant DOM globals additionally only to explicit Happy DOM tests, their DOM helper, and browser automation containing page callbacks. Keep the runtime-scope regression tests synchronized with new source locations.
  • Never explicitly throw inside a protected try body. Calls may throw naturally, and a catch handler may translate failures when it is outside another protected body.
  • Use periods rather than semicolons in source comments and JSDoc prose. Begin each new sentence with an uppercase letter. Keep code syntax intact and check prose with yarn lint:prose.
  • Require a clear file purpose, one blank comment line, @author Laurent Declercq l.declercq@agon-innovation.ch, and a valid @version YYYYMMDD header in JavaScript, CSS/SCSS, HTML, and comment-capable configuration. JSON and .nvmrc keep their native comment-free syntax.
  • Enforce ESLint’s JSDoc rules. Do not silence correctness checks merely to pass a gate. Avoid shadowed or redeclared bindings.
  • Prefer focused modules, explicit dependencies, and public extension points. Preserve accessible names, keyboard behavior, focus handling, loading/error/empty states, and teardown.
  • Keep route templates to one root element. Load route templates and their controller registration modules on demand through the generated page registry. The persistent entry document contains shell markup and page outlets only. Compile trusted HTML at build time. Never inject untrusted content through x-html.
  • Use theme tokens and Bootstrap SCSS overrides. Preserve light/dark modes, palette changes, logical direction, mobile navigation, and pinned/docked/scroll layouts.
  • Verify production CSP separately from Vite development. Scripts must work without inline scripts or unsafe-eval. Current dynamic styles require the documented inline-style allowance.
  • Keep .mjs for executable build/check configuration and .js for source modules. Workspaces declare type: module.
  • Use ESLint Stylistic for JavaScript and Prettier for other maintained formats. Run yarn format and verify its second run makes no further edits.

Author

Laurent Declercq l.declercq@agon-innovation.ch

License

Unless otherwise stated all source code is licensed under LGPL 2.1 and has the following copyright:

© 2026, Agon Partners Innovation AG, All rights reserved.

The design material and the “Agon Ātrium” trademark is the property of their authors. Reuse of them without prior consent of their respective authors is strictly prohibited.

Version

Version: 20260921