Stylistic

AI-powered editorial suggestions for Microsoft Word, applied as native Track Changes.

Stylistic analyzes Spanish-language documents, proposes improvements, and writes them directly into Word's review workflow so users can accept or reject every change with the tools they already know.

Table of Contents

• Why Stylistic
• What it does
• Product tour
• How it works
• Quick start
• Architecture at a glance
• Project structure
• Scripts
• Requirements
• Tech stack
• Documentation
• Known limitations
• Contributing
• Releasing
• README image assets
• License

Why Stylistic

Most AI writing tools ask users to leave their editor, review suggestions in a separate UI, then manually port changes back into the document. That breaks the editorial workflow.

Stylistic takes the opposite approach:

• it keeps the user inside Microsoft Word,
• it uses native Track Changes instead of a custom diff UI,
• it adds contextual comments explaining each suggestion,
• and it preserves a human-first review step for every change.

Core idea: the add-in behaves like an editorial assistant embedded in Word, not like an external rewriting tool.

What it does

• Analyzes Spanish-language text with AI through Stylistic Hub.
• Creates native tracked changes that appear directly in Word's Review tab.
• Attaches justification comments with category and reasoning for each suggestion.
• Supports large documents through paragraph-boundary chunking.
• Keeps review non-destructive by restoring the document's original tracking mode.
• Surfaces severity levels so users can prioritize which suggestions matter first.
• Includes resolved-comment cleanup to remove orphaned comments after review.
• Separates concerns cleanly across taskpane UI, domain logic, Word adapters, and backend adapters.

Product tour

Main analysis flow

Settings and profile management

Native review experience inside Word

How it works

1. Stylistic Hub serves the task pane and hands it an API token.
2. Stylistic reads the current document and splits it into safe processing chunks.
3. The hub analyzes the chunks and returns editorial suggestions.
4. The add-in applies those suggestions as real Word revisions.
5. The user reviews everything from the Review tab with standard Word controls.

This means the add-in does not invent a parallel approval system. It plugs AI assistance into the workflow writers and editors already trust.

Quick start

Prerequisites

• Node.js 18+
• Bun
• Microsoft Word desktop or Word Online
• A running Stylistic Hub with a model configured (hub branch feat/hub-api-v1)

Install dependencies

bun install

Connect to Stylistic Hub

There are no accounts and no backend URL to configure. The hub serves the task pane and injects its API token as <meta name="stylistic-hub-token">; the add-in calls the hub at its own origin plus /api/v1. A task pane that the hub did not serve has no token, so analysis stays unavailable and the pane says so.

See docs/api-contract.md for the parts of Stylistic Hub API v1 the add-in uses.

Run the add-in

bun run start

This starts the local dev server at https://localhost:3000 and sideloads the add-in into Word desktop.

First-run flow

1. Open Word and launch Show Task Pane from the ribbon.
2. Adjust the analysis profile in Settings if needed.
3. Click Analizar y sugerir.
4. Review the generated tracked changes in Word.
5. Optionally click Limpiar comentarios resueltos after accepting or rejecting changes.

Architecture at a glance

Stylistic follows a hexagonal frontend architecture. The add-in owns Word orchestration, taskpane state, and document mutation. Stylistic Hub owns the API token and AI analysis.

┌─────────────────────────────────────────────────┐
│  Word Add-in                                    │
│                                                 │
│  taskpane.ts — composition root                 │
│  ├── adapters/word — Office.js boundary         │
│  ├── adapters/hub — Stylistic Hub API v1        │
│  ├── domain — pure ports, types, workflows      │
│  └── taskpane/components — React + Fluent UI    │
├─────────────────────────────────────────────────┤
│  Stylistic Hub                                  │
│  ├── serves the task pane + API token           │
│  └── /api/v1 — analyses, feedback, preferences  │
└─────────────────────────────────────────────────┘

Layer	Location	Responsibility	Office.js access
Composition	src/taskpane/taskpane.ts	Wires ports, adapters, stores, and UI handlers	No
Presentation	src/taskpane/**	React shell, Fluent UI components, Zustand state	No
Word adapters	src/adapters/word/**	Document reads, writes, comments, tracked changes, cleanup	Yes
Hub adapters	src/adapters/hub/**	Analyses, feedback, and preferences on Stylistic Hub API v1	No
Domain	src/domain/**	Ports, types, pipeline orchestration, review workflow	No
Infrastructure	src/infrastructure/**	Configuration, shared helpers, chunking support	No

For the full architectural rationale, read docs/architecture.md.

Project structure

stylistic-addon/
├── src/
│   ├── commands/                 # Ribbon command handlers
│   ├── adapters/                 # Word, auth, and backend implementations
│   ├── domain/                   # Ports, workflows, and pure application logic
│   ├── infrastructure/           # Config and cross-cutting helpers
│   └── taskpane/                 # React taskpane, stores, bootstrap, views
├── assets/                       # App icons and brand assets
├── docs/                         # Architecture, testing, debugging, API docs
├── manifest.xml                  # Office add-in manifest
├── webpack.config.js             # Build configuration
└── package.json                  # Scripts and dependencies

Scripts

Command	Description
bun run start	Start the dev server and sideload the add-in in Word
bun run stop	Stop the dev server and unload the add-in
bun run dev-server	Start only the webpack dev server
bun run watch	Rebuild continuously during development
bun run build:hub	Production build that keeps https://localhost:3000, the origin Stylistic Hub serves from
bun run build:module	Production build released as the signed Stylistic Hub module (/m/stylistic-word-addin/)
bun run test	Run the Vitest suite
bun run test:coverage	Run tests with coverage reporting
bun run typecheck	Run TypeScript without emitting files
bun run lint	Run Office add-in lint checks
bun run validate	Run lint, architecture rails, naming checks, complexity checks, React rails, and typecheck
bun run manifest:validate	Validate the Office manifest

Requirements

Requirement	Minimum
WordApi	1.6
Office.js	1.1
Node.js	18+
Word Desktop	2019+ / Microsoft 365
Word Online	Supported
Stylistic Hub	API v1

The add-in relies on WordApi 1.6 for tracked-change range comparison and changeTrackingMode support.

Tech stack

Technology	Role
TypeScript	Application language
React	Taskpane rendering
Fluent UI v9	Microsoft-aligned taskpane component system
Zustand	React-owned UI state
Office.js	Word integration boundary
Vitest	Test runner
Webpack	Build and dev server tooling

Documentation

Document	Description
Architecture	System design, boundaries, and decisions
Review Domain & Track Changes	Frontend domain language and review lifecycle
Linting & File Anatomy	Enforced structure for files and components
Testing	Testing strategy and confidence model
Debugging	Evidence-first debugging workflow
API Contract	Stylistic Hub API v1 as the add-in uses it
Troubleshooting	Operational issues and host-specific gotchas
Adding Rules	Extending editorial analysis rules
Telemetry	Telemetry notes and related conventions

Known limitations

• Author attribution: tracked changes appear under the current user, not under the add-in identity.
• Co-authoring: active multi-author editing is not a safe target scenario.
• Protected documents: DRM/RMS-protected files cannot be modified by add-ins.
• Hub dependency: analysis, feedback, and preferences require the task pane to be served by a running Stylistic Hub.

Contributing

1. Fork the repository.
2. Create a branch for your change.
3. Read the relevant docs before changing architecture, backend integration, or Word behavior.
4. Run bun run validate and bun run test before opening a PR.
5. Open a pull request with a clear problem statement and verification notes.

Releasing

package.json version is the only version source; every build writes it into the manifest <Version> as <version>.0.

1. Bump version in package.json (major.minor.patch) and merge it into main.
2. Tag that commit v<version> and push the tag.
3. .github/workflows/release.yml checks the tag matches package.json, runs validate and the tests, builds with build:module, signs the build with the STYLISTIC_COMPONENT_KEY secret (scripts/release/packComponent.mjs), and publishes a GitHub release with stylistic-word-addin-<version>.zip, component.json and component.json.sig. A tag on a commit that is not on main fails.

The STYLISTIC_COMPONENT_KEY repository secret holds the signing key's PKCS#8 PEM; Stylistic Hub's keys.json must list its public key with role component and scope stylistic-addon.

The format is Stylistic Hub's signed component (docs/signed-releases.md and docs/addin-contract.md in stylistic-hub). Stylistic Hub picks a release up once its catalog lists it.

README image assets

The README now assumes these images will live under docs/images/readme/:

• hero-taskpane.png
• main-view.png
• settings-view.png
• track-changes-review.png

If you want a more marketing-style README later, I would also add:

• workflow-diagram.png
• before-after-word.png
• results-cards.png

License

Apache-2.0. See LICENSE.