320 lines
11 KiB
Markdown
320 lines
11 KiB
Markdown
# 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!
|