page-design
Use when the user asks to restyle, recolor, re-theme, change the look, use their brand or design system, or redesign their pages or resume template ("make it navy and gold", "bigger text", "less motio
SKILL.md.claude/skills/page-design/SKILL.md
GitHubPage design
All the user's pages share one system so they read as a set, and one file sets its look: profile/design.md. It has a design block (pages) and a documents block (resume and cover letter). The resume and cover-letter templates the user's look applies to are their own copies in profile/templates/; the app's templates/*.html always stay on the default look and are never edited (so app updates and git pull never clash with a theme). Pages only ever read CSS custom properties from their token block; applying a theme rewrites that block and the fonts line, never the page's structure or data. Change the theme, not individual elements.
Each page has one job, shown top-left, and a few layouts (one file per page; the layout is the data-layout attribute on its <html> tag, set from profile/design.md; see "Layouts" below):
- Dashboard, "what do I do today":
overview(default: a Today hero card with the next due items and one suggested move, KPI tiles with sparklines, weekly-goal rings beside the funnel, a compact board),board(kanban columns first, slim KPI strip, the due list as a side rail) ortimeline(every open job on one date axis: how long since applying, the next step, the deadline, a today line; the dates also written out under each row). - Flashcards, "practice this card":
flip(default: one big centered card, deck as a segmented control, a session bar, rating row with intervals, an end-of-session summary),list(a study sheet: the deck as an accordion with inline rating; good for skimming and print) orcards(cheat cards: every card as a fold-in-half cue card, question beside notes, with cut and fold lines; prints as cards to cut out). - Interview brief, "what to say":
sheet(default: header band with who/when/where chips and interviewer monograms, two columns, prints on one page) ordetailed(long-form screen read with a sticky section nav; prints as the same one-page sheet). - Portfolio, "who is this and how do I reach them":
profile(default: hero card with monogram and contact buttons, highlight tiles, experience as a timeline),editorial(no cards: big name, "label | content" rows, most print-like),bento(a grid of mixed tiles; phone shows them in reading order) orcolumn(one column at every width, phone first: a centered contact card like a link page, then the whole story, big tap targets). - Resume and cover letter (ATS):
classic(default),modern,compact; the cover letter's letterhead follows the resume's layout. Designed resume:sidebar(default),headlineorportrait(a centered header with a slot for a photo, which stays empty unless the user explicitly asks for one; ground rule 4). - More document templates (ATS, one look each, themed by the documents block):
cv-academic-template.html(academic CV: no page limit, name and page number on every page),resume-federal-template.html(US federal jobs on USAJOBS: two pages at most, hours per week and series/grade per job) andcv-europass-template.html(Europass-style CV for European jobs that ask for one: dates in a left column, CEFR language levels, an optional photo slot that stays empty unless the user asks).tailor-resumepicks one when the job calls for it; their comments hold the sources and rules.
Visual language (all pages): encourage, don't scold (a new week shows "Not started", never "Behind"; an empty page shows a labelled sample preview and one next step); one hero surface per page at most (the accent gradient); inline SVG line icons from the page's own sprite (24px grid, 1.75 stroke, currentColor, aria-hidden unless standalone); mono uppercase only for section kickers (.eyebrow, one per section), dates and counts in the body font (.meta); big numbers in the heading font with tabular figures; charts drawn with --chart-* (never status colors) and always with a text equivalent. Components and their rules are in references/page-building.md.
Read the matching file before you change anything, not after:
- Colors, contrast, a user's brand color, status colors:
references/color.md. - Fonts, sizes, spacing, layout, icons, print templates:
references/type-and-layout.md. - Anything that moves:
motion.md(rules first, then recipes). - Bringing in the user's brand or design system:
references/importing-a-design-system.md. - Changing a page's structure, markup, CSS, scripts or a print template (not just its theme or layout):
references/page-building.md(page contract, color and type systems, Tailwind v4 pitfalls, components, layout, motion, interaction, print). - When you're done: run
page-review(.claude/skills/page-review/SKILL.md).
The theme (profile/design.md)
- Presets (each a measured token set):
default(Bricolage Grotesque headings over Source Sans 3, warm stone neutrals, deep teal accent, 10px corners),modern(Inter throughout, violet, softer corners),minimal(IBM Plex, near-monochrome; color only for status),high-contrast(112.5% text, 7:1 text contrast, Lexend for headings and text, a font built for reading ease, plain grays, motion off),editorial(warm editorial: Fraunces headings over Source Serif 4, warm paper tones, deep plum, small corners),calm(calm pastel: DM Sans, soft blue-gray, muted periwinkle, round corners, roomy spacing, motion off),bold(bold creative: Space Grotesk over Work Sans, vivid magenta, sharp corners), andbrand(the user's own values, filled in frombased_on, defaultdefault). A fresh install andtemplates/blank/usedefault. - Values in the
designblock override the preset:accent,accent_dark,neutral(hex),font_heading/font_body/font_mono(Google Fonts or system fonts only),base_size(never below 100%),density(compact/comfortable/spacious, which scales Tailwind's spacing),radius,motion(full/reduced).sourcerecords where the look came from. Blank means "the preset's value". When switching presets, clear the override lines unless the user wants to keep them. - Documents block:
font(ATS-safe list only; every font on it reads back cleanly inmake-pdf's parse check. The app ships Garamond (EB Garamond), Source Sans 3, Roboto and Open Sans as static files, which PDFs embed as ordinary TrueType text; Lato loads from Google Fonts, so offline it falls back to Arial),accent(name, section headings and rules only; darkened automatically until it reads on white),density(compact/standard/roomy),paper(LetterorA4, from the user's country;tailor-resumestill follows the job's country per application). - Layout keys (blank = the default, listed first): design block
layout_dashboard(overview/board/timeline),layout_flashcards(flip/list/cards),layout_brief(sheet/detailed),layout_portfolio(profile/editorial/bento/column); documents blocklayout_resume(classic/modern/compact; the cover letter follows it) andlayout_designed(sidebar/headline/portrait). A layout is independent of the preset: switching presets keeps the layouts. An unknown value stops apply-theme with anerror:naming the allowed values.
Layouts (switch a page's layout)
"Switch my portfolio to bento", "make the dashboard a board", "a more compact resume":
- If they haven't seen the options, preview them first:
node .claude/skills/page-design/scripts/apply-theme.mjs --preview --layouts portfolio(ordashboard,flashcards,brief,resume,cover-letter,designed,academic-cv,federal-resume,europass-cv,documentsfor all the documents, several comma-separated, orall) writespages/.preview/<page>-<layout>.htmlfor every layout of that page, with sample content in their current theme, and prints the paths; their pages don't change. Open them as in step 5 of "Change my theme" below. Describe each in one line (the list above). - Show the one-line change (
layout_portfolio: bento) inprofile/design.mdand get an OK; edit only that line. - Run
apply-theme.mjs. It rewrites only thedata-layoutattribute (with the token block) inpages/*.html, everyjobs/*/interview-brief.html(briefs sharelayout_brief), and the user's template copies inprofile/templates/(created fromtemplates/the first time a layout or theme makes them differ). Resumes and letters already made for a job keep their layout; new ones copy the template and inherit it. - Run
page-reviewon that page in the new layout (light and dark, phone and desktop width; resumes: page count andparse: ok), then republish it if it's published (pages skill).
- After an app update changed a template (
/updateor agit pull),apply-theme.mjs --regenerate <name,...|all>rebuilds the user's copy inprofile/templates/from the new app template plus their theme (carrying the Custom region over) and keeps their earlier copy as<name>.previous.html. An older.previous.htmlthat differs (say, edited by hand) is never overwritten: it moves to the first free<name>.previous-2.html,-3, … and therefreshed:line names it. Relay those lines; offer to carry hand edits over. - A page made before layouts existed has no
data-layouton its<html>tag and only one look: offer to bring it up to date first (pages skill, "Bring a page up to date"). - Bespoke tweaks ("make the hero taller only on my portfolio"): never edit the page's own CSS or the token block. Put the rule between
/* ---- Custom ---- */and/* ---- End custom ---- */(the end of the page's first<style>; templates have the same region), scoped with:root[data-layout="bento"]when it's for one layout, using tokens only (no raw colors, fonts or sizes). apply-theme and--regeneratekeep that region as it is; a page refresh fromtemplates/blank/must copy it over by hand.
Change my theme / use my brand (any time)
- Ask what they want in one question if it isn't clear: a preset ("show me the looks"), a tweak ("bigger text", "navy accent"), or their brand ("use my brand / design system / website colors"). For a brand, follow
references/importing-a-design-system.md.- Two colors named ("navy and gold"): the system has one accent color (buttons, links, highlights), so the meaning of color stays clear. Use the first color (or the one they choose) as
accent, and say in one line what happens to the other: "Pages use one accent color, so I used navy; gold isn't used." Never drop a color silently, and never invent a second accent.
- Two colors named ("navy and gold"): the system has one accent color (buttons, links, highlights), so the meaning of color stays clear. Use the first color (or the one they choose) as
- Show the user the exact lines you'll change in
profile/design.mdand get an OK (it's their profile). Then edit only those lines. - Apply it:
node .claude/skills/page-design/scripts/apply-theme.mjs. It resolves the theme, measures every text pair in light and dark (and the print colors on white), fixes failing colors by adjusting lightness only, then rewrites the token block, fonts line anddata-layoutattribute inpages/*.htmland everyjobs/*/interview-brief.html, and the theme block of the user's template copies inprofile/templates/(the two ATS templates' document block, the designed resume's block and fonts line). The first time the theme makes a template differ from the app's copy, it creates the user's copy there (created:line); a template that already matches the app's copy needs none. It never touchestemplates/(the app's copies andtemplates/blank/), data blocks, or resumes already made for a job; only this skill re-themes pages (an app update never does).adjusted:/note:lines: tell the user in one plain line ("Your orange was too light for white button text, so buttons use a deeper orange.").error:(nothing was changed): fix the value it names inprofile/design.mdand run it again.--checkcompares without writing;--printshows the contrast table and block;--preset <name>tries a preset without editing design.md.
- Run
page-reviewon one page in light and dark, then tell the user what changed and that every page follows it. Republish published pages (pages skill). - Preview before choosing:
node .claude/skills/page-design/scripts/apply-theme.mjs --previewwrites a sample dashboard (sample data, not theirs) in every preset, and theirs, topages/.preview/and prints the paths. Their pages and templates don't change. Show them: if the built-in browser can open files from the computer, open them there; if it can't (some versions only open web addresses), don't keep trying: give the user the paths to double-click, or on a Mac runopen <file>. The previews can be deleted afterwards. Without Node, describe the presets in one line each instead.
Without Node (node not found, e.g. Codex on Windows): never ask the user to install anything; follow references/without-node.md (presets, fonts, sizes, layouts and the documents block by hand from presets/<name>.md; custom colors wait for Node).
Audience rules (who sees what)
| Output | Audience | What the theme may change | Always enforced |
|---|---|---|---|
Resume, cover letter, academic CV, federal resume, Europass-style CV (the user's copies profile/templates/*-template.html, made from templates/) |
Applicant tracking systems, recruiters | Documents block only: font from the ATS-safe list, accent on the name, section headings and rules, density, paper, layout (classic / modern / compact) |
One column, real text, standard headings, body text near-black (#111), no images/icons/tables, length set by tailor-resume, PDF parse check |
Designed resume (profile/templates/resume-designed-template.html, made from templates/) |
A person (emailed, shared), creative fields | The full page theme, printed light; layout sidebar, headline or portrait |
Always alongside the ATS version, never instead; same checked text; real selectable text; no images of text, no hidden or tiny text; text ≥ 4.5:1 on white; parse check passes; a photo only when the user asked for one |
Portfolio (pages/portfolio.html) |
Public: their personal brand | Everything | Contrast floors in both themes, reduced motion respected, resume-level facts only, no NDA material |
| Dashboard, flashcards, interview brief | Private | Everything | Contrast floors, text never below 100%, reduced motion respected (device setting or motion: reduced), the brief prints in light colors on one page (sheet) or two (detailed) |
| Panels (Outbox, Pipeline, …) | Terminal | Nothing: they follow the user's terminal theme | page-review's panel checks |
Rules for every page (details in references/page-building.md)
- Never edit a page's token block or fonts line by hand; change
profile/design.mdand runapply-theme.mjs. - To change content, rewrite only the page's JSON data block, with every
<written as the six characters\u003c(the portfolio is plain HTML instead: edit text, escaping<,>,&). Never paste imported text into the page's HTML or script. - Libraries and fonts load from
templates/assets/, so pages work offline (only Lexend and fonts a brand brings come from Google Fonts; details inreferences/page-building.md, "Offline assets"); never add a remote script or stylesheet, and keep each library line exactly asapply-theme.mjswrites it. - Facts come only from the user's files; the portfolio is public: resume-level facts only, never NDA material.
- Bespoke CSS goes only in the
/* ---- Custom ---- */region (see "Layouts"). - If you change a page's structure, read
references/page-building.mdfirst and apply the same change to its blank copy.