AI design workflow

Use for agent-driven UI work: new components, shell visual tweaks, new apps, iframe/micro-app embeds, changes to @prox-os/os-ui or @prox-os/design-tokens, dashb

When to use this doc

Use for agent-driven UI work: new components, shell visual tweaks, new apps, iframe/micro-app embeds, changes to @prox-os/os-ui or @prox-os/design-tokens, dashboards, settings, internal “store” or monitor surfaces, architecture tooling UI, etc.

Read before writing UI

DESIGN.md — posture, strong vs weak domains, anti-patterns summary
Task-specific:
- Shell chrome / desktop / windows → os-shell-design-language.md
- Apps / embeds → app-design-language.md
- Tokens → tokens.md
AGENTS.md — package boundaries and repo completion rules

Optional skill: .agents/skills/prox-design-engineer/SKILL.md (routing only — does not replace the docs above).

Expected outputs

UI that respects token-backed colors, borders, radii, shadows where applicable
No new shell–app coupling; apps use contract + public packages
Incremental changes: avoid unrelated refactors and visual drive-bys
English for new user-visible copy in the shell unless it belongs in apps/os-shell/src/i18n/languages/* (add keys to en.ts and mirror locales as needed). See AGENTS.md → Repository Language.
When behavior or boundaries change, update the smallest relevant docs/architecture/* or docs/design/* file — do not paste the entire spec into chat or skills

Anti-patterns

Landing tropes: blue/purple gradients “hero”, three equal feature cards, gigantic marketing type in tool surfaces
Trust theater: fake quotes, fake logos, emoji substitutes for real app icons in product chrome
Decorative skeuomorphism: stacked fake window screenshots purely for aesthetic
Architecture smells: importing apps/os-shell/src/** from shared packages or standalone apps; putting server data in Zustand in the shell pattern reserved for local OS UI state
Maintainability: one giant prompt or markdown blob that duplicates every rule instead of linking to DESIGN.md

Verification

Run repo checks from package.json (e.g. pnpm lint, pnpm typecheck, pnpm arch:check; broader: pnpm quality when appropriate)
For shell layout or chrome, smoke in browser when feasible
Respect AGENTS.md: avoid visual changes when the task is docs-only or mechanical