* feat: general-purpose skills with @-mention composition and user import
Lift skills from "one mode-bound skill per project" to a generic capability
the user can compose per turn:
- Daemon: scan multiple skill roots (user-skills under runtime data, then
the bundled `skills/`); user-imported skills can shadow built-ins by id.
- New `POST /api/skills/import` and `DELETE /api/skills/:id` endpoints,
with CONFLICT/BAD_REQUEST/NOT_FOUND error codes and built-in delete
protection.
- ChatRequest gains `skillIds: string[]`; the chat run concatenates each
picked skill's body (and merges craftRequires) into the system prompt
for that turn only — the project's persistent `skillId` is untouched.
- Web composer: `@` popover now lists skills alongside project files;
picks render as removable chips above the textarea and ride along with
the request as `skillIds`.
- Settings → Library: import form (name/description/triggers/body),
per-card delete for user skills, "user" origin badge.
* chore(web): drop welcome pet teaser + add ds→prompt-template mapping util
- SettingsDialog: remove the inline pet adoption teaser from the welcome
panel so the first-run modal stays focused on configuration.
- New `inferPromptTemplateCategoriesForDs(ds)` helper that maps a design
system's authored metadata to prompt-template gallery categories.
Imported by the design-system gallery wiring on a sibling branch; no
callers in this branch yet.
* feat: split skills/design-templates and add finalize-design API
Phase 0 of the skills/design-templates refactor (specs/current/
skills-and-design-templates.md):
- Move ~104 rendering catalogue entries from skills/ to design-templates/
and keep skills/ for the small set of functional skills that *do work*
on user input (utilities, briefs, packagers).
- Add design-templates/AGENTS.md and skills/AGENTS.md describing the
contract, and a brand-agnostic craft/ surface for opt-in craft rules.
- Daemon: add DESIGN_TEMPLATES_DIR / USER_DESIGN_TEMPLATES_DIR roots and
an /api/design-templates surface mirroring /api/skills. Asset/example
routes still span both registries so existing srcdoc URLs keep
resolving across the rename.
- Web: split LibrarySection into SkillsSection + DesignSystemsSection,
rename the EntryView "Examples" tab to "Templates", and update locales
+ the New-project picker accordingly.
Adds the finalize-design endpoint:
- New apps/daemon/src/finalize-design.ts and packages/contracts/src/api/
finalize.ts — one-shot synthesis of a project's transcript + active
design system + current artifact into <projectDir>/DESIGN.md via the
Anthropic Messages API. Per-project .finalize.lock mirrors the
transcript-export hygiene from PR #493; provider credentials are not
persisted by the daemon.
Other supporting changes:
- README + AGENTS.md updates to document the new directory split and
craft/ surface, plus i18n strings across 13 locales.
- Test refactors and new coverage (finalize-design, runs, sidecar
server, plus refreshed daemon integration tests).
- .gitignore: scope the *.exe ignore to /OpenDesign.exe so legitimate
vendor binaries are no longer hidden.
* fix(merge): move clinical-case-report to design-templates/
Origin/main added the clinical-case-report skill under skills/ before
the skills/design-templates split landed. Its od.mode is prototype, so
per specs/current/skills-and-design-templates.md it is a design template
and belongs alongside the other rendering catalogue entries — not under
the slimmed-down functional skills/ root. Moving it keeps the EntryView
Templates tab consistent with origin/main's intent.
* feat(skills): curated design/creative catalogue + collapsible Settings rows
Seed ~100 curated design/creative skill stubs under skills/ sourced from
awesome-claude-skills (ComposioHQ) and awesome-agent-skills (VoltAgent).
Each stub carries an od.category tag so the new filter pill row in
Settings -> Skills can group them. The seed script
(scripts/seed-curated-design-skills.ts, pnpm seed:curated-design-skills)
is idempotent: it only creates folders that don't already exist, so
hand-edited stubs are never overwritten.
- Daemon: parse and surface od.category on SkillInfo with a strict slug
normaliser; mirror the field on SkillSummary in @open-design/contracts.
Category is purely a UI hint — system-prompt composition is unchanged.
- Web: rewrite SkillsSection from a left-list / right-detail grid into a
vertical stack of collapsible rows mirroring the External MCP panel
(header always visible with name + mode/source/category pills + per-row
enable toggle; SKILL.md preview, file tree and inline edit form expand
on demand). Add a Category filter row above the list. Reorder Settings
nav so Skills + External MCP sit above the Composio/MCP cluster. Update
composer placeholder/hint across 17 locales to advertise '@ files or
skills · / for commands'.
- Docs: extend skills/AGENTS.md with the curated catalogue rules
(idempotency, category vocabulary, no upstream vendoring).
Co-authored-by: Cursor <cursoragent@cursor.com>
* test(skills): teach localized-content + system-prompt tests about the skills/design-templates split
mrcfps blocking review on PR #955: the skills/design-templates split
(b5993385) moved ~110 SKILL.md entries out of `skills/` and into
`design-templates/`, but two repo-level tests still hard-coded the
single-root layout, so CI gates went red on the merged branch:
- `e2e/tests/localized-content.test.ts` only scanned `<repo>/skills`
while the locale `skillCopy` map keeps id-keyed entries spanning
both roots (ExamplesTab/Templates uses one lookup regardless of
origin). Teach the helper to read both `skills/` and
`design-templates/`, deduplicating ids so the union matches the
localized claim.
- `apps/daemon/tests/prompts/system.test.ts` read
`skills/live-artifact/SKILL.md`, which now lives under
`design-templates/live-artifact/`. Update the absolute path so
composeSystemPrompt's coverage of the live-artifact preamble is
exercised again.
Also enroll the curated design/creative catalogue (PR #955, ~91
stubs sourced from awesome-claude-skills / awesome-agent-skills) in
the DE / FR / RU `_SKILL_IDS_WITH_EN_FALLBACK` lists. The stubs are
English-only by design (frontmatter advertises an upstream URL); the
fallback list is exactly the place to acknowledge "we know this id
exists, English copy is fine here" so the localized-content coverage
gate passes without forcing a translation task per locale.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(skills): always quote frontmatter name so importUserSkill round-trips numeric / boolean ids
mrcfps PR #955 review: `buildSkillMarkdown` emitted `name:
${escapeYamlString(name)}` without quotes, so YAML coerced names
like `123`, `true`, `false`, or `null` into non-string scalars on
re-parse. listSkills() then read `data.name` as a number/boolean
and the import flow's follow-up `findSkillById(skills, result.id)`
missed it, falling into `/api/skills/import`'s "imported skill
could not be re-read" 500 path for those ids.
Switch the emitter to a quoted scalar (`name: "..."`) — the
double-escape already in `escapeYamlString` makes the quoted form
safe — and add a round-trip test covering `123`, `true`, `false`,
`null`, and `0` to lock in the contract.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(web): drop staged-skill chips when the matching @<id> token leaves the draft
mrcfps PR #955 review: `submit()` always forwarded every id in
`stagedSkills`, but that state was only mutated on picker click and
chip removal. Hand-deleting an `@<id>` token from the textarea left
the chip staged, so the request still carried `skillIds: [<id>]` and
the daemon composed a skill the prompt no longer referenced.
Sync the chips with the draft inside `handleChange()` by pruning
`stagedSkills` whenever the new value no longer contains the
`@<id>` token (using the same whitespace boundary as
`removeStagedSkill`'s strip regex). Comment explains why this
prune does not run for `staged` file attachments — users frequently
add files via the upload button without leaving an `@<path>` token,
so a symmetric prune there would erase legitimate uploads.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(daemon): stage @-composed skills' side files alongside the active skill
codex PR #955 review: composing a per-turn `@`-picked skill into the
system prompt appended its body (with the `withSkillRootPreamble`
guidance pointing at relative paths under `<cwd>/.od-skills/<folder>/`)
but never staged the actual folder. `startChatRun` only copied
`activeSkillDir`, so when the project's primary skill was different
(or absent) the composed skill's references/, examples/, and scripts/
files lived only at their absolute repo path — agents that honour
the cwd-relative form (or that don't get `--add-dir`, e.g. Codex with
allowlisted gpt-image projects) couldn't reach them.
Thread the composed skills' dirs out of `composeDaemonSystemPrompt`
as `extraSkillDirs` and stage each one through the same
`stageActiveSkill` API used for the primary skill. Dedupe by folder
basename so a project whose primary skill is also `@`-composed isn't
copied twice. Each preamble already advertises its own folder, so the
prompt and the staged tree stay aligned without further changes.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(web): respect the Library disable toggle in the project @-mention picker
codex PR #955 review: only `EntryView` received `enabledSkills`
(filtered against `config.disabledSkills`); active projects still
got `skills={skills}` raw, so a skill the user disabled in Settings
kept appearing in the project's `@`-mention popover and could ride
along to the daemon via `skillIds`. That broke the Library toggle
for any project opened on the post-split branch.
Compute a functional-skills-only enabled subset
(`enabledFunctionalSkills`) and pass it into `<ProjectView>` instead.
Templates stay separate — design-templates are filtered through their
own `enabledDesignTemplates` memo for the Templates gallery — so
ProjectView's chat composer still only sees skills, never templates,
matching the pre-split prop surface.
Co-authored-by: Cursor <cursoragent@cursor.com>
* test(e2e): mock /api/design-templates for example-use-prompt flow
The Templates tab in EntryView fetches from /api/design-templates after
the skills/design-templates split (specs/current/skills-and-design-templates.md).
The example-use-prompt Playwright scenario only mocked /api/skills, so the
gallery card never appeared and the test timed out waiting on
example-card-warm-utility-example. Serve the same fixture summary on both
endpoints so the templates gallery renders the card the test clicks.
Co-authored-by: Cursor <cursoragent@cursor.com>
* test(tools-pack): create design-templates fixture for resources test
The packaging resources copy now bundles the new design-templates tree
alongside skills (see resources.ts BUNDLED_RESOURCE_TREES). The
copyBundledResourceTrees fixture only created skills, design-systems,
craft, etc., so the recursive copy crashed with ENOENT on
design-templates before it could check the prompt-templates assertion.
Add the missing fixture directory so the test exercises the same set
of resource trees the packaged build does.
Co-authored-by: Cursor <cursoragent@cursor.com>
* fix(skills): clone built-in side files into the shadow on first edit
mrcfps PR #955 review: editing a built-in skill wrote a USER_SKILLS_DIR
shadow folder that contained only a new SKILL.md. The next listSkills()
pass surfaced the shadow as the active dir, but every side-file resolver
(/api/skills/:id/files, /example, /assets/*, the system-prompt preamble,
and the per-turn cwd staging) reads through skill.dir. With nothing but
SKILL.md in the shadow, the bundled assets/, references/, scripts/, and
examples/ disappeared the moment the user hit save — a built-in like
last30days or live-artifact would break immediately after edit instead
of just having its body overridden.
Teach updateUserSkill() to take a `sourceDir` and clone every entry
except SKILL.md / dotfiles into the shadow on the very first edit. The
shadow stays self-contained, so all the resolvers keep working without
fallback bookkeeping. Subsequent edits detect the existing shadow and
skip the clone, so user tweaks under the side tree survive a re-save.
Wire `sourceDir: skill.dir` from server.ts's PUT /api/skills/:id handler
and add two regression tests:
- 'clones built-in side files into the shadow on the first edit' walks
the file tree after save and asserts assets/template.html, references/
notes.md, and scripts/helper.sh all round-trip from the built-in.
- 'preserves user-edited side files on subsequent edits' edits the
staged assets/template.html, re-saves, and confirms the user content
is still there.
Co-authored-by: Cursor <cursoragent@cursor.com>
* test(e2e): rename home tab from Examples to Templates
The Examples tab was renamed to Templates in EntryView (b5993385's
skills/design-templates split — entry.tabExamples became entry.tabTemplates
and the tab value moved from 'examples' to 'templates'), but
entry-chrome-flows still asserted the old label and testId. Update both.
* fix(skills+web): preserve template body in API mode and dir-based skill delete
Two follow-ups from PR #955 review:
1. ProjectView only received `enabledFunctionalSkills`, but
`composedSystemPrompt()` still resolved `project.skillId` through that
prop and `fetchSkill()`. Projects created from the new
`/api/design-templates` surface keep a template id in `project.skillId`,
so opening one in API mode dropped the template body from the system
prompt and the upstream request ran without the project's primary
template instructions. Now ProjectView takes a separate
`designTemplates` prop (the unfiltered template list, so a
later-disabled template still loads for projects already created from
it) and `composedSystemPrompt()` plus the metadata / `isDeck` lookups
fall back to that list, with `fetchDesignTemplate()` as the body-fetch
fallback to `fetchSkill()`. The chat composer's `@`-picker keeps
receiving only the enabled functional skills.
2. `DELETE /api/skills/:id` used `deleteUserSkill(USER_SKILLS_DIR, skill.id)`
which re-slugified the frontmatter id and removed
`<userSkillsDir>/<slug>/`. That matched the import shape but missed the
install shape — `installFromTarget` writes the folder at
`sanitizeRepoName(url)` (GitHub) or `path.basename(realpath)` (local
symlink), neither of which is guaranteed to equal the slugified
frontmatter `name`. A duplicate `app.delete('/api/skills/:id', ...)`
handler at the install routes never fired because Express resolved the
earlier registration first, leaving the install/uninstall path without
working teardown. The handler now removes `skill.dir` (the absolute
path listSkills already discovered) under a USER_SKILLS_DIR safety
check, using `lstat` + `unlinkSync` so symlinked local installs unlink
cleanly without recursing into the user's source tree. The dead
duplicate handler is removed; `deleteUserSkill` is dropped from the
server.ts import set (still exported and unit-tested in skills.ts).
Regression coverage in `apps/daemon/tests/skills-delete-route.test.ts`
pins both shapes plus the symlink-preserves-source case.
* test(daemon): point hyperframes system-prompt test at design-templates
The merge with main brought in a hyperframes system-prompt test that
reads `skills/hyperframes/SKILL.md`, but this branch's split moved
`hyperframes` into `design-templates/` (same migration as `live-artifact`
already handled above in this file). CI was failing with ENOENT on the
old path.
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
14 KiB
Themes · replit-deck
Eight complete visual systems captured from replit.com/slides. Each theme is a commitment — once the deck picks a theme, every slide inherits from that theme's token set via <body data-theme="…">. Do not override per-slide.
All hex values were sampled from the actual Replit Slides landing-page PNGs with ImageMagick on 2026-04-29 (see SKILL.md → Scope & provenance). Don't guess, don't substitute "similar" colors from memory. To add or refresh a theme, follow the procedure in Contributing a new theme at the bottom of this file.
How to pick
| If the brief mentions… | Pick |
|---|---|
| SaaS, metrics, board, analytics, fund | helix |
| law firm, memo, pre-read, confidential, investor note | holm |
| art, sculpture, photography, catalog, portfolio, gallery | vance |
| fashion, campaign, lookbook, SS26, jewelry, editorial | bevel |
| policy, macro, finance report, world economy, dark mood | world-dark |
| lighter companion deck for a world-dark topic (ESG, wellness finance, sustainability) | world-mint |
| history, chapter, archive, long-form narrative, museum | atlas |
| consumer product, real estate, lifestyle, playful | bluehouse |
Never mix two themes in one deck. <body data-theme="…"> is the single source of truth for the whole deck — one value, no per-slide overrides. This is enforced as a P0 gate in checklist.md.
If the brief really needs two visual registers (e.g. chapters vs. data), either pick the theme that already carries that internal contrast (bluehouse has gradient cards; atlas has chapter plates vs. data strips), or split the content into two separate decks. world-dark and world-mint are stylistic siblings (same palette, inverted surface), so if you need a companion deck in a different mood they are the most coherent pair — but still one theme per file.
helix — Modern minimal
Reference: replit slide-1, slide-4, slide-5.
--bg #fafafa near-white
--fg #19191c ink
--muted #6e6e73
--border #e4e4e7
--accent #5889fe electric blue
--display Inter Display · weight 600 · tracking -0.02em
--body Inter
--mono JetBrains Mono (bps / YoY labels)
Do
- Huge
.num($1.37B,128%,42,850) — dominant element on the slide, no decoration. - Blue shows up in
▲ 38% YoY/▼ 1 molabels only. Use the mono family for those. - Plenty of white space. Slides often have the content only in the top or left half.
- Page counter bottom-right in mono (
03 / 05).
Don't
- No gradients. No card shadows. No rounded accent bars.
- Never put a KPI inside a blue-filled box — blue is type-color only.
- Don't tilt or slant.
- Don't add emoji or icons to metric cards.
Best layouts: kpi-row-6 · split-hero-metric · big-number-center.
holm — Editorial serif memo
Reference: replit slide-2, slide-5.
--bg #e4dfd7 warm cream
--fg #0f0f0e ink
--muted #7c7e84
--border #c7c1b7
--accent #52311d deep chestnut
--display Tiempos / GT Super style serif · weight 500
--body Inter sans (body copy + mono eyebrows)
--mono JetBrains Mono (MEMO 04 / APR 2026 style meta)
Do
- Serif display only on the one hero statement per slide. Body copy stays sans.
- Eyebrows (
SERIES A — CONFIDENTIAL PRE-READ,04 — THE ASK) in mono, uppercase, widely tracked, colored by--accentor muted. - Large vertical rhythm. Think one sentence at 64–96px occupying the left half, the rest breathing.
- A small chestnut wordmark ("Holm") in the top-left meta bar is the only branding.
Don't
- No pure white surface — the cream is the identity. Don't lighten to #fff.
- Don't use the serif for body paragraphs (it will feel like a novel, not a memo).
- No boxed cards. A memo has edges only from whitespace.
Best layouts: memo-hero-statement · two-column-ask · name-card-team.
vance — Gallery catalog
Reference: replit slide-3, slide-7.
--bg #f1ede2 gallery cream
--fg #171815 ink
--bar #0a0a0a black band (top and/or bottom of slide)
--bar-fg #f1ede2 cream-on-black
--accent #171815 ink (there is no chromatic accent)
--display serif display · weight 400 (italic variants encouraged)
--body Inter
Do
- Top band holds
CATALOG — PLATE NN,II OF V · FEATURED,© 2026 THE ARTIST— always three-column meta in ALL CAPS small tracked type on black. - The artwork / photo fills the middle plate, edge-to-edge.
- Serif title (
Untitled (Threshold)) may break across two lines with italic for the parenthetical. - Bottom band mirrors top: caption on left (
Untitled (Threshold), 2022. Felt, plaster, and resin…),PHOTOGRAPHY — NAMEon right.
Don't
- No color accents. Chromatic noise kills the gallery tone.
- Don't center-align text inside the bands — always left/center/right three-column.
- Don't use the cream as a solid background without the black bands; the two-tone is the identity.
Best layouts: gallery-plate · spread-image-quote · index-grid.
bevel — Y2K editorial
Reference: replit slide-6, slide-13.
--bg #0d0d0b near-black
--fg #eae6dd warm off-white
--muted #a29e95
--border #2a2a28
--accent #c8ff00 neon / chartreuse (outline + dots only)
--display Y2K display face — Antonio / Bebas / italic chrome sans · weight 700
--body Inter
Do
- Display wordmark (
bevel,reflex) in the chrome-y Y2K italic face — oversized, often rotated off-axis by 0 (but tracked wide). - Dashed neon frames around product imagery. Each frame gets
::before/::afterneon dots in the corners. - Small neon square markers (
14 PIECES,SS26 INDEX) in the corners. - Product imagery treated as lookbook: desaturated on black, caption under image in serif-italic small caps.
Don't
- Never fill anything with neon. Neon is outline, dot, or 1-char accent only. More than ~2% neon by area = slop.
- Don't use photography that looks like stock SaaS. If the brief is SaaS, pick a different theme.
- Don't use sentence case for the display wordmark.
Best layouts: campaign-cover · product-triptych · index-grid.
world-dark — Finance dark
Reference: replit slide-8, slide-10.
--bg #0d3a2b deep racing green
--fg #bcd6cd mint text
--muted #789f91
--border #1d4c3c
--accent #e8f615 neon yellow
--display Inter Display · weight 500
--body Inter
Do
- Big sans display for the report title (
World Finance Report,Monetary Policy). - Neon yellow appears as:
- a small square marker (14×14px) near section breaks,
- the color of section labels (
Total debt,S&P 500) above the dark green cells, - never as a fill for a text block.
- Horizontal divider lines are 1px hairlines in
--border. - Image tiles (portraits, skyline, streetscape) use tall 2:3 aspect, full-bleed, with captions in white overlaid bottom-left.
Don't
- No icons in KPI cells.
- Don't use the yellow for links or CTAs — it is a pointer, not a button.
- No rounded corners on dividers or cells.
Best layouts: finance-hero-grid · quadrant-policy · indicator-strip.
world-mint — Finance light (sibling)
Reference: replit slide-9.
Exact mirror of world-dark: swap --bg with --fg. Deep green becomes the type color; mint becomes the surface. Yellow accent stays identical.
Use world-mint as a standalone deck when the topic is gentler (ESG report, wellness finance, sustainability). If a world-dark deck wants a lighter companion piece for a separate audience, make it a separate deck file with data-theme="world-mint" — do not alternate slides inside one deck (see one-theme rule above).
Do / Don't: same as world-dark.
Best layouts: section-divider-giant-title · quadrant-policy · indicator-strip.
atlas — Museum chapter
Reference: replit slide-11.
--bg #111010 near-black
--fg #e7e6e2 ivory
--muted #827d78
--border #2a2826
--accent #de3f40 vermilion
--display serif display · weight 500
--body Inter
Do
- Vermilion dot (●) before
THE ATLAS QUARTERLY · CHAPTER 01in the meta bar. - Huge serif titles split across 2 lines (
The Imperial/Age.) — the period is always vermilion. - Three-column data strip at the bottom:
PERIOD/REACH/CAPITALS, labels in mono all-caps small, data in sans display (one word per column if possible). - Right half often carries an archival photograph inside a thin ivory hairline border with
PLATE Ilabel top-left andEXHIBIT 04.Btag top-right. - Progress bar at the very bottom (vermilion segment + ivory hairline).
Don't
- Never use the vermilion for body text or callouts — only for the terminal period, the meta dot, and the progress segment.
- Don't pair the serif with a mono kicker that's larger than 12px; the mono must always feel like a catalogue footer.
- Avoid images with modern styling (filters, gradients). Archive-grade black & white or sepia only.
Best layouts: chapter-plate · timeline-strip · photo-with-caption.
bluehouse — Consumer card
Reference: replit slide-12.
--bg #0b1524 deep navy
--fg #ffffff
--muted #8ea0b8
--border #1a2c46
--accent #fb675d coral
--accent-2 #ff8f68 peach (for gradient)
--card-peach #e0af99
--card-lavender #c7cff0
--display Inter Display · weight 700 · tracking -0.025em
--body Inter
Do
- Big bold sans headlines (
Driving real estate ROI with prime properties) with an inline pill highlighting a key noun (e.g.,ROI) — pill uses--card-peachor--card-lavenderbackground with navy text. - 3–4 cards below in a horizontal row, mixing:
- one photo card with a subtle tint overlay,
- one coral→peach gradient card with the hero stat (
+47%), - one cool lavender→blue gradient card with a secondary stat,
- one navy / peach neutral card for small numbers.
- Cards are
border-radius: 24px, 4:3 aspect, label top-left, number/stat bottom-left. - Tiny icon cluster top-left of gradient cards (e.g., property-pin chips overlapping).
Don't
- Don't use the coral for headline text. It lives inside gradient cards.
- No more than one gradient direction per slide (either 135° coral→peach OR 180° lavender→blue, not both on the same card).
- Don't put text over the photo area that's smaller than 16px — the imagery competes.
Best layouts: pill-headline-cards-row · product-gradient-grid · hero-photo-split.
Cross-theme don'ts (all 8)
- No emoji (SaaS trap).
- No hand-drawn SVG people (AI-slop).
- No "aggressive purple gradient" — bluehouse is the only theme allowed to gradient, and only peach/coral/lavender.
- No rounded left-border cards with a hex-shift accent (generic AI card).
- Invented metrics are forbidden. Use
—or a muted rectangle when the number doesn't exist yet. - The display face is a theme setting, not a slide setting. Never mix serif and Y2K in one deck.
Contributing a new theme
If replit.com/slides ships a new template you want reflected here, or you want to propose a fork theme, follow this procedure so colors stay honest (no memory guesses, no "looks about right").
1. Capture the source PNG
Screenshot the replit.com/slides card at 2× device pixel ratio (macOS: Cmd+Shift+4 on a HiDPI display captures 2×). Save as reference-<theme>.png. Crop to just the template card — exclude chrome and shadows.
2. Extract the dominant colors
# Install once (macOS): brew install imagemagick
magick reference-<theme>.png \
-resize 200x200 \
-colors 8 \
-unique-colors txt:- \
| tail -n +2 \
| awk '{print $3}' \
| sort -u
This quantizes to 8 dominant colors and prints their hex values. The top few will be surface / type / border; the rare one is usually the accent.
For a specific point (e.g. sampling the accent from a known pixel):
magick reference-<theme>.png -format "%[pixel:p{420,280}]" info:
3. Map to the 6-token palette
Every theme uses the same 6 tokens plus a display font. Fill in:
--bg surface (largest area, ≥ 50% coverage)
--fg type color (largest area inside text blocks)
--muted secondary text (~40% alpha feel)
--border hairline dividers, 1px
--accent chromatic accent (≤ 5% coverage — the rare color)
--font-display sans / serif / Y2K display — see the three allowed families in template.html
If the source uses two near-identical grays, collapse to one --border. Don't invent new tokens; every theme must map cleanly to this set so data-theme switching stays lossless.
4. Add the theme block
- Append a new
body[data-theme="<name>"] { … }block toassets/template.htmlin the theme tokens section. Mirror an existing block's token order. - Add the theme row to the
od.inputs.theme.valuesenum inSKILL.md(frontmatter). - Add a "When to pick" row to the pick-table in
SKILL.mdand to the table in this file. - Write a new
## <theme> — <name>section below (palette block + Do / Don't / Best layouts), matching the shape of the other eight. - Add a P1 theme-specific must to
checklist.md(one bullet describing the theme's non-negotiable visual tell). - Add a row to the reviewer screenshot-mapping table in the PR description so future contributors can reconcile drift.
5. Verify
- Render a one-slide example with the new theme and compare side-by-side with the source PNG. If the
--accentlooks off, re-sample with a larger-colorscount (try16) and pick the one whose coverage matches the source. - Add an
example-<theme>.htmltoexamples/if the new theme is visually contrasting from the existing four (helix / holm / atlas / bluehouse). Otherwise a preview viaexamples/README.md's instructions is enough.