ui-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# UI Design

## Overview

UI design lives in `openspec/changes/<cNNNN-slug>/ui.md` — a sibling of `design.md` (architecture/logic) and `tasks.md`. While `design.md` captures architecture decisions, dependency graphs, and technical risks, `ui.md` captures the visual and interaction design: wireframes, component hierarchy, UI states (loading/empty/error/populated/edge cases), user flows, visual decisions, responsive behavior, and accessibility.

A good `ui.md` makes implementation tasks concrete: each UI state becomes an acceptance criterion, each component maps to a task file, and the wireframes give the implementer an unambiguous target.

## When to Use

- Your OpenSpec change introduces or modifies user-facing screens
- You are adding or changing interactive components (forms, lists, modals, navigation, buttons)
- The change affects layout, responsive behavior, or accessibility
- You need to document UI states (loading, empty, error, edge cases)
- The human explicitly requested UI design work

**When NOT to use:** Purely backend/data-layer changes, spec-only changes, infrastructure work, CLI-only changes. If the change has no visible surface, state "no UI surface — ui.md not created" in the propose output.

## The Design Process

### Step 1: Explore Existing Patterns

Before proposing any UI, explore the codebase to understand what already exists:

1. **Read the frontend package** — e.g., `apps/portal/src/`, `apps/web/src/` — to understand component naming conventions, file organization, and pattern libraries
2. **Check for design tokens** — `theme.ts`, `tokens.css`, `tailwind.config.*`, design system files in `components/ui/` or `lib/`
3. **Study existing components** — look for patterns: how do they handle error states? Loading states? Empty states? Form validation? What's the import style?
4. **Check capability specs** — read `openspec/specs/<capability>/spec.md` to understand the intended behavior the UI must support
5. **Note the tech stack** — React/Vue/Svelte? Tailwind/CSS Modules/Styled Components/vanilla CSS? Responsive or mobile-first? shadcn/ui, Radix, MUI, or custom?

Document findings as "Existing patterns observed:" in `ui.md` so the implementer knows what conventions to follow.

### Step 2: Create Wireframes / ASCII Art

Use ASCII art in fenced code blocks. Keep diagrams 72–80 characters wide. Each screen or significant state gets its own diagram.

```
+----------------------------------------------------------------------+
|  [Logo]  [Nav: Home | Search | Settings]               [Avatar v]   |
+----------------------------------------------------------------------+
|                                                                      |
|  +-----------+  +--------------------------------------------------+ |
|  | Filters   |  |  Search Results                                  | |
|  |           |  |                                                  | |
|  | [v Type]  |  |  +----------------------------------------------+ | |
|  | [ ] Active|  |  | ResultCard (title, excerpt, timestamp)      | | |
|  | [ ] Draft |  |  | [View] [Edit]                               | | |
|  |           |  |  +----------------------------------------------+ | |
|  | [Apply]   |  |  +----------------------------------------------+ | |
|  +-----------+  |  | ResultCard (title, excerpt, timestamp)      | | |
|                 |  | [View] [Edit]                               | | |
|                 |  +----------------------------------------------+ | |
|                 |                                                  | |
|                 |  [  <  Page 2 of 8  >  ]                        | |
|                 +--------------------------------------------------+ |
+----------------------------------------------------------------------+
```

Use the following conventions:
- `[Button]` or `[Label]` for interactive elements
- `[v Dropdown]` for dropdowns (v = chevron)
- `[x]` / `[ ]` for checkboxes
- `(...)` for radio buttons
- `+--...--+` for bordered containers
- `|` for vertical edges

### Step 3: Document Component Tree

Show the hierarchy of UI components using indentation. Annotate each leaf component with its possible states in brackets.

```
SearchPage
  SearchHeader
    SearchInput    [focused / blurred / filled / validation-error]
    SearchButton   [enabled / disabled / loading]
  SearchFilters
    FilterDropdown [unselected / selected / no-results]
    ToggleGroup    [all / active / archived]
  ResultList
    LoadingSpinner
    ResultCard[]   [populated / hovered / selected]
      CardTitle
      CardExcerpt
      CardMeta
      ActionMenu   [open / closed]
    EmptyState
      Illustration
      CallToAction
    ErrorState
      ErrorMessage
      RetryButton
  Pagination
    PageLink[]     [active / inactive / disabled]
```

Mark repeated elements with `[]` (e.g., `ResultCard[]`).

### Step 4: Enumerate UI States

For each interactive component, enumerate all relevant states:

| State | What the user sees |
|-------|-------------------|
| **Loading** | Skeleton, spinner, shimmer, or progressive placeholder while data fetches |
| **Empty** | Message + illustration + call-to-action when there's nothing to display |
| **Error** | Error message + retry button + fallback content on fetch/operation failure |
| **Populated** | The normal data-present state |
| **Disabled** | Greyed-out/inactive state while conditions aren't met |
| **Focused** | Keyboard/touch focus indicator for inputs and interactive elements |
| **Hovered** | Hover state for clickable elements |
| **Edge cases** | Long text truncation, rapid clicks, slow network, expired session, permissions denied, zero results |

### Step 5: Design User Flows

Write step-by-step flows for key scenarios. Cover the happy path, then branch for empty, error, and edge cases.

```
## Flow: Search and view a result

From minhlucvan/emdesign, Apache-2.0.

More from minhlucvan/emdesign