The example app

init my-app --example writes it (see Installation). The app is in the repository IngeniozIT/caits-example, not in the package of CAITS: init gets it with git, at the tag of its version.

What the app does

• A home page and a page Example (/messages), with the same menu. The menu marks the page that shows. Each page has its title: CAITS, and Example · CAITS.
• The home page lists the checks of the harness, the first steps, the daily commands, and a prompt for an AI agent. A button copies each command, and the prompt. It then says "Copied", or "Copy failed" when the browser refuses the clipboard.
• A button of the menu switches between the light theme and the dark theme.
• On the Example page, the user adds, edits and removes messages. A message has 1 to 280 characters, without the spaces around it. An emoji counts as one character.
• The backend keeps the messages in the file tmp/messages.json of the project (or in the folder DATA_DIR, when it is set and not empty).
• If the backend refuses a change (for example an empty message), the page shows why, and keeps what the user typed.
• With the keyboard, the focus goes where the user acts next after each change. A status tells the screen readers each change that succeeds.
• Until the user picks a theme, the pages follow the setting of their system: light or dark.

The path of a new message

MessageBoard.marko                      the view publishes MessageAdditionRequested
  → messagesStore.ts                    the store sends an AddMessageCommand (frontend DTO)
  → add-message.handler.ts (frontend)   the handler calls the MessagesGateway port
  → http-messages-gateway.ts            the adapter posts the text to /api/messages
  → routes/_backend/api/messages        the route gives the request to the controller
  → add-message-http.controller.ts      the controller sends an AddMessageCommand (backend DTO)
  → add-message.handler.ts (backend)    the handler asks the domain, then the MessageRepository port
  → Message.ts                          the domain refuses an empty text, or a text that is too long
  → file-message-repository.ts          the adapter keeps the message in tmp/messages.json

The answer goes back the same way. The frontend handler publishes MessagesChanged or MessagesChangeFailed. The store keeps the result, and after a change it asks for the messages again. The view shows the new list, or the reason for the refusal.

An edit (PUT /api/messages/{id}) and a removal (DELETE /api/messages/{id}) go the same way. How CAITS works draws this path, step by step, on each side.

The files

The design

The design takes the two colors of the logo, indigo and teal, on a paper of warm stone, or of ink in the dark. This part shows how its styles are organized: copy this shape for your own app.

The styles are in SCSS files, apart from the HTML (see Write the styles). The layout imports style/app.scss, the CSS of all the pages, which loads the partials of style/, in this order:

_values.scss gives the widths ($page, $narrow, $phone) and the grain of the paper ($grain) to the stylesheets of the routes, and no CSS.

Each page, each component and the view import their own stylesheet, next to them:

Each class of a page, a component or a view starts with its name: home-page__hero, logo__arch, theme-switch__moon, message-board__composer. The build makes three CSS files: one for all the pages, one for the home page, and one for the page Example.

• The fonts: Instrument Serif for the titles, Geist for the text, Geist Mono for the code and the labels. init --example adds their packages (Fontsource) to the dependencies. The build puts the files of the fonts in the app: the pages load nothing from another site.
• The theme: the colors follow the system of the user, until the user clicks the button of the theme. The button puts data-theme="light" or data-theme="dark" on <html>, and keeps the choice in the cookie theme. The layout reads this cookie: the server sends each page in the theme of the user, so a page never shows the other theme first. The layout also gives the theme to the button, and the icon of the button comes from light-dark(), which reads the theme: the button is right before the page runs any script.
• The motion: the blocks of a page rise into place; on the home page, the logo draws itself, takes its colors, then floats; a new message rises into the list; while a change is on its way, a light runs under the form. The users who ask for less motion (prefers-reduced-motion) see no motion.
• The busy board: while a change is on its way, the view puts aria-busy="true" on the board. The styles use it, and the screen readers tell it.
• The focus and the status: Edit gives the focus to the field of the editor. Save and Cancel give it back to the button Edit of the message. After a removal, it goes to the message after, else to the message before, else to the field of the addition. A change that fails gives it back to where the user was. A status, which takes no place on the screen, tells the screen readers "Message added.", "Message changed." or "Message removed.". The buttons Edit and Remove of a message are described by its text.
• The contrast: each color of text has a contrast of 4.5:1 or more on the paper and on the surface (_theme.scss). A field that has the focus keeps its outline.
• The icon of the tab: the logo, in the page (an address data:), in the colors of the theme of the system.

The menu marks the page that shows: the layout reads the route in $global.route, and gives aria-current="page" to the link of this route.

The tests

The example passes all the checks of a new project: the architecture rules, 100% coverage and 100% mutation score.

With one backend context, nothing needs a context map yet: the integration test, src/backend/context-map.integration.test.ts, waits next to the place of the map. When a second context reacts to the events of the first, write the map in src/backend/context-map.ts (see Connect two contexts).

Remove the example

When you know the example, remove it, and keep the harness:

1. Remove the contexts and their routes: src/backend/messages/, src/frontend/messages/, src/routes/_backend/api/messages/ and src/routes/_frontend/messages/.
2. Remove their tests: src/backend/context-map.integration.test.ts and test/e2e/messages.spec.ts.
3. In src/routes/_frontend/+layout.marko, remove the Example link of the menu, and the entry "/messages" of titles.
4. Change the home page, src/routes/_frontend/+page.marko: its step "Try the example" leads to /messages. Its text and its prompt for an AI agent name messages too. When you change what test/e2e/home.spec.ts checks, such as the prompt, change the test with it.
5. Change the logo, and the fonts, or remove them: the packages @fontsource… in package.json, and their @use in app.scss.
6. Run npm run check.