Heyeddi design

HeyEddi Design

End-to-end UI design for HeyEddi apps: discovery, briefs, critique, craft, and polish within PrimeVue, .heyeddi/design.md, and semantic CSS tokens. OpenProps is the HeyEddi scaffold default but not mandatory: detect token source per reference/token-strategy.md.

You do not need design vocabulary from the user. Plain intent ("enterprise view for our app") is enough: ask questions until direction is clear.

Subagents (default)

Delegate by sub-command: see reference/subagents.md. Main chat confirms briefs and merges results.

Always delegate	Subagent
@visual-auditor / Playwright	shell
validate_vue, npm test, build	shell
critique, craft, polish (route work)	generalPurpose
research, wireframe explore	generalPurpose
Codebase scan for document	explore

Do not run visual capture inline during craft/handoff turns.

Cross-pillar sync (mandatory)

Read reference/cross-pillar-handoff.md. Bookend craft, critique, polish, shape (confirmed brief):

@heyeddi-orchestrator  load_workflow_context --route /path
… design work + Decision log in design.md …
@heyeddi-orchestrator  append_pillar_opinion --pillar design …
→ @heyeddi-product scope check; @ux-flow-auditor flow note if IA affects tasks

Setup (every session)

1. Run python scripts/load_context.py --project-root <root> once per session (skip if output is already in the conversation).
2. If product_exists is false and the task needs strategic context, run init before shape/craft.
3. Read the sub-command reference file for the invoked mode (required: do not skip). 3a. Read reference/surface-completeness.md once per session when shaping, crafting, or critiquing any route: design full surfaces, not happy-path minimums. 3b. Read reference/foundations.md once per session: responsive, theme, i18n, a11y, reading modes are always on unless product.md waives them. 3c. Read reference/token-strategy.md when styling: detect OpenProps vs custom tokens before writing CSS. 3d. Read reference/modern-reference.md when shaping or crafting marketing, dashboard, or settings routes: avoid plain admin-template output. 3e. Read reference/audience-design.md when shaping, crafting, or polishing any user-facing route: tie direction to product.md personas. 3f. Read reference/design-ambition.md when shaping, crafting, or polishing flagship routes: project-specific signature and impressive craft bar (default; do not wait for user to ask). 3g. Read context/PROSE_ANTI_SLOP.md once per session when writing UI copy (Vue strings, locale files, product.md voice): no em/en dashes, no AI filler.
4. After craft, polish, critique (when leading to polish), or shape (brief confirmed), append to Decision log in .heyeddi/design.md per reference/design-talk.md: cite primary persona + pattern borrowed + memorable detail for this project.
5. After implementation, run reference/audience-fit.md on flagship routes before calling done.
6. Chain @primevue-openprops-architect validation and full @visual-auditor fix loop (review vs spec → fix → document) at 375/768/1440.

Commands

Command	Purpose
(no sub-command)	Vague design request → start discover
init	Create or refresh PRODUCT.md; offer document for DESIGN.md
discover	Discovery interview only: no code, no final brief yet
research	Web trend / reference research for current design direction
explore	Concept images + wireframes after discovery
shape	Full planning flow: discover → research → explore → confirmed brief
document	Generate or refresh DESIGN.md from code or seed questions
craft	Build a screen in Vue (runs shape first if no confirmed brief)
critique	UX review of existing UI: write report, no code unless asked
polish	Refine an existing route (after critique)

Visual proof always delegates to @visual-auditor via Task (shell subagent): see reference/subagents.md.

Routing rules

1. Existing UI: critique or improve ("critique", "review", "what's wrong", "looks bad", "ugly", "fix this page", "polish the login"): load reference/critique.md first. If user wants fixes in the same turn → critique, then reference/polish.md. Do not start greenfield discover when code already exists for the target route.
2. No sub-command, vague greenfield ("enterprise view", "design the settings area" with no existing screen): load reference/discover.md. Do not jump to code.
3. Sub-command matches table above: load reference/<command>.md and follow it. Remaining words are the target/brief.
4. craft without a confirmed design brief: pause and run shape (full flow) first; resume craft only after explicit brief confirmation. 4b. craft on flagship routes (/, /login, /dashboard, /settings): if load_context reports audience_ready: false, stop: @heyeddi-intake or discover first.
5. polish without critique this session: run critique first, then polish.
6. init blocker: if load_context reports missing PRODUCT.md and the task is net-new or strategic, complete init then resume the original command.
7. Screenshots / approved mockups provided: stop: tell the user to use @heyeddi-handoff instead.
8. Never invoke impeccable: this skill replaces it for the HeyEddi stack.

Artifacts

Artifact	Location
Design brief (confirmed)	.heyeddi/designs/<feature>/brief.md
Wireframes	.heyeddi/designs/<feature>/wireframes/
Research notes	.heyeddi/designs/<feature>/research.md
Concept direction	Chat images + summary in brief
Design system	.heyeddi/design.md: DESIGN.md format; see Superhuman example
Product context	.heyeddi/product.md (legacy: root PRODUCT.md)
Skill reports, critiques	.heyeddi/docs/ (critique reports, ship notes, audits)

Use kebab-case for <feature> (e.g. enterprise-settings).

Stack constraints

• Foundations: responsive, system light/dark, en+es i18n, WCAG 2.2 AA, dyslexia reading mode option: see reference/foundations.md.
• Tokens: semantic CSS variables from project tokens.css / DESIGN.md: OpenProps when the project already uses it; custom :root vars otherwise (reference/token-strategy.md). No raw hex in Vue/CSS unless documented exception.
• Components: PrimeVue from project catalog in DESIGN.md; no duplicate wrapper components.
• Register: product (app UI) vs brand (marketing) from PRODUCT.md: shapes density, nav patterns, and polish level.

See context/VOCABULARY.md, context/ANTI_PATTERNS.md, context/PROSE_ANTI_SLOP.md, context/EXAMPLES.md, and reference/foundations.md.

When the task is complete: suggest next skills

When you have finished the user's request for this skill (not after every tool call or subagent phase), suggest what to run next:

1. Run:

   python .agents/skills/heyeddi-orchestrator/scripts/suggest_next_skill.py --current-skill heyeddi-design --project-root .
   

   Add --route /path if you worked a specific route.

2. Include the script's ### Next step block in your final reply. The user copies the Prompt line into chat (e.g. @heyeddi-design craft /settings).

Pass --mode shape (or craft, audit, etc.) when you know which sub-command just finished.

See @heyeddi-orchestrator → reference/next-skill-handoff.md.