design

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: design
category: planning
status: active
core: true
description: Canonical repo-local DESIGN.md workflow for product, UI/UX, and frontend decision source of truth
agent_created: true
triggers: ["design", "design direction", "UX guidance", "frontend planning", "design system", "create DESIGN.md", "refresh DESIGN.md"]
---

> Ported from oh-my-codex `design`. OMX runtime conventions (`$macro` invocation, `omx` CLI, `.omx/` state directory) are replaced with WorkBuddy idioms (Skill tool, Agent tool, task list, `.workbuddy/memory`).

# Design Skill

Use the `design` skill when product, UI/UX, frontend, or design-system decisions need a durable
source of truth in the repository. This skill discovers existing design context, interviews for
missing product/design information, and creates or refreshes repo-local `DESIGN.md` so future
UI/UX/frontend work is grounded instead of improvised.

## Purpose

Make repo-local `DESIGN.md` the source of truth and canonical design contract for the current repository:

`existing repo evidence -> missing-context interview -> create/refresh DESIGN.md -> use DESIGN.md for UI/UX/frontend decisions`.

The output is not a pixel-matching loop and not a one-off visual critique. It is the maintained design brief/checklist that implementation, review, and future visual work should cite.

## Use when

- The user asks for design direction, UX guidance, frontend planning, or design-system alignment.
- A repo needs a design brief before UI/frontend implementation begins.
- Existing UI/components/assets/screenshots need to be summarized into a reusable design source of truth.
- UI/UX/frontend decisions are ambiguous and should be resolved through product context, constraints, and documented principles.
- A feature needs `DESIGN.md` created or refreshed before execution or implementation work proceeds.

## Do not use when

- The user provides or requests a visual reference/image/live URL and wants measured implementation until screenshots match. Use a visual-reference implementation loop (e.g. the `visual-ralph` skill if available) for that.
- The task is pure backend/API/infrastructure work with no user-facing design consequence.
- The user only asks to compare screenshots or score visual fidelity.

## Relationship to visual-reference implementation

`design` owns the durable repo design source of truth: product goals, users, IA, visual language, components, accessibility, constraints, and open questions in `DESIGN.md`.

A visual-reference implementation loop owns implementation against an approved generated/static/live-URL visual reference, with screenshot capture and pixel-diff evidence. It may read `DESIGN.md`, and it may leave design-system artifacts behind, but it does not replace the `DESIGN.md` discovery/interview/refresh workflow.

If both are needed, run `design` first to establish the design contract, then run the visual-reference loop only after the visual reference/baseline is approved.

## Workflow

### 1. Discover local design evidence

Inspect the repository before writing guidance. Look for:

- `DESIGN.md`, `docs/design*`, `docs/ux*`, `docs/frontend*`, `README.md`, product specs, PRDs, and issue notes.
- Existing UI source: routes, pages, layouts, components, stories, examples, demos, theme files, CSS variables, Tailwind/theme config, tokens, icons, and assets.
- Screenshots, mockups, brand files, logos, Figma/export notes, Storybook snapshots, Playwright screenshots, visual-regression baselines, or `.omw/visual-ralph/*` references.
- Accessibility, responsive, i18n, content, and platform constraints already encoded in code or docs.

Record evidence with file paths. Distinguish observed facts from design inferences.

### 2. Interview only for missing context

Ask concise questions only when repo evidence cannot answer design-critical context. Prefer one focused round that closes the biggest gaps, such as:

- target users/personas and jobs to be done,
- product/business goals and non-goals