pageship 0.1.1 → 0.3.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 +18 -108
- package/dist/cli.mjs +1889 -481
- package/dist/skills/LICENSE +21 -0
- package/dist/skills/pageship/SKILL.md +150 -0
- package/dist/skills/pageship/references/download.md +9 -0
- package/dist/skills/pageship/references/list-and-history.md +15 -0
- package/dist/skills/pageship/references/restore.md +9 -0
- package/dist/skills/pageship/references/visibility.md +12 -0
- package/dist/skills/pageship-chart/SKILL.md +110 -0
- package/dist/skills/pageship-code-block/SKILL.md +113 -0
- package/dist/skills/pageship-code-block/references/highlight-lock.json +542 -0
- package/dist/skills/pageship-code-block/references/highlight.mjs +138 -0
- package/dist/skills/pageship-decision-record/SKILL.md +43 -0
- package/dist/skills/pageship-diagram/SKILL.md +92 -0
- package/dist/skills/pageship-diagram/references/check-diagram.js +301 -0
- package/dist/skills/pageship-diagram/references/computed-layout.md +49 -0
- package/dist/skills/pageship-diagram/references/layout.mjs +310 -0
- package/dist/skills/pageship-diagram/references/mermaid.md +89 -0
- package/dist/skills/pageship-diagram/references/svg.md +205 -0
- package/dist/skills/pageship-docs/NOTICES.md +35 -0
- package/dist/skills/pageship-docs/SKILL.md +67 -0
- package/dist/skills/pageship-docs/references/ask.md +18 -0
- package/dist/skills/pageship-docs/references/check.md +39 -0
- package/dist/skills/pageship-docs/references/content.md +29 -0
- package/dist/skills/pageship-docs/references/design.md +60 -0
- package/dist/skills/pageship-docs/references/file.md +52 -0
- package/dist/skills/pageship-docs/references/plain-default.md +331 -0
- package/dist/skills/pageship-explainer/SKILL.md +92 -0
- package/dist/skills/pageship-interaction/SKILL.md +115 -0
- package/dist/skills/pageship-interaction/references/pointer.md +271 -0
- package/dist/skills/pageship-interaction/references/step-through.md +146 -0
- package/dist/skills/pageship-key-figures/SKILL.md +127 -0
- package/dist/skills/pageship-media/SKILL.md +122 -0
- package/dist/skills/pageship-motion/SKILL.md +58 -0
- package/dist/skills/pageship-plan/SKILL.md +55 -0
- package/dist/skills/pageship-report/SKILL.md +29 -0
- package/dist/skills/pageship-review-report/SKILL.md +90 -0
- package/dist/skills/pageship-slide-deck/SKILL.md +53 -0
- package/dist/skills/pageship-slide-deck/references/engine.md +362 -0
- package/dist/skills/pageship-spec/SKILL.md +58 -0
- package/dist/skills/pageship-table/SKILL.md +243 -0
- package/dist/skills/pageship-table/references/sort-and-filter.md +235 -0
- package/package.json +1 -1
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pageship-docs
|
|
3
|
+
description: First step for any document people read, such as a report, plan, spec, explainer, review, decision record or slide deck, in HTML or Markdown. Load it before any other pageship- skill. Use when the user asks for one of these documents, asks to regenerate, redesign, edit, rename, move or copy an HTML source file, or asks to record whether they want HTML or Markdown.
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: "0.3.0"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Pageship documents
|
|
10
|
+
|
|
11
|
+
The result is Markdown or one standalone HTML source file. You never publish yourself; you hand the file to the `pageship` skill, which does.
|
|
12
|
+
|
|
13
|
+
## 1. Settle the format
|
|
14
|
+
|
|
15
|
+
Take the first rule that applies.
|
|
16
|
+
|
|
17
|
+
- **Prompt rule.** The request names HTML or Markdown, or asks to convert a file from one to the other. Follow it.
|
|
18
|
+
- **Existing-file rule.** A request to regenerate, redesign, edit, rename, move or copy an existing file keeps its format.
|
|
19
|
+
- **Fixed-format rule.** A tool or a repository convention fixes the file as Markdown: READMEs, changelogs, glossaries, ADRs, agent instruction files, skill files, issue and pull request text, commit messages.
|
|
20
|
+
- **Project rule.** The project's agent instructions (`AGENTS.md`, `CLAUDE.md` and the files they import) record a format preference. Follow it.
|
|
21
|
+
- **Global rule.** The global agent instructions (such as `~/.claude/CLAUDE.md` or `~/.codex/AGENTS.md`) record one. Follow it.
|
|
22
|
+
- **Ask rule.** Nothing records a format. Read [the ask rule](references/ask.md), ask its question, and stop until the user answers.
|
|
23
|
+
|
|
24
|
+
## 2. Pick the document kind
|
|
25
|
+
|
|
26
|
+
For Markdown, go to step 3.
|
|
27
|
+
|
|
28
|
+
| Kind | The reader wants | Skill |
|
|
29
|
+
| --------------- | --------------------------------------------------------- | -------------------------- |
|
|
30
|
+
| Report | What was found, what it means and what to do about it | `pageship-report` |
|
|
31
|
+
| Plan | Where the work is going, the steps and what is decided | `pageship-plan` |
|
|
32
|
+
| Spec | A contract for what to build and how to test it | `pageship-spec` |
|
|
33
|
+
| Explainer | How something works | `pageship-explainer` |
|
|
34
|
+
| Review report | Findings on a change or plan, by severity, with a verdict | `pageship-review-report` |
|
|
35
|
+
| Decision record | What was decided, the options and the consequences | `pageship-decision-record` |
|
|
36
|
+
| Slide deck | Slides to present from a browser | `pageship-slide-deck` |
|
|
37
|
+
|
|
38
|
+
Load the skill of the kind that fits. When none fits exactly, or its skill is not installed, use the closest installed kind and tell the user which.
|
|
39
|
+
|
|
40
|
+
## 3. Choose the path
|
|
41
|
+
|
|
42
|
+
A new file goes at the path the user names, or else where the project keeps such documents, or else at a short descriptive path in the project, such as `docs/<name>.html`.
|
|
43
|
+
|
|
44
|
+
## 4. Write the file
|
|
45
|
+
|
|
46
|
+
For Markdown, write one file by the [content rules](references/content.md) alone, then hand over.
|
|
47
|
+
|
|
48
|
+
For HTML, the kind skill gives the parts, the order and its own rules, which win over this skeleton:
|
|
49
|
+
|
|
50
|
+
1. **Gather.** Read the request, every file it points to and the project's glossary. Where the kind asks for an **inventory**, list every item of the source in its order and words, until an item covers every sentence of the source. Done when you can point to where each fact you plan to write comes from.
|
|
51
|
+
2. **Sort.** Put every statement of the source into exactly one of the kind's parts.
|
|
52
|
+
3. **Write.** One file by the [content rules](references/content.md), the [file rules](references/file.md) and the [design rules](references/design.md), in the kind's order, under its headings or the closest glossary terms. A part the source leaves empty keeps its heading and one line saying the source gives none. Done when every sorted statement, or every inventory item, is in the file.
|
|
53
|
+
4. **Check.** Run [the check](references/check.md), with the checks the kind and pattern skills add.
|
|
54
|
+
|
|
55
|
+
Then hand over. Your final message lists, however briefly you otherwise reply:
|
|
56
|
+
|
|
57
|
+
- the file's path;
|
|
58
|
+
- the structure you added that the source didn't have, as [the check lists it](references/check.md#the-structure-you-added);
|
|
59
|
+
- the open questions, marking the ones you added;
|
|
60
|
+
- the checks that ran and the ones you skipped;
|
|
61
|
+
- what the kind and pattern skills add to this list.
|
|
62
|
+
|
|
63
|
+
For an HTML file, end the hand-over with the next step for publishing. When the user asked in this conversation to publish this document, or accepted an offer to, load `pageship` and publish it. Otherwise, when the `pageship` skill is installed, offer to publish the file through it; for a file with a document marker, offer to publish the change as a new revision of its document.
|
|
64
|
+
|
|
65
|
+
## Starting at a kind or pattern skill
|
|
66
|
+
|
|
67
|
+
When the user named a kind skill, or named a pattern skill and asked for just that pattern, write HTML unless the request names another format, and start at step 3. A lone pattern is the file's main content, under an `h1`, with no parts to sort. In every other case, start at step 1.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# The ask rule
|
|
2
|
+
|
|
3
|
+
Ask once, with your multiple-choice tool when you have one (`AskUserQuestion` in Claude Code, `request_user_input` in Codex), or else as a numbered question. Offer exactly these choices:
|
|
4
|
+
|
|
5
|
+
1. HTML always
|
|
6
|
+
2. HTML in this project
|
|
7
|
+
3. HTML just this time
|
|
8
|
+
4. Markdown
|
|
9
|
+
|
|
10
|
+
## Save the preference, only with consent
|
|
11
|
+
|
|
12
|
+
Ask with the same tool:
|
|
13
|
+
|
|
14
|
+
- after "HTML always", whether to save it to the global agent instructions; after "HTML in this project", to the project's. Name the file in the question;
|
|
15
|
+
- after "Markdown", whether to save it, with the choices "This project", "All projects" and "Don't save";
|
|
16
|
+
- after "HTML just this time", nothing.
|
|
17
|
+
|
|
18
|
+
When the user agrees, add one plain sentence as its own paragraph at the end of the instruction file the agent loads, such as "Write documents for people to read as HTML source files, not Markdown." or "Write documents for people to read as Markdown, not HTML." When that file only imports another (a `CLAUDE.md` holding just `@AGENTS.md`), write to the imported file. Create a file only when no instruction file exists.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Check before delivery
|
|
2
|
+
|
|
3
|
+
Run these checks on the finished file and fix what they find.
|
|
4
|
+
|
|
5
|
+
The files a check makes, such as screenshots, PDFs and scripts, are scratch: save them by absolute path in the system temporary folder, never in the project, and delete them, wherever they landed, once the check is done.
|
|
6
|
+
|
|
7
|
+
## Checks that need no browser
|
|
8
|
+
|
|
9
|
+
- Every `<script src>` and `<link rel="stylesheet">` tag matches a tag in the [file rules](file.md) exactly: the same URL, `integrity` and `crossorigin="anonymous"`. A script or stylesheet inside the file as a `data:` URL matches none. A hosted font matches by its address instead: a stylesheet link to `https://fonts.googleapis.com/css2?family=...`, with no `integrity`. A font preload (`rel="preload" as="font"`) needs no match.
|
|
10
|
+
- No relative paths load anything: search for `src="` and `url(` and confirm each one is `https://`, `data:` or a `#fragment`.
|
|
11
|
+
- The file uses nothing on the sandbox list in the file rules.
|
|
12
|
+
- The marker is as the file rules say: the same last line as before, or none at all.
|
|
13
|
+
- Every number, name and date in the file appears in the source. Each gap is an open question.
|
|
14
|
+
- Light and dark each set every variable in [the design rules](design.md#the-looks-colour-variables), each colour clears its floor, `--accent-2` sits as far from `--accent` as the table says, and both accents colour something on screen.
|
|
15
|
+
|
|
16
|
+
## Checks in a browser
|
|
17
|
+
|
|
18
|
+
Use a browser tool when you have one, such as `agent-browser` or Playwright; without one, skip this section. Open the file from disk and:
|
|
19
|
+
|
|
20
|
+
- At 1280px and at 390px wide, confirm the page doesn't scroll sideways: `document.documentElement.scrollWidth` is no larger than `clientWidth`.
|
|
21
|
+
- Look at a screenshot at each width, in light and in dark. Fix overlapping, clipped or unreadable content.
|
|
22
|
+
- Read the console. Fix every error, including failed integrity checks.
|
|
23
|
+
- Use every control by keyboard and confirm it works and shows focus.
|
|
24
|
+
|
|
25
|
+
## Claims
|
|
26
|
+
|
|
27
|
+
Read the file sentence by sentence beside the source, captions, labels and tooltips included. Keep each claim the source states. A claim one step past it goes, or becomes an open question: a cause, when something starts or ends, a count, how far a rule reaches, or a new name for something the source names. A caption claims only what its figure draws. Done when you can point to the source's words behind every sentence.
|
|
28
|
+
|
|
29
|
+
## The structure you added
|
|
30
|
+
|
|
31
|
+
After every other check, the kind's and pattern skills' included, read the file top to bottom beside the source, and list for the hand-over every place they differ in structure:
|
|
32
|
+
|
|
33
|
+
- headings, labels, headlines and numbering you wrote;
|
|
34
|
+
- text you wrote that the source has no counterpart for, such as a summary, a lead or a slide's main point;
|
|
35
|
+
- parts and items in a different order from the source's;
|
|
36
|
+
- source lists you split, merged or grouped, such as five figures spread over three slides;
|
|
37
|
+
- items you put under a part or in a place the source doesn't give them, such as a guess under assumptions or a decision shown as a deadline.
|
|
38
|
+
|
|
39
|
+
A change a skill's rule made, such as a kind's order of the file, is still yours: list it. Write "kept the source's order" only when nothing moved. Done when a reader comparing the file with the source finds nothing your list leaves out.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Content rules
|
|
2
|
+
|
|
3
|
+
The source is the request and the files and data it points to, or the project's own material when the request asks about that. Other project files give terms, not content: name a relevant one in the hand-over instead of adding from it.
|
|
4
|
+
|
|
5
|
+
## The glossary
|
|
6
|
+
|
|
7
|
+
Look for the project's glossary: `CONTEXT.md`, `GLOSSARY.md`, a glossary page in the docs, or the README's terms section. Use its terms as written, and its preferred term over any word it says to avoid. Where it lacks a term, keep the source's word.
|
|
8
|
+
|
|
9
|
+
## Say only what the source says
|
|
10
|
+
|
|
11
|
+
- Every fact traces to the source: names, numbers, dates, owners, causes and outcomes come from it word for word or by plain arithmetic on its figures. So do links between facts: a reading rests on some evidence only when the source says so.
|
|
12
|
+
- A gap stays a gap. Write it under **Open questions** as a question the reader can answer, such as "Which regions does the outage cover?", never filled with an example, a likely cause or a typical value. Say it is missing from the source ("the brief gives no March figure"), not from the world ("not recorded").
|
|
13
|
+
- Decisions, assumptions and open questions stay apart, each under its own heading or label.
|
|
14
|
+
- Label every number as the source does: measured, estimate, target or forecast, with its unit, period and source. A number the source gives without its kind gets no kind label.
|
|
15
|
+
- Label illustrative or sample data as illustrative, next to the data.
|
|
16
|
+
- Wording keeps its strength: quote the source where a paraphrase could change it. "Should" stays "should", "suggests" stays "suggests" and "we" stays "we". Give an item a status, such as agreed, decided, proposed, pending, done or blocked, only when the source uses that status for that item.
|
|
17
|
+
- Add no interpretation, recommendation, option, reason or finding of your own unless the user asks for your analysis, and then label each as yours.
|
|
18
|
+
|
|
19
|
+
## Describe code from what you read
|
|
20
|
+
|
|
21
|
+
- Each claim about what code does names the function or file it comes from, in code you read in this session. A step belongs to the function that runs it, not to one that calls it or returns a value it acts on.
|
|
22
|
+
- Counts and lists of files come from listing them, such as with `git ls-files`.
|
|
23
|
+
- A test catches a bug only when you ran it against the bug, or traced the bug's case through the code.
|
|
24
|
+
|
|
25
|
+
## Lead with the point
|
|
26
|
+
|
|
27
|
+
- The first lines state the most important point: the finding, the decision or the answer.
|
|
28
|
+
- Describe behaviour and outcomes, not the steps someone took to build them.
|
|
29
|
+
- Write plainly: the short common word ("use", "is", "has", "to"), an adjective or adverb only where it states a fact from the source, and findings and recommendations at the source's strength. End on the last fact.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Design rules
|
|
2
|
+
|
|
3
|
+
## Who sets the look
|
|
4
|
+
|
|
5
|
+
Take the look from the first source that has one:
|
|
6
|
+
|
|
7
|
+
1. The user's explicit visual instructions.
|
|
8
|
+
2. The project's design system: its tokens, stylesheets or brand guide.
|
|
9
|
+
3. An installed design skill: one in your list of available skills, not a skill file found elsewhere on disk. Prefer Anthropic's `frontend-design`, then the Taste Skill stack (`design-taste-frontend` and its companion skills). Follow its guidance on type, colour values and character. When it asks questions or offers options, take its default and keep going.
|
|
10
|
+
4. Otherwise, copy [the plain default](plain-default.md).
|
|
11
|
+
|
|
12
|
+
Whatever sets the look, these rules own structure, density, reading width, print, the colour count below and the [file rules](file.md). A design skill's one-accent or colour-lock rule shapes the values it picks, but the colour count here wins whatever a design skill says about accents: two accents, four series colours and three status colours. A document is for reading: leave out the landing-page parts a design skill may suggest, such as hero banners, decorative sections, marketing copy and entrance animations.
|
|
13
|
+
|
|
14
|
+
## The look's colour variables
|
|
15
|
+
|
|
16
|
+
Every source file sets these fourteen variables in `:root`, once for light and once more under `@media (prefers-color-scheme: dark)`. The look's source fills their values: a design system from its tokens, a design skill from the palette it chooses, the plain default as written. Each takes a plain colour value: hex, `rgb()`, `hsl()`, `oklch()`, or `light-dark()` of those. Pattern skills colour their parts from these variables and no other colour.
|
|
17
|
+
|
|
18
|
+
| Variable | Colours | Floor against `--bg` |
|
|
19
|
+
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
|
|
20
|
+
| `--bg` | The page background. | |
|
|
21
|
+
| `--fg` | Text. | 4.5:1 |
|
|
22
|
+
| `--muted` | Secondary text: meta lines, captions, axis labels, connector labels. | 4.5:1 |
|
|
23
|
+
| `--line` | Hairlines: rules, table borders, frames, gridlines. | |
|
|
24
|
+
| `--surface` | Tinted panels: callouts, code blocks, caption strips, diagram nodes. | |
|
|
25
|
+
| `--accent` | The first accent: the title area, section headings, callout bars, focus outlines and the focus of each figure. | 3:1 |
|
|
26
|
+
| `--accent-2` | The second accent: links, the title rule and quote bars. In each theme, at least 60° from the first in OKLCH hue, so it stands out from the first accent and from the page. | 4.5:1 |
|
|
27
|
+
| `--series-1` to `--series-4` | Chart series and diagram node categories, in this order. Four hues apart from each other and from the accents. | 3:1 |
|
|
28
|
+
| `--good`, `--warn`, `--bad` | A status the source gives, such as on track, at risk and blocked: green, amber and red tuned to the look. | 3:1 |
|
|
29
|
+
|
|
30
|
+
Spend colour by the 60-30-10 rule: the neutrals fill most of the page, the first accent carries the look, and the second accent is the small share that stands out. Both accents colour something a reader sees in every source file, as the table places them. The first accent meets 4.5:1 where it colours text, such as headings.
|
|
31
|
+
|
|
32
|
+
A status the source gives shows in the source's words, in an element with `data-status="good"`, `"warn"` or `"bad"` that carries the matching colour on a dot, border or bar beside the words; the words stay `--fg`. The words are the element's own text, or a `.status` label inside it when the element holds more, such as a card. Rate it only as the source's word does: good for done or on track, warn for at risk, bad for blocked, late or missed. Any other status, such as in progress or not started, stays `--muted` with no `data-status`.
|
|
33
|
+
|
|
34
|
+
## Base rules every file meets
|
|
35
|
+
|
|
36
|
+
- **Light and dark.** Both themes follow the system setting through `prefers-color-scheme`.
|
|
37
|
+
- **Contrast.** Text meets WCAG AA: 4.5:1 for body text, 3:1 for large text, icons and control borders. Each colour variable meets its floor in the table above, in light and in dark.
|
|
38
|
+
- **Reading width.** Prose lines hold about 70 characters (`max-width: 70ch` on prose).
|
|
39
|
+
- **Type size.** Body text is at least 16px. Nothing a reader needs is smaller than 13px, including captions, table text, labels and code.
|
|
40
|
+
- **Phone width.** At 390px wide the page never scrolls sideways and keeps at least 12px of side padding, so no text or figure frame touches the screen's edge. Wide content scrolls inside its own box: a `<div class="scroll">` (`overflow-x: auto`) around a diagram or chart, the `.table-scroll` box `pageship-table` gives, or a code block's own `pre`.
|
|
41
|
+
- **Print.** A print stylesheet shows all content, expands anything collapsed (`details::details-content { content-visibility: visible }`), hides controls, prints dark text on white, and avoids breaking inside figures, table rows and callouts.
|
|
42
|
+
- **Links and controls.** Hovering a link or control changes how it looks, such as a thicker underline or a tinted background, and keyboard focus shows a visible outline. Every control is a native interactive element. Before adding one, load `pageship-interaction`.
|
|
43
|
+
- **Motion.** Nothing moves until the reader acts. Under `prefers-reduced-motion: reduce`, nothing animates and every state shows in full. Before making anything move, load `pageship-motion`.
|
|
44
|
+
- **Headings.** One `h1`, then levels in order. The document has a `lang` attribute and a `title`.
|
|
45
|
+
|
|
46
|
+
## The form of each figure
|
|
47
|
+
|
|
48
|
+
Take each figure's form from what the reader wants of it. Before writing a form that has a pattern skill, load that skill, and follow it for every such figure in the file, including one an edit adds or changes.
|
|
49
|
+
|
|
50
|
+
| The reader wants | Form | Skill |
|
|
51
|
+
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------- |
|
|
52
|
+
| To look up or compare exact values of items with two or more attributes | Table | `pageship-table` |
|
|
53
|
+
| The shape of numbers: a trend, a distribution, a ranking, a gap, or more values than anyone reads | Chart | `pageship-chart` |
|
|
54
|
+
| The shape and the exact values | Chart, then a table of the same values | Both |
|
|
55
|
+
| A few headline numbers that carry the document | Key figures | `pageship-key-figures` |
|
|
56
|
+
| How things connect: a path that branches, a structure, dependencies, who hands what to whom, or events in time | Diagram | `pageship-diagram` |
|
|
57
|
+
| The lines of code the text is about | Code block | `pageship-code-block` |
|
|
58
|
+
| An image, video or audio the source gives | Media | `pageship-media` |
|
|
59
|
+
| Items with one attribute each, or steps in one line with no branch whose timing doesn't matter | List | |
|
|
60
|
+
| One or two relationships, or two or three numbers that aren't parts of a whole | Sentence | |
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# File rules
|
|
2
|
+
|
|
3
|
+
## One standalone file
|
|
4
|
+
|
|
5
|
+
- Write one `.html` file with its CSS in a `<style>` element and its JavaScript in `<script>` elements, with no build step or framework.
|
|
6
|
+
- Load nothing from beside the file. Images and media use absolute `https://` URLs or inline `data:` URLs, and drawings are inline SVG.
|
|
7
|
+
- Use system fonts by default. A hosted font from Google Fonts is allowed when the look calls for it, followed by system fallbacks in the `font-family` list.
|
|
8
|
+
|
|
9
|
+
## Trusted libraries only
|
|
10
|
+
|
|
11
|
+
A file loads scripts and stylesheets from this list and nowhere else. Copy the tag exactly, with its version, `integrity` and `crossorigin`. Load a library only when the file uses it. Load scripts with a classic `<script src>` tag; a module `import` from a URL can't be checked by integrity.
|
|
12
|
+
|
|
13
|
+
Tailwind's browser build, only when the look you follow is built on Tailwind:
|
|
14
|
+
|
|
15
|
+
```html
|
|
16
|
+
<script
|
|
17
|
+
src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4.3.3/dist/index.global.js"
|
|
18
|
+
integrity="sha384-2ql948lIdLcGEE0/qxNiudyTjgauA3RDJERu5xW75kFCvSl5a9odyQYCb6tEjnmB"
|
|
19
|
+
crossorigin="anonymous"
|
|
20
|
+
></script>
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Mermaid, only when a pattern skill calls for it:
|
|
24
|
+
|
|
25
|
+
```html
|
|
26
|
+
<script
|
|
27
|
+
src="https://cdn.jsdelivr.net/npm/mermaid@11.17.2/dist/mermaid.min.js"
|
|
28
|
+
integrity="sha384-EOXBFmc3gx5mb+vn0vPvvGqACToJD24hhacX5Yx+8NUUQrHIle/Qi5Bg9o3zKwW2"
|
|
29
|
+
crossorigin="anonymous"
|
|
30
|
+
></script>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Hosted fonts from `https://fonts.googleapis.com/css2?...` through a `<link rel="stylesheet">`, which can't carry `integrity`.
|
|
34
|
+
|
|
35
|
+
## The Pageship sandbox
|
|
36
|
+
|
|
37
|
+
A published file runs with scripts allowed and everything else blocked, so it works without these:
|
|
38
|
+
|
|
39
|
+
- forms and form submission
|
|
40
|
+
- new windows, popups and links with `target="_blank"`
|
|
41
|
+
- `alert`, `confirm` and `prompt`
|
|
42
|
+
- cookies, `localStorage`, `sessionStorage` and IndexedDB
|
|
43
|
+
- cross-window messages (`postMessage`, `BroadcastChannel`)
|
|
44
|
+
|
|
45
|
+
Keep state in page variables and in the URL fragment (`#section`, `history.replaceState`).
|
|
46
|
+
|
|
47
|
+
## The document marker
|
|
48
|
+
|
|
49
|
+
A file the Pageship CLI has published ends with a document marker, such as `<!-- pageship:v1 document=Ab12Cd -->`. Only the CLI writes or changes it.
|
|
50
|
+
|
|
51
|
+
- When you regenerate, redesign, edit, rename or move a file that has a marker, the new file ends with the same marker, copied byte for byte as its last line, after `</html>`. Read the old file's last line before writing, and check the new file's last line after.
|
|
52
|
+
- A new file has no marker, even when it starts as a copy of another file.
|
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
# The plain default
|
|
2
|
+
|
|
3
|
+
A document look: serif prose with sans headings, labels and figure text, a plum title band and section headings, steel-blue links, framed figures with a caption strip, and tinted callouts. Extend this stylesheet with the same variables and font stacks; keep its sizes, widths and print rules.
|
|
4
|
+
|
|
5
|
+
```css
|
|
6
|
+
:root {
|
|
7
|
+
color-scheme: light dark;
|
|
8
|
+
--bg: #fcfbfa;
|
|
9
|
+
--fg: #1e1a1d;
|
|
10
|
+
--muted: #665c63;
|
|
11
|
+
--line: #dcd5da;
|
|
12
|
+
--surface: #f4f0f3;
|
|
13
|
+
--accent: #5d2750;
|
|
14
|
+
--accent-2: #006e8e;
|
|
15
|
+
--series-1: #2a7f78;
|
|
16
|
+
--series-2: #3f6fb5;
|
|
17
|
+
--series-3: #6c7a1a;
|
|
18
|
+
--series-4: #6a56b0;
|
|
19
|
+
--good: #2f7d4a;
|
|
20
|
+
--warn: #a85a00;
|
|
21
|
+
--bad: #b3261e;
|
|
22
|
+
--sans:
|
|
23
|
+
-apple-system, "Segoe UI", "Ubuntu Sans", Ubuntu, Roboto, "Helvetica Neue", Arial,
|
|
24
|
+
"Liberation Sans", sans-serif;
|
|
25
|
+
--serif:
|
|
26
|
+
Charter, "Iowan Old Style", "Palatino Linotype", Palatino, P052, "Book Antiqua", Georgia, serif;
|
|
27
|
+
--mono: ui-monospace, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
|
|
28
|
+
font: 17px/1.6 var(--serif);
|
|
29
|
+
}
|
|
30
|
+
@media (prefers-color-scheme: dark) {
|
|
31
|
+
:root {
|
|
32
|
+
--bg: #161317;
|
|
33
|
+
--fg: #ece7ea;
|
|
34
|
+
--muted: #aaa1a7;
|
|
35
|
+
--line: #3a3339;
|
|
36
|
+
--surface: #1f1b20;
|
|
37
|
+
--accent: #dca5d2;
|
|
38
|
+
--accent-2: #71c1e0;
|
|
39
|
+
--series-1: #5fc4ba;
|
|
40
|
+
--series-2: #89aef0;
|
|
41
|
+
--series-3: #b9c35a;
|
|
42
|
+
--series-4: #b2a3f0;
|
|
43
|
+
--good: #6fcf8a;
|
|
44
|
+
--warn: #f0b25a;
|
|
45
|
+
--bad: #f38b84;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
* {
|
|
49
|
+
box-sizing: border-box;
|
|
50
|
+
}
|
|
51
|
+
body {
|
|
52
|
+
margin: 0;
|
|
53
|
+
background: var(--bg);
|
|
54
|
+
color: var(--fg);
|
|
55
|
+
border-top: 0.5rem solid var(--accent);
|
|
56
|
+
}
|
|
57
|
+
main {
|
|
58
|
+
max-width: 72rem;
|
|
59
|
+
margin: 0 auto;
|
|
60
|
+
padding: 2.5rem 1.25rem 5rem;
|
|
61
|
+
}
|
|
62
|
+
main :is(p, li, dd, blockquote) {
|
|
63
|
+
max-width: 70ch;
|
|
64
|
+
}
|
|
65
|
+
h1,
|
|
66
|
+
h2,
|
|
67
|
+
h3,
|
|
68
|
+
h4,
|
|
69
|
+
table,
|
|
70
|
+
figcaption,
|
|
71
|
+
dt,
|
|
72
|
+
.meta,
|
|
73
|
+
small,
|
|
74
|
+
button,
|
|
75
|
+
summary {
|
|
76
|
+
font-family: var(--sans);
|
|
77
|
+
}
|
|
78
|
+
h1 {
|
|
79
|
+
font-size: 2.5rem;
|
|
80
|
+
line-height: 1.1;
|
|
81
|
+
letter-spacing: -0.015em;
|
|
82
|
+
margin: 0 0 0.75rem;
|
|
83
|
+
}
|
|
84
|
+
h1::after {
|
|
85
|
+
content: "";
|
|
86
|
+
display: block;
|
|
87
|
+
width: 3.5rem;
|
|
88
|
+
height: 0.25rem;
|
|
89
|
+
margin-top: 1.25rem;
|
|
90
|
+
background: var(--accent-2);
|
|
91
|
+
}
|
|
92
|
+
h2 {
|
|
93
|
+
font-size: 1.5rem;
|
|
94
|
+
line-height: 1.25;
|
|
95
|
+
letter-spacing: -0.01em;
|
|
96
|
+
color: var(--accent);
|
|
97
|
+
margin: 3.5rem 0 1rem;
|
|
98
|
+
padding-top: 1.25rem;
|
|
99
|
+
border-top: 1px solid var(--line);
|
|
100
|
+
}
|
|
101
|
+
h3 {
|
|
102
|
+
font-size: 1.125rem;
|
|
103
|
+
line-height: 1.3;
|
|
104
|
+
margin: 2rem 0 0.5rem;
|
|
105
|
+
}
|
|
106
|
+
h4 {
|
|
107
|
+
font-size: 1rem;
|
|
108
|
+
margin: 1.5rem 0 0.25rem;
|
|
109
|
+
}
|
|
110
|
+
p,
|
|
111
|
+
ul,
|
|
112
|
+
ol,
|
|
113
|
+
dl {
|
|
114
|
+
margin: 0 0 1rem;
|
|
115
|
+
}
|
|
116
|
+
li + li {
|
|
117
|
+
margin-top: 0.25rem;
|
|
118
|
+
}
|
|
119
|
+
a {
|
|
120
|
+
color: var(--accent-2);
|
|
121
|
+
text-decoration-thickness: 1px;
|
|
122
|
+
text-underline-offset: 0.15em;
|
|
123
|
+
}
|
|
124
|
+
a:hover {
|
|
125
|
+
text-decoration-thickness: 2px;
|
|
126
|
+
}
|
|
127
|
+
:focus-visible {
|
|
128
|
+
outline: 2px solid var(--accent);
|
|
129
|
+
outline-offset: 2px;
|
|
130
|
+
}
|
|
131
|
+
.meta,
|
|
132
|
+
small,
|
|
133
|
+
figcaption {
|
|
134
|
+
color: var(--muted);
|
|
135
|
+
font-size: 0.875rem;
|
|
136
|
+
line-height: 1.5;
|
|
137
|
+
}
|
|
138
|
+
.meta {
|
|
139
|
+
margin: 0 0 2rem;
|
|
140
|
+
}
|
|
141
|
+
blockquote {
|
|
142
|
+
margin: 1.25rem 0;
|
|
143
|
+
padding: 0.25rem 0 0.25rem 1.25rem;
|
|
144
|
+
border-left: 3px solid var(--accent-2);
|
|
145
|
+
}
|
|
146
|
+
dt {
|
|
147
|
+
font-weight: 600;
|
|
148
|
+
font-size: 0.875rem;
|
|
149
|
+
color: var(--muted);
|
|
150
|
+
margin-top: 0.75rem;
|
|
151
|
+
}
|
|
152
|
+
dd {
|
|
153
|
+
margin: 0.125rem 0 0;
|
|
154
|
+
}
|
|
155
|
+
code,
|
|
156
|
+
pre,
|
|
157
|
+
kbd,
|
|
158
|
+
samp {
|
|
159
|
+
font-family: var(--mono);
|
|
160
|
+
font-size: 0.875rem;
|
|
161
|
+
}
|
|
162
|
+
pre {
|
|
163
|
+
background: var(--surface);
|
|
164
|
+
border: 1px solid var(--line);
|
|
165
|
+
border-radius: 4px;
|
|
166
|
+
padding: 1rem 1.25rem;
|
|
167
|
+
overflow-x: auto;
|
|
168
|
+
line-height: 1.5;
|
|
169
|
+
}
|
|
170
|
+
:not(pre) > code {
|
|
171
|
+
background: var(--surface);
|
|
172
|
+
padding: 0.1em 0.3em;
|
|
173
|
+
border-radius: 3px;
|
|
174
|
+
}
|
|
175
|
+
hr {
|
|
176
|
+
border: 0;
|
|
177
|
+
border-top: 1px solid var(--line);
|
|
178
|
+
margin: 2rem 0;
|
|
179
|
+
}
|
|
180
|
+
.scroll {
|
|
181
|
+
overflow-x: auto;
|
|
182
|
+
}
|
|
183
|
+
figure {
|
|
184
|
+
width: fit-content;
|
|
185
|
+
min-width: min(100%, 28rem);
|
|
186
|
+
max-width: 100%;
|
|
187
|
+
margin: 2rem 0;
|
|
188
|
+
padding: 1.25rem;
|
|
189
|
+
border: 1px solid var(--line);
|
|
190
|
+
border-radius: 4px;
|
|
191
|
+
}
|
|
192
|
+
figcaption {
|
|
193
|
+
margin: 1rem -1.25rem -1.25rem;
|
|
194
|
+
padding: 0.75rem 1.25rem;
|
|
195
|
+
background: var(--surface);
|
|
196
|
+
border-top: 1px solid var(--line);
|
|
197
|
+
border-radius: 0 0 4px 4px;
|
|
198
|
+
contain: inline-size;
|
|
199
|
+
}
|
|
200
|
+
figcaption:first-child {
|
|
201
|
+
margin: -1.25rem -1.25rem 1rem;
|
|
202
|
+
border-top: 0;
|
|
203
|
+
border-bottom: 1px solid var(--line);
|
|
204
|
+
border-radius: 4px 4px 0 0;
|
|
205
|
+
}
|
|
206
|
+
table {
|
|
207
|
+
border-collapse: collapse;
|
|
208
|
+
font-size: 0.9375rem;
|
|
209
|
+
font-variant-numeric: tabular-nums;
|
|
210
|
+
}
|
|
211
|
+
th,
|
|
212
|
+
td {
|
|
213
|
+
text-align: left;
|
|
214
|
+
padding: 0.5rem 0.75rem;
|
|
215
|
+
border-bottom: 1px solid var(--line);
|
|
216
|
+
vertical-align: top;
|
|
217
|
+
}
|
|
218
|
+
thead th {
|
|
219
|
+
border-bottom: 2px solid var(--fg);
|
|
220
|
+
}
|
|
221
|
+
td.num,
|
|
222
|
+
th.num {
|
|
223
|
+
text-align: right;
|
|
224
|
+
}
|
|
225
|
+
.callout {
|
|
226
|
+
background: var(--surface);
|
|
227
|
+
border-left: 4px solid var(--accent);
|
|
228
|
+
border-radius: 0 4px 4px 0;
|
|
229
|
+
padding: 1rem 1.25rem;
|
|
230
|
+
margin: 1.5rem 0;
|
|
231
|
+
}
|
|
232
|
+
.callout > :last-child {
|
|
233
|
+
margin-bottom: 0;
|
|
234
|
+
}
|
|
235
|
+
details {
|
|
236
|
+
border: 1px solid var(--line);
|
|
237
|
+
border-radius: 4px;
|
|
238
|
+
padding: 0.5rem 1rem;
|
|
239
|
+
margin: 1rem 0;
|
|
240
|
+
}
|
|
241
|
+
summary {
|
|
242
|
+
font-weight: 600;
|
|
243
|
+
cursor: pointer;
|
|
244
|
+
}
|
|
245
|
+
button {
|
|
246
|
+
font: 600 0.9375rem var(--sans);
|
|
247
|
+
color: var(--fg);
|
|
248
|
+
background: var(--bg);
|
|
249
|
+
border: 1px solid var(--muted);
|
|
250
|
+
border-radius: 4px;
|
|
251
|
+
padding: 0.375rem 0.875rem;
|
|
252
|
+
}
|
|
253
|
+
button:hover,
|
|
254
|
+
summary:hover {
|
|
255
|
+
background: var(--surface);
|
|
256
|
+
}
|
|
257
|
+
button:is([aria-pressed="true"], [aria-selected="true"], [aria-expanded="true"]) {
|
|
258
|
+
border: 2px solid var(--accent);
|
|
259
|
+
padding: calc(0.375rem - 1px) calc(0.875rem - 1px);
|
|
260
|
+
}
|
|
261
|
+
@media (max-width: 40rem) {
|
|
262
|
+
main {
|
|
263
|
+
padding: 1.5rem 1rem 3rem;
|
|
264
|
+
}
|
|
265
|
+
h1 {
|
|
266
|
+
font-size: 2rem;
|
|
267
|
+
}
|
|
268
|
+
h2 {
|
|
269
|
+
margin-top: 2.5rem;
|
|
270
|
+
}
|
|
271
|
+
figure {
|
|
272
|
+
min-width: 100%;
|
|
273
|
+
padding: 0.75rem 0;
|
|
274
|
+
border-width: 1px 0;
|
|
275
|
+
border-radius: 0;
|
|
276
|
+
}
|
|
277
|
+
figcaption {
|
|
278
|
+
margin: 0.75rem 0 -0.75rem;
|
|
279
|
+
border-radius: 0;
|
|
280
|
+
}
|
|
281
|
+
figcaption:first-child {
|
|
282
|
+
margin: -0.75rem 0 0.75rem;
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
@media (prefers-reduced-motion: reduce) {
|
|
286
|
+
* {
|
|
287
|
+
animation: none !important;
|
|
288
|
+
transition: none !important;
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
@media print {
|
|
292
|
+
:root {
|
|
293
|
+
--bg: #fff;
|
|
294
|
+
--fg: #000;
|
|
295
|
+
--muted: #333;
|
|
296
|
+
--line: #bbb;
|
|
297
|
+
--surface: #fff;
|
|
298
|
+
--accent: #5d2750;
|
|
299
|
+
--accent-2: #006e8e;
|
|
300
|
+
--series-1: #2a7f78;
|
|
301
|
+
--series-2: #3f6fb5;
|
|
302
|
+
--series-3: #6c7a1a;
|
|
303
|
+
--series-4: #6a56b0;
|
|
304
|
+
--good: #2f7d4a;
|
|
305
|
+
--warn: #a85a00;
|
|
306
|
+
--bad: #b3261e;
|
|
307
|
+
}
|
|
308
|
+
main {
|
|
309
|
+
max-width: none;
|
|
310
|
+
padding: 0;
|
|
311
|
+
}
|
|
312
|
+
button,
|
|
313
|
+
[role="toolbar"] {
|
|
314
|
+
display: none;
|
|
315
|
+
}
|
|
316
|
+
details::details-content {
|
|
317
|
+
content-visibility: visible;
|
|
318
|
+
}
|
|
319
|
+
figure,
|
|
320
|
+
tr,
|
|
321
|
+
.callout,
|
|
322
|
+
pre {
|
|
323
|
+
break-inside: avoid;
|
|
324
|
+
}
|
|
325
|
+
.scroll,
|
|
326
|
+
pre {
|
|
327
|
+
overflow: visible;
|
|
328
|
+
white-space: pre-wrap;
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
```
|