Create a UI Surface

Workflow

Create a UI Surface

agent stardesign

Phase 1 — Context

Identify which feature, action, or event this UI serves. Verify that the target document exists in content/.

Determine the high-level layout container:

Author the surface block.

Use indentation for nesting.
Use literal strings for content (e.g., heading "Title Text", button Click Me or checkbox Remember me).
Use semantic components: stack, row, input, button, list, table.
Add placeholder tags for missing visual elements.

Define form fields, buttons, and navigation links. Ensure every primary action (button/link) corresponds to a requirement or domain action.

Present the complete .surface.mdoc draft for confirmation before writing. Output: content/uis/{id}.ui.mdoc

Do:

Identify which feature, action, or event this UI serves before designing
Use semantic components (stack, row, input, button, list, table) in the Pug DSL
Ensure every primary action (button/link) corresponds to a requirement or domain action
Use placeholder tags for missing visual elements that will be designed later
Present the full draft for confirmation before writing

Don’t:

Don’t use implementation-level components (React, Vue, etc.) in the Pug DSL
Don’t design a surface without a linked feature — surfaces always serve a feature
Don’t create interactive elements that have no backing requirement or domain action
Don’t mix tabs and spaces for indentation; inconsistent indentation breaks renders
Don’t skip the context phase; knowing what the UI serves shapes every design decision

Draft presented to user for confirmation
Document written as content/uis/{id}.ui.mdoc with correct frontmatter and root tag
for attribute links to an existing feature or domain document
Every primary action corresponds to a requirement or domain action
Indentation is consistent throughout
All cross-references resolve to existing documents
pnpm compile succeeds