# Design

> Canonical repo-local DESIGN.md workflow for product, UI/UX, and frontend decision source of truth

- Skill: `yeachan-heo-oh-my-codex/design` (Agent Skill)
- Install (CLI): `npx skillmds add yeachan-heo-oh-my-codex/design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yeachan-heo-oh-my-codex/design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Yeachan-Heo (https://skillmd.com/u/yeachan-heo-oh-my-codex)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/yeachan-heo-oh-my-codex/design

---


# Design Skill

Use `$design` to discover product and UI evidence, close only design-critical context gaps, and create or refresh the repository’s durable `DESIGN.md` contract. It is a maintained design brief, not a pixel-matching loop or one-off critique.

Shared operating, delegation, state, hook, team, cancellation, and verification invariants live in [`templates/AGENTS.md`](../../templates/AGENTS.md). Follow that source instead of duplicating its rules here.

## Use when

- Product, UX, frontend, or design-system decisions need a repo-local source of truth.
- A feature needs a design brief before `$ralph`, a designer lane, or implementation.
- Existing UI, assets, screenshots, or constraints need an actionable design summary.

Do not use it for visual-reference implementation matching (use `$visual-ralph`), screenshot comparison alone, or backend/infrastructure work without user-facing design impact.

## Relationship to `$visual-ralph`

`$design` owns product goals, users, information architecture, visual language, components, accessibility, constraints, and open questions in `DESIGN.md`. `$visual-ralph` owns implementation against an approved visual reference or live-URL baseline, measured verdicts, and pixel-diff evidence. Run `$design` first when both are needed; `DESIGN.md` supports but does not replace the visual verdict target.

## Workflow

### 1. Discover local evidence

Inspect and cite existing `DESIGN.md`, design/UX/frontend docs, README/specs/issues, routes/pages/layouts/components/stories, theme and token files, assets, screenshots/mockups, Storybook or Playwright baselines, and accessibility/responsive/i18n/platform constraints. Separate observations from inferences; note absent evidence.

### 2. Interview only missing context

Ask concise questions only for gaps the repository cannot resolve: users/jobs, goals/non-goals, brand personality and forbidden aesthetics, primary flows, accessibility/device/browser targets, or unavailable assets/references. If answers are unavailable, record explicit assumptions and open questions rather than blocking.

### 3. Create or refresh `DESIGN.md`

Preserve useful content, remove contradictions, mark unknowns, and keep decisions actionable. The root file must contain these sections:

# Design
## Source of truth
Status (Draft | Active | Needs refresh), date, product surfaces, evidence reviewed.
## Brand
Personality, trust signals, avoid.
## Product goals
Goals, non-goals, success signals.
## Personas and jobs
Primary personas, user jobs, contexts of use.
## Information architecture
Navigation, routes/screens, content hierarchy.
## Design principles
Principles and tradeoffs.
## Visual language
Color, typography, spacing, shape/elevation, motion, imagery/iconography.
## Components
Existing/new components, variants/states, token ownership.
## Accessibility
Target standard, keyboard/focus, contrast, semantics, reduced motion/sensory concerns.
## Responsive behavior
Breakpoints/devices, layout adaptations, touch/hover differences.
## Interaction states
Loading, empty, error, success, disabled, offline/slow network where applicable.
## Content voice
Tone, terminology, microcopy rules.
## Implementation constraints
Framework/styling, tokens, performance, compatibility, test/screenshot expectations.
## Open questions
`[ ]` question, owner, and impact.

### 4. Apply the contract

Before UI decisions, cite relevant `DESIGN.md` sections, reuse documented components/tokens, and update the file or add an open question when implementation exposes a contradiction. Do not invent a parallel design-system layer.

### 5. Handoff

For normal frontend work, provide the relevant sections, repo evidence, and acceptance criteria. For visual-reference, image, or live-URL matching, hand off to `$visual-ralph` with the approved baseline and identify `DESIGN.md` as supporting context only.

## Evidence and completion

Complete only when design docs/assets/components/screenshots were inspected or noted absent; missing context is answered, assumed, or listed; root `DESIGN.md` contains every required section; recommendations cite it; and any Visual Ralph handoff is clearly separated from design governance.

Task: {{ARGUMENTS}}