# Build interfaces around roles and intent

Resolve appropriate surfaces for people and agents while keeping authority on the execution side.

Source context: Source-guided
Source: https://github.com/lssm-tech/contractspec/blob/d58fa5b7de53a947811e5cc68346be028ce18528/packages/platform/ui/surface-runtime/src/rolemorph/resolver.ts

## Start with the task, actor and context

A reviewer, an operator and an agent may work on the same workflow while needing different information and actions. Model that difference explicitly instead of copying the entire workflow into unrelated screens.

RoleMorph resolves a contract-authored surface from supplied context. The resolver validates the context and registry bindings, removes invalid components and returns actions with their resolved boundaries.

## Make action states understandable

The resulting actions distinguish allowed, requires_approval and blocked states. For an AI agent, the resolver also builds a plan that separates those action lists and reports missing information from diagnostics.

Use these states to explain what a caller can attempt next. A reviewer may need an approval action; an agent may need a structured reason it cannot proceed. Avoid turning a hidden button into the sole enforcement mechanism.

| Surface behavior | Good use | Boundary |
| --- | --- | --- |
| Different data depth | Show the information needed for a role | Fetch and redact through trusted server rules |
| Review-required action | Explain the next approval step | Require evidence again at execution |
| Blocked action | Provide a useful reason or alternative | Do not execute through another unguarded route |
| Agent plan | Expose allowed and missing-information paths | The plan itself grants no authority |

## Design the unresolved state

An unknown or ambiguous surface match is a real product state. The resolver can return an unresolved result with diagnostics and no actionable components. Design a clear explanation and recovery path for that case.

A fallback screen should help the person choose a valid context or seek access. It should not silently replace missing policy context with a more permissive role.

## Test a small role matrix

Choose one workflow and compare the intended surfaces for two human roles and one agent actor. Verify the components, action states and explanations each receives. Include an invalid binding and an unknown role.

Then call the backend directly for an action hidden or blocked by the UI. The server must still enforce its policy and approval requirements. Surface resolution and execution authorization are complementary checks.

## Related examples

- [Adapt the view. Preserve the boundary.](https://lssm.co/examples/rolemorph-approvals/): Inspect role-specific approval surfaces where adaptive hints cannot grant authority.
- [Build a table from a data view](https://lssm.co/examples/data-grid-showcase/): Compare a declarative account table with the shared client and server controller surfaces.