feat(html-to-docx): document CSS styling, prefer inline styles

skills/turbodocx-html-to-docx/SKILL.md

@@ -3,7 +3,7 @@ name: turbodocx-html-to-docx
 description: Set up @turbodocx/html-to-docx to convert HTML to Microsoft Word (.docx) documents in a Node.js project. Use this skill when the user wants to generate DOCX files from HTML, add document generation to their app, convert HTML templates to Word documents, or integrate TurboDocx html-to-docx into their project. Also trigger for mentions of HTML-to-Word, HTML-to-DOCX, document generation, report generation from HTML, or any request involving the @turbodocx/html-to-docx package.
 metadata:
   author: TurboDocx
-  version: "1.2.0"
+  version: "1.3.0"
 license: MIT
 ---
 
@@ -76,6 +76,15 @@ The helper should:
 - Include commonly useful defaults (font, margins) that the user can override
 - Use TypeScript if the project uses TypeScript
 
+**Styling:** when you write example or template HTML, prefer inline `style="..."`
+attributes — they are the most reliable, predictable way to style a generated
+DOCX and the form the library resolves everything to internally. A CSS stylesheet
+is also supported via `documentOptions.css`, but treat it as secondary: reach for
+it only when the user already has a stylesheet, explicitly wants class/selector
+styling, or is generating highly repetitive markup. See the "Styling: inline
+styles vs. CSS stylesheet" section in `references/usage.md` for the trade-offs
+and the `css` option's limits (`!important` and `@media` are not supported).
+
 ### Step 4.4: Generate integration code
 
 Based on what the project needs:

skills/turbodocx-html-to-docx/references/usage.md

@@ -122,6 +122,58 @@ const options = {
 };
 ```
 
+### Styling: inline styles vs. CSS stylesheet
+
+**Prefer inline `style="..."` attributes.** They are the most reliable and
+predictable way to style a generated DOCX, and they work on every version of the
+package. Internally the library resolves all styling down to per-element inline
+styles before building the Word document, so inline styles are the canonical
+form — what you write is exactly what gets applied, with no cascade or
+specificity surprises to reason about.
+
+```typescript
+const html = `
+  <h1 style="text-align: center; color: #1a3c7a;">Quarterly Report</h1>
+  <p style="font-size: 12pt; color: #222;">Body text styled inline.</p>
+`;
+const buffer = await HTMLtoDOCX(html);
+```
+
+**CSS stylesheets are also supported** (recent versions) via the
+`documentOptions.css` option, for when you already have a stylesheet or want to
+keep large amounts of markup clean by styling many elements at once. Selectors
+are matched and folded into each element's inline style, so an element's own
+inline `style` always wins.
+
+```typescript
+const css = `
+  h1, h2 { text-align: center; }
+  .title { color: #1a3c7a; font-size: 28pt; }
+  p      { color: #222; }
+`;
+const buffer = await HTMLtoDOCX(html, null, { css });
+```
+
+When you reach for `css`, keep its limits in mind (these are why inline is the
+safer default):
+
+- An element's inline `style` overrides a matching stylesheet rule.
+- The cascade follows standard specificity (id > class > type), source order
+  breaks ties.
+- Embedded `<style>` tags in the HTML are honored and removed from the output.
+- **Not supported:** `!important`, at-rules such as `@media`/`@supports` (they
+  are ignored, not applied), and external `<link rel="stylesheet">` files — pass
+  the CSS text via the `css` option instead.
+- Only properties the renderer already understands (color, `text-align`,
+  `font-size`, `font-family`, width/height, borders, background,
+  text-decoration, …) take effect; others are ignored.
+
+**Guidance when generating code for a user:** default to inline styles in the
+HTML you produce. Only use `documentOptions.css` if the user already has a
+stylesheet to reuse, explicitly asks for class/selector-based styling, or is
+generating highly repetitive markup where a shared stylesheet meaningfully
+reduces duplication.
+
 ### Heading Styles
 
 All heading styles are nested under the `heading` key. Each level supports `font`, `fontSize`, `bold`, `spacing`, `keepLines`, `keepNext`, and `outlineLevel`.