` tags for reusable components
- Include all state variants (default, loading, disabled, error, success)
- Document component props and usage in HTML comments
- Reference design dictionary values (color, spacing, typography) from system design
- Include accessibility attributes
#### 3. Mockup File
**Path**: `src/pages/{module}/{page}/html/mockup.html`
**Purpose**: Visual mockup with sample data and interactions
**Structure**:
```html
Page Mockup
```
**Mockup Rules**:
- Include all possible UI states (loading, success, empty, error)
- Use sample/mock data that represents real data
- Implement basic interactivity (state switching, form inputs)
- Use inline CSS with Tailwind utilities
- Support all breakpoints (mobile, tablet, desktop)
- Include comments explaining each section and state
## Tailwind CSS Integration & Design System Reference
### ⭐ CRITICAL: Design System Compliance
**Every HTML file MUST reference the project's design specifications before generation:**
```
Read: {PROJECT_ROOT}/.r2mo/design/spec.md
Apply: All design tokens, color palettes, typography, spacing
Implement: Use Tailwind CSS utility classes following design system rules
```
### Design System Structure in spec.md
The design specification file defines:
```
1. Color Palette
└─ Brand colors (primary-50 to primary-900)
└─ Neutral colors (gray, white backgrounds)
└─ Semantic colors (success, warning, error, info)
└─ Mapping to Tailwind utility classes (bg-primary-600, text-gray-500, etc.)
2. Typography
└─ Type scale (text-xs, text-sm, text-base, text-lg, text-xl, text-2xl)
└─ Font families (font-sans, font-mono)
└─ Font weights and line heights
└─ Usage recommendations for each level
3. Layout & Spacing
└─ Breakpoints (sm, md, lg, xl, 2xl)
└─ Container configuration with padding
└─ Spacing scale (gap, p, m, etc.)
└─ Mobile-first approach
4. Borders & Effects
└─ Border radius (rounded-sm, rounded-md, rounded-lg, rounded-full)
└─ Box shadows (shadow-sm, shadow, shadow-md, shadow-xl)
└─ Elevation levels
5. Component Primitives
└─ Button styles (Primary, Secondary, Ghost)
└─ Form input styles
└─ Badge/Chip styles
└─ @apply directives for component combinations
```
### Tailwind CSS Application Process
1. **Read the design spec FIRST**
```
Extract color definitions (e.g., primary-600: #2563eb)
Extract typography scale (e.g., text-lg: 18px/28px, Semibold)
Extract spacing rules (e.g., gap-4, p-6)
Extract component primitives (e.g., Btn-Base, Input-Base)
```
2. **Map spec tokens to Tailwind utilities**
```
Instead of: style="color: #2563eb; padding: 16px; border-radius: 6px;"
Use: class="text-primary-600 p-4 rounded-md"
```
3. **Apply semantic color aliases**
```
For success state: bg-emerald-50 text-emerald-600
For error state: bg-red-50 text-red-600
For warning state: bg-amber-50 text-amber-500
For info state: bg-blue-50 text-blue-500
```
4. **Follow responsive patterns from spec**
```
Mobile-first approach:
Using defined breakpoints (sm, md, lg, xl, 2xl)
```
5. **Use component primitives for consistency**
```
Buttons: Combine Btn-Base + Btn-Size-Default + Btn-Variant (Primary/Secondary/Ghost)
Inputs: Combine Input-Base + Input-Size + Input-State (Error/Disabled)
Badges: Combine Badge-Base + Badge-Color-Variant
```
### Example: Applying Design System to HTML
```html
```
### Validation Against Design System
Before finalizing HTML output:
- [ ] All colors use spec.md color tokens (primary-*, gray-*, semantic colors)
- [ ] All typography uses spec.md type scale (text-xs through text-2xl)
- [ ] All spacing matches spec.md grid (px-*, py-*, gap-*, etc.)
- [ ] All border radius follows spec.md definitions
- [ ] All components match spec.md primitives
- [ ] Responsive design uses spec.md breakpoints (sm, md, lg, xl, 2xl)
- [ ] Button variants match Btn-Primary/Secondary/Ghost
- [ ] Form inputs follow Input-Base pattern
- [ ] Colors are semantic (success=emerald, error=red, warning=amber, info=blue)
---
## Design Draft Workflow
### Scenario 1: Draft Exists
If `.r2mo/design/draft/{page_id}/` directory contains HTML files:
1. **Read Draft**: Load existing draft HTML file
2. **Analyze Structure**: Understand layout, styling, components
3. **Enhance**: Add components, states, responsiveness
4. **Preserve Design**: Keep original design intent and styling
5. **Output**: Generate three output files based on enhanced draft
**Example**:
```
.r2mo/design/draft/user-list/
├── layout.html (existing draft)
└── notes.txt (optional design notes)
Output:
src/pages/system/user/html/
├── layout.html (enhanced from draft)
├── components.html (extracted components)
└── mockup.html (complete mockup)
```
### Scenario 2: No Draft
If no draft exists in `.r2mo/design/draft/{page_id}/`:
1. **Read Specification**: Use `requirement.page.md` and `page.yaml` exclusively
2. **Design from Specs**: Create layout based on UI Specification section
3. **Apply Design System**: Use global design specs and Tailwind utilities
4. **Generate All Files**: Create three output files from specifications
**Example**:
```
requirement.page.md (UI Specification section)
page.yaml (@LAYOUT configuration)
Output:
src/pages/system/user/html/
├── layout.html (from UI Specification)
├── components.html (from @LAYOUT components)
└── mockup.html (complete implementation)
```
## Process
### 1. Detect Design Draft
```
Check: .r2mo/design/draft/{page_id}/ directory
If exists:
- Load HTML draft files
- Parse structure and styling
- Identify design patterns
If not exists:
- Use requirement.page.md and page.yaml only
```
### 2. Read Page Specification
```
Input: {MODULE_PATH}/requirement.page.md
Extract:
- Section 1: Context (Goal, User, Parameters)
- Section 2: Data Model (Props, Local State)
- Section 4: UI Specification (Structure, View States)
- Section 5: API Integration (Field list)
Input: {MODULE_PATH}/page.yaml
Extract:
- @METADATA: Page metadata
- @DICT: Data dictionaries
- @LAYOUT: Layout components
```
### 3. Reference Design System
```
Input: {PROJECT_ROOT}/.r2mo/design/spec.md ⭐ MANDATORY
Extract:
- Color palette and semantic color aliases
- Typography scale and font definitions
- Layout breakpoints and spacing rules
- Border radius and shadow definitions
- Component primitives (buttons, inputs, badges)
- Tailwind utility class mappings
```
### 4. Generate layout.html
```
Output: src/pages/{module}/{page}/html/layout.html
Structure:
- DOCTYPE and HTML head (meta, title, styles)
- Page layout skeleton per UI Specification → Structure
- Main content regions
- Semantic HTML5 structure
- Tailwind CSS utility classes (ref: .r2mo/design/spec.md)
- ARIA labels for accessibility
- Data attributes for state visualization
Apply Design System:
- Use color tokens from spec.md (primary-600, gray-500, emerald-600, etc.)
- Use typography scale from spec.md (text-lg, font-semibold, etc.)
- Use spacing from spec.md (gap-4, p-6, px-4, etc.)
- Use component primitives from spec.md (Btn-Base, Input-Base, etc.)
- Use responsive breakpoints from spec.md (md:, lg:, etc.)
- Use semantic colors from spec.md (success, error, warning, info)
Include All States:
- data-state="loading" (loading skeleton with spec.md colors)
- data-state="empty" (empty state with spec.md typography)
- data-state="error" (error with spec.md error color)
- data-state="success" (normal content with spec.md primary color)
```
### 5. Generate components.html
```
Output: src/pages/{module}/{page}/html/components.html
Component Types (based on page.yaml @LAYOUT):
- Form components (input, textarea, select, checkbox)
- Table/List components (rows, cells, pagination)
- Modal/Dialog components
- Button variants (primary, secondary, danger)
- Badge/Tag components
- Loading skeleton
- Empty state template
- Error state template
Each Component Includes:
- Markup structure
- Tailwind CSS classes
- State variants
- Accessibility attributes
- HTML comments with usage examples
```
### 6. Generate mockup.html
```
Output: src/pages/{module}/{page}/html/mockup.html
Content:
- Complete HTML page (DOCTYPE, head, body)
- Sample data populated in all UI elements
- All state variants visible or switchable
- Basic JavaScript for state management (optional)
- Inline Tailwind CSS + custom styles
- Comments explaining each section
State Switching:
- Include buttons or tabs to switch between states
- Demonstrate loading → success flow
- Show error state recovery
- Display empty state
```
### 7. Validate Output
```
Checks:
- [ ] All 3 files exist in correct location
- [ ] HTML is valid and well-formed
- [ ] Tailwind classes are correct
- [ ] Semantic HTML structure used
- [ ] Accessibility attributes included
- [ ] All UI states represented
- [ ] Responsive design implemented
- [ ] Draft (if exists) design intent preserved
- [ ] No hardcoded pixel values (use Tailwind)
- [ ] Comments explain complex sections
```
## Rules
### Mandatory Rules
1. **Design System Compliance** ⭐ **CRITICAL**
- MUST read and reference `{PROJECT_ROOT}/.r2mo/design/spec.md` BEFORE generating any HTML
- Use ONLY Tailwind CSS utility classes from design spec
- NO inline styles (style="...") for any design elements
- All colors MUST use spec.md color palette tokens
- All typography MUST use spec.md type scale
- All spacing MUST use spec.md spacing definitions
- All responsive design MUST use spec.md breakpoints
- Follow spec.md component primitives exactly
- Example: `class="bg-primary-600 text-white hover:bg-primary-700"` not `style="background: blue"`
2. **Output Directory Fixed**
- ALL outputs MUST go to `src/pages/{module}/{page}/html/`
- Exactly 3 files: layout.html, components.html, mockup.html
- No outputs to other directories
3. **HTML Quality**
- Use semantic HTML5 tags
- Valid HTML structure (DOCTYPE, proper nesting)
- Accessibility: ARIA labels, semantic elements, keyboard navigation
- No inline JavaScript (use data attributes instead)
4. **Tailwind CSS with Design System**
- Use ONLY Tailwind CSS utility classes (no custom CSS)
- All utilities MUST be defined in `.r2mo/design/spec.md`
- No hardcoded colors, sizes, or spacing - reference spec.md
- Responsive design with spec.md breakpoints (sm, md, lg, xl, 2xl)
- Component combinations follow spec.md @apply patterns
- Example color usage: `text-primary-600` (not `text-blue-600`)
- Example spacing usage: `gap-4 p-6` (from spec.md scale)
4. **State Management**
- Use data attributes for state: `data-state="loading|empty|error|success"`
- Include all states from requirement.page.md Section 4: View States
- Document state transitions in comments
5. **Design Draft Handling**
- If draft exists: use as template, enhance with components and states
- If draft not exists: create from scratch using specifications
- Preserve design intent from draft
- Don't override draft styling unless necessary for functionality
6. **Consistency**
- All three files must use same design system
- Component markup consistent between files
- Class names and structure aligned
- Design tokens from global specs applied
### Content Rules
1. **No Fabrication**
- Use only values from requirements and design specs
- Don't invent component names or structures
- Reference existing design system components
2. **Accessibility First**
- Semantic HTML (main, section, article, aside, nav, etc.)
- ARIA labels for complex components
- Form labels with proper associations
- Color contrast compliance
3. **Mobile-First Responsive**
- Start with mobile layout
- Use Tailwind breakpoints for tablet/desktop
- Test at multiple viewport sizes
- No hardcoded dimensions
4. **Documentation**
- Comments for non-obvious sections
- Component usage examples
- State explanation and transitions
- Data attributes and their meaning
## Validation Checklist
### File Structure
- [ ] Directory: `src/pages/{module}/{page}/html/` exists
- [ ] File: `layout.html` present and valid
- [ ] File: `components.html` present and valid
- [ ] File: `mockup.html` present and valid
- [ ] No other files in html directory
### HTML Quality
- [ ] Valid HTML structure (DOCTYPE, head, body, proper nesting)
- [ ] Semantic HTML5 tags used appropriately
- [ ] All tags properly closed
- [ ] Consistent indentation (2 spaces)
### Styling
- [ ] Only Tailwind CSS utility classes
- [ ] Responsive breakpoints implemented (sm, md, lg, xl)
- [ ] Color classes from design system
- [ ] No hardcoded pixel values
- [ ] Consistent spacing (use Tailwind spacing scale)
### Accessibility
- [ ] ARIA labels on interactive elements
- [ ] Form labels properly associated
- [ ] Keyboard navigation supported
- [ ] Color not sole way to convey information
- [ ] Semantic HTML structure
### State Management
- [ ] All states represented (loading, empty, error, success)
- [ ] State visualization using data attributes
- [ ] State transitions documented
- [ ] Components show state variations
### Design Specification Compliance
- [ ] Layout matches UI Specification → Structure
- [ ] Components match page.yaml @LAYOUT
- [ ] Colors from design system
- [ ] Typography from design tokens
- [ ] Component behaviors specified
### Draft Integration (If Applicable)
- [ ] Draft design intent preserved
- [ ] Draft styling enhanced (not replaced)
- [ ] Draft structure maintained where appropriate
- [ ] Components extracted from draft
### Components Coverage
- [ ] All layout components included
- [ ] Component variants for all states
- [ ] Loading skeleton template
- [ ] Empty state template
- [ ] Error state template
## Context Paths Reference
```
Page Specification:
├── {MODULE_PATH}/requirement.page.md ← Primary input
├── {MODULE_PATH}/page.yaml ← Layout config
└── {MODULE_PATH}/requirement.module.md ← Module context
Design References:
├── .r2mo/design/draft/{page_id}/ ← Design draft (if exists)
├── .r2mo/design/page/{page_id}/spec.md ← Page-specific design
├── .r2mo/design/spec.md ← Global design system
└── {PROJECT_ROOT}/.r2mo/api/marker.md ← Field validation rules
Output Directory:
└── src/pages/{module}/{page}/html/
├── layout.html ← HTML structure
├── components.html ← Component library
└── mockup.html ← Visual mockup
```
## Success Criteria
- ✅ All 3 HTML files generated in correct location
- ✅ HTML is valid, semantic, and accessible
- ✅ Tailwind CSS styling applied consistently
- ✅ All UI states represented
- ✅ Responsive design implemented
- ✅ Design intent from draft (if exists) preserved
- ✅ No validation errors in HTML or CSS
- ✅ Components match specification requirements
- ✅ Documentation clear and comprehensive
- ✅ Ready for r2-dev-page skill implementation
- ✅ Developers can implement pages directly from mockup
---
## Built-in Tools
### extract-draft.py
**Location**: `{SKILL_ROOT}/scripts/extract-draft.py`
**Purpose**: Extract design draft HTML and analyze structure
**Usage**:
```bash
cd {module-path}
python {SKILL_ROOT}/scripts/extract-draft.py \
--draft .r2mo/design/draft/{page_id} \
--output draft-analysis.json
```
**Output**: draft-analysis.json containing:
- HTML structure
- CSS classes used
- Component identifiers
- Color scheme
- Typography
- Layout structure
---
## Integration Points
### Input from r2-req-page
This skill uses output from `r2-req-page`:
- `requirement.page.md` - Page specification
- `page.yaml` - Page configuration
### Output for r2-dev-page
This skill provides visual reference for `r2-dev-page`:
- HTML mockups for component reference
- Layout structure for code implementation
- Component patterns for code generation
- State visualization for implementation guidance
### Design Workflow
- Input: Design drafts from `.r2mo/design/draft/`
- Process: Enhance and structure drafts
- Output: Production-ready HTML templates
- Next: r2-dev-page uses HTML as reference for code
---
## Troubleshooting
### Issue: Draft exists but styling seems wrong
**Solution**: Check that draft path matches `{page_id}`. Draft should be in `.r2mo/design/draft/{page_id}/`.
### Issue: Components don't match specification
**Solution**: Verify `page.yaml @LAYOUT` matches generated components. Extract component requirements from `requirement.page.md` Section 4.
### Issue: States not clearly visible
**Solution**: Use CSS comments and `data-state` attributes to clearly mark each state section. Consider adding state selector buttons in mockup.
### Issue: Responsive design not working
**Solution**: Ensure Tailwind breakpoints are used (sm, md, lg, xl). Test at multiple viewport sizes. Check that mobile styles come first (mobile-first approach).
### Issue: ARIA labels missing
**Solution**: Review all interactive elements. Add aria-label to buttons without text. Associate form labels with inputs using for/id. Add aria-describedby for error messages.
---
## Examples
### Example 1: User List Page with Draft
```
Input:
- requirement.page.md: User list with search, filter, table
- page.yaml: SearchBar, Table, Modal components
- .r2mo/design/draft/user-list/layout.html: Existing draft
Process:
1. Load draft HTML
2. Enhance with missing components
3. Add state variations (loading, empty, error)
4. Create components.html from draft analysis
5. Generate mockup.html with sample data
Output:
src/pages/system/user/html/
├── layout.html (draft-based structure)
├── components.html (extracted + new components)
└── mockup.html (complete interactive mockup)
```
### Example 2: Form Page Without Draft
```
Input:
- requirement.page.md: User creation form with validation
- page.yaml: Form components, validation rules
- .r2mo/design/spec.md: Form styling guidelines
Process:
1. No draft found in .r2mo/design/draft/
2. Create layout.html from UI Specification
3. Generate form components from page.yaml
4. Apply design system styling
5. Create mockup with form validation states
Output:
src/pages/system/user/html/
├── layout.html (form structure)
├── components.html (input, button variants, error states)
└── mockup.html (interactive form with validation)
```
---
**Version**: 1.0.0
**Last Updated**: 2026-02-07
**Status**: Production Ready
---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/silentbalanceyh) — claim your Tome and manage your conversions.