playbooks

home / skills / wellapp-ai / well / design-context

design-context skill

/cursor-rules/skills/design-context

This skill helps ensure UI wireframes and UI decisions align with the design system, Storybook, and codebase patterns for cohesive experiences.

npx playbooks add skill wellapp-ai/well --skill design-context

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.6 KB
---
name: design-context
description: Refresh UI/UX context from design system, Storybook, and codebase
---

# Design Context Skill

Ensures wireframes and UI decisions leverage existing patterns from the design system, Storybook, and codebase.

## When to Use

- Before presenting wireframes (Ask mode DIVERGE)
- Before implementing UI changes (Agent mode)
- At every DIVERGE Loop to stay grounded in existing patterns

## Instructions

### Phase 1: Design System Check

Read the design system documentation:

```
Read /docs/design-system/components.md
Read /docs/design-system/spacing.md
Read /docs/design-system/colors.md (if color decisions needed)
Read /docs/design-system/interactions.md (if interaction patterns needed)
```

**Note applicable:**
- Design tokens (`h-13`, `px-4`, `gap-3`)
- Component patterns (Button variants, DataTable, Dialog)
- Spacing conventions (p-4 for cards, gap-6 for sections)

### Phase 2: Storybook Patterns

Find existing component stories:

```
Glob **/*.stories.tsx
```

**Identify:**
- Components matching current wireframe needs
- Existing variants and props
- Documented states (loading, error, empty)

**Key story locations:**
- `/src/stories/` - General component stories
- `/features/*/components/*.stories.tsx` - Feature-specific stories

### Phase 3: Codebase Search

Search for similar UI patterns:

```
SemanticSearch "How is [pattern] implemented in the codebase?"
```

**Look for:**
- Similar features already built
- Reusable hooks and utilities
- Existing layout patterns

### Phase 4: Library Documentation (Context7 MCP)

Query library docs for unfamiliar patterns:

```
1. resolve-library-id with libraryName (e.g., "radix-ui")
2. query-docs with libraryId and specific question
```

**Common libraries:**
- `/radix-ui/primitives` - Dialog, Dropdown, Select patterns
- `/tanstack/query` - Data fetching patterns
- `/tanstack/table` - Table patterns

## Output Format

After running this skill, output:

```markdown
## Design Context

| Source | Relevant Patterns |
|--------|-------------------|
| Design System | [tokens, components] |
| Storybook | [stories that apply] |
| Codebase | [existing implementations] |
| Libraries | [patterns from docs] |

### Applicable Components
- [Component]: [How it applies to current wireframe]

### Design Tokens to Use
- Spacing: [tokens]
- Colors: [tokens]
- Typography: [tokens]
```

## Invocation

Invoke manually with "use design-context skill" or follow Ask mode DIVERGE loop which references this skill's phases.

## Related Skills

- `problem-framing` - Run before design-context
- `competitor-scan` - Compare with external patterns

Overview

This skill refreshes UI/UX context by extracting patterns from the design system, Storybook, and the live codebase to keep new wireframes and implementations consistent. It surfaces applicable components, tokens, and implementation references so designers and engineers reuse existing building blocks. The goal is faster delivery with fewer visual regressions and more predictable behavior.

How this skill works

The skill runs an ordered inspection: read design system docs for tokens and component rules, scan Storybook for matching stories and variants, and search the codebase for implemented patterns and utilities. For unfamiliar dependencies, it queries library documentation to validate expected behavior and APIs. It then produces a concise mapping of sources to relevant patterns and a short list of applicable components and tokens.

When to use it

  • Before presenting wireframes in the DIVERGE phase to ensure proposals reuse patterns
  • Before implementing any UI changes to avoid duplicate components and styles
  • During each DIVERGE loop to keep design iterations grounded in existing patterns
  • When onboarding to a project to quickly learn the design system and common implementations
  • When resolving layout or interaction ambiguity to find precedent in Storybook/codebase

Best practices

  • Prioritize design system tokens and component variants over ad-hoc styles
  • Document which story or file influenced decisions for easy traceability
  • Favor existing hooks and utilities found in the codebase to reduce new surface area
  • Validate critical interactions against library docs (e.g., radix-ui patterns) when behavior matters
  • Keep the output concise: list only directly applicable patterns and tokens

Example use cases

  • Designing a new invoice list view: map to existing DataTable patterns, spacing tokens, and loading states
  • Prototyping a dialog-based workflow: reuse Dialog component variants and documented focus/closing behavior
  • Implementing an action button set: align with Button variants and interaction states from Storybook
  • Reworking a form layout: apply spacing tokens and shared input components discovered in the codebase
  • Resolving inconsistent colors: pick approved color tokens and cite the design system reference

FAQ

What outputs should I expect after running this skill?

A compact mapping of Design System, Storybook, Codebase, and Libraries to relevant patterns, a short list of applicable components, and recommended tokens for spacing, colors, and typography.

Can this skill find implementation code for custom components?

Yes — it searches stories and code files to locate matching implementations and any reusable hooks or utilities to reference.