Create Workflow

Use this guide when:

• Creating a new document from scratch
• Redesigning/beautifying an existing poorly-formatted document (content extraction + new design)

1. Lane Clarification

When input exists but user wants redesign, treat the file as content source, not template.

2. Content Extraction (When Input Exists)

2.1 Detect Container Type

Check magic bytes before processing:

xxd -l 8 <input-file>

2.2 Convert Legacy .doc

soffice --headless --convert-to docx --outdir <tmp-dir> <input.doc>

• Do NOT use textutil (loses structure fidelity)
• Keep original read-only
• Work with converted copy

2.3 Extract Content

# Preview text content
python3 <skill-path>/docx_engine.py preview <input.docx>

# Or use pandoc for structured extraction
pandoc <input.docx> -t markdown -o content.md

Extract:

• Text content (paragraphs, headings)
• Table data
• List items
• Image references (if reusable)

Discard:

• Poor styling/formatting
• Broken layouts
• Inconsistent spacing

3. Scene Routing

Match the document's purpose to a template starting point:

No exact match? Use design primitives (Section 2) to compose from scratch.

4. Design Primitives

When no template fits, combine these building blocks:

2.1 Cover Page Patterns

Implementation: render/page_art.py for backgrounds, Word text layer for editability.

2.2 Body Layout Patterns

Implementation: See Layout.cs for column/section helpers.

2.3 Navigation Elements

5. Design Decision Framework

When composing without a template, answer these questions:

3.1 Content Density

3.2 Visual Focus

3.3 Reading Pattern

3.4 Audience & Purpose

6. Adjustment Guide

4.1 Color Palette

Location: src/Templates/Themes.cs or inline in your code.

// Use a predefined theme
var colors = Themes.Ocean;  // or Forest, Stone, Ember, Amethyst, Monochrome

// Apply to heading
new Color { Val = colors.Heading }

// Apply to body
new Color { Val = colors.Body }

Principles:

• Maximum 3 primary colors
• Use muted/desaturated tones
• Ensure sufficient contrast (heading vs body)

Scene-color mapping:

4.2 Spacing & Margins

Location: src/Core/Layout.cs, src/Core/Primitives.cs

Unit reference: 1 pt = 20 twips, 1 inch = 1440 twips

4.3 Structure Modifications

Add cover page:

// 1. Add cover content
body.Append(CreateCoverPage(title, subtitle, date));

// 2. End cover section (CRITICAL for small paper)
body.Append(new Paragraph(
    new ParagraphProperties(
        new SectionProperties(
            new SectionType { Val = SectionMarkValues.NextPage }
        )
    )
));

// 3. Continue with body content

Add TOC:

// Use Fields.cs helper
body.Append(Fields.TableOfContents());

// Add refresh hint (gray, smaller font)
body.Append(new Paragraph(
    new ParagraphProperties(new ParagraphStyleId { Val = "TOCHint" }),
    new Run(
        new RunProperties(
            new Color { Val = "808080" },
            new FontSize { Val = "18" }
        ),
        new Text("(Right-click TOC → Update Field to refresh page numbers)")
    )
));

Remove headers/footers: Simply don't append HeaderPart/FooterPart.

4.4 Paper Size Adaptation

Small paper (A5/B5) checklist:

• Use section breaks, not spacing hacks, for cover isolation
• Reduce all spacing proportionally (see 4.2)
• Test that cover content fits on one page
• Consider removing TOC if document is short

Reference: src/Templates/PoetryCollection.cs demonstrates A5/B5 patterns.

7. Scenario Completeness

When creating from scratch, verify role-critical blocks are present:

8. Visual Exit Checklist

Before delivery, verify:

• Hierarchy: H1 > H2 > H3 visually distinct (size, weight, spacing)
• Spacing: Consistent paragraph gaps, no cramped sections
• Alignment: Text aligned consistently (usually left/justified)
• Colors: ≤3 primary colors, no clashing tones
• Whitespace: Margins ≥72pt, content not edge-to-edge
• Flow: KeepNext on headings, PageBreakBefore on chapters
• Navigation: Page numbers present if multi-page
• TOC: Includes refresh hint if present

9. Build Commands

# 1. Check environment
python3 <skill-path>/docx_engine.py doctor

# 2. Generate document
python3 <skill-path>/docx_engine.py render output.docx

# 3. Validate
python3 <skill-path>/docx_engine.py audit output.docx

# 4. Preview content
python3 <skill-path>/docx_engine.py preview output.docx

10. Code References