Initial commit
This commit is contained in:
Zhongwei Li
319
skills/fluxwing-screen-scaffolder/docs/04-screen-composition.md
Normal file
319
skills/fluxwing-screen-scaffolder/docs/04-screen-composition.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# Screen Composition - Building Complete UIs
|
||||
|
||||
How to compose complete screens from existing components.
|
||||
|
||||
## What is a Screen?
|
||||
|
||||
A **screen** is a complete page or view composed of multiple components. Unlike individual components, screens:
|
||||
- Reference existing components by ID
|
||||
- Define layout and positioning
|
||||
- Show complete user flows
|
||||
- Include rendered examples with real data
|
||||
|
||||
## The Three-File System for Screens
|
||||
|
||||
Every screen needs THREE files:
|
||||
|
||||
### 1. `screen-name.uxm` (Metadata)
|
||||
Defines which components are used and how they're arranged
|
||||
|
||||
### 2. `screen-name.md` (Template)
|
||||
Shows the layout with {{variables}} for dynamic content
|
||||
|
||||
### 3. `screen-name.rendered.md` (Example)
|
||||
**Critical**: Shows the screen with REAL data (not variables)
|
||||
|
||||
## Creating a Screen
|
||||
|
||||
### Step 1: Inventory Components
|
||||
|
||||
Before composing, list what's available:
|
||||
- Check `./fluxwing/components/` for user-created components
|
||||
- Check `./fluxwing/library/` for customized templates
|
||||
- Check `../examples/` for bundled components
|
||||
|
||||
**If missing components**, create them first with `/fluxwing-create`
|
||||
|
||||
### Step 2: Design the Layout
|
||||
|
||||
Choose a layout pattern (see patterns below) and plan:
|
||||
- Component placement
|
||||
- Visual hierarchy
|
||||
- Spacing and alignment
|
||||
- User flow
|
||||
|
||||
### Step 3: Create screen-name.uxm
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "login-screen",
|
||||
"type": "container",
|
||||
"version": "1.0.0",
|
||||
"metadata": {
|
||||
"name": "Login Screen",
|
||||
"description": "User authentication screen",
|
||||
"created": "2024-10-11T12:00:00Z",
|
||||
"modified": "2024-10-11T12:00:00Z",
|
||||
"tags": ["auth", "login", "screen"],
|
||||
"category": "display"
|
||||
},
|
||||
"props": {
|
||||
"title": "Welcome Back",
|
||||
"components": [
|
||||
"email-input",
|
||||
"password-input",
|
||||
"submit-button",
|
||||
"error-alert"
|
||||
]
|
||||
},
|
||||
"layout": {
|
||||
"display": "flex",
|
||||
"positioning": "relative",
|
||||
"spacing": {
|
||||
"padding": 16
|
||||
}
|
||||
},
|
||||
"behavior": {
|
||||
"states": [
|
||||
{"name": "idle", "properties": {}},
|
||||
{"name": "loading", "properties": {"showSpinner": true}},
|
||||
{"name": "error", "properties": {"showError": true}}
|
||||
],
|
||||
"accessibility": {
|
||||
"role": "main",
|
||||
"ariaLabel": "Login form"
|
||||
}
|
||||
},
|
||||
"ascii": {
|
||||
"templateFile": "login-screen.md",
|
||||
"width": 40,
|
||||
"height": 25
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Create screen-name.md (Template)
|
||||
|
||||
````markdown
|
||||
# Login Screen
|
||||
|
||||
User authentication screen with email/password.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
╭────────────────────────────────────────╮
|
||||
│ {{title}} │
|
||||
├────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Email │
|
||||
│ {{emailInput}} │
|
||||
│ │
|
||||
│ Password │
|
||||
│ {{passwordInput}} │
|
||||
│ │
|
||||
│ {{error}} │
|
||||
│ │
|
||||
│ {{submitButton}} │
|
||||
│ │
|
||||
╰────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
## Components Used
|
||||
|
||||
- `email-input`: Email address field
|
||||
- `password-input`: Password field with show/hide
|
||||
- `submit-button`: Form submission
|
||||
- `error-alert`: Error messages
|
||||
|
||||
## States
|
||||
|
||||
### Idle (default)
|
||||
User has not yet interacted
|
||||
|
||||
### Loading
|
||||
While authenticating
|
||||
|
||||
### Error
|
||||
When authentication fails
|
||||
|
||||
## Variables
|
||||
|
||||
- `title` (string): Screen heading
|
||||
- `emailInput` (component): Email input component
|
||||
- `passwordInput` (component): Password input component
|
||||
- `submitButton` (component): Submit button
|
||||
- `error` (component): Error alert (hidden by default)
|
||||
````
|
||||
|
||||
### Step 5: Create screen-name.rendered.md (REAL DATA)
|
||||
|
||||
**This is critical** - show actual rendered output:
|
||||
|
||||
```markdown
|
||||
# Login Screen - Rendered Example
|
||||
|
||||
This shows the actual screen with example data.
|
||||
|
||||
╭────────────────────────────────────────╮
|
||||
│ Welcome Back │
|
||||
├────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Email │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ john@example.com │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Password │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ •••••••• │👁│
|
||||
│ └──────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ╭──────────────────────────────────╮ │
|
||||
│ │ Sign In │ │
|
||||
│ ╰──────────────────────────────────╯ │
|
||||
│ │
|
||||
╰────────────────────────────────────────╯
|
||||
|
||||
## Data Context
|
||||
|
||||
- Email: john@example.com (valid email)
|
||||
- Password: ******** (8 characters, masked)
|
||||
- State: Idle (ready for submission)
|
||||
|
||||
## User Flow
|
||||
|
||||
1. User enters email address
|
||||
2. User enters password
|
||||
3. Optional: Toggle password visibility with 👁 icon
|
||||
4. Click "Sign In" button
|
||||
5. If error: Alert shows above button
|
||||
6. If success: Navigate to dashboard
|
||||
```
|
||||
|
||||
**Why this matters**: Other agents can see the actual intended output, not just templates with {{variables}}.
|
||||
|
||||
## Common Layout Patterns
|
||||
|
||||
### Pattern 1: Vertical Stack (Login/Signup)
|
||||
```
|
||||
╭──────────────────╮
|
||||
│ [Logo/Header] │
|
||||
├──────────────────┤
|
||||
│ [Form Fields] │
|
||||
│ [Input 1] │
|
||||
│ [Input 2] │
|
||||
│ [Input 3] │
|
||||
├──────────────────┤
|
||||
│ [Submit Button] │
|
||||
├──────────────────┤
|
||||
│ [Footer Links] │
|
||||
╰──────────────────╯
|
||||
```
|
||||
|
||||
### Pattern 2: Sidebar + Main (Dashboard)
|
||||
```
|
||||
╭──────╮╭──────────────────────────╮
|
||||
│ ││ │
|
||||
│ Nav ││ Main Content │
|
||||
│ ││ │
|
||||
│ Menu ││ [Components Grid] │
|
||||
│ ││ │
|
||||
│ Items││ [Data/Charts/Cards] │
|
||||
│ ││ │
|
||||
╰──────╯╰──────────────────────────╯
|
||||
```
|
||||
|
||||
### Pattern 3: Tabbed Content (Settings)
|
||||
```
|
||||
╭────────────────────────────────────╮
|
||||
│ Settings [Save] │
|
||||
├────────────────────────────────────┤
|
||||
│ [Tab1] [Tab2] [Tab3] [Tab4] │
|
||||
├────────────────────────────────────┤
|
||||
│ │
|
||||
│ [Tab Content - Form Fields] │
|
||||
│ │
|
||||
╰────────────────────────────────────╯
|
||||
```
|
||||
|
||||
### Pattern 4: Grid Layout (Gallery/Cards)
|
||||
```
|
||||
╭───────────╮ ╭───────────╮ ╭───────────╮
|
||||
│ Card 1 │ │ Card 2 │ │ Card 3 │
|
||||
╰───────────╯ ╰───────────╯ ╰───────────╯
|
||||
╭───────────╮ ╭───────────╮ ╭───────────╮
|
||||
│ Card 4 │ │ Card 5 │ │ Card 6 │
|
||||
╰───────────╯ ╰───────────╯ ╰───────────╯
|
||||
```
|
||||
|
||||
### Pattern 5: List/Table (Data View)
|
||||
```
|
||||
╭──────────────────────────────────────╮
|
||||
│ [Search] [Filters] [Actions] │
|
||||
├──────────────────────────────────────┤
|
||||
│ Header1 │ Header2 │ Header3 │ Action │
|
||||
├─────────┼─────────┼─────────┼────────┤
|
||||
│ Data │ Data │ Data │ [•] │
|
||||
│ Data │ Data │ Data │ [•] │
|
||||
│ Data │ Data │ Data │ [•] │
|
||||
├──────────────────────────────────────┤
|
||||
│ [Pagination] │
|
||||
╰──────────────────────────────────────╯
|
||||
```
|
||||
|
||||
## Responsive Considerations
|
||||
|
||||
Show mobile and desktop layouts when needed:
|
||||
|
||||
````markdown
|
||||
## Desktop Layout (> 768px)
|
||||
|
||||
```
|
||||
╭────╮╭────────────────────────────╮
|
||||
│Nav ││ Main Content │
|
||||
╰────╯╰────────────────────────────╯
|
||||
```
|
||||
|
||||
## Mobile Layout (<= 768px)
|
||||
|
||||
```
|
||||
╭──────────────╮
|
||||
│ [☰] Header │
|
||||
├──────────────┤
|
||||
│ Main Content │
|
||||
╰──────────────╯
|
||||
```
|
||||
````
|
||||
|
||||
## Tips for Great Screens
|
||||
|
||||
1. **Start with wireframe**: Sketch layout before coding
|
||||
2. **Reuse components**: Don't recreate what exists
|
||||
3. **Consistent spacing**: Use multiples of 4 characters
|
||||
4. **Visual hierarchy**: Important items prominent
|
||||
5. **Real examples**: Always create .rendered.md with actual data
|
||||
6. **Document flows**: Explain what users can do
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"Component not found"**
|
||||
- Check component ID spelling (case-sensitive)
|
||||
- Ensure component file exists in ./fluxwing/components/
|
||||
|
||||
**"Layout looks misaligned"**
|
||||
- Use monospace font
|
||||
- Check for consistent box-drawing characters
|
||||
- Ensure spacing is uniform
|
||||
|
||||
**"Too complex"**
|
||||
- Break into smaller sections
|
||||
- Consider nested layouts
|
||||
- Use clear visual dividers
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **View library**: Use `/fluxwing-library` to see all screens
|
||||
- **Create more**: Build additional screens for your app
|
||||
|
||||
You can now compose complete, production-ready screen designs!
|
||||
Reference in New Issue
Block a user