Your first Atrium page

You do not need to rebuild the dashboard shell. Start with the working starter, add a page, and choose components from the library.

Start in your generated application

Complete application integration first. From your frontend root, run yarn dev and keep the server running while following this guide. The starter uses port 5174 and the showcase uses port 5173. Stop the process with Ctrl+C when finished.

Examples below use the starter layout. In a showcase-derived application, the route file is config/routes.js instead of routes.js. Add the route to an existing navigation group or add the workspace group to your configuration. Your source files belong to this application, not to Atrium’s development repository.

Add one page

Create example.html:

<!--
Present the application's first component example.

@author Laurent Declercq l.declercq@agon-innovation.ch
@version 20260921
-->
<section>
  <h1 tabindex="-1">My first page</h1>
  <article class="card">
    <div class="card-body">
      <p>The shell, navigation, and theme are already available.</p>
      <button type="button" class="btn btn-primary" @click="$store.toasts.push('It works!')">Try a notification</button>
    </div>
  </article>
</section>

Add this object to the routes array in routes.js, before the final wildcard route:

{
  path: '/example',
  label: 'example',
  icon: 'layers',
  group: 'workspace',
  template: 'example.html',
},

Extend each locale in the messages object in main.js with your own label:

messages: {
  en: {
    ...en,
    example: 'My first page',
  },
  fr: {
    ...fr,
    example: 'Ma première page',
  },
  de: {
    ...de,
    example: 'Meine erste Seite',
  },
  it: {
    ...it,
    example: 'La mia prima pagina',
  },
},

Visit /example. The page should appear in the sidebar. Press the button to show a notification. The page is loaded on demand without reloading the document.

Add component behavior

For a static component, copy its HTML example into your page. Shared providers such as uiTabs, uiAccordion, and uiDialog are already available.

For a component needing data or an adapter, create a JavaScript file beside the page, export register(context), and add module: 'example.js' to that route. The map guide demonstrates a complete module and template. Replace the provider and filename with the component you need.

Keep one root element in each route template. Use a provider’s init method to start requests or timers and destroy to stop them. Use x-text for backend text. Do not render untrusted HTML.

Change the appearance

Use the customizer for runtime preferences. Edit the public Sass configuration in theme.scss for your product’s defaults. Follow the theming guide for color palettes, sidebar dimensions, and surface tokens.

Build and integrate

Run yarn build from your application root to build your frontend into dist/. yarn build:development produces readable development output. Production builds minify HTML, JavaScript, and CSS and remove source headers from distributed HTML.

Use backend integration for real data and deployment for hosting and application acceptance. The component index links to dedicated settings and examples. Atrium’s own repository checks belong to its separate maintainer guide.

If something does not work

• A page is missing. Check its route path, template filename, group, and position before the wildcard route.
• A provider is unknown. Check the route’s module field and its exported register function.
• An include cannot be found. Application include paths are relative to the application root, and shared includes use uiRoot.
• An expression fails under CSP. Move complex logic and DOM property assignments into a documented provider method.
• A map is blank. Give its host a height and supply geometry or authorized tiles. The minimal map has no implicit tile provider.
• A remote console cannot connect. Verify the backend adapter, authorization, WebSocket URL, and deployment CSP. Atrium itself is not an SSH or VNC server.
• A caption track fails. Serve a VTT file with text/vtt and keep the import external using ?no-inline.

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