solarwire-prd

name	solarwire-prd
description	Generate complete PRD documents with SolarWire wireframes, Mermaid diagrams, and SVG exports. v2.0 - Enhanced with brainstorming best practices: project context exploration, incremental validation, spec self-review, and user review gates.

SolarWire PRD Generator v2.0

Configuration

• Output Directory: .solarwire (modify here if needed)

---

Overview

This skill generates complete Product Requirements Documents (PRD), including:

1. Complete PRD Document (.md format)
2. Mermaid Flowcharts/Sequence Diagrams
3. SolarWire Wireframes (each page with complete information and element descriptions)
4. SVG Rendered Images (with notes and without notes versions)

---

Workflow

Phase 0: Exploration & Preparation

Goal: Understand project context and scope before collecting requirements

Step 0: Explore Project Context

• Check existing code files (if any)
• Check existing documentation (if any)
• Check recent git commits (if any)
• Understand project background and goals

Step 1: Scope Check

• Determine if project needs to be decomposed into multiple sub-projects
• If too large, help user decompose and select first sub-project
• Decomposition criteria:

  • 5 independent modules → needs decomposition

  • 10 pages → needs decomposition

  • Multiple independent business flows → needs decomposition

Step 2: Multiple Approaches Comparison (Optional)

• Provide 2-3 design approaches
• Each with trade-off analysis
• Recommend one approach

---

Phase 1: Requirements Collection

Goal: Confirm user requirements step by step, don't rush to generate

Step 3: Product Type Confirmation

What type of application is this?
- 📱 Mobile App
- 💻 Web Client
- ⚙️ Admin Dashboard
- 📺 Other (please describe)

Please select or describe your product type.

Step 4: Core Features Confirmation

What core features/pages does this product need?

For example:
- User Login/Register
- Home Page
- Profile Center
- Product List
- Order Management
...

Step 5: Multi-language Confirmation

Does this project require multi-language support?

If yes:
- Which languages need to be supported?
- Common options: English, 中文, 日本語, 한국어, Deutsch, Français, Español, etc.
- The default language will be set based on your primary language.

If no:
- All notes will be written in default language only.
- No i18n information will be added to any elements.

⚠️ IMPORTANT: Multi-language Rules

1. Only when explicitly confirmed: Add i18n information ONLY when user explicitly confirms multi-language support is needed
2. Never add i18n if not requested: If user says no multi-language, absolutely DO NOT add any i18n information
3. All meaningful elements: If multi-language is confirmed, ALL meaningful text elements MUST include i18n translations
4. Default language: Based on user's primary language (the language they use to communicate)

Elements requiring i18n (if multi-language is confirmed):

• Button text
• Label text
• Placeholder text
• Error/Success messages
• Table headers
• Menu items
• Page titles
• Status values

Elements NOT requiring i18n:

• User input data (usernames, comments, etc.)
• System generated data (IDs, timestamps, etc.)
• Decorative elements
• Icons

---

Phase 2: Requirements Validation

Step 6: Requirements Summary

Here's my understanding of requirements:

**Product Type**: [Type]
**Core Pages**:
1. [Page 1] - [Brief description]
2. [Page 2] - [Brief description]
3. ...

**Multi-language**: [Yes/No + Languages]

**Special Requirements**:
- [Requirement 1]
- [Requirement 2]

Is this understanding correct? Any adjustments or additions needed?

Step 7: Requirements Confirmation Gate

• User MUST confirm requirements
• If adjustments needed, go back to Phase 1

---

Phase 3: Generate & Quality

Step 8: Generate PRD

• Generate complete PRD document
• Save to .solarwire/[project-name]/solarwire-prd.md

Step 9: Spec Self-Review

Check 1: Placeholder Scan

Check items:
- Any "TBD", "To Be Determined", "待定"
- Any "TODO", "待完成"
- Incomplete sections
- Vague requirement descriptions

If found:
- Fix or clarify immediately
- No placeholders allowed

Check 2: Internal Consistency

Check items:
- Product type matches page design
- Core features list matches page details
- Multi-language rules are consistent throughout document
- Color standards are used consistently
- Font standards are used consistently

If contradictions found:
- Priority: Page details > Feature list > Product type
- Unify standards

Check 3: Scope Check

Check items:
- Focused on implementable scope
- Not too many independent subsystems
- Doesn't need decomposition

Criteria:
- If >5 independent modules → needs decomposition
- If >10 pages → needs decomposition
- If multiple independent business flows → needs decomposition

If needs decomposition:
- Go back to Phase 0 Step 1
- Help user decompose and select first sub-project

Check 4: Ambiguity Check

Check items:
- Requirements with two possible interpretations
- Vague business rules (e.g., "appropriate", "reasonable")
- Undefined terms

If ambiguity found:
- Choose one interpretation and make it explicit
- Add term definitions to Appendix
- Clarify business rules (e.g., "appropriate permissions" → "read-only permissions")

**Note: Visual ambiguity is allowed**
- Visual descriptions like "appropriate spacing", "reasonable layout" don't need quantification
- But functional requirements must be clear (e.g., "user can edit" not "user might be able to edit")

Fix Principle:

• Fix all issues immediately, no need to re-review
• Proceed to Step 10 after fixing

Step 10: User Review Gate

✅ PRD generated and passed self-review

**File Location:** `.solarwire/[project-name]/solarwire-prd.md`

**Includes:**
- Product Overview (1.1-1.4)
- Feature Scope (2.1-2.2)
- Business Flow (3.1-3.2)
- Page Design (4.1-5.x)
- Non-functional Requirements (6.1-6.3)
- Appendix (7.1-7.2)

**Please review:**
1. Completeness - Any missing features?
2. Accuracy - Any misunderstandings?
3. Page Design - Matches expectations?
4. Business Logic - Correct?

**Review Method:**
- Edit directly in file
- Or tell me what needs adjustment

**After review approval, I will:**
- Generate SVGs for all pages (with notes and without notes)
- Complete entire PRD generation process

Please start reviewing, let me know if you have any questions.

User Review Gate Rules:

• MUST wait for user to explicitly confirm "ok" or "no problem"
• If user requests changes, go back to Step 8 to regenerate PRD
• If user only needs minor adjustments, can fix before Step 11

---

Phase 4: Output

Step 11: Generate SVG

• Run node generate-svg.js .solarwire/[project-name]/solarwire-prd.md
• Generate SVGs with notes and without notes

---

Multiple Approaches Comparison

Trigger Conditions:

• When project has multiple viable design approaches
• When user is uncertain about implementation approach
• When trade-offs need to be weighed

Approach Format:

For [feature/module], I've analyzed 3 implementation approaches:

**Approach A: [Approach Name]**
- Description: [Brief description]
- Pros:
  - [Pro 1]
  - [Pro 2]
- Cons:
  - [Con 1]
  - [Con 2]

**Approach B: [Approach Name]**
- Description: [Brief description]
- Pros:
  - [Pro 1]
  - [Pro 2]
- Cons:
  - [Con 1]
  - [Con 2]

**Approach C: [Approach Name]**
- Description: [Brief description]
- Pros:
  - [Pro 1]
  - [Pro 2]
- Cons:
  - [Con 1]
  - [Con 2]

**My Recommendation: Approach [X]**
- Reason: [Recommendation reason]

Which approach would you like to choose?

Use Cases:

• Login method (password/third-party login/hybrid)
• Data storage (local/cloud/hybrid)
• Navigation structure (top/sidebar/bottom)

---

Complete Checklist

You MUST complete each step in order:

Phase 0: Exploration & Preparation

1. Explore project context (code, docs, commits)
2. Scope check (needs decomposition?)
3. Multiple approaches comparison (optional)

Phase 1: Requirements Collection 4. [ ] Product type confirmation 5. [ ] Core features confirmation 6. [ ] Multi-language confirmation

Phase 2: Requirements Validation 7. [ ] Requirements summary 8. [ ] Requirements confirmation gate (user MUST confirm)

Phase 3: Generate & Quality 9. [ ] Generate PRD 10. [ ] Spec self-review (4 checks) 11. [ ] User review gate (user MUST review)

Phase 4: Output 12. [ ] Generate SVG

---

Output File Structure

All requirements are organized under the .solarwire directory, each in its own folder:

.solarwire/                              # Root directory for all PRD outputs
├── [requirement-name-1]/                # Folder for requirement 1
│   ├── solarwire-prd.md                 # PRD document (fixed name)
│   ├── [page-name]-with-notes.svg       # Wireframe with notes
│   ├── [page-name]-without-notes.svg    # Wireframe without notes
│   └── ...                              # More SVGs for this requirement
│
├── [requirement-name-2]/                # Folder for requirement 2
│   ├── solarwire-prd.md
│   └── ...
│
└── ...                                  # More requirement folders

Naming Convention:

• Root directory: .solarwire (at project root)
• Requirement folder: Based on requirement/project name (e.g., user-login-system/, order-management/)
• PRD file: Always named solarwire-prd.md
• SVG files: Based on the !title attribute in each solarwire code block
  • Format: [title-value]-with-notes.svg and [title-value]-without-notes.svg
  • Title is converted to lowercase kebab-case (e.g., !title="User Login" → user-login-with-notes.svg)

---

SVG Generation

This skill is fully portable. All dependencies are bundled in the lib directory.

After generating the PRD markdown file, run the SVG generation script:

node generate-svg.js .solarwire/[requirement-name]/solarwire-prd.md

The script will:

• Extract all solarwire code blocks from the markdown file
• Generate two SVG files for each block:
  • [page-name]-with-notes.svg - Includes note annotations
  • [page-name]-without-notes.svg - Clean wireframe only
• Save files to the same directory as the markdown file (the requirement folder)

Updating Dependencies:

If you need to update the bundled dependencies:

# Build the latest parser and renderer
cd SolarWire/packages/core/parser && npm run build
cd SolarWire/packages/core/renderer-svg && npm run build

# Copy to skill lib directory
cp -r SolarWire/packages/core/parser/dist/* solarwire-prd/lib/parser/
cp -r SolarWire/packages/core/renderer-svg/dist/* solarwire-prd/lib/renderer-svg/

---

PRD Document Structure

# Product Requirements Document - [Project Name]

## Document Information
| Project Name | [Project Name] |
|-------------|----------------|
| Version | v1.0 |
| Created Date | [Date] |
| Author | [Author] |

---

## 1. Product Overview

### 1.1 Product Background
[Brief description of product background and goals]

### 1.2 Target Users
[Description of target user groups]

### 1.3 Core Value
[Core value provided to users by product]

### 1.4 User Stories

**Format: As a [user role], I want to [action], so that [benefit]**

| ID | User Story | Acceptance Criteria | Priority |
|----|------------|---------------------|----------|
| US-001 | As a [role], I want to [action], so that [benefit] | - Given [context], when [action], then [result] | P0 |
| US-002 | As a [role], I want to [action], so that [benefit] | - Given [context], when [action], then [result] | P0 |
| US-003 | As a [role], I want to [action], so that [benefit] | - Given [context], when [action], then [result] | P1 |

**User Story Writing Guidelines:**
- **User Role**: Identify who the user is (e.g., "As a registered user", "As an admin")
- **Action**: What the user wants to do (e.g., "I want to reset my password")
- **Benefit**: Why the user wants this (e.g., "so that I can regain access to my account")
- **Acceptance Criteria**: Use Given-When-Then format to define testable conditions
- **Priority**: P0 (Must have), P1 (Should have), P2 (Nice to have)

---

## 2. Feature Scope

### 2.1 Feature List
| Module | Feature | Priority | Description |
|--------|---------|----------|-------------|
| [Module 1] | [Feature 1] | P0 | [Description] |
| [Module 1] | [Feature 2] | P1 | [Description] |

### 2.2 Feature Boundary
- Included: [List included features]
- Not Included: [List excluded features]

---

## 3. Business Flow

### 3.1 Core Business Flowchart
```mermaid
flowchart TD
    A[Start] --> B[Step 1]
    B --> C[Step 2]
    C --> D{Decision}
    D -->|Yes| E[Step 3]
    D -->|No| F[Step 4]
    E --> G[End]
    F --> G

3.2 Interaction Sequence Diagram

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant B as Backend
    participant D as Database

    U->>F: Send Request
    F->>B: API Call
    B->>D: Data Query
    D-->>B: Return Data
    B-->>F: Response Result
    F-->>U: Display Result

---

4. Page Design

4.1 Page List

Page Name	Page Type	Description
[Page 1]	Main Page	[Description]
[Page 2]	Modal	[Description]

---

5. Page Details

Core Principle: All element descriptions are integrated into the SolarWire wireframe notes for "what you see is what you read"

5.1 [Page Name]

Page Overview: [One sentence describing core functionality of page]

!title="[Page Name]"
!c=#111827
!size=13
!bg=#E5E7EB
!r=0

// Container Rectangle
[] @(0,0) w=1440 h=900 bg=#FFFFFF

// Page Content - Each element has detailed note description
["Logo"] @(50,50) w=120 h=60 note="""Logo
1. Click action
   - Return to homepage"""

"User Login" @(100,150) size=24 bold

"Username" @(100,220)
["Enter phone or email"] @(100,245) w=300 h=44 bg=#FFFFFF b=#E5E7EB note="""Username input
1. Input rules
   - Supports phone number or email
   - Automatically trims leading/trailing spaces
   - Max length: 50 characters
2. Validation
   - Format: 11-digit phone number or email format
   - Error message: 'Please enter a valid phone number or email'"""

"Password" @(100,310)
["Enter password"] @(100,335) w=300 h=44 bg=#FFFFFF b=#E5E7EB note="""Password input
1. Input rules
   - Password displayed as dots
   - Min length: 6 characters, Max: 32 characters
   - Must contain letters and numbers
2. Interaction
   - Show/hide toggle icon on right"""

[""] @(100,400) w=16 h=16 note="""Remember me checkbox
1. Behavior
   - When checked: Stay logged in for 7 days
   - Unchecked by default"""
"Remember Me" @(124,402)

"Forgot Password?" @(320,400) c=#3B82F6 note="""Forgot password link
1. Click action
   - Navigate to password recovery page"""

["Login"] @(100,450) w=300 h=48 bg=#3B82F6 c=#FFFFFF size=16 note="""Login button
1. Click action
   - Validate username and password
2. Success handling
   - Save login state
   - Redirect to homepage
3. Failure handling
   - Display modal: 'Invalid username or password'
   - Clear password field
4. Disabled conditions
   - Disabled when username or password is empty"""

"Or login with" @(160,530) c=#9CA3AF

[?"WeChat Work"] @(120,560) w=40 h=40 note="""WeChat Work login
1. Click action
   - WeChat Work QR code login"""
[?"DingTalk"] @(180,560) w=40 h=40 note="""DingTalk login
1. Click action
   - DingTalk QR code login"""
[?"WeChat"] @(240,560) w=40 h=40 note="""WeChat login
1. Click action
   - WeChat authorization login"""

---

6. Non-functional Requirements

6.1 Performance Requirements

• Page load time: < 2 seconds
• API response time: < 500ms

6.2 Security Requirements

• [List security requirements]

6.3 Compatibility Requirements

• Browsers: Chrome 90+, Safari 14+
• Mobile: iOS 14+, Android 10+

---

7. Appendix

7.1 Glossary

Term	Description
[Term 1]	[Description]

7.2 References

• [Reference links]

---

## SolarWire Wireframe Specifications

### Core Principles (Must Strictly Follow)

#### 1. Syntax Rules

1. All elements must have coordinates @(x,y)
2. Write attributes directly without brackets: w=100 h=40 (not [w=100 h=40])
3. Text content MUST use double quotes: "Login" (not Login)
4. Attribute order: Content → Coordinates → Size → Other attributes → note
5. **NOTE ATTRIBUTE MUST USE TRIPLE QUOTES """: note="""Note content""" (never use single or double quotes)

**⚠️ CRITICAL: Always use triple quotes `"""` for notes**
- Triple quotes allow any characters inside, including newlines and double quotes
- No need to escape anything inside triple quotes
- DO NOT use single quotes `'` or double quotes `"` for notes

**Correct Example:**
```solarwire
["Login"] @(100,50) w=100 h=40 bg=#3B82F6 c=#FFFFFF note="""Submit login form"""
"Username" @(100,100)
(("Avatar")) @(100,150) w=40  // Circle with text - MUST use double quotes

Incorrect Examples:

["Login"]                    // ❌ No coordinates
["Login"] [w=100 h=40]       // ❌ Attributes in brackets
["Login"] @(100,50) w=100    // ❌ Missing height
((Avatar)) @(100,50) w=40    // ❌ Text without double quotes - WRONG!
(("Avatar")) @(100,50) w=40  // ✅ Correct - text in double quotes

⚠️ IMPORTANT: All text content MUST be wrapped in double quotes ""

Element	Correct	Incorrect
Rectangle	["Button"]	[Button]
Circle	(("Avatar"))	((Avatar))
Rounded	("Card")	(Card)
Plain Text	"Label"	Label

2. Element Selection Principles

Choose appropriate element types based on actual UI components:

Scenario	Recommended Element	Example
Primary Buttons	Rectangle [] with background color	["Login"] @(100,50) w=100 h=40 bg=#3B82F6 c=#FFFFFF
Secondary Buttons	Rectangle [] with border	["Cancel"] @(220,50) w=80 h=40 bg=#FFFFFF b=#E5E7EB
Cards/Containers	Rounded Rectangle ()	("User Info Card") @(100,50) w=300 h=200
Avatars	Circle with placeholder	(("A")) @(100,50) w=40 bg=#E5E7EB c=#6B7280
Icon Buttons	Circle with icon text	(("?")) @(100,50) w=32 h=32 bg=#E5E7EB
Labels/Text	Plain Text ""	"Username" @(100,50)
Input Fields	Rectangle with placeholder	["Enter username..."] @(100,50) w=280 h=40 bg=#FFFFFF b=#E5E7EB c=#9CA3AF
Dividers	Line --	-- @(0,100)->(400,100) b=#E5E7EB
Data Tables	Table ##	## @(100,50) w=500 border=1

⚠️ CRITICAL: Text Content Syntax

Element	Correct Syntax	Wrong Syntax
Rectangle	["Button Text"]	[Button Text] ❌
Rounded	("Card Title")	(Card Title) ❌
Circle	(("Avatar"))	((Avatar)) ❌
Plain Text	"Label"	Label ❌

Common Mistakes to Avoid:

• ❌ ((Avatar)) - Text without double quotes
• ❌ [Login] - Text without double quotes
• ❌ Using placeholder [?] for buttons (use ["Button Text"] instead)
• ❌ Using rectangle [] for plain labels (use "Label" instead)
• ❌ Overcrowding elements - use 10px spacing

2.5 Coordinate System

Anchor Point Rule: All elements use the top-left corner as the coordinate anchor point @(x,y).

Visual Explanation:

     (x,y) ← anchor point
       ┌─────────────────┐
       │                 │
       │    Element      │ h (height)
       │                 │
       └─────────────────┘
              w (width)

Text Alignment Calculation:

When aligning text with other elements (like labels inside buttons), the text Y coordinate is NOT the center of the target element.

Standard	Value
Default font size	13px
Default line height	22px
Text baseline offset	~7px from top

Alignment Formula:

Text Y = Target_Y + (Target_Height - Line_Height) / 2 + Baseline_Adjustment

Examples:

// Button with centered text
["Submit"] @(100,100) w=100 h=40 bg=#3B82F6 c=#FFFFFF

// Label above input field - aligned with input
"Username" @(100,175)  // 10px gap from input top
["Enter username"] @(100,200) w=280 h=40 bg=#FFFFFF b=#E5E7EB

// Text inside button (if needed separately)
// Button: Y=100, Height=40, Center=120
// Text Y ≈ 100 + (40-22)/2 + adjustment ≈ 109
"Submit" @(120,109) c=#FFFFFF  // Centered inside button

3. Page Organization Rules

Each SolarWire code block handles only one independent view:

Situation	Handling Method	Example
Modals/Dialogs	Separate SolarWire fragment	## Login Failed Modal + independent code block
Different Page States	Separate fragment for each state	## Login Page - Loading State, ## Login Page - Error State
Tab Switching	Separate fragment for each tab	## Settings Page - Basic Info Tab, ## Settings Page - Security Tab

Do not mix multiple view states in one code block.

4. Container Rectangle Requirements

Every page must have a container rectangle:

!title="Page Name"
!c=#111827
!size=13
!bg=#F9FAFB
!r=0

// Container Rectangle - Represents screen/device boundary, placed at beginning
[] @(0,0) w=375 h=812 bg=#FFFFFF

// Page content...

Container Rectangle Specifications:

• Place at the beginning of the code block
• Use [] rectangle (don't display text content)
• bg=#FFFFFF white background
• Dimensions by scenario:
  • Mobile: w=375 h=812 (iPhone X) or w=390 h=844 (iPhone 12+)
  • Web: w=1440 h=900 or as needed
  • Admin Dashboard: w=1920 h=1080

Container Size Principle: Container must contain all child elements

Forbidden: Child elements extending beyond parent container boundaries.

5. Note Writing Guidelines

Core Principle: Notes describe functional behavior and business logic, not visual details or technical implementation

---

0. When to Read EXAMPLES.md

📖 Read EXAMPLES.md when you encounter:

Scenario	What to Look Up
Writing complex button notes	"Button with Permission Control", "Batch Operations", "Form Submission"
Writing input field notes	"Input Field with Validation", "Search Bar with Filters", "Data Linkage"
Writing data table notes	"Data Table", "Table with Actions Column"
Writing statistics notes	"Statistics Card", "Calculated Field"
Writing navigation notes	"Pagination Component"
Handling special states	"Loading States", "Empty State Handling"
Unsure about note quality	"Common Mistakes" section

📖 EXAMPLES.md contains:

• Complete note examples for each element type
• Good vs Bad comparisons
• All edge cases and error handling examples

⚠️ Important:

• SKILL.md contains rules (what must be included)
• EXAMPLES.md contains examples (how to write it)
• Always follow rules in SKILL.md, use EXAMPLES.md for reference

---

1. When to Write Notes

Write notes for:

• Interactive elements (buttons, links, etc.)
• Input elements with validation or logic
• Dropdowns (selection behavior, options source)
• Data display elements with complex rules (tables, lists)
• Elements with business logic (calculations, conditions)
• Complex concepts requiring additional explanation

Skip notes for:

• Pure visual elements (dividers, containers, decorative icons)
• Static labels and titles

Common Sense Exemption (no note needed unless special behavior):

• Back button (standard behavior: return to previous page)
• Close button
• Page selector
• Number stepper/incrementer

Note: If exempted elements have special validation or interaction, they MUST be documented.

---

2. Note Structure Format

Format Rules:

First line: Element definition (what this element is, NOT element type)
First level: Numbered (1. 2. 3.)
Second level: - or # (if third level exists)
Third level: -- or -

Example:

["Enter password"] @(100,100) w=280 h=40 note="""Password input
1. Input rules
   - Password displayed as dots
   - Minimum 6 characters, maximum 32 characters
   - Must contain both letters and numbers
2. Interaction
   - Show/hide toggle icon on right
   - Validate format on blur
   - Display error on format failure: 'Invalid password format'
3. Special notes
   - Lock account for 15 minutes after 5 consecutive errors"""

---

3. First Line: Element Definition

The first line of a note MUST define what this element is (functional description, NOT element type).

Correct	Incorrect
Password input	[Password Field]
Username input	[Input Field]
User data table	[Data Table]
Submit form button	[Primary Button]

---

4. Content Requirements by Element Type

Interactive/Operational Elements:

Must include:

• What happens on click/operation
• Success/failure handling
• Disabled conditions
• Special handling (debounce, throttle, etc.)

📖 See EXAMPLES.md: "Button with Permission Control", "Batch Operations", "Form Submission"

---

Elements with Logic:

Must include:

• Show/hide conditions
• Calculation rules
• Validation rules
• State transitions

---

Data Display Elements:

Must include ALL of the following sections:

Section	Required	Description
1. Data source	✅ Required	Where data comes from, filtering conditions, sorting rules
2. Display rules	✅ Required	Field meanings, formats, empty value handling
3. Business rules	Optional	Status mappings, conditional display, calculations
4. Sorting/Filtering	Optional	If applicable, describe sorting and filtering behavior

📖 See EXAMPLES.md: "Data Table", "Table with Actions Column", "Statistics Card", "Status Badge"

---

Input Fields:

Must include:

• Input rules (format, length, allowed characters)
• Validation (required, format check, error messages)
• Business rules (unique check, duplicate check)

📖 See EXAMPLES.md: "Input Field with Validation", "Search Bar with Filters", "Data Linkage"

---

Dropdowns/Selects:

Must include:

• Data source (options source, static or dynamic)
• Display rules (default, selected, options list)
• Business rules (required, default value, dependencies)

📖 See EXAMPLES.md: "Dropdown Options", "Data Linkage (Cascading Select)"

---

Empty State Handling:

Data Type	Empty Display	Example
Text	'-' or 'Not set'	"Contact: -"
Number	'0' or '--'	"Amount: ¥ --"
Date	'-' or 'Not specified'	"Last login: -"
Status	Default status	"Status: Pending"
List/Table	Empty state message	"No data available"

📖 See EXAMPLES.md: "Empty State Handling", "Loading States"

---

Tooltip/Toast:

Describe directly in note, no separate wireframe needed.

📖 See EXAMPLES.md: "Tooltip/Toast Examples"

---

5. Note Writing Principles

Principle	Description
Necessity	Only write for meaningful elements, avoid over-documentation
Completeness	Fully describe element, cover all aspects
Single Responsibility	Only describe current element; affected elements document in their own notes
Organization	Use standard format, clear hierarchy
Self-explanatory	Element definition should be clear, no need for secondary explanation
Business-focused	Describe business logic, avoid technical implementation details

---

5.3 Required Content by Element Type (Quick Reference)

📖 For complete examples, see EXAMPLES.md

Buttons/Actions:

• ✅ Permission control
• ✅ Click action
• ✅ Success handling
• ✅ Failure handling (all error types)
• Optional: Disabled conditions, Loading state

Input Fields:

• ✅ Input rules (format, length, allowed characters)
• ✅ Validation (required, format check, error messages)
• Optional: Display rules, Business rules

Data Tables:

• ✅ Data source (module, filters, default sort)
• ✅ Display rules (field formats, empty handling, status colors)
• ✅ Actions column (available actions, visibility, permissions)
• Optional: Sorting/Filtering, Pagination, Row behavior

Search/Filter:

• ✅ Input rules
• ✅ Search behavior (debounce, trigger, clear)
• ✅ Search scope (fields, match type)
• ✅ No results handling

Dropdowns/Selects:

• ✅ Data source (options source)
• ✅ Display rules (default, selected, options list)
• Optional: Business rules, Loading behavior

Forms:

• ✅ Pre-submission validation
• ✅ Submission state (loading, disabled, double-click protection)
• ✅ Success handling
• ✅ Failure handling (all error types)
• Optional: Retry mechanism

---

5.4 Common Mistakes in Note Writing

📖 For detailed examples, see EXAMPLES.md "Common Mistakes" section

Mistake	Problem	Solution
Missing Permission Control	No visibility/disabled rules	Add who can see/use element
Incomplete Error Handling	Only generic "show error"	List all error types: validation, network, server, timeout, permission
Missing Data Source Details	Just "User data"	Add module, filters, sort, permission
Wrong First Line	"[Primary Button]"	Use functional description: "Login button"
Visual Details in Note	"Blue background, 14px font"	Remove, these are shown in wireframe

---

5.5 Data Format Specifications

When describing data display, always specify format rules:

Date/Time Formats:

Type	Format	Example
Date only	YYYY-MM-DD	2024-01-25
Date with time	YYYY-MM-DD HH:mm	2024-01-25 14:30
Full datetime	YYYY-MM-DD HH:mm:ss	2024-01-25 14:30:45
Relative time	Within X days show relative	"3 days ago", "Just now"
Time only	HH:mm	14:30

Number Formats:

Type	Format	Example
Integer	With thousand separators	1,234
Decimal	2 decimal places	1,234.56
Currency	With symbol and separators	¥1,234.56
Percentage	With % symbol	68.5%
Large numbers	Abbreviated	1.23万, 1.5M

Text Formats:

Type	Handling	Example
Long text	Truncate with ellipsis	"Long text content..."
Phone	Mask sensitive digits	138****8000
Email	Show full or truncate	[e-mail]
ID	Partial mask	110***********1234

Status/Tag Display:

Always describe status values with their visual representation:

"跟进中" @(100,50) note="""Lead status
1. Display rules
   - Status values with visual style:
     - 待分配: Gray tag (#D1D5DB background)
     - 跟进中: Blue tag (#3B82F6 background)
     - 已转化: Green tag (#22C55E background)
     - 无效: Red tag (#EF4444 background)
   - All tags: White text, rounded corners, 4px padding"""

---

6. Content Forbidden in Notes

NEVER include:

Forbidden	Example (Don't Write)
Colors	"Button is blue", "Text color #333"
Fonts	"Font size 14px", "Bold text"
Sizes	"Width 100px", "Height 40px"
Spacing	"Margin 16px", "Padding 8px"
Border	"Border radius 8px"
Shadows	"Box shadow 0.2px 4px"
Animations	"Fade in 0.3s"
Technical details	"API: /api/login", "Database: user_id"

Why? These are:

• Already shown visually in wireframe
• Design decisions to be made later
• Subject to change during implementation

---

7. Multi-language (i18n) Support

⚠️ CRITICAL: Only add i18n when user explicitly confirms multi-language support is needed

If user does NOT need multi-language:

• Do NOT add any i18n information to any element
• Write notes in the user's primary language only

If user confirms multi-language support:

• ALL meaningful text elements MUST include i18n translations
• Use full language names (e.g., "English", "中文", "日本語") instead of language codes
• Default language is based on user's primary language

---

i18n Format for Single Text Element:

["Login"] @(100,50) w=100 h=40 note="""Login button
1. Click action
   - Validate username and password
2. i18n: English=Login, 中文=登录, 日本語=ログイン"""

Format: i18n: Language1=Text1, Language2=Text2, Language3=Text3

⚠️ IMPORTANT: No double quotes inside double quotes

• Use single quotes ' for text values inside i18n
• Correct: i18n: English=Login, 中文='登录', 日本語='ログイン'
• Incorrect: i18n: English=Login, 中文="登录", 日本語="ログイン"

---

i18n Format for Multiple Text Elements (e.g., buttons in a group):

["Cancel"] @(100,50) w=80 h=36 note="""Cancel button
1. Click action
   - Close dialog without saving
2. i18n: English=Cancel, 中文=取消, 日本語=キャンセル"""

["Confirm"] @(200,50) w=80 h=36 note="""Confirm button
1. Click action
   - Save changes and close dialog
2. i18n: English=Confirm, 中文=确认, 日本語=確認"""

---

i18n Format for Table with Multiple Fields:

Use compact format with language names declared once:

## @(100,50) w=600 border=1 note="""User list table
1. Data source
   - User list data from User Management module
2. Fields (i18n: English/中文/日本語)
   - ID: Unique user identifier [ID/ID/ID]
   - Name: User display name [Name/用户名/ユーザー名]
   - Status: 1=Active, 0=Disabled [Status/状态/ステータス]
     - Values: Active/正常/有効, Disabled/禁用/無効
   - Created: Account creation time [Created/创建时间/作成日時]
   - Actions: View and edit operations [Actions/操作/操作]
3. Buttons (i18n: English/中文/日本語)
   - View [View/查看/表示]
   - Edit [Edit/编辑/編集]
   - Delete [Delete/删除/削除]"""

Format for table fields:

• Declare languages once: Fields (i18n: Language1/Language2/Language3)
• Each field: - FieldName: Description [Text1/Text2/Text3]
• Status values: Values: Value1/Lang1/Lang2, Value2/Lang1/Lang2

---

i18n Format for Dropdown Options:

["Select status"] @(100,50) w=200 h=36 note="""Status dropdown
1. Options (i18n: English/中文/日本語)
   - All [All/全部/すべて]
   - Active [Active/正常/有効]
   - Disabled [Disabled/禁用/無効]
2. Default: All"""

---

i18n Format for Error/Success Messages:

["Submit"] @(100,50) w=100 h=40 note="""Submit button
1. Click action
   - Validate and submit form data
2. Success message
   - i18n: English=Submitted successfully, 中文=提交成功, 日本語=送信成功
3. Error messages
   - Network error: i18n: English=Network error, please try again, 中文=网络错误，请重试, 日本語=ネットワークエラー、再試行してください
   - Validation error: i18n: English=Please check your input, 中文=请检查您的输入, 日本語=入力内容を確認してください"""

---

8. Examples: Good vs Bad Notes

❌ Bad Note (Visual details + element type label):

["Login"] @(100,50) w=100 h=40 note="""[Primary Button]
- Blue background, white text
- Border radius 8px
- API: POST /api/auth/login"""

✅ Good Note (Functional behavior):

["Login"] @(100,50) w=100 h=40 note="""Login button
1. Click action
   - Validate username and password
2. Success handling
   - Save login state
   - Redirect to homepage
3. Failure handling
   - Display error: 'Invalid credentials'
4. Disabled conditions
   - Disabled when username or password is empty"""

✅ No Note Needed (Visual element):

-- @(0,100)->(400,100) b=#E5E7EB

---

SVG Output Specifications

Generation Requirements

Each page/tab/modal needs to generate two SVG files:

1. With Notes Version ([page-name]-with-notes.svg)

   • Contains note descriptions for all elements
   • For requirements review and development reference

2. Without Notes Version ([page-name]-without-notes.svg)

   • Displays only wireframe elements
   • For design reference and presentation

SVG Rendering Specifications

• Use SolarWire renderer to convert solarwire code blocks in .md to SVG
• Ensure all elements use syntax supported by existing rules
• SVG dimensions match container rectangle dimensions
• Output path: Same directory as solarwire-prd.md file (the requirement folder)

---

Syntax Quick Reference

Document-level Declarations

!title="Page Title"
!c=#111827        // Default text color
!size=13          // Default font size
!bg=#F9FAFB       // Background color
!r=0              // Default border radius

Basic Elements

Symbol	Usage	Example
[]	Button, input field, container	["Confirm"] @(100,50) w=80 h=36
()	Card, rounded container	("Tip Card") @(100,50) w=200 h=100
(())	Avatar, circular icon	(("Avatar")) @(100,50) w=40
""	Plain text, label	"Username" @(100,50)
[?]	Icon placeholder	[?"Search"] @(100,50) w=32 h=32
<url>	Real image	<https://example.com/logo.png> @(100,50) w=40
--	Divider line	-- @(0,100)->(400,100)
##	Table container	## @(100,50) w=500 border=1
#	Table row (MUST be inside ##)	# bg=#F9FAFB

Table Syntax (Indentation Required)

Tables use strict indentation:

## @(x,y) w=width border=1 note="""Data table
1. Data source
   - Data from relevant module
2. Field descriptions
   - Column 1: Description
   - Column 2: Description
   - Column 3: Description"""
  # bg=#F9FAFB                  // Header row (indented 2 spaces)
    "Column 1"                  // Cell (indented 4 spaces)
    "Column 2"
    "Column 3"
  #                             // Data row (indented 2 spaces)
    "Data 1"                    // Cell (indented 4 spaces)
    "Data 2"
    "Data 3"
  # bg=#F9FAFB                  // Alternating row color
    "Data 4"
    "Data 5"
    "Data 6"

⚠️ Indentation Rules:

• Table ## - No indentation
• Row # - 2 spaces indentation
• Cell content - 4 spaces indentation

⚠️ CRITICAL: Table Row Must Be Inside Table

• Row element # CANNOT exist independently - it MUST be inside a table container ##
• A row without a parent table is invalid syntax
• Table structure: ## (container) → # (rows) → cells (content)

⚠️ Table Child Element Restrictions:

• Row # and cells CANNOT have coordinates @(x,y) - positions are determined by table structure
• Row # and cells CANNOT have width/height w h - sizes are determined by table container
• Row # and cells CANNOT have border b or border - border is set on table container ##
• Only supported attributes for rows: bg, c, size, bold, italic, align
• Only supported attributes for cells: bg, c, size, bold, italic, align, colspan, rowspan

⚠️ Table Cell Content Format:

• Use [""] (rectangle) for cell content - text will be centered in the cell
• Avoid "" (plain text) for cells - text will stick to the top-left corner
• Example: ["John Doe"] ✅ (centered) vs "John Doe" ❌ (top-left aligned)

⚠️ Table Note Rules:

• Table-level note: Add note attribute to the table element ## for overall table description
• Row-level note: note attribute is NOT supported on table rows #
• If you need to describe a table, put all information in the table-level note

Common Attributes

Attribute	Description	Example
w h	Width, Height	w=100 h=40
bg	Background color	bg=#3B82F6
c	Text color	c=#FFFFFF or c=#111827
b	Border color	b=#E5E7EB
r	Border radius	r=8
size	Font size	size=16
bold	Bold text	bold
opacity	Element opacity (0-1)	opacity=0.5 for 50% transparency
colspan	Column span for table cells	colspan=2 (merge 2 columns)
rowspan	Row span for table cells	rowspan=2 (merge 2 rows)
note	Functional description	note="Click to submit form"

Table Row Attributes

Table rows (#) support the following attributes:

• bg – Background color for the entire row
• c, size, bold, italic, align – Text style defaults for all cells in the row

⚠️ Important Rules:

• note attribute is NOT supported on table rows #
• To describe a table, add note to the table element ## instead
• Row-level attributes serve as defaults for all cells in that row
• Individual cells can override row-level attributes with their own values

Example:

## @(100,50) w=500 border=1 note="""User list table
1. Data source
   - User list data from User Management module
2. Field descriptions
   - ID: Unique user identifier
   - Name: User display name
   - Actions: Edit and delete operations"""
  # bg=#F9FAFB c=#111827 bold      // Header row
    ["ID"]
    ["Name"]
    ["Actions"] colspan=2            // Merge 2 columns for actions
  # bg=#F9FAFB                     // Data row: alternating color
    ["1"]
    ["John Doe"]
    ["Edit"]                       // Each button in separate cell
    ["Delete"]

---

Creating Clean, Realistic Wireframes

Goal: Wireframes should look like actual UI, clean and professional

Key Principles

1. Use Realistic Placeholder Content

   • Use actual placeholder text, not generic labels
   • Example: ["Enter your email..."] instead of ["Input"]
   • Example: ["Login"] instead of ["Button"]

2. Proper Visual Hierarchy

   • Primary buttons: Colored background (bg=#3B82F6 c=#FFFFFF)
   • Secondary buttons: Border only (bg=#FFFFFF b=#E5E7EB)
   • Important elements should be larger/prominent

3. Appropriate Element Types

   • Buttons → Rectangle [] with text
   • Cards → Rounded rectangle ()
   • Avatars → Circle with letter (("A"))
   • Labels → Plain text ""
   • Inputs → Rectangle with placeholder

4. Consistent Spacing

   • Element spacing: 10px (unified)
   • Group related elements together
   • Use consistent margins throughout

5. Clean Layout

   • Don't overcrowd elements
   • Use dividers -- to separate sections
   • Container rectangle should contain all elements

Page Presentation Rules

Scenario	Handling
New page	Draw all elements completely, including navigation, menu, etc.
Redesign page	Redraw completely
Minor changes to existing page	Mark only changed parts on original wireframe; existing parts not modified or explained
New content on existing page	Add new elements to original wireframe

Completeness Requirements:

• Pages must show all elements completely, including navigation, menu and common parts
• Within the same requirement, common parts already explained in other pages do not need to be repeated
• Ensure developers have a clear concept of relative element positions on each page

Field Presentation Rules

Rule	Description
Field grouping	Group fields when there are many, for better user understanding
Field naming	Use common, user-friendly language; self-explanatory
Auxiliary explanation	When field name cannot be self-explanatory, explain via Tooltip, etc.

Color Standards (Tailwind CSS)

All colors follow Tailwind CSS design system for modern, consistent UI.

Purpose	Tailwind	Hex	Usage
Primary text	gray-900	#111827	Labels, headings, content
Secondary text	gray-500	#6B7280	Descriptions, helper text
Tertiary text	gray-400	#9CA3AF	Placeholder, timestamps
Page background	gray-50	#F9FAFB	Page background
Card background	white	#FFFFFF	Cards, panels
Alternating row	gray-50	#F9FAFB	Table alternating rows
Borders/Lines	gray-200	#E5E7EB	Dividers, borders
Primary action	blue-500	#3B82F6	Primary buttons, links
Primary light	blue-50	#EFF6FF	Hover, selected background
Success	green-500	#22C55E	Success states, positive
Success light	green-50	#F0FDF4	Success background
Warning	amber-500	#F59E0B	Warnings, attention
Warning light	amber-50	#FFFBEB	Warning background
Error	red-500	#EF4444	Errors, destructive
Error light	red-50	#FEF2F2	Error background
Info	sky-500	#0EA5E9	Information, tips
Info light	sky-50	#F0F9FF	Info background

Spacing Standards

Rule	Value
Element spacing	10px (unified)
Font size	13px
Line height	22px

Other Rules

Rule	Description
Images/Icons	Use sparingly in client pages to avoid affecting UI design
Shadows	Use sparingly
Layout	Clear structure, distinct functional areas

SolarWire Default Configuration

!title="Page Title"
!c=#111827        // gray-900: Default text color
!size=13          // Default font size
!bg=#F9FAFB       // gray-50: Page background color
!r=0              // Default border radius

---

Modal Presentation Rules

All modals MUST have a separate SolarWire wireframe, not just a simple description in a note.

Modal Types

Type	Description
Confirmation modal	Delete confirmation, operation confirmation, etc.
Form modal	Create, edit, etc.
Information modal	Detail view, etc.
Alert modal	Success, failure, warning, etc.

Modal vs Tooltip/Toast

Type	Handling	Description
Modal	Separate SolarWire wireframe	Complete UI, interactions, action buttons
Tooltip	Describe directly in note	Simple text hint, no interaction
Toast	Describe directly in note	Simple message, auto-dismiss

📖 See EXAMPLES.md: "Modal Examples" for complete modal wireframe examples

---

Scenario Specifications

Mobile App

Characteristics:

• Narrow canvas (375-430px)
• Vertical layout, bottom navigation
• Touch-friendly large buttons (min 44x44px)

Container Size: w=375 h=812 (iPhone X) or w=390 h=844 (iPhone 12+)

Element Sizes:

• Button height: 44-56px
• Input field height: 44-52px
• Text size: 13px (default), 18-22px (titles)
• Element spacing: 10px (unified), Page margins: 16-24px

Common Patterns:

• Login: Logo + Title + Form + Button (full width)
• List: Search bar + List items + Pull to refresh
• Detail: Back button + Title + Content + Bottom action

Mobile-specific Fields:

Field	Type	Description
deviceToken	string	Device push token
deviceId	string	Device unique identifier
osType	string	iOS/Android
appVersion	string	App version

Mobile-specific Rules:

• Support one-tap login, third-party login (WeChat, Apple ID)
• Token validity: 7 days
• Push notifications can be disabled

---

Web Client

Characteristics:

• Wide canvas (1200-1440px)
• Horizontal layout, top navigation
• Moderate button/input sizes

Container Size: w=1440 h=900

Element Sizes:

• Button height: 36-48px, width: min 80px
• Input field height: 36-44px, width: 200-400px
• Text size: 13px (default), 18-24px (titles)
• Element spacing: 10px (unified), Page margins: 24-48px

Common Patterns:

• Login: Centered layout, Logo + Form + Button
• List: Search/filter bar + Data table + Pagination
• Detail: Breadcrumb + Title + Content cards + Actions

Web-specific Fields:

Field	Type	Description
sessionId	string	Session ID
userAgent	string	Browser info
referrer	string	Source page

Web-specific Rules:

• Support password, QR code, third-party login
• Session validity: 30 min inactivity auto-expire
• Browsers: Chrome 90+, Safari 14+, Firefox 88+, Edge 90+

---

Admin Dashboard

Characteristics:

• Very wide canvas (1440-1920px)
• Fixed left sidebar (200-280px)
• Data-intensive (tables, charts, cards)
• Many action buttons

Container Size: w=1920 h=1080

Element Sizes:

• Button height: 32-40px
• Input field height: 32-36px
• Table row height: 40-48px
• Sidebar width: 200-280px
• Text size: 13px (default), 16-20px (titles)
• Element spacing: 10px (unified), Page margins: 24-32px

Common Patterns:

• List: Search/filter + Batch actions + Table + Pagination
• Statistics: Multiple stat cards + Charts + Time selector
• Form: Breadcrumb + Multi-column form + Save/Cancel

Admin-specific Fields:

Field	Type	Description
operatorId	string	Operator ID
operateTime	datetime	Operation time
operateType	string	Add/Edit/Delete/Export
ipAddress	string	Operation IP

Admin-specific Rules:

• Super Admin: Full permissions
• Admin: View/Edit, no Delete
• Operator: View/Export only
• Pagination: 20 items/page, max 10000 export
• Sensitive operations require confirmation
• Login timeout: 30 min inactivity

---

Important Reminders

1. Confirm Requirements Step by Step - Don't rush to generate, fully understand requirements first
2. Notes Describe Function and Business Logic - Focus on behavior and logic, avoid visual details and technical implementation
3. Not Every Element Needs a Note - Skip notes for visual elements; common sense exemption for back button, close button, page selector, number stepper
4. First Line Defines Element - Note first line must describe what element is (e.g., "Login button"), not element type (e.g., "[Primary Button]")
5. Note Structure Required - First line: element definition; First level: numbered (1. 2. 3.); Second level: dash (-); Third level: double dash (--)
6. Coordinates Must Be Complete - Every element must have @(x,y)
7. No Brackets for Attributes - Write directly w=100 h=40
8. Choose Elements Reasonably - Buttons use rectangles, labels use text, only icons use placeholders
9. Layout Close to Reality - Wireframes should reflect actual page structure with 10px spacing
10. Separate Modals/States/Tabs - Each independent view in separate code block; all modals must have separate wireframe
11. Table Row Must Be Inside Table - Row element # CANNOT exist independently, MUST be inside table container ##
12. Table Child Element Restrictions - Rows and cells CANNOT have coordinates @(x,y), width w, height h, or border b; only support style attributes (bg, c, size, bold, italic, align, colspan, rowspan)
13. Table Cell Content Format - Use [""] (rectangle) for cell content to center text; avoid "" (plain text) which sticks to top-left corner
14. Container Rectangle Required - First element of each page is white background container
15. Generate Dual SVG Versions - With notes and without notes versions
16. Color Standards (Tailwind CSS) - Use unified colors: #111827 (text), #6B7280 (secondary), #E5E7EB (border), #FFFFFF (bg), #F9FAFB (alternating row), #3B82F6 (primary), #EF4444 (error)
17. Font Standards - Font size 13px, line height 22px
18. i18n Only When Confirmed - Add multi-language support ONLY when user explicitly confirms; if not confirmed, absolutely NO i18n information; if confirmed, ALL meaningful elements MUST include i18n translations using full language names (English, 中文, 日本語)