Personal Website Builder

website-dev

Build the personal website a thoughtful person would make for themselves. It says plainly who they are and what they do, puts their real work on every screen, and looks like it belongs to them: not a portfolio theme, not the statistical average of every "Hi, I'm a passionate developer" site on the internet, and not an art piece that hides the work. The bar is the best hand-made personal sites of designers, developers, writers, photographers and researchers: quiet, specific, fast, and unmistakably one person's.

Scope: personal websites only. One person's portfolio, homepage, blog, CV site, academic page or link hub. A freelancer's site counts, because it is about one person and their work. A business, a shop, a product, a startup or an agency site does not. If the task is one of those, say that this skill is for personal sites and do not apply it.

This skill is one skill with its parts in assets/. The table below says which part loads when, what each part does during setup, and when the agent must write back into it. Three parts load every time. The rest load when the task touches them.

The files

File	Invoke	Initial setup	Read trigger	Update trigger
design-principles	Always	Never sets up. Read as written during setup; nothing in it is asked or changed.	Every time this skill loads, before the first design or code decision.	Never by the agent. Edit only when the user explicitly asks to change a principle. A dislike goes to design-dont-dos, not here.
design-dont-dos	Always	Runs whenever setup runs. Every direction, palette, font and component proposed during setup is checked against every row before the user sees it. Any reference site or trait the user dislikes in their setup answers becomes a user row at once. On an existing site, list the rows it already breaks.	Every time this skill loads, and again before anything visible on the site is written or changed.	Every time the user says they do not like something about the site (a colour, shape, layout, effect, word, font, motion, or a reference site). Append one row at the bottom in the same turn, before continuing the work. Every appended row is a user row.
users-design-system	Always	If there is no true design system, set it up first. No true design system means: the Direction row is not confirmed, or the colour and type tables have no confirmed rows. Then, before any design work, ask the setup questions from initial-setup. The user can also start setup at any time ("set up the design system", "start the look over"). If the user answers "you decide" or "set it up for me", run the research path. User answers become confirmed, research becomes proposed, values read from existing code become extracted. If a true design system exists, do not ask again: ask only about the rows the current task needs that are still empty.	Every time this skill loads. Its confirmed values beat every default in the other files.	Every time the user adds or changes anything in their design system (a colour, font, size, spacing step, radius, shadow, motion token, component rule, logo or monogram, imagery rule, voice rule). Update the row in the same turn and log the change. Also when setup extracts or researches tokens.
initial-setup	When: a new website or repo, the first run on a site, a redesign start, or users-design-system has no confirmed direction.	Runs the setup when any signal fires: (1) users-design-system has no true design system, (2) a new website or repo, (3) the user asks to set up or redo the design system, (4) a redesign starts. Asks the question rounds at once, in the first reply, before any design work. If the user says "you decide", "solve it" or "set it up for me", runs the research path instead. Skips when a true design system exists and the user did not ask.	At the start of the task, before any page or component is written.	When the user changes how a site must start (the questions, the stack, the tooling), or when a setup step proves wrong in practice.
design-directions	When: setup asks for the overall look, the research path runs, or the user asks to change the look of the site.	Runs when setup asks the direction question or runs the research path. The first setup question offers the 3 directions that fit the person best, plus "Research it for me". The research path starts from this catalogue, then searches for niche directions beyond it.	Before asking the direction question, and before any research into directions.	When research finds a direction not in the catalogue, add it. When the user picks or rejects a direction, log it. A rejected direction's defining trait also goes to design-dont-dos.
hero-design	When: the task builds, redesigns or reviews the home page or its first screen.	Runs when setup asks Q13 (only if the person has no work image or photo). The answer sets the hero's visual source in users-design-system.	At the screen-plan step, before the hero is built, and in the review.	When the user approves a hero, log it and write it to users-design-system. A disliked hero goes to design-dont-dos. A generated hero's prompt goes to its log.
visual-modules	When: the task plans a page or section, a site reads as bland, or the user asks for "more life".	Runs with the research path: each candidate names 2 to 4 modules.	At the screen-plan step, before any section is built, and in the review.	When the user likes a module, log it and add it to users-design-system. A disliked module goes to design-dont-dos. A module found in research goes in its catalogue.
motion-design	When: the task touches animation, transitions, hover or press states, scroll effects, loaders, page entrances, or anything that moves.	Runs when setup asks the motion question. The answer sets the motion dial in users-design-system. Not asked again once the dial is confirmed.	Before any motion code is written or reviewed.	When the user approves a motion pattern or changes a motion value: record it in its decisions table. A motion the user dislikes goes to design-dont-dos.
copy-writing	When: the task writes, rewrites or reviews any text visible on the site (the intro, bio, project write-ups, headings, links, alt text, meta tags).	Runs when setup asks the voice question. The answer sets the voice in users-design-system. Not asked again once the voice is confirmed.	Before the first word of copy is written, and again before handover.	When the user states a copy rule that applies beyond one string: add it to its user copy rules table. A disliked phrase or tone also goes to design-dont-dos. A voice rule goes to users-design-system.
review-gate	When: before handing over any page, section or component, and when the user asks to review or audit their site.	Never sets up. Not used during setup.	After the build, before the report to the user.	When the user finds a problem after handover that the gate missed: add a check to its user checks table, and add the problem to design-dont-dos.

What taste means here

Taste is not a style. It is a set of decisions made on purpose, for this person, where a model would otherwise take the default.

• Specific beats generic. Every personal site a model writes drifts toward the version that would fit anyone: "Hi, I'm [Name] 👋", "a passionate developer who loves crafting digital experiences", skill bars, a timeline, three project cards with GitHub buttons, a purple glow. Each of those is a decision nobody made. The specific has to come from the person: their work, their words, their photographs, their design system. Never from a style rule, and never invented.
• The work is the hero. A visitor comes to see what this person has made, written or found. Put the best of it on the first screen or one scroll away. Decoration (orbs, particles, 3D blobs, fake terminals, concept-demo widgets) is what fills a page when the work is missing.
• One person, one voice. A personal site sounds like someone, not like a recruiter's template. Short, plain, specific sentences in the voice the person chose. No self-praise: the work praises.
• Curate, do not archive. Three to six strong pieces beat thirty thumbnails. The best one leads and gets more room. The rest is one link away.
• Restraint is the luxury. One palette. One radius scale. One link style. One theme. Space used as a material. A site with fewer, better decisions reads as more considered.
• Alive, not bland. A site of text and greys is as generic as a site of glow. Give it colour: two matching colours, and one pop that makes them sing in the header and the hero only. Give it a designed hero and 2 to 4 visual modules: the person's work shown with craft, and form from the palette that claims nothing. Never a fake section to fill the space.
• Hierarchy you can see in a squint. Blur your eyes at the screenshot. One thing leads each screen: the name, the work, or the words.
• Type carries the person. Pick the face for this person, set it with tight display tracking, a readable body measure (about 65 characters), and real weight steps. For a writer the body text is the design.
• Rhythm, not uniformity. Let one project run long and another be two lines. Identical cards in a grid is the look of a theme.
• Motion answers, it does not perform. The intro arrives once, one designed moment earns its place, and every link answers the pointer. Nothing types itself out, spins or fades in on scroll because it can.
• Small and fast is a feature. A personal site loads in a blink, reads well on a phone, works without JavaScript, and still works in five years.
• The person picks the look, not the agent. A photographer, a poet, a backend engineer and an illustrator each deserve a different answer. The same request must not produce the same site twice.

The house rules

These win over everything in the assets except the user's own words and confirmed design system.

1. Personal sites only. One person and their work. Anything else is out of scope.
2. Set up before designing. If there is no true design system (the Direction row in users-design-system is not confirmed, or colour and type have no confirmed rows), run initial-setup first and ask the question rounds in the first reply. The user can also start setup at any time, or say "you decide" to have the agent research and propose the system. Never start a site on assumed taste.
3. Never glow, never pill-with-glow, never AI purple. The user banned these by name. No outer glow, neon, glowing orb, glowing border, or purple and violet gradient, on any surface, ever, unless the user's design system confirms it.
4. The ledger is law. Before writing anything visible, check it against design-dont-dos. A user row is never broken.
5. Listen and write it down. When the user says they do not like something, add the ledger row in the same turn, before fixing it. When the user names a colour, font or token, update users-design-system in the same turn. The skill must never make the same mistake twice for the same person.
6. Tokens, not values. Every colour, size, radius, shadow and duration comes from the design system, through one CSS variables block or theme. No raw hex in a component.
7. Show the real work. Real project images, real writing, real photographs of the person if they want one. Never a fake project UI made of grey boxes, never stock or AI images passed off as theirs. An open-licence or generated image is allowed only as hero atmosphere, after the user agrees for a generated one, and never shows the person or their work.
8. Invent nothing. No invented testimonials, clients, employers, awards, numbers or life story. Anything assumed is marked in the code and listed in the report.
9. The first screen says who and what at 1440x900 and at 390x844: the name, what they do in one line, and the way to the work or to contact.
10. Accessible by default. Contrast 4.5:1, a visible focus ring, alt text on every piece of work, 44px tap targets, reduced motion honoured. Never traded for looks.
11. Look before handing over. Run review-gate. Report what failed or was not checked first.

The three dials

After setup, three dials steer every layout, motion and density decision. Their values live in the user's design system (setup sets them; the user can change them in a sentence: "make it calmer", "more motion", "denser").

Dial	1 to 3	4 to 6	7 to 10
Variance (symmetry to asymmetry)	Centred, symmetric, one column of text. Writers, academics, CV sites.	Left-aligned reading, a split intro, mixed image sizes, varied section layouts.	Asymmetric grids, large empty zones, type set as image, editorial breaks. Single column below 768px at any level.
Motion (still to cinematic)	Hover and press states only.	Default. Plus the intro entrance and one designed moment.	Only when the person's own work is interactive or moving (creative coding, motion design, games, film). Never scroll reveals on every element at any level.
Density (gallery to index)	Few words, big images, lots of space.	A balanced personal site.	An index: lists of writing, projects or links in tight rows, hairlines, tabular dates.

Baseline when setup did not set them: Variance 5, Motion 4, Density 3.

The person	Variance	Motion	Density
writer, blogger, academic, researcher	2 to 4	1 to 3	4 to 7
developer, engineer	3 to 6	2 to 4	3 to 6
designer, art director, illustrator	6 to 9	4 to 6	2 to 4
photographer, visual artist, filmmaker	5 to 8	3 to 6	1 to 3
creative coder, motion designer, game maker	7 to 10	6 to 9	2 to 4
job seeker, CV site	2 to 4	1 to 3	4 to 6
link hub, personal homepage	3 to 6	2 to 4	3 to 5

The run

1. Load the three always-on files. Note every user row in the ledger and every confirmed row in the design system.
2. Setup if house rule 2's condition holds: ask the question rounds from initial-setup, or run its research path if the user says "you decide". Write the results into the design system with their status.
3. Design read. One line before any code: "Reading this as: <kind of personal site> for <who it must reach>, with a <direction> language, leaning toward <stack>." Then the site's one goal (get hired, get commissions, be read, be found) and its one main action (design-principles section 1).
4. Write the words first, with copy-writing: the one-line intro, the short bio, a sentence for each piece of work. Layout serves the words.
5. Plan the site as screens. Start with the hero line from hero-design: composition, visual source, palette, action. Then one line per section: its one idea, its image, its layout family, its height, its module from visual-modules if any, and any motion with its purpose. Check the plan against the layout rules and the ledger before building.
6. Build from tokens. Semantic HTML, the design system's variables, real images, every state.
7. Motion last, with motion-design, and only what the plan named.
8. Review with review-gate: screenshots at 1440, 768 and 390, the ledger sweep, contrast, focus, reduced motion.
9. Report. Failed or unchecked items first. Then: assumed facts, missing images and write-ups, and every row written to the ledger or the design system during the task.

How the skill learns

The skill gets better for this person with every task. Three writes keep it honest:

• A dislike becomes a ledger row. "I hate that pill", "too dark", "this font feels cheap", "not that kind of animation": each becomes a new row at the bottom of design-dont-dos, and is fixed on the site in the same turn.
• A choice becomes a design system row. "Use #1F4D3A as the primary", "links are underlined", "set my name in Söhne": each becomes a confirmed row in users-design-system and goes into the token file.
• A miss becomes a check. A problem the user caught after handover becomes a check in review-gate, so the next handover catches it.

Never write these silently. Say in one line what was added and where.

Never

The full list is the ledger. These are the ones that sink a personal site at a glance:

• Glow of any kind, glowing pill containers, purple or violet gradients, gradient name text, blurred orbs, particle or starfield backgrounds.
• "Hi, I'm [Name] 👋", "passionate", "crafting digital experiences", typewriter roles, a 3D blob hero.
• Skill bars, a wall of tech logos, the alternating timeline, identical project cards with tech pills and GitHub buttons.
• Glassmorphism, the floating glass pill nav, heavy shadows, one huge radius on everything.
• Fade-up on every section, bounce easing, magnetic buttons, custom cursors, a name-spelling preloader.
• Emoji, em dashes, invented testimonials and round numbers ("50+ projects"), stock or AI images passed off as the person's work.
• On a one-page site: header links to its own sections, "Back to top", and buttons that scroll to content already below. The header holds the name and external links only.
• Self-labels and filler chrome: "PERSONAL SITE", "[NAME] · 2026", a period after the name, a copyright line, a footer that repeats the intro.
• Invented explainer widgets and concept demos (sliders, fake records, status dots), and side panels that repeat other content. A panel only shows or links to real work: a GitHub repo, a real design, a live embed of the person's own project.
• A site in one colour plus greys, a hero that was never designed, a page with no visual module.
• Unicode arrows (↗ ↘ →) or hand-drawn SVGs as icons. Icons come from a free icon library (Hugeicons free set first).

Default stack

If the person names no stack and does not have an existing site (for example, they say "just build me a website"), use this stack. Do not ask about it, and do not add a framework or a build step.

• HTML5 for the content.
• CSS3 for the design and the phone layout.
• Vanilla JavaScript only where the site needs interaction.
• GitHub Pages for hosting.

How to apply it:

• Files: index.html at the root, one styles.css (the design system tokens in one :root block), script.js only if needed, an images/ folder, a 404.html, and one .html file per extra page.
• No npm, no bundler, no framework. The site opens by double-clicking index.html.
• Icons: inline SVG copied from the Hugeicons free set (or the library in users-design-system). No icon font, no icon CDN script.
• Use relative paths, so the site works both at username.github.io and at username.github.io/repo-name/.
• Add an empty .nojekyll file at the root, so GitHub Pages serves the files exactly as written.
• A custom domain goes in a CNAME file at the root.
• If the person names a stack, or the site already has one, use theirs instead.