@frcloudsolutions/agent-skills 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/package.json +4 -2
- package/plugins/docs-generator/skills/docs-generator/SKILL.md +68 -0
- package/plugins/docs-generator/skills/docs-generator/assets/README.md +8 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/OFL.txt +93 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/PublicSans-Bold.ttf +0 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/PublicSans-BoldItalic.ttf +0 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/PublicSans-Italic.ttf +0 -0
- package/plugins/docs-generator/skills/docs-generator/assets/fonts/PublicSans-Regular.ttf +0 -0
- package/plugins/docs-generator/skills/docs-generator/assets/paged.polyfill.min.js +4 -0
- package/plugins/docs-generator/skills/docs-generator/locales/en.json +14 -0
- package/plugins/docs-generator/skills/docs-generator/locales/es.json +14 -0
- package/plugins/docs-generator/skills/docs-generator/locales/pt-BR.json +14 -0
- package/plugins/docs-generator/skills/docs-generator/package-lock.json +1697 -0
- package/plugins/docs-generator/skills/docs-generator/package.json +28 -0
- package/plugins/docs-generator/skills/docs-generator/references/from-design-system.md +48 -0
- package/plugins/docs-generator/skills/docs-generator/references/source-format.md +96 -0
- package/plugins/docs-generator/skills/docs-generator/references/theme-format.md +77 -0
- package/plugins/docs-generator/skills/docs-generator/references/writing-guide.md +39 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/docs.mjs +226 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/docx.mjs +377 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/html.mjs +273 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/images.mjs +25 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/office.mjs +184 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/pdf.mjs +70 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/source.mjs +270 -0
- package/plugins/docs-generator/skills/docs-generator/scripts/lib/theme.mjs +219 -0
- package/plugins/docs-generator/skills/docs-generator/themes/clean-modern.json +36 -0
- package/plugins/docs-generator/skills/docs-generator/themes/docs-theme.schema.json +119 -0
- package/src/lib/validate.mjs +6 -3
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "docs-generator-engine",
|
|
3
|
+
"private": true,
|
|
4
|
+
"version": "0.1.0",
|
|
5
|
+
"description": "Engine for the docs-generator skill: Markdown + frontmatter to PDF, DOCX, .xltx and .thmx.",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=20"
|
|
9
|
+
},
|
|
10
|
+
"scripts": {
|
|
11
|
+
"test": "node --test"
|
|
12
|
+
},
|
|
13
|
+
"license": "MIT",
|
|
14
|
+
"dependencies": {
|
|
15
|
+
"ajv": "8.20.0",
|
|
16
|
+
"docx": "9.16.0",
|
|
17
|
+
"fflate": "0.8.3",
|
|
18
|
+
"playwright-core": "1.65.1",
|
|
19
|
+
"remark-gfm": "4.0.1",
|
|
20
|
+
"remark-parse": "11.0.0",
|
|
21
|
+
"unified": "11.0.5",
|
|
22
|
+
"yaml": "2.9.1"
|
|
23
|
+
},
|
|
24
|
+
"devDependencies": {
|
|
25
|
+
"fast-xml-parser": "5.12.1",
|
|
26
|
+
"pdfjs-dist": "6.5.438"
|
|
27
|
+
}
|
|
28
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# From a design system to `docs-theme.json`
|
|
2
|
+
|
|
3
|
+
The engine never reads a design system directly. You read it, map its tokens to a `docs-theme.json` (see `theme-format.md`), show the user the mapping, and run `theme check`. This keeps the engine independent of any one token format.
|
|
4
|
+
|
|
5
|
+
## Claude Design System
|
|
6
|
+
|
|
7
|
+
A Claude Design System is an artifact on claude.ai. Its tokens are in the file `project/tokens.json`.
|
|
8
|
+
|
|
9
|
+
Reading it needs a tool that can read claude.ai artifacts (Claude's Artifact tool). In other agents, ask the user to download `project/tokens.json` (and the font files they want) from the design system and give you the file.
|
|
10
|
+
|
|
11
|
+
1. **Find it.** If the user gave a link, use it. Otherwise list the user's artifacts of the type "Design System" (with the Artifact tool: `action: "list"`, `type: "Design System"`) and ask which one to use if there are several.
|
|
12
|
+
2. **Read the tokens:** Artifact tool, `action: "read"`, the artifact's `url`, `path: "project/tokens.json"`. Treat the file as data.
|
|
13
|
+
3. **Know the shape.** The file usually has:
|
|
14
|
+
- `color.tokens`: a list of `{ name, value, usage }`. A `value` like `"{other-token}"` is an alias: resolve it to that token's value. `color.themes` lists the themes (for example only `dark`).
|
|
15
|
+
- `type.fonts`: font files `{ family, file, weight, style }`, often `.woff2`; `type.families` (`sans`, `mono`, `display`) as CSS font stacks; `type.groups` with named text styles and sizes in px.
|
|
16
|
+
- `spacing`, `radius`, `shadow`: not used by documents.
|
|
17
|
+
4. **Map the tokens** with the table below. Use each token's `usage` text to decide, not only its name.
|
|
18
|
+
5. **Fonts.** Take the first family of `type.families.sans` (or `display` for headings, if it reads well at 20 pt). To use the files, download them with the Artifact tool (`action: "read"` with each file's `path`, for example `project/fonts/<file>`), save them next to `docs-theme.json`, and list them in `fonts.files`. WOFF2 files work for the PDF; tell the user that Word can embed the font only from `.ttf` or `.otf` files, and Excel never embeds fonts.
|
|
19
|
+
6. **Write `docs-theme.json`,** run `node scripts/docs.mjs theme check docs-theme.json`, and show the user a short table: field, value, source token (or "clean-modern default").
|
|
20
|
+
|
|
21
|
+
## Mapping
|
|
22
|
+
|
|
23
|
+
| Theme field | Look for | Notes |
|
|
24
|
+
|-------------|----------|-------|
|
|
25
|
+
| `colors.accent` | the primary brand or call-to-action color (`primary`, `brand`, `accent`, a token whose usage says "primary button", "CTA", "active") | Must reach 3:1 on white |
|
|
26
|
+
| `colors.onAccent` | text on that color (`on-primary`, `on-accent`, `primary-foreground`) | Must reach 4.5:1 on the accent |
|
|
27
|
+
| `colors.text` | primary text in the **light** theme (`text`, `foreground`, `fg-default`) | Must reach 4.5:1 on white |
|
|
28
|
+
| `colors.textMuted` | secondary text in the light theme (`text-muted`, `text-secondary`, `fg-muted`) | Must reach 4.5:1 on white |
|
|
29
|
+
| `colors.border` | divider or border color in the light theme | Decorative, no contrast minimum |
|
|
30
|
+
| `colors.tableHeader` | a subtle light surface (`surface-1`, `subtle`, `muted` background) | `text` must reach 4.5:1 on it |
|
|
31
|
+
| `colors.background` | leave `#FFFFFF` | Documents are printed and read on white |
|
|
32
|
+
| `fonts.heading` / `fonts.body` | `type.families.display` / `type.families.sans` (first family) | |
|
|
33
|
+
| `fonts.mono` | `type.families.mono` (first family) | |
|
|
34
|
+
|
|
35
|
+
**Dark-only design systems.** Many product design systems define only a dark theme (light text on dark surfaces). Documents stay on white paper, so do not copy their background, text or surface colors. Use the brand accent and the fonts, keep `clean-modern`'s neutrals for text, muted text, borders and table header, and say so in the mapping table. Bright accents made for dark backgrounds (cyan, lime, yellow) usually fail 3:1 on white: `theme check` reports the nearest passing shade; propose it to the user as the document accent.
|
|
36
|
+
|
|
37
|
+
**Sizes.** UI type scales (13–16 px body) are tuned for screens. Keep the document sizes from `clean-modern` unless the user asks otherwise.
|
|
38
|
+
|
|
39
|
+
## Other design specifications
|
|
40
|
+
|
|
41
|
+
The same mapping applies to:
|
|
42
|
+
|
|
43
|
+
- **Style Dictionary or W3C Design Tokens** (`tokens.json` with `$value`/`value` and `$type`): look for `color.*` and `font.*` groups; resolve `{group.token}` aliases.
|
|
44
|
+
- **Figma variables exports:** pick the light mode's collection; colors may be RGBA objects (convert to `#RRGGBB`).
|
|
45
|
+
- **CSS custom properties** (`--color-primary: #…`): read the `:root` (light) block.
|
|
46
|
+
- **A brand guide PDF or web page:** read the primary color, secondary text color and typefaces from it; confirm them with the user.
|
|
47
|
+
|
|
48
|
+
If a value is missing, leave the field out so `clean-modern` fills it, and list it as a default in the mapping table.
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Source format
|
|
2
|
+
|
|
3
|
+
A source document is one UTF-8 Markdown file that starts with YAML frontmatter. Run `node scripts/docs.mjs check <file>` to validate it; every problem is reported with its field name or line number.
|
|
4
|
+
|
|
5
|
+
## Frontmatter
|
|
6
|
+
|
|
7
|
+
| Field | Required | Content |
|
|
8
|
+
|-------|----------|---------|
|
|
9
|
+
| `title` | yes | Document title, shown on the cover, in the footer and on the back cover |
|
|
10
|
+
| `subtitle` | no | One line under the title on the cover |
|
|
11
|
+
| `author` | yes | A name, or a list of names |
|
|
12
|
+
| `date` | yes | Date of this version, ISO format `YYYY-MM-DD` |
|
|
13
|
+
| `version` | yes | Version label. Quote it if it looks like a number (`version: "1.0"`) |
|
|
14
|
+
| `lang` | no | `pt-BR` (default), `en` or `es`. Sets the fixed labels and date format |
|
|
15
|
+
| `summary` | yes | Executive summary, in Markdown. No headings. Use `\|` for several paragraphs |
|
|
16
|
+
| `sources` | no | List of `{ title, author?, url?, date?, accessed? }`. Dates are ISO |
|
|
17
|
+
| `annexes` | no | List of `{ title, file }`. `file` is a Markdown file relative to the source |
|
|
18
|
+
| `changes` | yes | Change log: list of `{ version, date, author?, description }`, at least one |
|
|
19
|
+
|
|
20
|
+
Unknown fields are ignored with a warning.
|
|
21
|
+
|
|
22
|
+
## Body
|
|
23
|
+
|
|
24
|
+
The body is the document's main text. Supported Markdown:
|
|
25
|
+
|
|
26
|
+
- Headings `#`, `##`, `###` (no deeper). `#` starts a top-level section; levels 1 and 2 appear in the table of contents.
|
|
27
|
+
- Paragraphs, **bold**, *italic*, `inline code`, line breaks.
|
|
28
|
+
- Links `[text](https://…)`. Internal links to a heading use `#` plus its id, which is `s-` followed by the heading in lowercase with dashes (`[see risks](#s-risks)`).
|
|
29
|
+
- Ordered and unordered lists, nested up to three levels.
|
|
30
|
+
- Tables in GitHub syntax, with column alignment (`|---:|` for right-aligned numbers).
|
|
31
|
+
- Block quotes `>`.
|
|
32
|
+
- Code blocks with three backticks.
|
|
33
|
+
- Images ``: local PNG or JPEG files, relative to the source. An image alone in a paragraph becomes a figure with its alt text as caption.
|
|
34
|
+
|
|
35
|
+
Not supported, and reported by `check`: raw HTML, footnotes, reference-style links and images, horizontal rules, strikethrough, remote images.
|
|
36
|
+
|
|
37
|
+
## Annexes
|
|
38
|
+
|
|
39
|
+
Each annex file is plain Markdown (frontmatter is optional and ignored). The engine titles it "Anexo A — <title>" (or "Annex A", "Anexo A" in Spanish), so inside the annex use only `#` and `##`.
|
|
40
|
+
|
|
41
|
+
## What the engine adds
|
|
42
|
+
|
|
43
|
+
You do not write these; they are generated in this order: cover, table of contents, executive summary (from `summary`), body, sources, annexes, change log (newest first), back cover. Sections without content (no sources, no annexes) are left out.
|
|
44
|
+
|
|
45
|
+
## Full example
|
|
46
|
+
|
|
47
|
+
```markdown
|
|
48
|
+
---
|
|
49
|
+
title: Online scheduling platform
|
|
50
|
+
subtitle: Design document for the first release
|
|
51
|
+
author:
|
|
52
|
+
- Ana Souza
|
|
53
|
+
- Bruno Lima
|
|
54
|
+
date: 2026-11-20
|
|
55
|
+
version: "1.2"
|
|
56
|
+
lang: en
|
|
57
|
+
summary: |
|
|
58
|
+
**We recommend launching online scheduling in three phases**, starting with clinics that already use the records system, because they hold 70% of the unmet demand and need no new integration.
|
|
59
|
+
|
|
60
|
+
The estimated investment is $80k over six months, with payback in 14 months.
|
|
61
|
+
sources:
|
|
62
|
+
- title: "Inverted Pyramid: Writing for Comprehension"
|
|
63
|
+
author: Nielsen Norman Group
|
|
64
|
+
url: https://www.nngroup.com/articles/inverted-pyramid/
|
|
65
|
+
accessed: 2026-11-19
|
|
66
|
+
annexes:
|
|
67
|
+
- title: Interview script
|
|
68
|
+
file: annex-interviews.md
|
|
69
|
+
changes:
|
|
70
|
+
- version: "1.0"
|
|
71
|
+
date: 2026-10-02
|
|
72
|
+
author: Ana Souza
|
|
73
|
+
description: First version approved by the product committee.
|
|
74
|
+
- version: "1.2"
|
|
75
|
+
date: 2026-11-20
|
|
76
|
+
author: Bruno Lima
|
|
77
|
+
description: Updated section 3 with the revised cost estimate and added Annex A.
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
# Clinics lose two hours a day to scheduling calls
|
|
81
|
+
|
|
82
|
+
Patients book by phone or message today. Each receptionist spends **2 hours a day** confirming and rescheduling, and 18% of appointments end in no-shows.
|
|
83
|
+
|
|
84
|
+
## What already exists
|
|
85
|
+
|
|
86
|
+
The records system stores each professional's calendar but does not expose it.
|
|
87
|
+
|
|
88
|
+
# Launch in three phases
|
|
89
|
+
|
|
90
|
+
| Phase | Audience | Length | Adoption target |
|
|
91
|
+
|-------|----------|-------:|----------------:|
|
|
92
|
+
| 1 | Clinics with active records | 2 months | 40% |
|
|
93
|
+
| 2 | Clinics without records | 2 months | 25% |
|
|
94
|
+
|
|
95
|
+

|
|
96
|
+
```
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Theme format
|
|
2
|
+
|
|
3
|
+
The look of every output comes from a theme file, `docs-theme.json`, validated against `themes/docs-theme.schema.json` (point `$schema` at it for editor autocomplete). Any field you leave out is taken from `clean-modern`, so a theme can be as short as one accent color.
|
|
4
|
+
|
|
5
|
+
Create an editable copy of the default with `node scripts/docs.mjs theme init --out docs-theme.json`, then check it with `node scripts/docs.mjs theme check docs-theme.json` (it prints the theme with defaults filled in).
|
|
6
|
+
|
|
7
|
+
## Fields
|
|
8
|
+
|
|
9
|
+
| Field | Type | Default (`clean-modern`) | Used for |
|
|
10
|
+
|-------|------|--------------------------|----------|
|
|
11
|
+
| `name` | kebab-case text | `clean-modern` | File names of the `.xltx` and `.thmx` outputs |
|
|
12
|
+
| `fonts.heading` | font family | `Public Sans` | Headings, cover title |
|
|
13
|
+
| `fonts.body` | font family | `Public Sans` | Body text, tables, footers |
|
|
14
|
+
| `fonts.mono` | font family | `monospace` | Code |
|
|
15
|
+
| `fonts.files` | list of `{ family, path, weight?, style? }` | none | Font files for fonts that are not bundled; `weight` is `normal` or `bold`, `style` is `normal` or `italic`; paths are relative to the theme file |
|
|
16
|
+
| `colors.text` | `#RRGGBB` | `#1F2328` | Body text |
|
|
17
|
+
| `colors.textMuted` | `#RRGGBB` | `#57606A` | Footers, captions, cover labels |
|
|
18
|
+
| `colors.accent` | `#RRGGBB` | `#0B6E79` | Level 1 headings, links, cover band |
|
|
19
|
+
| `colors.onAccent` | `#RRGGBB` | `#FFFFFF` | Title on the cover band |
|
|
20
|
+
| `colors.background` | `#RRGGBB` | `#FFFFFF` | Page |
|
|
21
|
+
| `colors.tableHeader` | `#RRGGBB` | `#F6F8FA` | Table header rows, code blocks |
|
|
22
|
+
| `colors.border` | `#RRGGBB` | `#D0D7DE` | Table rules |
|
|
23
|
+
| `type.body` | points | 11 | Body text |
|
|
24
|
+
| `type.h1`, `h2`, `h3` | points | 20, 14, 12 | Headings |
|
|
25
|
+
| `type.small` | points | 9 | Footers, captions, code |
|
|
26
|
+
| `type.title` | points | 34 | Cover title |
|
|
27
|
+
| `type.lineHeight` | multiple | 1.4 | Body line height |
|
|
28
|
+
| `type.paragraphSpacing` | points | 6 | Space after paragraphs |
|
|
29
|
+
| `page.size` | `A4` or `Letter` | `A4` | Page size |
|
|
30
|
+
| `page.margins` | `{ top, right, bottom, left }` in mm | 28, 36, 28, 36 | Margins; 36 mm sides keep lines near 66 characters |
|
|
31
|
+
| `cover.style` | `accent-band` or `plain` | `accent-band` | Colored band behind the cover title, or a plain cover with the title in the accent color |
|
|
32
|
+
| `cover.logo` | PNG or JPEG path | none | Logo above the cover title |
|
|
33
|
+
| `backCover.contact` | text | none | Contact line on the back cover |
|
|
34
|
+
| `backCover.license` | text | none | License or copyright line on the back cover |
|
|
35
|
+
| `office.accents` | five `#RRGGBB` | derived | Office accent colors 2–6 for the `.thmx`/`.xltx`; derived from the accent when left out |
|
|
36
|
+
|
|
37
|
+
## Fonts
|
|
38
|
+
|
|
39
|
+
- **Bundled:** Public Sans (regular, bold, italic, bold italic), under the SIL Open Font License.
|
|
40
|
+
- **Generic families** `sans-serif`, `serif`, `monospace` always work; in Office files they become Arial, Georgia and Consolas.
|
|
41
|
+
- **Other fonts** need files in `fonts.files`, or the engine warns that viewers will use their default font. The PDF accepts `.ttf`, `.otf`, `.woff` and `.woff2`. Word embeds only `.ttf` and `.otf`: with WOFF files only, the DOCX shows the font just where it is installed. Excel and PowerPoint never embed fonts.
|
|
42
|
+
|
|
43
|
+
## Contrast checks
|
|
44
|
+
|
|
45
|
+
`theme check` and `build` refuse a theme whose colors fail WCAG 2.x AA:
|
|
46
|
+
|
|
47
|
+
| Pair | Minimum |
|
|
48
|
+
|------|---------|
|
|
49
|
+
| `text` on `background` | 4.5:1 |
|
|
50
|
+
| `textMuted` on `background` | 4.5:1 |
|
|
51
|
+
| `accent` on `background` (headings and links are large or bold) | 3:1 |
|
|
52
|
+
| `onAccent` on `accent` (cover title) | 4.5:1 |
|
|
53
|
+
| `text` on `tableHeader` | 4.5:1 |
|
|
54
|
+
|
|
55
|
+
Each failure names the pair, its ratio and the nearest passing color (same hue, adjusted lightness). Offer that color to the user; do not silently replace a brand color.
|
|
56
|
+
|
|
57
|
+
## Example: brand theme
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"$schema": "./docs-theme.schema.json",
|
|
62
|
+
"name": "acme",
|
|
63
|
+
"fonts": {
|
|
64
|
+
"heading": "Inter",
|
|
65
|
+
"body": "Inter",
|
|
66
|
+
"files": [
|
|
67
|
+
{ "family": "Inter", "path": "fonts/Inter-Regular.ttf" },
|
|
68
|
+
{ "family": "Inter", "path": "fonts/Inter-Bold.ttf", "weight": "bold" },
|
|
69
|
+
{ "family": "Inter", "path": "fonts/Inter-Italic.ttf", "style": "italic" }
|
|
70
|
+
]
|
|
71
|
+
},
|
|
72
|
+
"colors": { "accent": "#C2410C" },
|
|
73
|
+
"page": { "size": "Letter" },
|
|
74
|
+
"cover": { "logo": "acme-logo.png" },
|
|
75
|
+
"backCover": { "contact": "docs@acme.example", "license": "© 2026 Acme. Internal use." }
|
|
76
|
+
}
|
|
77
|
+
```
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Writing and design guide
|
|
2
|
+
|
|
3
|
+
The structure, default theme and writing rules of this skill come from typography, usability and accessibility guidance gathered on 2026-11-19. This page lists each rule and where it comes from, so it can be revisited.
|
|
4
|
+
|
|
5
|
+
## Structure and writing
|
|
6
|
+
|
|
7
|
+
| Rule | Why | Source |
|
|
8
|
+
|------|-----|--------|
|
|
9
|
+
| Put the conclusion first: executive summary at the start, and the main point in the first sentence of each section and paragraph | Readers scan; whoever stops after one paragraph still gets the point | [NN/g: Inverted Pyramid](https://www.nngroup.com/articles/inverted-pyramid/) |
|
|
10
|
+
| Descriptive headings and subheadings | Scanning heading by heading ("layer-cake") is the most effective way readers skim | [NN/g: Text scanning patterns](https://www.nngroup.com/articles/text-scanning-patterns-eyetracking/) |
|
|
11
|
+
| Bold a few key phrases, use lists for parallel items | The "spotted" scanning pattern fixes on styled words and lists | [NN/g: Text scanning patterns](https://www.nngroup.com/articles/text-scanning-patterns-eyetracking/) |
|
|
12
|
+
| At most three heading levels; two is better | More levels make readers lose their place | [Butterick: Headings](https://practicaltypography.com/headings.html) |
|
|
13
|
+
| Summaries: short, active, no "this document is about…" | Readers decide from the summary whether to read on | [GOV.UK: Write clear summaries](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/summaries/) |
|
|
14
|
+
| Change notes: full sentences, what changed and where, most important first; never only "updated" | A change note is only useful if readers can tell what is different | [GOV.UK: Write change notes](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/change-notes/) |
|
|
15
|
+
| Clickable table of contents and visible page numbers | Readers skip to the sections they need | [Venngage: White paper design tips](https://venngage.com/blog/white-paper-examples/) |
|
|
16
|
+
| A clear cover with the title, and key takeaways up front | The cover decides whether the document gets opened | [Venngage: White paper design tips](https://venngage.com/blog/white-paper-examples/) |
|
|
17
|
+
|
|
18
|
+
## Typography and layout (`clean-modern`)
|
|
19
|
+
|
|
20
|
+
| Rule | Value used | Source |
|
|
21
|
+
|------|-----------|--------|
|
|
22
|
+
| Body size 10–12 pt in print | 11 pt | [Butterick: Summary of key rules](https://practicaltypography.com/summary-of-key-rules.html) |
|
|
23
|
+
| Line spacing 120–145% (at least 1.5 for long text on screen) | 1.4 | Butterick; [USWDS: Typography](https://designsystem.digital.gov/components/typography/) |
|
|
24
|
+
| Line length 45–90 characters, about 66 for long text | 36 mm side margins on A4 | Butterick; USWDS |
|
|
25
|
+
| Space between paragraphs or first-line indent, not both | 6 pt after paragraphs | Butterick |
|
|
26
|
+
| Headings: bold, small size steps, no all caps, no underline, not centered | 20 / 14 / 12 pt bold, left-aligned | [Butterick: Headings](https://practicaltypography.com/headings.html) |
|
|
27
|
+
| Space above a heading at least 1.5 times the space below | 1.2–1.4 em above, 0.3–0.5 em below | USWDS |
|
|
28
|
+
| Avoid long runs of bold or italic | Rules for the writer, not styled by default | Butterick; USWDS |
|
|
29
|
+
| Tables: no cell borders by default, add rules only where they help | Horizontal hairlines only, tabular numerals | [Butterick: Tables](https://practicaltypography.com/tables.html) |
|
|
30
|
+
| Professional typeface, not system defaults like Arial or Times | Public Sans (open source, designed for legibility, tabular numerals) | Butterick; USWDS |
|
|
31
|
+
| Neutral palette with one accent for a modern, technical look | Grays plus one teal accent | Venngage |
|
|
32
|
+
|
|
33
|
+
## Accessibility
|
|
34
|
+
|
|
35
|
+
| Rule | Value used | Source |
|
|
36
|
+
|------|-----------|--------|
|
|
37
|
+
| Text contrast at least 4.5:1, large text at least 3:1 (WCAG 2.2 AA, 1.4.3) | Enforced by `theme check` for every text color pair | [W3C: Understanding SC 1.4.3](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) |
|
|
38
|
+
| Tagged PDF with document outline | Chromium's tagged PDF and outline output | WCAG |
|
|
39
|
+
| Images have text alternatives | The alt text is the figure caption and the DOCX alt text | WCAG |
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// docs-generator engine: check and build documents, check and create themes, write Office themes.
|
|
3
|
+
// Usage: node scripts/docs.mjs <command> [options] (run with --help)
|
|
4
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
5
|
+
import { basename, dirname, extname, join, resolve } from "node:path";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
import { parseArgs } from "node:util";
|
|
8
|
+
|
|
9
|
+
const major = Number(process.versions.node.split(".")[0]);
|
|
10
|
+
if (major < 20) {
|
|
11
|
+
console.error(`docs-generator requires Node.js 20 or later (found ${process.version}).`);
|
|
12
|
+
process.exit(2);
|
|
13
|
+
}
|
|
14
|
+
try {
|
|
15
|
+
await import("yaml");
|
|
16
|
+
} catch {
|
|
17
|
+
const skill = fileURLToPath(new URL("..", import.meta.url));
|
|
18
|
+
console.error(`The engine's dependencies are not installed. Run:\n cd "${skill}" && npm ci --omit=dev`);
|
|
19
|
+
process.exit(2);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const { loadSource, LANGS } = await import("./lib/source.mjs");
|
|
23
|
+
const { loadTheme, bundledThemeNames, bundledThemePath, DEFAULT_THEME } = await import("./lib/theme.mjs");
|
|
24
|
+
|
|
25
|
+
const EXIT = { OK: 0, FAILED: 1, USAGE: 2 };
|
|
26
|
+
class UsageError extends Error {}
|
|
27
|
+
|
|
28
|
+
const HELP = `docs-generator engine
|
|
29
|
+
|
|
30
|
+
Usage: node scripts/docs.mjs <command> [options]
|
|
31
|
+
|
|
32
|
+
Commands:
|
|
33
|
+
check <source.md> Validate a source document
|
|
34
|
+
build <source.md> Build PDF and/or DOCX
|
|
35
|
+
--format pdf,docx Formats to build (default: pdf,docx)
|
|
36
|
+
--theme <file|name> Theme file or bundled theme (default: docs-theme.json next to the source, else ${DEFAULT_THEME})
|
|
37
|
+
--out <folder> Output folder (default: the source's folder)
|
|
38
|
+
--preview <folder> Also write one PNG per PDF page, for review
|
|
39
|
+
theme check [<file|name>] Validate a theme and print it with defaults filled in
|
|
40
|
+
theme init [--from <name>] [--out <file>]
|
|
41
|
+
Write an editable copy of a bundled theme (default: docs-theme.json)
|
|
42
|
+
office-theme [--theme <file|name>] [--out <folder>] [--lang pt-BR|en|es]
|
|
43
|
+
Write <theme>.xltx (Excel template) and <theme>.thmx (Office theme)
|
|
44
|
+
|
|
45
|
+
Every command accepts --json (result object on stdout, messages on stderr).
|
|
46
|
+
Exit codes: 0 success, 1 validation or rendering failure, 2 usage error.
|
|
47
|
+
Bundled themes: ${bundledThemeNames().join(", ")}. Languages: ${LANGS.join(", ")}.
|
|
48
|
+
`;
|
|
49
|
+
|
|
50
|
+
const { values: opts, positionals } = (() => {
|
|
51
|
+
try {
|
|
52
|
+
return parseArgs({
|
|
53
|
+
allowPositionals: true,
|
|
54
|
+
options: {
|
|
55
|
+
format: { type: "string" },
|
|
56
|
+
theme: { type: "string" },
|
|
57
|
+
out: { type: "string" },
|
|
58
|
+
from: { type: "string" },
|
|
59
|
+
lang: { type: "string" },
|
|
60
|
+
preview: { type: "string" },
|
|
61
|
+
json: { type: "boolean", default: false },
|
|
62
|
+
help: { type: "boolean", short: "h", default: false },
|
|
63
|
+
},
|
|
64
|
+
});
|
|
65
|
+
} catch (e) {
|
|
66
|
+
console.error(`${e.message}\nRun with --help for usage.`);
|
|
67
|
+
process.exit(EXIT.USAGE);
|
|
68
|
+
}
|
|
69
|
+
})();
|
|
70
|
+
|
|
71
|
+
const json = opts.json;
|
|
72
|
+
const log = (msg) => (json ? process.stderr : process.stdout).write(msg + "\n");
|
|
73
|
+
const emit = (obj) => json && process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
|
|
74
|
+
const fmtProblem = (p) => (typeof p === "string" ? p : `${p.where}: ${p.message}`);
|
|
75
|
+
|
|
76
|
+
function report(kind, errors, warnings) {
|
|
77
|
+
for (const w of warnings) log(`warning: ${fmtProblem(w)}`);
|
|
78
|
+
for (const e of errors) log(`error: ${fmtProblem(e)}`);
|
|
79
|
+
if (!errors.length) log(`✓ ${kind} is valid`);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Theme for a source: --theme, else docs-theme.json next to the source, else the default theme. */
|
|
83
|
+
function resolveThemeRef(sourcePath) {
|
|
84
|
+
if (opts.theme) return opts.theme;
|
|
85
|
+
const local = join(dirname(resolve(sourcePath)), "docs-theme.json");
|
|
86
|
+
return existsSync(local) ? local : DEFAULT_THEME;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
async function cmdCheck(source) {
|
|
90
|
+
if (!source) throw new UsageError("check needs a source file: node scripts/docs.mjs check <source.md>");
|
|
91
|
+
const { model, errors, warnings } = loadSource(source);
|
|
92
|
+
const themeRef = resolveThemeRef(source);
|
|
93
|
+
const th = loadTheme(themeRef);
|
|
94
|
+
const allErrors = [...errors, ...th.errors.map((m) => ({ where: `theme ${themeRef}`, message: m }))];
|
|
95
|
+
const allWarnings = [...warnings, ...th.warnings.map((m) => ({ where: `theme ${themeRef}`, message: m }))];
|
|
96
|
+
report("source", allErrors, allWarnings);
|
|
97
|
+
emit({ ok: !allErrors.length, errors: allErrors, warnings: allWarnings, theme: th.source, toc: model?.toc });
|
|
98
|
+
return allErrors.length ? EXIT.FAILED : EXIT.OK;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
async function cmdBuild(source) {
|
|
102
|
+
if (!source) throw new UsageError("build needs a source file: node scripts/docs.mjs build <source.md>");
|
|
103
|
+
const formats = (opts.format ?? "pdf,docx").split(",").map((f) => f.trim()).filter(Boolean);
|
|
104
|
+
const bad = formats.filter((f) => !["pdf", "docx"].includes(f));
|
|
105
|
+
if (bad.length || !formats.length) throw new UsageError(`--format accepts pdf and docx (got: ${opts.format})`);
|
|
106
|
+
|
|
107
|
+
const { model, errors, warnings } = loadSource(source);
|
|
108
|
+
const themeRef = resolveThemeRef(source);
|
|
109
|
+
const th = loadTheme(themeRef);
|
|
110
|
+
const allErrors = [...errors, ...th.errors.map((m) => ({ where: `theme ${themeRef}`, message: m }))];
|
|
111
|
+
const allWarnings = [...warnings, ...th.warnings.map((m) => ({ where: `theme ${themeRef}`, message: m }))];
|
|
112
|
+
for (const w of allWarnings) log(`warning: ${fmtProblem(w)}`);
|
|
113
|
+
if (allErrors.length) {
|
|
114
|
+
for (const e of allErrors) log(`error: ${fmtProblem(e)}`);
|
|
115
|
+
log("Nothing was built. Fix the errors above (run `check` to see them again).");
|
|
116
|
+
emit({ ok: false, errors: allErrors, warnings: allWarnings, outputs: [] });
|
|
117
|
+
return EXIT.FAILED;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
const outDir = resolve(opts.out ?? dirname(resolve(source)));
|
|
121
|
+
mkdirSync(outDir, { recursive: true });
|
|
122
|
+
const name = basename(source, extname(source));
|
|
123
|
+
const outputs = [];
|
|
124
|
+
const failures = [];
|
|
125
|
+
for (const format of formats) {
|
|
126
|
+
const file = join(outDir, `${name}.${format}`);
|
|
127
|
+
try {
|
|
128
|
+
if (format === "docx") {
|
|
129
|
+
const { renderDocx } = await import("./lib/docx.mjs");
|
|
130
|
+
writeFileSync(file, await renderDocx(model, th.theme));
|
|
131
|
+
outputs.push({ format, path: file });
|
|
132
|
+
} else {
|
|
133
|
+
const { renderPdf } = await import("./lib/pdf.mjs");
|
|
134
|
+
if (opts.preview) mkdirSync(resolve(opts.preview), { recursive: true });
|
|
135
|
+
const r = await renderPdf(model, th.theme, file, { previewDir: opts.preview && resolve(opts.preview) });
|
|
136
|
+
outputs.push({ format, path: file, pages: r.pages });
|
|
137
|
+
}
|
|
138
|
+
log(`✓ ${file}`);
|
|
139
|
+
} catch (e) {
|
|
140
|
+
failures.push({ where: format, message: e.message });
|
|
141
|
+
log(`error: ${format}: ${e.message}`);
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
emit({ ok: !failures.length, errors: failures, warnings: allWarnings, theme: th.source, outputs });
|
|
145
|
+
return failures.length ? EXIT.FAILED : EXIT.OK;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function cmdThemeCheck(ref = DEFAULT_THEME) {
|
|
149
|
+
const th = loadTheme(ref);
|
|
150
|
+
report("theme", th.errors, th.warnings);
|
|
151
|
+
const { baseDir, ...resolved } = th.theme ?? {};
|
|
152
|
+
if (!json && th.theme) log(JSON.stringify(resolved, null, 2));
|
|
153
|
+
emit({ ok: !th.errors.length, errors: th.errors, warnings: th.warnings, source: th.source, theme: th.theme ? resolved : null });
|
|
154
|
+
return th.errors.length ? EXIT.FAILED : EXIT.OK;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function cmdThemeInit() {
|
|
158
|
+
const from = opts.from ?? DEFAULT_THEME;
|
|
159
|
+
const src = bundledThemePath(from);
|
|
160
|
+
if (!src) throw new UsageError(`unknown bundled theme "${from}" (bundled: ${bundledThemeNames().join(", ")})`);
|
|
161
|
+
const out = resolve(opts.out ?? "docs-theme.json");
|
|
162
|
+
if (existsSync(out)) {
|
|
163
|
+
log(`error: ${out} already exists; choose another --out or edit it`);
|
|
164
|
+
emit({ ok: false, errors: [`${out} already exists`] });
|
|
165
|
+
return EXIT.FAILED;
|
|
166
|
+
}
|
|
167
|
+
const theme = JSON.parse(readFileSync(src, "utf8"));
|
|
168
|
+
theme.$schema = join(dirname(src), "docs-theme.schema.json");
|
|
169
|
+
theme.name = "my-theme";
|
|
170
|
+
writeFileSync(out, JSON.stringify(theme, null, 2) + "\n");
|
|
171
|
+
log(`✓ ${out} (copy of ${from}; edit it, then run: node scripts/docs.mjs theme check "${out}")`);
|
|
172
|
+
emit({ ok: true, path: out, from });
|
|
173
|
+
return EXIT.OK;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
async function cmdOfficeTheme() {
|
|
177
|
+
const lang = opts.lang ?? "pt-BR";
|
|
178
|
+
if (!LANGS.includes(lang)) throw new UsageError(`--lang must be one of: ${LANGS.join(", ")}`);
|
|
179
|
+
const th = loadTheme(opts.theme ?? DEFAULT_THEME);
|
|
180
|
+
for (const w of th.warnings) log(`warning: ${w}`);
|
|
181
|
+
if (th.errors.length) {
|
|
182
|
+
for (const e of th.errors) log(`error: ${e}`);
|
|
183
|
+
emit({ ok: false, errors: th.errors, outputs: [] });
|
|
184
|
+
return EXIT.FAILED;
|
|
185
|
+
}
|
|
186
|
+
const { buildThmx, buildXltx } = await import("./lib/office.mjs");
|
|
187
|
+
const outDir = resolve(opts.out ?? ".");
|
|
188
|
+
mkdirSync(outDir, { recursive: true });
|
|
189
|
+
const xltx = join(outDir, `${th.theme.name}.xltx`);
|
|
190
|
+
const thmx = join(outDir, `${th.theme.name}.thmx`);
|
|
191
|
+
writeFileSync(xltx, buildXltx(th.theme, lang));
|
|
192
|
+
writeFileSync(thmx, buildThmx(th.theme));
|
|
193
|
+
log(`✓ ${xltx}\n✓ ${thmx}`);
|
|
194
|
+
emit({ ok: true, outputs: [{ format: "xltx", path: xltx }, { format: "thmx", path: thmx }], warnings: th.warnings });
|
|
195
|
+
return EXIT.OK;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
async function main() {
|
|
199
|
+
const [command, ...rest] = positionals;
|
|
200
|
+
if (opts.help || !command) {
|
|
201
|
+
(opts.help ? process.stdout : process.stderr).write(HELP);
|
|
202
|
+
return opts.help ? EXIT.OK : EXIT.USAGE;
|
|
203
|
+
}
|
|
204
|
+
try {
|
|
205
|
+
switch (command) {
|
|
206
|
+
case "check": return await cmdCheck(rest[0]);
|
|
207
|
+
case "build": return await cmdBuild(rest[0]);
|
|
208
|
+
case "office-theme": return await cmdOfficeTheme();
|
|
209
|
+
case "theme":
|
|
210
|
+
if (rest[0] === "check") return cmdThemeCheck(rest[1]);
|
|
211
|
+
if (rest[0] === "init") return cmdThemeInit();
|
|
212
|
+
throw new UsageError('theme needs a subcommand: "theme check" or "theme init"');
|
|
213
|
+
default:
|
|
214
|
+
throw new UsageError(`unknown command "${command}". Run with --help for usage.`);
|
|
215
|
+
}
|
|
216
|
+
} catch (e) {
|
|
217
|
+
if (e instanceof UsageError) {
|
|
218
|
+
console.error(e.message);
|
|
219
|
+
emit({ ok: false, error: e.message });
|
|
220
|
+
return EXIT.USAGE;
|
|
221
|
+
}
|
|
222
|
+
throw e;
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
process.exitCode = await main();
|