Basinfy/Basinfy-SaaS-Studio / .agents/skills/saas-ux-design
saas-ux-design
UnverifiedAuthor UX specs for App Shell, core screens, interaction patterns, and WCAG accessibility.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.1 KB |
| references/2-gather-context.md | markdown | 8.5 KB |
| references/3-file-skeleton.md | markdown | 5.1 KB |
| references/4-authoring.md | markdown | 1.6 KB |
| references/5-crossref-handoff.md | markdown | 2.9 KB |
| references/sections-app-shell.md | markdown | 7.7 KB |
| references/sections-patterns.md | markdown | 2.0 KB |
| references/sections-ux-spec.md | markdown | 12.0 KB |
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.
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |