design

> 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, - brand personality or forbidden aesthetics, - primary flows and information architecture, - accessibility level, device/browser support, and implementation constraints, - existing design assets or references the repo does not contain. If the user wants autonomous progress or cannot answer, create `DESIGN.md` with explicit assumptions and open questions instead of blocking. ### 3. Create or refresh `DESIGN.md` Use the structure below. Preserve useful existing content, remove contradictions, and mark unknowns as open questions. Keep it actionable for implementers and reviewers. #### Required `DESIGN.md` structure/checklist ```markdown # Design ## Source of truth - Status: Draft | Active | Needs refresh - Last refreshed: YYYY-MM-DD - Primary product surfaces: - Evidence reviewed: ## Brand - Personality: - Trust signals: - Avoid: ## Product goals - Goals: - Non-goals: - Success signals: ## Personas and jobs - Primary personas: - User jobs: - Key contexts of use: ## Information architecture - Primary navigation: - Core routes/screens: - Content hierarchy: ## Design principles - Principle 1: - Principle 2: - Tradeoffs: ## Visual language - Color: - Typography: - Spacing/layout rhythm: - Shape/radius/elevation: - Motion: - Imagery/iconography: ## Components - Existing components to reuse: - New/changed components: - Variants and states: - Token/component ownership: ## Accessibility - Target standard: - Keyboard/focus behavior: - Contrast/readability: - Screen-reader semantics: - Reduced motion and sensory considerations: ## Responsive behavior - Supported breakpoints/devices: - Layout adaptations: - Touch/hover differences: ## Interaction states - Loading: - Empty: - Error: - Success: - Disabled: - Offline/slow network, if applicable: ## Content voice - Tone: - Terminology: - Microcopy rules: ## Implementation constraints - Framework/styling system: - Design-token constraints: - Performance constraints: - Compatibility constraints: - Test/screenshot expectations: ## Open questions - [ ] Question / owner / impact ``` ### 4. Use `DESIGN.md` as the decision contract For UI/UX/frontend work after the refresh: - Cite the relevant `DESIGN.md` sections before making design choices. - Prefer existing components, tokens, and documented constraints. - If implementation reveals a design contradiction, update `DESIGN.md` or add an open question before proceeding. - Do not introduce a new design-system layer when existing repo-native patterns can be extended. ### 5. Handoff to implementation or visual-reference loop when appropriate - For normal frontend implementation, hand off with the relevant `DESIGN.md` sections, repo evidence, and acceptance criteria (spawn an Agent or use the `team` skill for parallel lanes). - For visual-reference/image/live-URL matching, hand off to the visual-reference implementation loop with the approved reference/baseline and note that `DESIGN.md` is supporting context, not the visual verdict target. ## Completion checklist Do not declare the design workflow complete until: - Existing design docs/assets/components/screenshots have been inspected or explicitly noted as absent. - Missing product/design context has been answered, assumed, or listed in `DESIGN.md` open questions. - `DESIGN.md` exists at the repo root and contains all required checklist sections. - UI/UX/frontend recommendations cite `DESIGN.md` rather than relying on unstated preferences. - Any visual-reference handoff is clearly separated as visual implementation matching, not `DESIGN.md` governance.