HeyEddi Design
Stack-agnostic UI design for HeyEddi apps: discovery, briefs, critique, and design-system documentation. Implementation (Vue, Flutter, CSS in components) belongs to stack skills — see reference/implement-routing.md.
Calm wow: when users ask for modern / wow / living UI, read reference/modern-reference.md and reference/aesthetic-direction.md (Calm wow for B2B) before shaping.
You do not need design vocabulary from the user. Plain intent ("enterprise view for our app") is enough: ask questions until direction is clear.
Design vs implement (mandatory split)
| Layer |
Skill |
Delivers |
| Design (this skill) |
@heyeddi-design |
Briefs, wireframes, critique, design.md, IA, aesthetic direction |
| Implement (stack) |
@heyeddi-handoff, @design-handoff-flutter |
Production UI code in Vue / Flutter |
| Enforce (stack) |
@primevue-openprops-architect |
Vue tokens + PrimeVue guardrails |
| Verify (agnostic) |
@visual-auditor, @ux-flow-auditor |
Screenshots, contrast, flows, fixes |
Read reference/implement-routing.md every session that ends in shipped UI.
Default behavior (no confirmation)
- Critique + fix: "looks bad", "fix this page", "improve UI" → critique report then stack implementer fixes code then
@visual-auditor — do not ask
- Craft: confirmed brief → hand off to stack implementer in the same workflow
- Ambition bar: impressive craft is default on flagship routes — do not wait for user to ask
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 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)
- Run
python scripts/load_context.py --project-root <root> once per session (skip if output is already in the conversation).
- If
product_exists is false and the task needs strategic context, run init before shape/craft.
- Read the sub-command reference file for the invoked mode (required: do not skip).
3a. Read
reference/implement-routing.md when shaping, crafting, critiquing, or polishing any route.
3b. Read reference/surface-completeness.md once per session when shaping, crafting, or critiquing any route.
3c. Read reference/foundations.md once per session: responsive, theme, i18n, a11y, reading modes are always on unless product.md waives them.
3d. Read reference/modern-reference.md when shaping marketing, dashboard, or settings routes.
3e. Read reference/audience-design.md when shaping, crafting, or polishing any user-facing route.
3f. Read reference/design-ambition.md on flagship routes.
3g. Read reference/aesthetic-direction.md on any user-facing route.
3h. Read context/PROSE_ANTI_SLOP.md when writing UI copy in briefs or design.md.
3i. Read reference/visual-tools.md during explore, shape, and critique on flagship routes: use GenerateImage for direction probes and Canvas for compare/brief/critique summaries when the IDE provides them.
- After shape (brief confirmed), critique, or polish, append to Decision log in
.heyeddi/design.md.
- After stack implementer finishes, ensure
@visual-auditor ran at 375/768/1440 before calling design work done.
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 (GenerateImage) + Canvas compare + wireframes |
shape |
Full planning flow: discover → research → explore → confirmed brief |
document |
Generate or refresh DESIGN.md from code or seed questions |
craft |
Brief ready → hand off to stack implementer (see implement-routing) |
critique |
UX review of existing UI → report → auto-chain implement + visual-auditor |
polish |
Design-spec refinement + stack implementer for code (after critique) |
Routing rules
- Existing UI: critique or improve ("critique", "looks bad", "fix this page"): load
reference/critique.md → implement + @visual-auditor in the same workflow. Do not ask.
- No sub-command, vague greenfield: load
reference/discover.md.
- Sub-command matches table: load
reference/<command>.md.
craft without confirmed brief: run shape first.
4b. Flagship routes without personas: @heyeddi-intake or discover first.polish without critique this session: run critique first.- Screenshots / approved mockups:
@heyeddi-handoff (implement), not design craft code.
- Never invoke impeccable: this skill replaces it.
Artifacts
| Artifact |
Location |
| Design brief (confirmed) |
.heyeddi/designs/<feature>/brief.md |
| Wireframes |
.heyeddi/designs/<feature>/wireframes/ |
| Research notes |
.heyeddi/designs/<feature>/research.md |
| Design system |
.heyeddi/design.md |
| Product context |
.heyeddi/product.md |
| Critiques, audits |
.heyeddi/docs/ |
Use kebab-case for <feature>.
Foundations (design spec — implementer enforces in code)
Responsive, light/dark, en+es i18n, WCAG 2.2 AA, semantic tokens: see reference/foundations.md, reference/token-strategy.md.
See context/VOCABULARY.md, context/ANTI_PATTERNS.md, context/PROSE_ANTI_SLOP.md, context/EXAMPLES.md.
When the task is complete: suggest next skills
python .agents/skills/heyeddi-orchestrator/scripts/suggest_next_skill.py \
--current-skill heyeddi-design --project-root .
Add --route /path and --mode <sub-command> when known.
1---2name: heyeddi-design3description: Stack-agnostic UI design: discovery, briefs, critique, design system docs. Uses GenerateImage + Canvas to show direction during explore/shape. Implementation via @heyeddi-handoff or @design-handoff-flutter. Auto-fix on critique. Screenshots → @heyeddi-handoff.4---56# HeyEddi Design78**Stack-agnostic UI design** for HeyEddi apps: discovery, briefs, critique, and design-system documentation. **Implementation** (Vue, Flutter, CSS in components) belongs to stack skills — see `reference/implement-routing.md`.910**Calm wow:** when users ask for modern / wow / living UI, read `reference/modern-reference.md` and `reference/aesthetic-direction.md` (**Calm wow for B2B**) before shaping.1112**You do not need design vocabulary from the user.** Plain intent ("enterprise view for our app") is enough: ask questions until direction is clear.1314## Design vs implement (mandatory split)1516| Layer | Skill | Delivers |17|-------|-------|----------|18| Design (this skill) | `@heyeddi-design` | Briefs, wireframes, critique, `design.md`, IA, aesthetic direction |19| Implement (stack) | `@heyeddi-handoff`, `@design-handoff-flutter` | Production UI code in Vue / Flutter |20| Enforce (stack) | `@primevue-openprops-architect` | Vue tokens + PrimeVue guardrails |21| Verify (agnostic) | `@visual-auditor`, `@ux-flow-auditor` | Screenshots, contrast, flows, **fixes** |2223Read **`reference/implement-routing.md`** every session that ends in shipped UI.2425## Default behavior (no confirmation)2627- **Critique + fix:** "looks bad", "fix this page", "improve UI" → critique report **then** stack implementer fixes code **then** `@visual-auditor` — do not ask28- **Craft:** confirmed brief → hand off to stack implementer in the same workflow29- **Ambition bar:** impressive craft is default on flagship routes — do not wait for user to ask3031## Subagents (default)3233**Delegate by sub-command**: see `reference/subagents.md`. Main chat confirms briefs and merges results.3435| Always delegate | Subagent |36|-----------------|----------|37| `@visual-auditor` / Playwright | `shell` |38| `validate_vue`, npm test, build | `shell` |39| `critique`, `craft`, `polish` (route work) | `generalPurpose` |40| `research`, wireframe `explore` | `generalPurpose` |41| Codebase scan for `document` | `explore` |4243Do not run visual capture inline during handoff turns.4445## Cross-pillar sync (mandatory)4647Read **`reference/cross-pillar-handoff.md`**. Bookend **craft**, **critique**, **polish**, **shape** (confirmed brief):4849```50@heyeddi-orchestrator load_workflow_context --route /path51… design work + Decision log in design.md …52@heyeddi-orchestrator append_pillar_opinion --pillar design …53→ @heyeddi-product scope check; @ux-flow-auditor flow note if IA affects tasks54```5556## Setup (every session)57581. Run `python scripts/load_context.py --project-root <root>` once per session (skip if output is already in the conversation).592. If `product_exists` is false and the task needs strategic context, run **`init`** before shape/craft.603. Read the sub-command reference file for the invoked mode (required: do not skip).613a. Read `reference/implement-routing.md` when shaping, crafting, critiquing, or polishing any route.623b. Read `reference/surface-completeness.md` once per session when shaping, crafting, or critiquing any route.633c. Read `reference/foundations.md` once per session: responsive, theme, i18n, a11y, reading modes are **always on** unless `product.md` waives them.643d. Read `reference/modern-reference.md` when shaping **marketing, dashboard, or settings** routes.653e. Read `reference/audience-design.md` when shaping, crafting, or polishing **any user-facing route**.663f. Read `reference/design-ambition.md` on **flagship routes**.673g. Read `reference/aesthetic-direction.md` on **any user-facing route**.683h. Read `context/PROSE_ANTI_SLOP.md` when writing **UI copy** in briefs or `design.md`.693i. Read `reference/visual-tools.md` during **`explore`**, **`shape`**, and **`critique`** on flagship routes: use **GenerateImage** for direction probes and **Canvas** for compare/brief/critique summaries when the IDE provides them.704. After **shape** (brief confirmed), **critique**, or **polish**, append to **Decision log** in `.heyeddi/design.md`.715. After stack implementer finishes, ensure `@visual-auditor` ran at 375/768/1440 before calling design work done.7273## Commands7475| Command | Purpose |76|---------|---------|77| *(no sub-command)* | Vague design request → start **`discover`** |78| `init` | Create or refresh `PRODUCT.md`; offer `document` for `DESIGN.md` |79| `discover` | Discovery interview only: no code, no final brief yet |80| `research` | Web trend / reference research for current design direction |81| `explore` | Concept images (GenerateImage) + Canvas compare + wireframes |82| `shape` | Full planning flow: discover → research → explore → confirmed brief |83| `document` | Generate or refresh `DESIGN.md` from code or seed questions |84| `craft` | Brief ready → **hand off to stack implementer** (see implement-routing) |85| `critique` | UX review of existing UI → report → **auto-chain implement + visual-auditor** |86| `polish` | Design-spec refinement + stack implementer for code (after critique) |8788## Routing rules89901. **Existing UI: critique or improve** ("critique", "looks bad", "fix this page"): load `reference/critique.md` → implement + `@visual-auditor` in the same workflow. Do **not** ask.912. **No sub-command, vague greenfield**: load `reference/discover.md`.923. **Sub-command matches table**: load `reference/<command>.md`.934. **`craft` without confirmed brief**: run **`shape`** first.944b. **Flagship routes** without personas: `@heyeddi-intake` or `discover` first.955. **`polish` without critique this session**: run **critique** first.966. **Screenshots / approved mockups**: `@heyeddi-handoff` (implement), not design `craft` code.977. **Never invoke impeccable**: this skill replaces it.9899## Artifacts100101| Artifact | Location |102|----------|----------|103| Design brief (confirmed) | `.heyeddi/designs/<feature>/brief.md` |104| Wireframes | `.heyeddi/designs/<feature>/wireframes/` |105| Research notes | `.heyeddi/designs/<feature>/research.md` |106| Design system | `.heyeddi/design.md` |107| Product context | `.heyeddi/product.md` |108| Critiques, audits | `.heyeddi/docs/` |109110Use kebab-case for `<feature>`.111112## Foundations (design spec — implementer enforces in code)113114Responsive, light/dark, `en`+`es` i18n, WCAG 2.2 AA, semantic tokens: see `reference/foundations.md`, `reference/token-strategy.md`.115116See `context/VOCABULARY.md`, `context/ANTI_PATTERNS.md`, `context/PROSE_ANTI_SLOP.md`, `context/EXAMPLES.md`.117118## When the task is complete: suggest next skills119120```bash121python .agents/skills/heyeddi-orchestrator/scripts/suggest_next_skill.py \122 --current-skill heyeddi-design --project-root .123```124125Add `--route /path` and `--mode <sub-command>` when known.
HeyEddi-com