Samdae Archflow UI

Global Rules: Adheres to rules/archflow-rules.md.

Model: Opus required. UI derivation needs domain knowledge and pattern matching.

UI Workflow

Generate UI specification from requirements + backend API endpoints.

Tool Fallback

Document Structure

docs/{serviceName}/
  ├── spec.md      # Input (requirements)
  ├── arch-be.md   # Input (backend API)
  └── ui.md        # ← This skill's output

Phase -1: Service Discovery

Scan docs/, select service, resolve spec.md and arch-be.md paths.

Phase 0: Skill Entry

0-1. Collect Document Input

If Service Discovery successful: verify spec.md and arch-be.md exist. Both exist → auto-load. Missing → guide to /spec or /arch.

If Service Discovery failed:

{
  "title": "UI Specification",
  "questions": [
    {
      "id": "has_spec",
      "prompt": "Do you have a requirements document? (docs/{serviceName}/spec.md)",
      "options": [
        {"id": "yes", "label": "Yes - I will provide via @filepath"},
        {"id": "no", "label": "No - Run /spec first"}
      ]
    },
    {
      "id": "has_arch_be",
      "prompt": "Do you have a backend design document? (docs/{serviceName}/arch-be.md)",
      "options": [
        {"id": "yes", "label": "Yes - I will provide via @filepath"},
        {"id": "no", "label": "No - Run /arch (Backend) first"}
      ]
    }
  ]
}

Either no → guide to required skill. Both yes → request paths → 0-1.5.

0-1.5. Responsive Option

{
  "title": "Target Platform",
  "questions": [
    {
      "id": "responsive",
      "prompt": "What platforms are you targeting?",
      "options": [
        {"id": "mobile", "label": "Mobile only - 375px viewport"},
        {"id": "desktop", "label": "Desktop only - 1280px+"},
        {"id": "responsive", "label": "Both (Responsive) - Mobile First"}
      ]
    }
  ]
}

Breakpoint hints for responsive:

breakpoints:
  mobile: "< 640px"
  tablet: "640-1024px"
  desktop: "> 1024px"

Record selection in ui.md header, apply to all wireframes.

0-2. Infer serviceName

Extract from path: docs/blog/spec.md → serviceName = "blog" → output: docs/blog/ui.md

0-3. Load Documents

Read spec.md (functional requirements) and arch-be.md (API endpoints, schemas).

Phase 1: Derive Screen List

1-1. Analyze Endpoints

1-2. Map Requirements to Screens

Cross-reference spec.md with derived screens. Flag screens without requirements or requirements without screens.

1-3. Generate Screen List

1-4. User Checkpoint

"I've derived {N} screens from the API endpoints. Please review:

{Screen List Table}

Should I proceed with detailed UI specifications?"

Phase 2: Screen Specifications

For each screen:

2-1. UI Components (ASCII Wireframe)

┌─────────────────────────────────────────────┐
│ [Logo]                    [Login/Profile]   │
├─────────────────────────────────────────────┤
│                                             │
│  Main content area                          │
│                                             │
└─────────────────────────────────────────────┘

2-2. Component Hierarchy

{ScreenName}Page:
  - Header:
      - Logo
      - Navigation
      - AuthButton
  - MainContent:
      - {Feature}Section:
          - {Component}
          - {Component}
  - Footer

2-3. States Definition

2-4. User Interactions

Phase 3: Shared Components

3-1. Identify Reusable Components

3-2. Design System Reference

recommendation:
  ui_library: "{recommended library}"
  styling: "{styling approach}"
  icons: "{icon library}"
patterns:
  layout: "{layout pattern}"          # e.g., max-w-4xl mx-auto
  spacing: "{spacing system}"         # e.g., Tailwind default scale
  typography: "{typography approach}"  # e.g., prose class for content

Phase 4: Generate ui.md

Template

# UI Specification: {Feature Name}

> Created: {date}
> Service: {serviceName}
> Platform: {mobile|desktop|responsive}
> Requirements: docs/{serviceName}/spec.md
> Backend API: docs/{serviceName}/arch-be.md

## 0. Responsive Strategy
```yaml
platform: "{type}"
breakpoints:              # responsive only
  mobile: "< 640px"
  tablet: "640-1024px"
  desktop: "> 1024px"
approach: "Mobile First"

1. Screen List

2. Screen Specifications

2.1 {ScreenName} ({route})

Purpose: {description} UI Components:

{ASCII wireframe}

Component Hierarchy:

{component tree}

States:

User Interactions:

(Repeat for each screen)

3. Shared Components

4. Design System Reference

recommendation:
  ui_library: "{lib}"
  styling: "{approach}"
  icons: "{lib}"

5. Next Steps

Run /arch Frontend to generate technical architecture. Input: docs/{serviceName}/spec.md + docs/{serviceName}/ui.md

Save: `docs/{serviceName}/ui.md`

## Phase 5: Completion Report

Report: service, screen count, component count, derived-from docs. Next: run `/arch` Frontend.

---

# Integration Flow

[spec] → spec.md ↓ [arch] (Backend) → arch-be.md ↓ [ui] → ui.md ↓ [arch] (Frontend) → arch-fe.md ↓ [build] (Frontend) → Implementation

## Important Notes

1. **Endpoint-driven**: every screen maps to at least one endpoint; screens without endpoints may indicate missing backend features
2. **Domain patterns**: use common UI patterns for the domain (e-commerce, blog, dashboard, etc.)
3. **State handling**: every screen must define all 4 states (loading/empty/error/loaded)
4. **ASCII wireframes**: focus on component structure and hierarchy, not visual design

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/samdae) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-16 -->