Developing with an AI agent
Building a screen is largely a matter of following specifications. Button heights, table dividers, dark theme colors, the sentence to show when there is nothing to display — all of it has to stay consistent across the product, and there is more of it than a person cares to memorize.
The Logpresso Design System publishes those specifications in a form an AI agent can read directly. When you ask an agent to build a screen, tell it where the material is and the order to read it in, and it can look the specifications up as it implements.
This document is useful even if you do not use an agent, because it records where the design-system material lives and what you have to comply with.
Design-system reference material
The Logpresso Design System publishes the material below. Point an agent at the manifest first rather than at individual documents: the manifest indexes everything else.
| Purpose | Address |
|---|---|
| Manifest (entry point) | https://design.logpresso.com/design-system.manifest.json |
| Agent guide | https://design.logpresso.com/docs/AI-AGENT-GUIDE.md |
| Starter prompts | https://design.logpresso.com/agent-starters.json |
| Component index | https://design.logpresso.com/docs/components/components.md |
| Screen pattern index | https://design.logpresso.com/docs/patterns/patterns.md |
| Color token source | https://design.logpresso.com/sonar5.css |
| Token definitions | https://design.logpresso.com/docs/tokens/design-tokens.json |
| Accessibility baseline | https://design.logpresso.com/docs/accessibility/component-accessibility-matrix.json |
Take color values from sonar5.css. That file defines the variables the Logpresso Sonar web console itself uses, and an app uses the same names and values. design-tokens.json names its variables differently, so use it for typography and spacing specifications and for how tokens are classified. Following the design system explains the distinction.
The design system does not ship an installable component library. You read the material above and express the tokens and component specifications in your app's own stylesheet.
Reading order
The design system prescribes the order to read its documents in. A higher-level document sets the structure of the screen and a lower-level one sets the details of an individual component, so skipping ahead means missing the higher-level rules.
manifest → agent guide → screen pattern → parent composition → child component → foundation
One principle runs through that order: a parent composition owns the structure of the screen, and a child component owns its own specification. A higher-level document must not change a child component's specification. A document defining screen layout, for example, is not allowed to redefine button heights.
What you must comply with
Every screen has to handle six states. Building only the screen with data in it is the most common omission.
| State | Description |
|---|---|
| Default | Data displayed normally |
| Loading | Data is being fetched |
| Empty | There is no data to display |
| Error | The query failed; offer a way to retry alongside the message |
| Permission | The account cannot read or act on this because of permissions |
| Selected | The item currently selected in a list |
Word the empty state according to its cause. Getting no results because of a search condition and having no data at all lead the user to different next actions. Show the same sentence for both and the user cannot tell what to do.
Some things must never be filled in by guessing. An agent tends to fill blanks with something plausible, so forbid it explicitly.
- Design token values: do not invent a color or spacing value that is not in the documents.
- Component specifications: do not define an undocumented state or variant.
- Product copy, business rules, permission policy, API behavior: mark what is unconfirmed as unconfirmed.
Do not convey information through color alone. State, severity, and selection have to be distinguishable by text, an icon, or an accessibility attribute as well. Removing the keyboard focus indicator is also forbidden.
Do not use real customer data in examples. Accounts, IP addresses, host names, and credentials must not carry real values even in examples. Example IP addresses come from the ranges RFC 5737 defines (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24).
Screen patterns
The design system organizes frequently used screen structures into patterns. When you build a new screen, pick the closest pattern first, then read the documents that pattern points to in order.
| Category | Patterns |
|---|---|
| Screen structure | Dashboard, list-detail, settings and policy form, data table workflow, audit and event history, guided setup |
| Interaction | Bulk action, destructive action, loading feedback, optimistic update, form submission, inline editing, hierarchical navigation, empty state recovery, permission-based UI |
Each pattern comes with a starter prompt you can hand to an agent as-is. You find them at the agent-starters.json address in the table above. The list can change, so check the site for the current values.
Agent instruction file
Put an AGENTS.md file in the root of your app repository and an agent reads it when it starts work. That saves you from repeating the same rules in every conversation, so record what does not change — build contracts and the like — in this file.
Put the following in AGENTS.md.
| Item | Contents |
|---|---|
| App-specific values | App code, bundle name, Java package, connect profile type, REST address prefix |
| Directory layout | What goes in which directory |
| Build contract | Build steps and their order, plugins whose versions are pinned and why |
| Manifest rules | App code format, menu route format, required files |
| Screen behavior | Build base path, navigation messages, theme integration |
| REST API conventions | Address rules, how the session is passed |
| Design system | Reference addresses and reading order, specifications that are easy to get wrong |
| Prohibitions | The list of what not to do |
| Verification | What to run and what to check |
Keep the app-specific values in a table near the top of the file. When you reuse the file for another app, that table is all you have to change.
| | |
| --- | --- |
| App code | `sample` |
| Bundle symbolic name | `com.logpresso.sonar.sample` |
| Java package | `com.logpresso.sonar.sample` |
| Connect profile type | `sample` |
| REST endpoint prefix | `/sonar/sample` (browser: `/api/sonar/sample`) |
| UI dev port | 6100 |
You find a written example in the sample app repository's AGENTS.md. Copy it into your own app repository and change only the app-specific values.
Claude Code also reads a CLAUDE.md file. Putting the same content in both files makes it easy to update one and leave the other behind, so keep a single line in CLAUDE.md.
See [AGENTS.md](AGENTS.md) for build, runtime, and design-system contracts.
Prompts for each step
Each document in this chapter ends with a prompt for delegating that step to an agent.
| Step | Prompt location |
|---|---|
| Creating a UI project | Creating a UI project |
| Diagnosing build problems | Building and installing a UI |
| Registering menus | App manifest and menus |
| Implementing navigation | Screen routing |
| Connecting server data | REST API plugin |
| Reviewing design specs | Following the design system |
Always install what an agent builds on a real Logpresso Sonar instance and check it there. A build passing and the code looking plausible is a separate matter from the screen actually working. Dark theme switching, the browser back button, and the state with no data in particular cannot be verified without running it.
The next section explains how to add a UI project to an app.