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.
Running this workflow on this client
Run commands from the project root (use Git Bash on Windows if bash points to an unavailable WSL distro). Shared studio files live in .claude/; follow .agents/PORTABLE-RUNTIME.md and .claude/docs/config-resolution.md for client tools, delegation, and approval rules.
Run bash .claude/hooks/yaml-helper.sh resolve_config --keys locale,automation,workflow,docs.density and use its output below.
Resolved above — use as-is. No block → defaults in
.claude/docs/config-resolution.md.
UX Design
Locale & User Profile: Match
locale(pt-BR→ natural Brazilian Portuguese questions/options, overriding English examples;en→ English) anduser_profile(founder→ plain business language with(Recomendado)first, zero tech jargon;developer→ technical). Keep code/tests in English.
When this skill is invoked:
Every AskUserQuestion call follows .claude/docs/automation-modes.md
(collaborative asks always · guided major-only · autonomous logs and proceeds;
automation_always_ask categories always prompt).
Authoring guidance: the skeletons below are self-contained — author from them directly. When a section needs depth (worked examples, pattern catalogs, accessibility criteria), the matching guide has it:
| Producing | Guide |
|---|---|
| UX spec | .claude/skills/saas-ux-design/references/sections-ux-spec.md |
| App shell navigation | .claude/skills/saas-ux-design/references/sections-app-shell.md |
| Interaction patterns | .claude/skills/saas-ux-design/references/sections-patterns.md |
| Accessibility requirements | .claude/docs/templates/accessibility-requirements.md |
Load a guide per-section, never whole — each is organised by section and the pointers in the templates name the exact section to read.
workflow (see .claude/docs/workflow-modes.md):
full— a UX spec is required per screen.standard— core screens only (landing page, app shell, dashboard, primary user workflow).minimal— not required. Can still be run voluntarily.
docs.density — it controls per-section depth, where workflow
controls which screens are specced. modes.rigor sets both together; set
docs.density explicitly to vary depth alone: terse (the default, via rigor: minimal) = wireframe descriptions +
interaction bullets; balanced = wireframes + paragraph descriptions of flows
(rigor: standard); thorough = full prose including user-research summaries and
alternative flow considerations. Apply it to every section you author.
1. Parse Arguments & Determine Mode
Four authoring modes exist based on the argument:
| Argument | Mode | Output file |
|---|---|---|
app-shell | App shell navigation | design/ux/app-shell.md |
patterns | Interaction pattern library | design/ux/interaction-patterns.md |
accessibility | Project-wide accessibility requirements | design/accessibility-requirements.md |
Any other value (e.g., dashboard, settings-billing) | UX spec for a screen or flow | design/ux/[argument].md |
| No argument | Ask the user | (see below) |
accessibilityis the only mode that writes outsidedesign/ux/. Its output is a project-wide standard the per-screen specs consult, not a spec for one screen —.claude/docs/workflow-catalog.yaml, the Pre-Production and Polish gates, and/saas-architecture-reviewall checkdesign/accessibility-requirements.mdat that exact path. Do not "tidy" it underdesign/ux/: every one of those checks would stop matching, and the Technical Setup → Pre-Production gate would become unpassable.
If no argument is provided, do not fail — ask instead. Use AskUserQuestion:
- "What are we designing today?"
- Options: "A specific screen or flow (I'll name it)", "The App Shell & Global Navigation", "The interaction pattern library", "The project-wide accessibility requirements", "I'm not sure — help me figure it out"
If the user selects "I'll name it" or types a screen name, normalize it to kebab-case
for the filename (e.g., "Settings Billing" becomes settings-billing).
2. Gather Context (Read Phase)
Read references/2-gather-context.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
3. Create File Skeleton
Read references/3-file-skeleton.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
4. Section-by-Section Authoring
Read references/4-authoring.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
Section guidance — read the ONE file for the active mode
Per-section authoring guidance lives in its own file per mode. When you reach Phase 4, read only the file matching the mode resolved in Section 1; never load the other two.
| Mode | Guidance file |
|---|---|
| UX Spec (screen or flow) | references/sections-ux-spec.md |
| App Shell Design | references/sections-app-shell.md |
| Interaction Pattern Library | references/sections-patterns.md |
| Accessibility Requirements | .claude/docs/templates/accessibility-requirements.md |
The accessibility guidance lives under
templates/guidance/rather than this skill'sreferences/because the template it documents (.claude/docs/templates/accessibility-requirements.md) is consumed by/saas-ux-reviewand the gate files too. Same rule applies: load only the part covering the section you are authoring, never the whole file.
Apply docs.density (Section 1) to whatever that file tells you to author — it
controls the depth of each section, not which sections exist.
5. Cross-Reference Check
Read references/5-crossref-handoff.md now and follow it — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
7. Recovery & Resume
If the session is interrupted (compaction, crash, new session):
- Read
production/session-state/active.md— it records the current screen and which sections are complete. - Read
design/ux/[filename].md— sections with real content are done; sections with[To be designed]still need work. - Resume from the next incomplete section — no need to re-discuss completed ones.
This is why incremental writing matters: every approved section survives any disruption.
8. Specialist Agent Routing
This skill uses ux-designer as the primary agent (set in frontmatter). For
specific sub-topics, additional context or coordination may be needed:
| Topic | Coordinate with |
|---|---|
| Visual aesthetics, color, layout feel | design-system-director — UX spec defines zones; art defines how they look |
| Implementation feasibility (engine constraints) | frontend-engineer — before finalizing component catalog |
| Core Business Workflow data requirements | lead-product-manager — when data ownership is unclear |
| Microcopy & brand voice visible in the UI | ux-content-strategist — for microcopy, empty states, help tooltips |
| Accessibility tier decisions | Recorded by this session (/saas-ux-design accessibility; the user picks the tier) against the criteria accessibility-auditor defines and audits — consult it when a requirement's criterion is unclear |
When delegating to another agent via the Agent tool:
- Provide: screen name, product concept summary, the specific question needing expert input
- The agent returns analysis to this session
- This session presents the agent's output to the user
- The user decides; this session writes to file
- Agents do NOT write to files directly — this session owns all file writes
Collaborative Protocol
In collaborative mode (the default). For guided and autonomous modes,
see the per-mode rules in .claude/docs/automation-modes.md — the steps below
describe what collaborative mode requires, not what applies universally.
This skill follows the collaborative design principle at every step:
- Question -> Options -> Decision -> Draft -> Approval for every section
- AskUserQuestion at every decision point (Explain -> Capture pattern):
- Phase 2: "Ready to start, or need more context?"
- Phase 3: "May I create the skeleton?"
- Phase 4 (each section): design questions, approach options, draft approval
- Phase 5: "Run cross-reference check? What's next?"
- "May I write to [filepath]?" before the skeleton and before each section write
- Incremental writing: Each section is written to file immediately after approval
- Session state updates: After every section write
Aesthetic deference: When layout or visual choices come down to personal taste, present the options and ask. Do not select a layout because it is "standard" — always confirm. The user is the creative director.
Conflict surfacing: When a PRD requirement and the available screen real estate conflict, surface the conflict and present resolution options. Never silently drop a requirement. Never silently expand the layout without flagging it.
Never auto-generate the full spec and present it as a fait accompli. Never write a section without user approval. Never contradict an existing approved UX spec without flagging the conflict. Always show where decisions come from (PRD requirements, customer journey, user choices).
Verdict: COMPLETE — UX spec written and approved section by section.
Recommended Next Steps
- Run
/saas-ux-review [filename]to validate this spec before it enters the implementation pipeline - Run
/saas-ux-design [next-screen]to continue designing remaining screens or flows - Run
/saas-gate-check productiononce all key screens have approved UX specs
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: 197k | 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: 197k | 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: 197k | Updated | Claude CodeCodex | Verified | Install |