Uniword ships with OFL-licensed open-source resources that replace proprietary Microsoft Word assets. These resources allow you to create professional documents without requiring a Microsoft Word installation.

1. Resource Files

Resource Count Location

Color schemes

23

data/color_schemes/*.yml

Font schemes

25

data/font_schemes/*.yml

Document elements

240

data/resources/document_elements/{locale}/*.yml

Font registry

1

data/resources/font_registry.yml

XSD schemas

40

data/schemas/{iso,ecma,microsoft}/*.xsd

Stylesets

12

data/stylesets/*.yml

Themes

29

data/themes/*.yml

2. Supported Locales

30 locales are supported for document elements:

Americas Europe Europe (cont.) Middle East Asia

en

cs

nl

ar

ja

en-GB

da

no

he

ko

es

de

pl

zh-CN

es-MX

el

pt

zh-TW

fr

fi

pt-PT

fr-CA

hu

ru

id

sk

it

sv

th

tr

3. Document Element Categories

Each locale provides 8 categories of document elements (30 locales x 8 categories = 240 files):

Category Description

Bibliographies

Citation and bibliography formatting templates

Cover pages

Pre-designed cover page layouts

Equations

Equation display templates

Footers

Header and footer designs

Headers

Document header layouts

Table of contents

TOC formatting and styles

Tables

Table design templates

Watermarks

Document watermark overlays

4. XSD Schemas

Uniword bundles 40 XSD schemas from three sources for DOCX validation:

ISO

data/schemas/iso/ — ISO/IEC 29500 schema files

ECMA

data/schemas/ecma/ — ECMA-376 schema files

Microsoft

data/schemas/microsoft/ — Microsoft-specific extensions

These schemas are used by the uniword verify --xsd command for rigorous structural validation.

5. Usage 

# Apply a bundled theme
doc.apply_theme('celestial')

# Apply a bundled styleset
doc.apply_styleset('distinctive')

# Resources are loaded automatically from the gem's data directory

6. Resource Resolution

The ResourceResolver resolves resources from multiple sources in order:

  1. Cached — User-imported or previously resolved resources stored in the local cache directory

  2. Bundled — Resources shipped with the Uniword gem in data/

resolver = Uniword::Resource::ResourceResolver.new

# Check if a theme exists in any source
resolver.exists?(:theme, "celestial")  # => true

# List all available resources (cached + bundled)
resolver.list_all(:theme)  # => ["celestial", "meridian", ...]

# List only bundled resources
resolver.list(:theme, source: :bundled)

# Resolve a resource (returns ResourceLocation)
location = resolver.resolve(:theme, "celestial")
location.exists?  # => true

7. Resource Caching

The Cache class manages imported resources on the local filesystem:

cache = Uniword::Resource::Cache.new

# Write a custom theme to cache
cache.write(:theme, "my-brand", yaml_content)

# Read from cache
content = cache.read(:theme, "my-brand")

# List cached resources
cache.list(:theme)  # => ["my-brand"]

# Delete a cached resource
cache.delete(:theme, "my-brand")

# Clear all cached resources
cache.clear!

8. Font Substitution

The FontSubstitutor maps proprietary Microsoft fonts to OFL-licensed alternatives at three levels:

# Substitute a single font name
Uniword::Resource::FontSubstitutor.substitute("Calibri")
# => "Carlito"

# Substitute by OOXML script code
Uniword::Resource::FontSubstitutor.substitute_script("Jpan", "MS Gothic")
# => "Noto Sans CJK JP"

# Transform an entire font scheme (Latin + EA + CS)
scheme = doc.theme.theme_elements.font_scheme
Uniword::Resource::FontSubstitutor.transform_font_scheme(scheme)

# Check font availability via Fontist (if installed)
Uniword::Resource::FontSubstitutor.check_availability("Carlito")
# => true

9. MS Theme Auto-Transition

When opening documents created in Microsoft Word, Uniword can detect and replace MS themes with OFL equivalents using color fingerprint matching.

doc = Uniword::Document.open("ms_report.docx")

# Auto-detect MS theme and apply Uniword equivalent
result = Uniword::Resource::ThemeTransition.auto_transition!(doc)
puts result.ms_name         # => "Atlas"
puts result.uniword_slug    # => "meridian"

# Detect by theme object (color fingerprint)
slug = ThemeTransition.detect_ms_theme(doc.theme)

# Detect by name string
slug = ThemeTransition.from_ms_name("Atlas")
# => "meridian"

See Auto Theme Transition for full details.

10. Resource Architecture

The resource module is organized into categories:

Category Components

Services

ColorTransformer, FontSubstitutor — stateless pure functions

Loaders

ColorSchemeLoader, FontSchemeLoader, DocumentElementLoader, ThemeMappingLoader — load from data files

Transitions

ThemeTransition — detect and migrate between MS and Uniword themes

Models

ThemeProcessor, Cache, CacheVersion, ResourceResolver — stateful objects

Value Objects

CachePaths, ResourceLocation — immutable structs

Converters

DocumentElementConverter — transform between formats

Templates

DocumentElementTemplate — document element templates