The text of CUSTOMISING.md from the Shipfolder 1.1.0 download.

Customising Shipfolder

This guide covers the changes buyers make most often. Run python3 qa/qa.py after each one.

1. How the colour system works

css/theme.css has four parts:

1. Scale tokens: type, spacing, radius, layout, shadow and motion.

2. Presets: each preset sets eight accent values, four for light mode and four for dark mode:

   Token	Used for
   --accent-light / --accent-dark	primary buttons, check marks, focus ring, featured pricing border
   --accent-text-light / --accent-text-dark	links, eyebrow labels, active navigation
   --on-accent-light / --on-accent-dark	text on primary buttons
   --accent-soft-light / --accent-soft-dark	tinted backgrounds: badges, active nav item, CTA band

3. Light mode: neutral colours (background, surfaces, text, borders, code, tags), plus a mapping such as --color-accent: var(--accent-light).
4. Dark mode: the same tokens with dark values. This block appears twice, once inside @media (prefers-color-scheme: dark) and once as :root[data-theme="dark"]. CSS cannot share one rule between a media query and a normal selector. Keep the two copies identical; qa/qa.py fails if they differ.

components.css uses only the --color-* tokens and never raw colours. The QA script checks this too.

2. Make your own preset

1. Copy the :root[data-preset="teal"] { … } block in theme.css.
2. Rename it, for example :root[data-preset="brand"].
3. Set your eight values. As a starting point:
   • --accent-light should be dark enough for white text (aim for 4.5:1 against #ffffff).
   • --accent-text-light is usually a shade darker than --accent-light.
   • --accent-dark should be a light tint of the same hue, with dark --on-accent-dark text on it.
   • --accent-soft-* are very pale (light mode) or very deep (dark mode) tints for backgrounds.
4. Set data-preset="brand" on the <html> element of every page.
5. Add "brand" to PRESETS near the top of qa/qa.py and run it. It checks your new colours in both modes and names any pair below the minimum.

3. Change neutral colours, fonts, spacing

• Neutrals (backgrounds, text, borders): edit the light block and both dark blocks.
• Fonts: the kit uses the visitor's system fonts, so nothing downloads. To use a different stack, change --font-sans and --font-mono. To self-host a web font, put the font files in assets/fonts/, add an @font-face rule at the top of theme.css, and record the font and its licence in LICENSES.md. Use only fonts whose licence allows it, such as the SIL Open Font License. Note that the QA script flags font files on purpose: the kit as shipped uses none. Remove that rule from check_external in qa/qa.py if you add fonts deliberately.
• Type scale: --text-* tokens. The two biggest sizes use clamp() so headings shrink on phones.
• Spacing and radius: --space-* and --radius-*.

4. Change the logo and name

• The header and footer logo is an inline SVG with the class brand-mark. It draws a rounded square in the accent colour with a chevron on top. Replace the <svg>…</svg> with your own. Keep aria-hidden="true", because the visible product name next to it is the link text.
• assets/favicon.svg is the browser-tab icon. Edit its colours or replace the file.
• Search all pages for Example API and Example Co.

5. Header and footer

The header and footer are copied into each page (no build step means no includes). To change them:

1. Edit them in index.html.
2. Paste the same markup into the other five pages.
3. Move aria-current="page" to the right navigation link on each page.
4. Run python3 qa/qa.py. The shared-chrome check fails if any page's header or footer differs from index.html, ignoring aria-current.

6. Code blocks and the copy button

<div class="code-block" data-copy>
  <div class="code-header"><span>Shell</span></div>
  <pre tabindex="0"><code>npm install -g example-cli</code></pre>
</div>

• data-copy adds a Copy button when JavaScript runs. Remove it for blocks that shouldn't have one.
• Escape < as <, > as > and & as & inside <code>.
• Syntax colours are optional. Wrap tokens in <span class="tok-k"> (keyword), tok-s (string), tok-f (function or command), tok-n (number) or tok-c (comment). There is no highlighter script, which keeps the JavaScript small. Code without spans shows in one colour.
• Long lines scroll inside the block, never the page.

7. Add pages

• Docs page: copy docs.html to, say, docs-webhooks.html. Update the <title>, meta description, <h1>, content and "On this page" list. In the sidebar of every docs page, link to the new file and move aria-current="page" to it. In the sample, the sidebar entries after "Quick start" point to sections of docs.html. Point them at your real pages as you add them.
• Blog post: copy blog-post.html, then add a card for it in blog.html.
• Changelog entry: copy an <article class="changelog-entry"> block to the top of the list. Give it a unique id (for example v2-5-0) so you can link to it. Use <time datetime="YYYY-MM-DD">. Tag classes: tag-new, tag-improved, tag-fixed, tag-breaking.

Every page needs a unique <title> and meta description, and exactly one <h1>. The QA script checks all three.

8. JavaScript

js/main.js (about 3.9 KB, no dependencies) does three things:

1. Applies the saved theme before the page paints. It loads in <head> without defer on purpose, so a dark-mode reader never sees a flash of white.
2. Shows and wires up the theme toggle.
3. Adds Copy buttons and collapses the docs menu on small screens.

Everything else works without it. To drop JavaScript entirely, delete the <script> tag and the file. Remove the toggle button too, or leave it, since it stays hidden.

The storage key is shipfolder-theme. Change KEY at the top of main.js if you want your own.

9. Things to replace before launch

• Every sentence containing "Placeholder", and the placeholder author on blog-post.html.
• The "How it works" steps, features, pricing plans and FAQ on index.html.
• Links to example.com, and the hello@/sales@example.com addresses.
• Pricing plans and limits.
• The meta descriptions on every page.

The sample pages contain no testimonials, customer logos or usage numbers. If you add any, use only real ones that you have permission to publish.