Design and UX

OPB Brain has one visual system and two registers. Read this section before changing a page, component, email, chart, form, state, or user-facing string. DESIGN.md is normative. These pages publish its contract without replacing it.

What the examples are

The worked examples name Task, Agent and Event because those are the records this product is built around. They are specified, not shipped: the entities live in the domain model and the agent interfaces, and apps/app has no Task route yet. Read every example below as the contract for building those surfaces, never as a description of a page you can open today. The tokens, primitives and accessibility rules are the opposite — they are shipped, and the tests in __tests__/design-docs-drift.test.ts fail if these pages name one that is not.

Rule

Build in this order:

1. Identify the register. product covers the authenticated app and Storybook. brand covers the website, documentation, and email.
2. Name the information and state the surface must expose.
3. Choose an existing pattern and primitive.
4. Resolve every visual choice through a token.
5. Write empty, loading, error, and success behavior together.
6. Verify both themes, the keyboard path, reduced motion, and agent readability.

The product register spends space on information. The brand register spends more space on argument and long-form reading. Both use the same tokens and the same accessibility contract.

Token contract

Start with colors.surface, colors.on-surface, spacing.gutter, spacing.reading-max, typography.ui-md, and typography.body-md. Continue into the specific component recipes only after the information structure is correct.

Correct example

A Task collection uses ruled rows, written status, mono identifiers, and one primary action. Empty, loading, and error states are specified before the success state is called complete. The page consumes existing list, badge, button, and type tokens.

Rejected example

A generic dashboard starts with a grid of identical cards, invents a colour for each status, hides identifiers, and adds a modal for the primary flow. It chooses a visual template before it understands the record.

Reasoning

The product is a system of record, not an execution simulator. Read the personas and the visual-language reasoning before making a new composition.

Continue

• Tokens: the complete normative token catalogue.
• Typography: interface, reading, and machine truth.
• Layout: rhythm, measure, grids, and density.
• Components: recipes and primitive ownership.
• Patterns: collections, details, forms, overlays, and charts.
• Motion: state change without spectacle.
• Accessibility: the WCAG contract in both themes.
• Voice: element copy and self-describing errors.
• Agents: deterministic, context-efficient browser rendering.