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.
Team: @taste-penpot owns the look in one pass (Anthropic frontend-design + tokens), including the identity gate (references/identity-gate.md: project/peers/stance documented under .heyeddi/designs/, then 3–5 What/Why/How options when no style is pinned). This skill owns product fit and implementation handoff. Read reference/design-team.md before any design turn. Do not author a second palette or restart discover → research → explore to find a look.
Auto-pickup: Design talk still loads this skill, and it immediately loads @taste-penpot if identity/tokens are not locked. If taste must run the identity gate, wait for clarifying answers and the user's A–E choice before recording tokens or crafting. Scaffolding never skips that wait. reference/brief-language.md is product language for the brief, not a second art direction.
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) |
@vue-design-system |
Quasar shell, PrimeVue Aura, motion, tokens, CLI |
| 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)
- Design talk of any kind: load
brief-language.md first; if identity unset → @taste-penpot identity gate (designer thinking in .heyeddi/, ask if needed, 3–5 options, wait); then pin taste + subject + hard rejects before chrome
- Better design / redesign: "better design", "make it better", "redesign", "new look", "overhaul", "wow", "top notch" → do not polish-only. Run critique ambition gate (
reference/critique.md); if template-like or ambition fails → identity gate (if unset) → shape → craft → implement. Spacing/token tweaks alone are wrong for these phrases.
- Critique + fix (local): "looks bad", "fix this page", "polish", "tweak spacing" → keep existing identity; critique then stack implementer +
@visual-auditor — unless the ambition gate says escalate to shape (then identity gate if replacing look; do not ask).
- Craft: confirmed brief + locked identity → hand off to stack implementer in the same workflow. No craft while identity-thinking or options are still open.
- Ambition bar: impressive craft is default on flagship routes — do not wait for user to ask
- Exception that requires confirmation: identity Phase 0 questions + A–E choice when the gate applies (and brief confirmation after shape)
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 load_workflow_context --route /path
… design work + Decision log in design.md …
@heyeddi 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/brief-language.md first on any design/look/feel talk (discover, shape, craft, critique, polish, or informal "make it look…"): subject/metaphor, hard rejects, hero/type/accent/responsive/SSOT, first-viewport checklist, done gate.
3b. Read reference/implement-routing.md when shaping, crafting, critiquing, or polishing any route.
3c. Read reference/surface-completeness.md once per session when shaping, crafting, or critiquing any route.
3d. Read reference/foundations.md once per session: responsive, theme, i18n, a11y, reading modes are always on unless product.md waives them.
3e. Read reference/modern-reference.md when shaping marketing, dashboard, or settings routes.
3f. Read reference/audience-design.md when shaping, crafting, or polishing any user-facing route.
3g. Read reference/design-ambition.md on flagship routes.
3h. Read reference/aesthetic-direction.md on any user-facing route.
3i. Read context/PROSE_ANTI_SLOP.md whenever you author prose (briefs, design.md, chat, docs, books). Writing anti-slop is general-use, not UI-only.
3j. 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.
3k. Before craft / handoff: confirm @taste-penpot layout hard gates A–G (taste-penpot/references/layout-hard-gates.md): no text-wall; design system + real fonts; Flex only if reflow real (else absolute 8px / hifi.html); export PNG (not audit alone); no orphan empty pages. Missing any gate → send back to taste. Do not invent a second look to paper over a text-wall.
- After shape (brief confirmed), critique, or polish, append to Decision log in
.heyeddi/design.md.
- After stack implementer finishes:
@visual-auditor fast widths 375,768,1440 while iterating. Before calling done on flagship/marketing: done widths 375,430,768,1024,1440,1920 (--preset done) and fix what you see. Logo-off test: if it could be another startup after removing the brand, it is not done. Design-only / Penpot passes still need taste Gate D (export or render hi-fi, read pixels) before calling the design 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
- Redesign, from scratch, new look, or overhaul of an existing app, some pages, or one page:
@taste-penpot loads references/code-to-design.md first. Write .heyeddi/designs/<feature>/code-audit.md and redesign.md. Draw the scoped boards. Copy the new tokens into .heyeddi/design.md. Do not edit .vue files in this pass unless the user also asked to implement. When they ask to build, craft covers only those pages.
- Better design on one existing route ("better design", "make it better", "major improvement", "wow", "top notch") without a from-scratch or whole-app redesign: load
reference/critique.md ambition gate → if escalate → reference/shape.md then craft (not polish-only). See reference/design-ambition.md § Improve vs redesign.
- Existing UI: local fix ("critique", "looks bad", "fix this page", "polish"): load
reference/critique.md → run ambition gate → polish-path implement + @visual-auditor only if gate says stay local. Do not ask.
- No sub-command, vague greenfield: load
reference/discover.md + brief-language.md.
- Sub-command matches table: load
reference/<command>.md (+ brief-language.md for shape/craft/critique/polish).
craft without confirmed brief: run shape first (brief must include subject + hard rejects).
6b. Flagship routes without personas: @heyeddi-intake or discover first.
polish without critique this session: run critique first (including ambition gate).
- 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/ |
| Code-to-design audit |
.heyeddi/designs/<feature>/code-audit.md |
| Redesign proposal |
.heyeddi/designs/<feature>/redesign.md |
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, reference/brief-language.md.
See context/VOCABULARY.md, context/ANTI_PATTERNS.md, context/PROSE_ANTI_SLOP.md, context/EXAMPLES.md, reference/brief-language.md.
When the task is complete: suggest next skills
python .agents/skills/heyeddi/scripts/suggest_next_skill.py \
--current-skill heyeddi-design --project-root .
Add --route /path and --mode <sub-command> when known.
1---2name: heyeddi-design3description: "Product design partner for @taste-penpot. Use on design, UI, look, polish, or handoff AFTER taste locks identity (identity gate: designer thinking in .heyeddi/, then 3–5 What/Why/How options when unset) and the look. Records personas, route job, and tokens into .heyeddi/design.md, then hands off to @heyeddi-handoff or @design-handoff-flutter. Does not invent a second palette, type system, or multi-step aesthetic. Blocks handoff unless taste layout hard gates pass (no text-wall, hifi.html when MCP cannot Flex, visual QA). Screenshot gate still applies before done."4version: 2.13.05product-version: 3.8.186author: HeyEddi-com7metadata:8 source: https://skillmd.com/skills/heyeddi-com/heyeddi-design9---1011# HeyEddi Design1213**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`.1415**Team:** `@taste-penpot` owns the look in one pass (Anthropic frontend-design + tokens), including the **identity gate** (`references/identity-gate.md`: project/peers/stance documented under `.heyeddi/designs/`, then **3–5** What/Why/How options when no style is pinned). This skill owns product fit and implementation handoff. Read `reference/design-team.md` before any design turn. Do not author a second palette or restart discover → research → explore to find a look.1617**Auto-pickup:** Design talk still loads this skill, and it immediately loads `@taste-penpot` if identity/tokens are not locked. If taste must run the identity gate, **wait for clarifying answers and the user's A–E choice** before recording tokens or crafting. Scaffolding never skips that wait. `reference/brief-language.md` is product language for the brief, not a second art direction.1819## Design vs implement (mandatory split)2021| Layer | Skill | Delivers |22|-------|-------|----------|23| Design (this skill) | `@heyeddi-design` | Briefs, wireframes, critique, `design.md`, IA, aesthetic direction |24| Implement (stack) | `@heyeddi-handoff`, `@design-handoff-flutter` | Production UI code in Vue / Flutter |25| Enforce (stack) | `@vue-design-system` | Quasar shell, PrimeVue Aura, motion, tokens, CLI |26| Verify (agnostic) | `@visual-auditor`, `@ux-flow-auditor` | Screenshots, contrast, flows, **fixes** |2728Read **`reference/implement-routing.md`** every session that ends in shipped UI.2930## Default behavior (no confirmation)3132- **Design talk of any kind:** load `brief-language.md` first; if identity unset → `@taste-penpot` identity gate (designer thinking in `.heyeddi/`, ask if needed, **3–5** options, wait); then pin taste + subject + hard rejects before chrome33- **Better design / redesign:** "better design", "make it better", "redesign", "new look", "overhaul", "wow", "top notch" → **do not polish-only**. Run critique ambition gate (`reference/critique.md`); if template-like or ambition fails → identity gate (if unset) → **`shape` → craft → implement**. Spacing/token tweaks alone are wrong for these phrases.34- **Critique + fix (local):** "looks bad", "fix this page", "polish", "tweak spacing" → keep existing identity; critique **then** stack implementer + `@visual-auditor` — **unless** the ambition gate says escalate to `shape` (then identity gate if replacing look; do not ask).35- **Craft:** confirmed brief + locked identity → hand off to stack implementer in the same workflow. No craft while identity-thinking or options are still open.36- **Ambition bar:** impressive craft is default on flagship routes — do not wait for user to ask37- **Exception that requires confirmation:** identity Phase 0 questions + A–E choice when the gate applies (and brief confirmation after shape)3839## Subagents (default)4041**Delegate by sub-command**: see `reference/subagents.md`. Main chat confirms briefs and merges results.4243| Always delegate | Subagent |44|-----------------|----------|45| `@visual-auditor` / Playwright | `shell` |46| `validate_vue`, npm test, build | `shell` |47| `critique`, `craft`, `polish` (route work) | `generalPurpose` |48| `research`, wireframe `explore` | `generalPurpose` |49| Codebase scan for `document` | `explore` |5051Do not run visual capture inline during handoff turns.5253## Cross-pillar sync (mandatory)5455Read **`reference/cross-pillar-handoff.md`**. Bookend **craft**, **critique**, **polish**, **shape** (confirmed brief):5657```58@heyeddi load_workflow_context --route /path59… design work + Decision log in design.md …60@heyeddi append_pillar_opinion --pillar design …61→ @heyeddi-product scope check; @ux-flow-auditor flow note if IA affects tasks62```6364## Setup (every session)65661. Run `python scripts/load_context.py --project-root <root>` once per session (skip if output is already in the conversation).672. If `product_exists` is false and the task needs strategic context, run **`init`** before shape/craft.683. Read the sub-command reference file for the invoked mode (required: do not skip).693a. Read **`reference/brief-language.md` first** on any design/look/feel talk (discover, shape, craft, critique, polish, or informal "make it look…"): subject/metaphor, hard rejects, hero/type/accent/responsive/SSOT, first-viewport checklist, done gate.703b. Read `reference/implement-routing.md` when shaping, crafting, critiquing, or polishing any route.713c. Read `reference/surface-completeness.md` once per session when shaping, crafting, or critiquing any route.723d. Read `reference/foundations.md` once per session: responsive, theme, i18n, a11y, reading modes are **always on** unless `product.md` waives them.733e. Read `reference/modern-reference.md` when shaping **marketing, dashboard, or settings** routes.743f. Read `reference/audience-design.md` when shaping, crafting, or polishing **any user-facing route**.753g. Read `reference/design-ambition.md` on **flagship routes**.763h. Read `reference/aesthetic-direction.md` on **any user-facing route**.773i. Read `context/PROSE_ANTI_SLOP.md` whenever you author prose (briefs, `design.md`, chat, docs, books). Writing anti-slop is general-use, not UI-only.783j. 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.793k. Before **craft** / handoff: confirm `@taste-penpot` **layout hard gates A–G** (`taste-penpot/references/layout-hard-gates.md`): no text-wall; design system + real fonts; Flex only if reflow real (else absolute 8px / `hifi.html`); export PNG (not audit alone); no orphan empty pages. Missing any gate → send back to taste. Do not invent a second look to paper over a text-wall.804. After **shape** (brief confirmed), **critique**, or **polish**, append to **Decision log** in `.heyeddi/design.md`.815. After stack implementer finishes: `@visual-auditor` **fast** widths `375,768,1440` while iterating. **Before calling done** on flagship/marketing: **done** widths `375,430,768,1024,1440,1920` (`--preset done`) and fix what you see. Logo-off test: if it could be another startup after removing the brand, it is not done. Design-only / Penpot passes still need taste Gate D (export or render hi-fi, read pixels) before calling the design done.8283## Commands8485| Command | Purpose |86|---------|---------|87| *(no sub-command)* | Vague design request → start **`discover`** |88| `init` | Create or refresh `PRODUCT.md`; offer `document` for `DESIGN.md` |89| `discover` | Discovery interview only: no code, no final brief yet |90| `research` | Web trend / reference research for current design direction |91| `explore` | Concept images (GenerateImage) + Canvas compare + wireframes |92| `shape` | Full planning flow: discover → research → explore → confirmed brief |93| `document` | Generate or refresh `DESIGN.md` from code or seed questions |94| `craft` | Brief ready → **hand off to stack implementer** (see implement-routing) |95| `critique` | UX review of existing UI → report → **auto-chain implement + visual-auditor** |96| `polish` | Design-spec refinement + stack implementer for code (after critique) |9798## Routing rules991001. **Redesign, from scratch, new look, or overhaul** of an existing app, some pages, or one page: `@taste-penpot` loads `references/code-to-design.md` first. Write `.heyeddi/designs/<feature>/code-audit.md` and `redesign.md`. Draw the scoped boards. Copy the new tokens into `.heyeddi/design.md`. Do not edit `.vue` files in this pass unless the user also asked to implement. When they ask to build, `craft` covers only those pages.1012. **Better design on one existing route** ("better design", "make it better", "major improvement", "wow", "top notch") without a from-scratch or whole-app redesign: load `reference/critique.md` **ambition gate** → if escalate → `reference/shape.md` then `craft` (not polish-only). See `reference/design-ambition.md` § Improve vs redesign.1023. **Existing UI: local fix** ("critique", "looks bad", "fix this page", "polish"): load `reference/critique.md` → run ambition gate → polish-path implement + `@visual-auditor` **only if** gate says stay local. Do **not** ask.1034. **No sub-command, vague greenfield**: load `reference/discover.md` + `brief-language.md`.1045. **Sub-command matches table**: load `reference/<command>.md` (+ `brief-language.md` for shape/craft/critique/polish).1056. **`craft` without confirmed brief**: run **`shape`** first (brief must include subject + hard rejects).1066b. **Flagship routes** without personas: `@heyeddi-intake` or `discover` first.1077. **`polish` without critique this session**: run **critique** first (including ambition gate).1088. **Screenshots / approved mockups**: `@heyeddi-handoff` (implement), not design `craft` code.1099. **Never invoke impeccable**: this skill replaces it.110111## Artifacts112113| Artifact | Location |114|----------|----------|115| Design brief (confirmed) | `.heyeddi/designs/<feature>/brief.md` |116| Wireframes | `.heyeddi/designs/<feature>/wireframes/` |117| Research notes | `.heyeddi/designs/<feature>/research.md` |118| Design system | `.heyeddi/design.md` |119| Product context | `.heyeddi/product.md` |120| Critiques, audits | `.heyeddi/docs/` |121| Code-to-design audit | `.heyeddi/designs/<feature>/code-audit.md` |122| Redesign proposal | `.heyeddi/designs/<feature>/redesign.md` |123124Use kebab-case for `<feature>`.125126## Foundations (design spec — implementer enforces in code)127128Responsive, light/dark, `en`+`es` i18n, WCAG 2.2 AA, semantic tokens: see `reference/foundations.md`, `reference/token-strategy.md`, `reference/brief-language.md`.129130See `context/VOCABULARY.md`, `context/ANTI_PATTERNS.md`, `context/PROSE_ANTI_SLOP.md`, `context/EXAMPLES.md`, `reference/brief-language.md`.131132## When the task is complete: suggest next skills133134```bash135python .agents/skills/heyeddi/scripts/suggest_next_skill.py \136 --current-skill heyeddi-design --project-root .137```138139Add `--route /path` and `--mode <sub-command>` when known.