Skip to content

Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-ux-design

saas-ux-design

Unverified

Author UX specs for App Shell, core screens, interaction patterns, and WCAG accessibility.

references/2-gather-context.md

View on GitHub
# /saas-ux-design — Sections 2 and 2b: Gather Context and Retrofit Detection

> Part of `/saas-ux-design`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.

## 2. Gather Context (Read Phase)

**In this file:**

- 2a: Required Reads
- 2b: User Journey
- 2c: PRD UI Requirements
- 2d: Existing UX Specs
- 2e: Interaction Pattern Library
- 2f: Design Tokens
- 2g: Accessibility Requirements
- 2h: Input Method (from Project Config)
- 2i: Present Context Summary

Read all relevant context **before** asking the user anything. The skill's value
comes from arriving informed. Read each PRD and the design tokens by section: Use the project discovery protocol to find the relevant headings and read those sections. When the index cannot provide them, find the headings with a local text search and read the matching ranges.

### 2a: Required Reads

- **Product concept**: Read `design/prd/product-concept.md` — or `design/product-brief.md`,
  the one-page brief that replaces it at `rigor: minimal` — if neither exists, warn:
  > "No product concept found. Run `/saas-brainstorm` first to establish the application's
  > foundation before designing UX."
  > Continue anyway if the user asks.

### 2b: User Journey

Read `design/customer-journey-map.md` if it exists. For each relevant section, extract:
- Which journey phase(s) does this screen appear in?
- What is the user's emotional state on arrival at this screen?
- What user need is this screen serving in the journey?
- What critical moments (from the journey map) does this screen deliver?

If the customer journey file does not exist, note the gap and proceed:
> "No customer journey map found at `design/customer-journey-map.md`. Designing without it
> means we'll be making assumptions about user context. Consider running a user
> journey session after this spec is drafted."

Also add to the UX spec's Open Questions section:
> "Customer journey map not yet created. Author it from the template at `.claude/docs/templates/customer-journey-map.md` to establish user context for this screen."

> **Do not tell the user to "run `/saas-ux-design` Phase 2b" to create it.** Phase 2b
> is this step — the one that *reads* the file. That remediation is circular: it
> sends the user back to the check that just reported the gap. No skill
> writes `design/customer-journey-map.md`; it is hand-authored from its template.

### 2c: PRD UI Requirements

Glob `design/prd/*.md` and grep for `UI Requirements` sections. Read any PRD whose
UI Requirements section references this screen by name or category.

These PRD UI Requirements are the **requirements input** to this spec. Collect them
as a list of constraints the spec must satisfy.

If designing the app shell, you need the UI Requirements of **every** system — the app shell
aggregates them. Collect them with one scan rather than opening each PRD:

```
Grep pattern="^#+ .*UI Requirements" glob="design/prd/*.md" output_mode="content" -A 20
```

Establish the denominator first (glob `design/prd/*.md`, count **N**) and check
the match count against it. Count system PRDs only: `product-concept.md`,
`features-modules-index.md`, `product-pillars.md`, `core business workflow-tags.md`, `entity-registry.md`,
`fixture-swap-ledger.md`, `brand-voice-tone-guide.md` and any `prd-cross-review-*.md` live
there too, but they are not systems and have no UI to aggregate.
**A PRD with no UI Requirements section is not a PRD
with no UI needs** — it may predate the section. List the unmatched ones and
confirm with the user that they are genuinely headless before excluding them
from the app shell's requirement set; an app shell that silently omits a system's readout is
the exact failure this aggregation exists to prevent.

### 2d: Existing UX Specs

Glob `design/ux/*.md` and note which screens already have specs. For screens that
will link to or from the current screen, read their navigation/flow sections to
find the entry and exit points this spec must match.

### 2e: Interaction Pattern Library

If `design/ux/interaction-patterns.md` exists, read the pattern catalog index
(the list of pattern names and their one-line descriptions). Do not read full
pattern details — just the catalog. This tells you which patterns already exist
so you can reference them rather than reinvent them.

### 2f: Design Tokens

Check for `design/tokens/design-tokens.md`. If found, read the visual direction
section. UX layout must align with the aesthetic commitments already made.

### 2g: Accessibility Requirements

Check for `design/accessibility-requirements.md`. If found, read it. The spec
must satisfy the accessibility tier committed to there.

### 2h: Input Method (from Project Config)

Read the `platform` block from `project.yaml`; if `project.yaml` has no
`platform` block, fall back to the `## Input & Platform` section of
`.claude/docs/technical-preferences.md`. Store these values for use throughout
the skill — they drive the Interaction Map and inform accessibility
requirements:

- **Primary Input** — `platform.primary_input` — the dominant input for this SaaS product
- **Mobile/Tablet Support** — `platform.mobile_support` — Full / Partial / None
- **Touch Support** — `platform.touch_support` — Full / Partial / None
- **Target Platforms** — `platform.targets` — for safe zone and aspect ratio decisions
- **Input Methods** — the set of supported methods. When reading from
  `project.yaml`, derive it: keyboard/mouse if `PC` or `Web` is in `targets`;
  touch if mobile/tablet support is enabled; touch if touch support is
  Full/Partial; plus the primary input. When falling back to
  `technical-preferences.md`, use its explicit Input Methods field.

If neither source is configured, ask once:
> "Input methods aren't configured yet. What does this SaaS product target?"
> Options: "Desktop web only", "Responsive web", "Cross-platform (Web + PWA)", "Touch (mobile)", "All of the above"
>
> (Run `/saas-setup-stack` to save this permanently so you won't be asked again.)

Store the answer for the rest of this session. Do **not** ask again per section
or per screen.

### 2i: Present Context Summary

Before any design work, present a brief summary to the user:

> **Designing: [Screen/Flow Name]**
> - Mode: [UX Spec / App Shell & Navigation Design / Pattern Library]
> - Journey phase(s): [from customer-journey-map.md, or "unknown — no journey map"]
> - PRD requirements feeding this spec: [count and names, or "none found"]
> - Related screens already specced: [list, or "none yet"]
> - Known patterns available: [count, or "no pattern library yet"]
> - Accessibility tier: [from requirements doc, or "not yet defined"]
> - Input methods: [derived from the `project.yaml` platform block, or "asked above"]

Then ask: "Anything else I should read before we start, or shall we proceed?"

---

## 2b. Retrofit Mode Detection

Before creating a skeleton, check if the target output file already exists.

Glob the resolved output path from Phase 1 — `design/ux/[filename].md`, or
`design/accessibility-requirements.md` in `accessibility` mode.

**If the file exists — retrofit mode:**
- Read the file in full
- For each expected section, check whether the body has real content (more than a `[To be designed]` placeholder) or is empty/placeholder
- Present a section status summary to the user:

> "Found existing UX spec at `design/ux/[filename].md`. Here's what's already done:
>
> | Section | Status |
> |---------|--------|
> | Purpose & User Need | [Complete / Empty / Placeholder] |
> | User Context on Arrival | ... |
> | Navigation Position | ... |
> | Entry & Exit Points | ... |
> | Layout Specification | ... |
> | States & Variants | ... |
> | Interaction Map | ... |
> | Data Requirements | ... |
> | Events Fired | ... |
> | Transitions & Animations | ... |
> | Input Method Completeness Checklist | ... |
> | Accessibility | ... |
> | Localization Considerations | ... |
> | Acceptance Criteria | ... |
> | Open Questions | ... |
>
> (Rows are the skeleton's own `##` headings for the active mode — the list above is
> UX spec mode; App shell and accessibility modes list their skeleton's headings.)
>
> I'll work on the [N] incomplete sections only — existing content will not be overwritten."

- Skip Section 3 (skeleton creation) — the file already exists
- In Phase 4 (Section Authoring), only work on sections with Status: Empty or Placeholder
- Use `Edit` to fill placeholders in-place rather than creating a new skeleton

**If the file does not exist — fresh authoring mode:**
Proceed to Phase 3 (Create File Skeleton) as normal.

---
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall