Homepage Creation Skill v2.0
Origin: The actual output was judged as "uncool." Then, I opened and measured a website created by another AI service on the same subject, and turned the good points into my own procedure. It's not about preference, but about actual measurements and what I was neglecting at that time.
What You Need to Know First (This is the Basis for Everything)
What I learned from the comparison was that the biggest difference lay in the preparation before starting to build. The most effective move was the following:
Before you start writing, verbalize your design thesis and fix it in a file with negative constraints.
The competitor's site had a short description at the top of the stylesheet stating the policy of "how to show" and "what not to do."
(The writing method and types are in reference/DESIGN_THESIS.md. The format to use in Step 0 is also there.)
My failed version was exactly the "repetition of centered, uniform cards" which falls under that "what not to do." I knew that if left unchecked, it would always fall into that trap, and I had prohibited it in advance. That alone made the difference.
These 6 Rules Are Everything
- Write the thesis before coding and fix it in a file. Declarations in conversation fade away.
- Include at least 2 negative constraints. Without explicitly prohibiting defaults, you cannot break away from them.
- Use two typefaces: serif + sans-serif. Sticking to one typeface makes everything look like an admin panel interface.
- Do not arrange centered, uniform cards. Divide asymmetrically. Place at least one dark band.
- Zero images is not allowed. If you have no materials, generate them. If generated, clearly mark as "image."
- It is not complete until rendered and inspected with your own eyes. "It's not broken" is not an evaluation.
⚠ Actual Past Incidents (3 Cases)
Incident 1 — Mistaking "Not Broken" for "Good"
I checked for horizontal scrolling and whether tables fit, then shipped it. All checks were for failures, with zero evaluations of appeal. The result was a deliverable with no demerits but also no merits.
Detection method: When the verification log only contains checks like "◯◯ does not appear" or "◯◯ fits," this incident is occurring.
Incident 2 — Accepting the Constraint of No Materials Without Considering Workarounds
"Cannot obtain real photos" → settled on "no images." I could have used image generation but didn't. Sincerity is not an excuse to abandon images. Mitigate with annotations.
Detection method: If you drop an element included in the request (e.g., "photos too") from the deliverable, always suspect this case.
Incident 3 — Visual Glitch Found After All Machine Checks Passed
After verify.py turned all green, I looked at it zoomed to 25% and found the h1 was breaking mid-word
(e.g., "Freshly baked, deli─\nvered / ." where the last 1-2 characters fall to the next line. The example is fictional).
This is a type of defect that numerical checks can never catch.
Countermeasure: Do not skip the visual inspection in §5.
verify.pyautomatically outputs images for visual review. Be sure to read them.
§1 Procedure
Step 0. Write the Thesis (Before HTML, Mandatory)
Read reference/DESIGN_THESIS.md. It contains 6 types and a catalog of negative constraints.
Choose a type → Adjust the name to match the subject → Select at least 2 negative constraints →
Replace at least one with a subject-specific constraint → Write it into the top comment of template.html.
Design: "◯◯◯◯" — {One sentence of visual statement}.
Visual rules: {Negative constraint 1}; {Negative constraint 2}; {Negative constraint 3}.
Information rule: {Rule for information placement}.
Then, declare it once to the requester. If discomfort arises here, you can stop before writing.
◆ Design Policy
Thesis: "◯◯" — {Statement} / Forbidden: {At least 2 negative constraints}
Color scheme: Satoyama (green) / Indigo / Pottery ← one of these, or new
Font sizes: h1=70px at 1280px / h2=51px / Margin: sections top/bottom 120px
Images: {Real photos / N generated illustrations (with "image" annotation) / Diagrams}
Structure: hero → {blocks} → dark band → facts table → closing
Step 1. Gather Facts (When the Subject Exists)
- Priority: official databases. The corporate number publication site, industry-specific licensing/certification publication systems (run by national or local governments). These rank higher than industry portals, and often license numbers and certification numbers can be retrieved. Example (fictional): The certification number for "◯◯ Classroom in Midori Town," which only had a name and phone number on the industry portal, was confirmed on the local government's publication page ── this is how you use it.
- If sources conflict, honestly write both with a note saying "difference in notation." Do not silently favor one.
- If there are zero reviews, do not create a reviews section. Never fabricate.
Step 2. Prepare Materials (Do Not Proceed with Zero Images)
Consider in order, and do not finalize as "no images" until you can write a reason why they cannot be obtained.
- Get real photos from the requester
- Generate (If you have access to tools for creating images, use them) + Always add a source annotation
- Substitute with diagrams, charts, data visualizations
- Rely solely on typography and color surfaces (= make it clear that this is an intentional choice)
Style specifications and prohibitions are in reference/DESIGN_SYSTEM.md §6. Do not generate human faces.
After generation, compress for the Web (achieved: 7.4MB → 566KB. Do not output at 1.8MB per image).
Step 3. Assemble
assets/satoyama.css … link it directly (switch color scheme via `body` class)
assets/template.html … replace all {{ }}
Always keep the asymmetric hero and the dark band. Layout for each block is in reference/DESIGN_SYSTEM.md §5.
⚠ h1 must be within 7 characters per line. Exceeding causes auto-wrapping breakage (Incident 3).
Step 4. Measure
python ~/.claude/skills/homepage/verify.py path/to/index.html
Measures: presence of thesis, number of negative constraints, font sizes, margins, image count, typeface separation, dark bands, structural repetition,
and overflow at 3 widths. Outputs images for visual review into _review/.
Step 5. Inspect Visually (Cannot Be Skipped or Replaced by Machine)
Be sure to read the _review/review-25percent.png and review-desktop.png output by verify.py.
- Look at it zoomed out — Does contrast remain? If everything looks like the same gray band, the dark band or margins are insufficient.
- Read only the headings — Do they make sense? If they are just a list of table-of-contents words, it violates R-11.
- Look at the first screen alone — Does it convey "whose, what place this is" without scrolling?
- Look for breakage — Heading wraps, overflow, missing images. Incident 3 can only be caught here.
- Verbalize the good and bad in one line. "It's not broken" is not an evaluation. Do not ship without being able to verbalize.
§2 Actual Measurement Benchmarks (Determined by Comparison with Other AI Outputs)
| Item | Benchmark | Past Failed Value |
|---|---|---|
| Thesis in file | Mandatory | None |
| Number of negative constraints | ≥2 | 0 |
| h1 actual rendering (1280px) | ≥56px (recommended 70px) | 46px ← capped by clamp() upper limit |
| h2 actual rendering (1280px) | ≥40px (recommended 51px) | 30px |
| Section top/bottom padding | ≥100px (recommended 120px) | 76px |
| Image count | ≥1 (recommended 4) | 0 |
| Typefaces | Different typefaces for headings and body | 1 typeface |
| Full-width dark band | ≥1 location | 0 |
| Structural variety | More than half of main blocks have different structures | All identical |
⚠ Color count did not make a difference. The failed version had 15 color tokens, more than the superior version's 10. What matters is thesis, typefaces, font sizes, margins, images, and copy.
§3 Requirements (Do Not Ship Unless Met)
- R-1 Separate typefaces for headings and body. For Japanese, make serif the first choice for headings.
- R-2 Actual rendering at 1280px: h1≥56px / h2≥40px. Measure whether
clamp()upper limit is capping. - R-5 Desktop section top/bottom padding ≥100px. Information volume is not an excuse for density.
- R-7 Zero images is not allowed (must go through the 4 steps in Step 2).
- R-8 For generated images, clearly state "Image (not actual ◯◯)" in a visible position.
- R-9 Not all sections should follow the same pattern. Include at least one full-width dark band.
- R-11 Do not use functional labels for section headings. Move table-of-contents words to
.label. - R-13 Do not omit accessibility features (skip-link / visible focus / alt / reduced-motion).
- R-14 Fix the thesis at the top of the file and write at least 2 negative constraints.
- R-15 Read the rendered image with your own eyes, verbalize the good and bad in one line, then ship.
§4 Content Prohibitions (When Handling Real Shops/Facilities)
- Do not fabricate reviews or customer testimonials. If zero reviews, write "0 reviews" and just place a recruitment link.
- Do not pretend that real photos exist when they don't. Always annotate generated images.
- Do not copy photos or text from other sites. Embedding (e.g., official Instagram embeds) is allowed.
- Do not promise results or improvements (especially for medical, welfare, or education). Stick to factual information.
- Only publish with the requester's permission. Do not publish pages representing real organizations without authorization. For practice/draft purposes, leave a comment at the top of the file indicating this.
- When handling materials containing children, always confirm whether publication is allowed.
§5 Files
~/.claude/skills/homepage/
├── SKILL.md This procedure document
├── verify.py Measurement inspection + visual review image output
├── assets/
│ ├── satoyama.css Design system core, includes 3 color schemes
│ ├── template.html Skeleton (with thesis frame at the top)
│ └── placeholder.svg Placeholder image to make it work even without materials
└── reference/
├── DESIGN_THESIS.md ★ Most important. Thesis writing method, 6 types, negative constraint catalog
└── DESIGN_SYSTEM.md Basis for each value, 10 block types, how to craft copy
Reading order when starting: DESIGN_THESIS.md → DESIGN_SYSTEM.md → template.
Mimicking only the numbers will not reproduce the types. The thesis comes first.
§6 When Not to Use This System
Admin panels, dashboards, LPs centered on comparison tables, time-sensitive announcements, game UI, projects with existing brand guidelines. Serif headings and wide margins would have the opposite effect here.