Audit a UI Surface

Workflow

Audit a UI Surface

agent stardesign

Fetch Before Auditing

get_document("surface/{id}")
get_document("{linked-type}/{linked-id}")    ← the id from the ui's `for` attribute
get_instructions("starspec/agents/conventions/naming-standards")

1. Frontmatter

type: ui is set
id is kebab-case with no type prefix (correct: login-screen, wrong: surface:login-screen)
title is present and human-readable
status reflects actual completeness — do not promote past the current state
context includes the linked feature id so the agent bundle gets TLDR context

2. Feature Linkage

surface has a for attribute
The for value is a valid qualified id that exists in content/
The linked document is review or ready status — a surface linked to a draft feature is premature
Every primary action (button, form submit, navigation link) corresponds to a domain action or requirement in the linked feature

Flag any interactive element that has no backing requirement.

3. DSL Structure

Indentation is consistent throughout — mixed tabs and spaces produce broken renders
The outermost container is section, nav, card, or modal — not a layout primitive like stack
card and modal are not nested directly inside each other without a layout container
tabs, accordion, and stepper contain only their expected child types (tab, panel, step)
table contains at least one column child
list has an item attribute describing what is repeated

4. Accessibility

Every input, select, checkbox, and slider has a label attribute
Every button has a label or text content
Every nav link has a label attribute
Every tab, panel, and step has a label attribute
placeholder elements are not used in place of required interactive content

5. Placeholders

Every placeholder has both a type and a label
For status: review: every placeholder has a comment or note explaining why it is still deferred
For status: ready: no placeholder elements remain unless the surface explicitly documents a region as intentionally undesigned

6. Naming Coherence

surface id is plain kebab-case with no type prefix: id="login-form"
UI file id matches the document id in frontmatter

Reporting Format

For each failed check, report:

Section and check number
Current value (what is there now)
Required fix (what it should be)

Group all violations before proposing any fixes. Present the fix plan for confirmation before editing.

Do’s and Don’ts

Do:

Work through every audit section in order before reporting
Report all violations before proposing any fixes
Fetch the linked feature and naming standards before auditing
Present the fix plan for confirmation before applying any changes
Group violations by section for clear reporting

Don’t:

Don’t fix violations as you find them; collect all violations first, then propose a fix plan
Don’t promote a surface past its actual completeness level
Don’t skip the accessibility checks — they are as important as structural checks
Don’t accept placeholder elements in ready status unless explicitly justified
Don’t audit a surface without its linked feature document loaded

Definition of Done

All audit sections checked in order
All violations reported with section number, current value, and required fix
Fix plan presented to user for confirmation
Fixes applied only after user confirmation
All cross-references resolve to existing documents
pnpm compile succeeds after fixes