word-styles

Word Styles and Formatting

This skill provides deep expertise for style-based document formatting in Microsoft Word (.docx). Use styles instead of direct formatting for maintainable, consistent documents.

Style Hierarchy (Override Order)

1. Document defaults (docDefaults in styles.xml) - Base formatting
2. Style definition - Named style properties
3. Direct formatting - Inline overrides on specific text

Understanding this hierarchy is essential for troubleshooting "why isn't my formatting applying?"

Quick Reference

Access Styles with python-docx

from docx import Document
from docx.shared import Pt, Inches, RGBColor
from docx.enum.style import WD_STYLE_TYPE
from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING

doc = Document('file.docx')

# Get existing style
style = doc.styles['Normal']
style = doc.styles['Heading 1']

# Create new paragraph style
new_style = doc.styles.add_style('CustomBody', WD_STYLE_TYPE.PARAGRAPH)
new_style.base_style = doc.styles['Normal']
new_style.font.name = 'Calibri'
new_style.font.size = Pt(11)

# Create character style
char_style = doc.styles.add_style('Emphasis', WD_STYLE_TYPE.CHARACTER)
char_style.font.italic = True
char_style.font.color.rgb = RGBColor(0x00, 0x00, 0x80)

Common Paragraph Formatting

from docx.shared import Pt, Twips

style = doc.styles['Normal']
pf = style.paragraph_format

# Spacing
pf.space_before = Pt(0)
pf.space_after = Pt(8)
pf.line_spacing = 1.15  # Multiple
pf.line_spacing_rule = WD_LINE_SPACING.MULTIPLE

# Indentation
pf.left_indent = Inches(0)
pf.right_indent = Inches(0)
pf.first_line_indent = Inches(0.5)  # First line indent
pf.first_line_indent = Inches(-0.5)  # Hanging indent (negative)

# Alignment
pf.alignment = WD_ALIGN_PARAGRAPH.JUSTIFY

# Pagination controls
pf.keep_together = True
pf.keep_with_next = True
pf.page_break_before = False
pf.widow_control = True

Common Character Formatting

style = doc.styles['Normal']
font = style.font

font.name = 'Calibri'
font.size = Pt(11)
font.bold = False
font.italic = False
font.underline = True  # or WD_UNDERLINE.SINGLE
font.color.rgb = RGBColor(0x00, 0x00, 0x00)
font.highlight_color = WD_COLOR_INDEX.YELLOW
font.all_caps = False
font.small_caps = False
font.strike = False
font.subscript = False
font.superscript = False

Decision Tree

When to Use Styles vs Direct Formatting

Use styles when:

• Formatting applies to multiple paragraphs/runs
• Document will be edited or maintained
• Consistency across document is required
• Creating templates

Use direct formatting when:

• One-off formatting exception
• Quick prototype/draft
• Overriding style for specific instance

When to Modify vs Create New Style

Modify existing style when:

• Changing document-wide appearance
• Style name already describes purpose (e.g., making "Heading 1" blue)

Create new style when:

• Need distinct formatting for different purposes
• Want to preserve original style
• Style is based on another (inheritance)

Working with Style Inheritance

Based-on Relationships

# Create style based on another
custom = doc.styles.add_style('CustomHeading', WD_STYLE_TYPE.PARAGRAPH)
custom.base_style = doc.styles['Heading 1']
custom.font.color.rgb = RGBColor(0x00, 0x66, 0x99)
# Inherits all Heading 1 properties except color

Best practices:

• Keep inheritance chains shallow (2-3 levels max)
• Only override properties that differ
• Test changes by applying style to sample text

Next Paragraph Style

# After pressing Enter, switch to Normal
doc.styles['Heading 1'].next_paragraph_style = doc.styles['Normal']

# After pressing Enter in list item, continue with same style
doc.styles['List Paragraph'].next_paragraph_style = doc.styles['List Paragraph']

OOXML Direct Access

When python-docx lacks API support, access raw XML. First unpack the document:

python /mnt/skills/public/docx/ooxml/scripts/unpack.py document.docx unpacked/

Style XML Structure (styles.xml)

<w:style w:type="paragraph" w:styleId="CustomBody">
  <w:name w:val="Custom Body"/>
  <w:basedOn w:val="Normal"/>
  <w:next w:val="Normal"/>
  <w:qFormat/>  <!-- Show in Quick Styles gallery -->
  <w:uiPriority w:val="1"/>
  <w:pPr>
    <w:spacing w:after="160" w:line="259" w:lineRule="auto"/>
    <w:ind w:firstLine="720"/>
    <w:jc w:val="both"/>
  </w:pPr>
  <w:rPr>
    <w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/>
    <w:sz w:val="22"/>  <!-- Half-points: 22 = 11pt -->
    <w:szCs w:val="22"/>
  </w:rPr>
</w:style>

Style Types

w:type value	Description
paragraph	Paragraph style (includes character props)
character	Character-only style
table	Table style
numbering	List/numbering style

Making Styles Visible in Word UI

Styles may be "latent" (hidden). To show them:

<w:latentStyles>
  <w:lsdException w:name="Custom Body" w:semiHidden="0" w:unhideWhenUsed="0"/>
</w:latentStyles>

Or set on the style itself:

<w:style w:type="paragraph" w:styleId="CustomBody">
  <w:qFormat/>  <!-- Add to Quick Styles -->
  <w:uiPriority w:val="1"/>  <!-- Sort order in gallery -->
</w:style>

Common Patterns

Professional Body Text Setup

body = doc.styles['Normal']
body.font.name = 'Calibri'
body.font.size = Pt(11)
body.paragraph_format.space_after = Pt(8)
body.paragraph_format.line_spacing = 1.15
body.paragraph_format.widow_control = True

Heading Hierarchy

for i, (name, size) in enumerate([('Heading 1', 16), ('Heading 2', 14), ('Heading 3', 12)], 1):
    h = doc.styles[name]
    h.font.name = 'Calibri Light'
    h.font.size = Pt(size)
    h.font.bold = True
    h.font.color.rgb = RGBColor(0x2E, 0x74, 0xB5)
    h.paragraph_format.space_before = Pt(12)
    h.paragraph_format.space_after = Pt(4)
    h.paragraph_format.keep_with_next = True

Block Quote Style

quote = doc.styles.add_style('BlockQuote', WD_STYLE_TYPE.PARAGRAPH)
quote.base_style = doc.styles['Normal']
quote.font.italic = True
quote.paragraph_format.left_indent = Inches(0.5)
quote.paragraph_format.right_indent = Inches(0.5)
quote.paragraph_format.space_before = Pt(12)
quote.paragraph_format.space_after = Pt(12)

Troubleshooting

Style Not Applying

1. Check direct formatting - Select text, clear direct formatting (Ctrl+Space for character, Ctrl+Q for paragraph)
2. Check inheritance - Style may inherit conflicting property from base style
3. Check document defaults - docDefaults in styles.xml may override

Inconsistent Formatting

1. Multiple styles with same name - Check for duplicates in styles.xml
2. Latent style override - Check latentStyles section
3. Theme font substitution - Document may use theme fonts that vary by system

List Numbering Issues

See references/numbering-lists.md for numbering.xml structure and troubleshooting.

Reference Files

• references/style-properties.md - Complete property reference for paragraph/character formatting with python-docx and OOXML equivalents
• references/numbering-lists.md - List and numbering definition patterns, abstractNum/num relationships
• references/theme-colors.md - Theme color system, tint/shade calculations

Utility Scripts

• scripts/inspect_styles.py - Dump all styles from a document with properties and inheritance
• scripts/apply_style_template.py - Copy style definitions from template to target document

Usage:

python scripts/inspect_styles.py document.docx
python scripts/apply_style_template.py template.docx target.docx --styles "Heading 1,Normal"

Dependencies

pip install python-docx --break-system-packages