waitsec 0.5.0 → 0.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.cursor-plugin/plugin.json +1 -1
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/skills/waitsec/references/anti-overengineering.md +27 -15
- package/skills/waitsec/references/ask-first.md +25 -13
- package/skills/waitsec/references/debug-first.md +25 -13
- package/skills/waitsec/references/small-diff.md +25 -13
- package/skills/waitsec/references/verify-first.md +25 -13
- package/skills/waitsec-code/SKILL.md +87 -12
- package/skills/waitsec-pagemaker/SKILL.md +420 -8
- package/skills/waitsec-pagemaker/references/about-me.md +39 -0
- package/skills/waitsec-pagemaker/references/article-single.md +64 -0
- package/skills/waitsec-pagemaker/references/blog-index.md +46 -0
- package/skills/waitsec-pagemaker/references/contact-page.md +41 -2
- package/skills/waitsec-pagemaker/references/landing-page.md +68 -0
- package/skills/waitsec-quality/SKILL.md +95 -16
- package/skills/waitsec-ui/SKILL.md +74 -17
|
@@ -1,24 +1,160 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: waitsec-pagemaker
|
|
3
|
-
description: "Web page architect
|
|
3
|
+
description: "Web page architect for AI coding agents. Detects the project stack, then produces clean, mobile-first, SEO and GEO ready pages with valid Schema.org data, responsive navigation, and zero visual slop."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# waitsec-pagemaker: Clean Web Page Architect
|
|
7
7
|
|
|
8
8
|
You operate under the **waitsec-pagemaker** engineering discipline. This skill guides the agent in designing, structuring, and building complete web pages from scratch. It works hand-in-hand with [`skills/waitsec/SKILL.md`](../waitsec/SKILL.md) to keep code lean, secure, and free from AI design slop.
|
|
9
9
|
|
|
10
|
+
Before writing a single line of markup, always run the Project Recon in Part 0. It tells you which framework, template engine, styling system, and icon library are already in play, so you extend the project instead of fighting it.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Generation Contract (Mandatory)
|
|
15
|
+
|
|
16
|
+
Treat this section as the prompt you must satisfy every time you generate a page. These are generation-time rules, not documentation notes. Apply all of them to the actual output, and if one cannot be satisfied, stop and tell the user instead of shipping something that violates it.
|
|
17
|
+
|
|
18
|
+
1. **Recon before markup.** Run Part 0, then state the detected stack, template engine, styling system, load method, version, and icon library in one short block.
|
|
19
|
+
2. **Follow the project.** Use the framework, template syntax, and styling system that already exist. Never add a second CSS system. Ask before switching a native CSS project to a framework.
|
|
20
|
+
3. **Install with the right method.** Tailwind with an existing build step installs through npm. Tailwind in a static project uses the CDN unless the user asks for a local install. Bootstrap and other requested frameworks install locally.
|
|
21
|
+
4. **Every generated page includes JSON-LD.** Add a valid Schema.org block in `<head>`, with the type matched to the page (see Part 8). No page ships without structured data.
|
|
22
|
+
5. **Icons only from a library.** Use the project's existing icon library, or Lucide from CDN as the default. Never use an emoji as an icon. Never hand-write inline SVG markup. Never use an image as a UI icon.
|
|
23
|
+
6. **No em dash and no en dash.** Use colons, commas, periods, parentheses, or plain hyphens in every word of the output.
|
|
24
|
+
7. **No emoji anywhere.** Not in headings, body copy, buttons, badges, alt text, or metadata.
|
|
25
|
+
8. **Interaction follows the UX rules.** Confirm actions sit on the right on desktop and at the bottom of the stack on mobile, with Cancel before Save. Design loading, empty, error, and success states.
|
|
26
|
+
9. **The navbar must be responsive.** A working menu button on mobile, a solid sticky background, 4 to 5 primary links, and a visible active and focus state.
|
|
27
|
+
10. **Meet the SEO and GEO bar.** One H1, a unique title and meta description, a canonical URL, Open Graph tags, and answer-first content that machines can quote.
|
|
28
|
+
11. **Finish with the Pre-Flight Checklist.** Do not report the page as done until every box is checked.
|
|
29
|
+
|
|
10
30
|
---
|
|
11
31
|
|
|
12
32
|
## Operating Mode & Role
|
|
13
33
|
|
|
14
|
-
When you are asked to build a new page, template, or screen, act as an experienced product designer and clean frontend engineer. Build pages where every section, color, and spacing choice has a real purpose.
|
|
34
|
+
When you are asked to build a new page, template, or screen, act as an experienced product designer and clean frontend engineer. Build pages where every section, color, and spacing choice has a real purpose. Read the existing project first, follow its conventions, and only then generate markup.
|
|
15
35
|
|
|
16
36
|
## Activation Triggers
|
|
17
37
|
|
|
18
38
|
Activate this skill whenever:
|
|
19
39
|
- The user asks for a complete new page (for example: "build a landing page", "make a contact page", "create a blog template", "make an about me page").
|
|
20
40
|
- Structuring multi-section web views or routes (`/`, `/about`, `/contact`, `/blog`, `/blog/[slug]`).
|
|
21
|
-
- Writing layout containers, responsive grids, and design themes.
|
|
41
|
+
- Writing layout containers, responsive grids, navigation bars, and design themes.
|
|
42
|
+
- Adding SEO metadata, Open Graph tags, or Schema.org structured data to a page.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Part 0: Project Recon (Run This First, Every Time)
|
|
47
|
+
|
|
48
|
+
Never generate a page blind. Spend the first minute reading the project, then state what you found. Recon is read-only: do not install or change anything until you have reported your findings.
|
|
49
|
+
|
|
50
|
+
### 1. Detect the Framework
|
|
51
|
+
|
|
52
|
+
Look for these markers in the project root and report the result in one line:
|
|
53
|
+
|
|
54
|
+
| Marker found | Framework |
|
|
55
|
+
| :--- | :--- |
|
|
56
|
+
| `artisan`, `composer.json` with `laravel/framework`, `app/`, `routes/web.php` | Laravel (PHP) |
|
|
57
|
+
| `package.json` with `next` | Next.js (React) |
|
|
58
|
+
| `package.json` with `nuxt` | Nuxt (Vue) |
|
|
59
|
+
| `package.json` with `vite` and no SSR framework | Vite SPA (React, Vue, or Svelte) |
|
|
60
|
+
| `package.json` with `@sveltejs/kit` | SvelteKit |
|
|
61
|
+
| `manage.py`, `settings.py` | Django |
|
|
62
|
+
| `config/routes.rb`, `Gemfile` with `rails` | Ruby on Rails |
|
|
63
|
+
| `wp-config.php` | WordPress |
|
|
64
|
+
| Only `.html` files, no framework files | Native or static site |
|
|
65
|
+
|
|
66
|
+
If two markers conflict, or none are found, say so plainly and ask the user which stack to target before continuing.
|
|
67
|
+
|
|
68
|
+
### 2. Detect the Template Engine
|
|
69
|
+
|
|
70
|
+
Check how views are written, then follow that exact syntax:
|
|
71
|
+
|
|
72
|
+
- Blade (`.blade.php`) for Laravel, using `{{ }}`, `{!! !!}`, `@if`, `@foreach`, `@extends`, `@section`.
|
|
73
|
+
- Twig (`.twig`), EJS (`.ejs`), Pug (`.pug`), Jinja (`.html` with `{% %}`), ERB (`.erb`).
|
|
74
|
+
- JSX or TSX for React, SFC (`.vue`) for Vue, Svelte components for Svelte.
|
|
75
|
+
- Plain `.html` for static pages.
|
|
76
|
+
|
|
77
|
+
If the user names a specific file or template in the prompt, use that file and that syntax. If the mention is ambiguous (for example "make a page" in a project that has both Blade views and a Vite SPA), ask which one before writing.
|
|
78
|
+
|
|
79
|
+
### 3. Detect the Styling System
|
|
80
|
+
|
|
81
|
+
Find out what styles the project already uses before adding a single class:
|
|
82
|
+
|
|
83
|
+
- **Tailwind CSS:** look for `tailwind.config.js`, `tailwind.config.ts`, `tailwind.config.cjs`, `@tailwind base;` in a CSS file, `@import "tailwindcss";`, or a Tailwind CDN script tag. Record the major version, because v3 and v4 differ in config and syntax.
|
|
84
|
+
- **Bootstrap:** look for `bootstrap` in `package.json`, a `bootstrap.min.css` link, or a `bootstrap.scss` import. Record the version, because v4 and v5 differ.
|
|
85
|
+
- **Other frameworks:** Bulma, Foundation, Pico, UnoCSS, or any utility or component library. Identify and record it.
|
|
86
|
+
- **Native CSS:** plain `.css` files, `<style>` blocks, CSS modules, or SCSS and Sass without a utility framework.
|
|
87
|
+
|
|
88
|
+
For whichever system you find, also record **how it loads**: local build (npm or bundler import) or CDN, and the exact version when it is visible.
|
|
89
|
+
|
|
90
|
+
### 4. Decide the Styling Path
|
|
91
|
+
|
|
92
|
+
Follow this order and do not skip it:
|
|
93
|
+
|
|
94
|
+
1. **A framework already exists in the project:** use it. Never introduce a second CSS system.
|
|
95
|
+
2. **The user explicitly asked for Bootstrap or another framework:** use that framework, installed locally through the project's package manager.
|
|
96
|
+
3. **The user explicitly wants native CSS:** keep native CSS.
|
|
97
|
+
4. **Native CSS with no stated preference:** pause and ask one direct question: "Keep native CSS, or switch to Tailwind CSS?" Then wait for the answer.
|
|
98
|
+
5. **Tailwind chosen and the project has `package.json`:** install it through npm and wire it into the build. Do not use a CDN when a build step already exists.
|
|
99
|
+
6. **Tailwind chosen in a static project with no build step:** use the Tailwind CDN so the user gets a fast result. Only install locally if the user asks for it.
|
|
100
|
+
7. **Never mix two styling systems** (for example Tailwind utilities plus a Bootstrap grid) in the same page.
|
|
101
|
+
|
|
102
|
+
Report the final decision in one line: styling system, load method (local or CDN), and version.
|
|
103
|
+
|
|
104
|
+
### 5. Detect the Icon Library
|
|
105
|
+
|
|
106
|
+
- If the project already has an icon library (Lucide, Heroicons, Font Awesome, Bootstrap Icons, Phosphor, Tabler), use it.
|
|
107
|
+
- If the user asks for a specific icon set, use that set.
|
|
108
|
+
- Otherwise, default to **Lucide icons loaded from CDN**. Use the official Lucide browser script and `data-lucide` names, then call `lucide.createIcons()` after the page renders:
|
|
109
|
+
```html
|
|
110
|
+
<script src="https://unpkg.com/lucide@latest"></script>
|
|
111
|
+
<i data-lucide="save" class="w-5 h-5"></i>
|
|
112
|
+
<script>lucide.createIcons();</script>
|
|
113
|
+
```
|
|
114
|
+
- Never hand-write raw inline SVG markup. Never use an emoji as an icon. Never use a raster image as a stand-in for a UI icon.
|
|
115
|
+
|
|
116
|
+
### 6. Hard Content Rules
|
|
117
|
+
|
|
118
|
+
These rules apply to every generated page without exception:
|
|
119
|
+
|
|
120
|
+
- No emoji anywhere: not in copy, headings, buttons, or alt text.
|
|
121
|
+
- No hand-written inline SVG illustrations or icon markup.
|
|
122
|
+
- No em dash and no en dash. Use colons, commas, periods, parentheses, or plain hyphens.
|
|
123
|
+
- Icons come from the detected icon library or from Lucide CDN.
|
|
124
|
+
|
|
125
|
+
### 7. State Findings and Ask Only What Matters
|
|
126
|
+
|
|
127
|
+
Post a short recon summary before building, for example:
|
|
128
|
+
|
|
129
|
+
> Stack: Laravel 11 with Blade. Styling: Tailwind CSS v3, local build. Icons: none found, defaulting to Lucide CDN. Page: blog article template.
|
|
130
|
+
|
|
131
|
+
Then ask at most one or two questions, only about decisions that are expensive to reverse (styling system, template target, icon library). Everything else uses sensible defaults, and you state the defaults you chose.
|
|
132
|
+
|
|
133
|
+
### 8. Recon Pitfalls
|
|
134
|
+
|
|
135
|
+
#### 1. Assuming the Stack
|
|
136
|
+
|
|
137
|
+
* **The Bad Habit:** Generating a React component in a Blade project, or writing Tailwind classes in a project that uses plain CSS.
|
|
138
|
+
* **The Problem:** The page does not render, or it renders unstyled, and the user has to rewrite it.
|
|
139
|
+
* **Why It Fails:** The agent followed a template from memory instead of reading the project. Trust drops immediately.
|
|
140
|
+
* **Clean Fix:** Run Part 0 before writing markup. Match the framework, template syntax, and styling system you actually found.
|
|
141
|
+
* **The Waitsec Way:** Read the project first. The stack decides the syntax, not the model's habit.
|
|
142
|
+
|
|
143
|
+
#### 2. Mixing Two Styling Systems
|
|
144
|
+
|
|
145
|
+
* **The Bad Habit:** Adding Tailwind utilities on top of an existing Bootstrap page, or dropping Bootstrap classes into a Tailwind project.
|
|
146
|
+
* **The Problem:** Two spacing scales, two color systems, and two resets fight each other.
|
|
147
|
+
* **Why It Fails:** Spacing and colors drift, the bundle grows, and future changes become unpredictable.
|
|
148
|
+
* **Clean Fix:** Use the styling system already in the project, or ask before switching.
|
|
149
|
+
* **The Waitsec Way:** One system per project. Consistency is cheaper than variety.
|
|
150
|
+
|
|
151
|
+
#### 3. Silent Stack Guess
|
|
152
|
+
|
|
153
|
+
* **The Bad Habit:** Proceeding with a guessed stack instead of telling the user what you detected.
|
|
154
|
+
* **The Problem:** The user only discovers the mismatch after the page is generated.
|
|
155
|
+
* **Why It Fails:** Review time is wasted, and the correction costs more than the original question would have.
|
|
156
|
+
* **Clean Fix:** Print the recon summary in one short block, then proceed. If a crucial detail is missing, ask.
|
|
157
|
+
* **The Waitsec Way:** Say what you found before you build on it.
|
|
22
158
|
|
|
23
159
|
---
|
|
24
160
|
|
|
@@ -174,25 +310,291 @@ Activate this skill whenever:
|
|
|
174
310
|
|
|
175
311
|
---
|
|
176
312
|
|
|
177
|
-
## Part 5:
|
|
313
|
+
## Part 5: Interaction & UX Discipline
|
|
314
|
+
|
|
315
|
+
### 1. Primary Action on the Wrong Side
|
|
316
|
+
|
|
317
|
+
* **The Bad Habit:** Placing the confirming action ("Save", "Submit", "Continue") on the left and the secondary action ("Cancel", "Back") on the right.
|
|
318
|
+
* **The Problem:** On mobile the primary button sits away from the thumb, and on desktop it breaks the reading order users expect.
|
|
319
|
+
* **Why It Fails:** People expect the confirming action at the end of the row, on the right. Reversing it causes hesitation and mis-taps, and it is worse when a destructive action sits in the primary spot.
|
|
320
|
+
* **Clean Fix:** Keep the secondary action (Cancel, Back) first and the primary action (Save, Submit) last. On mobile the primary action sits at the bottom of the stack, close to the thumb. On desktop it sits on the right:
|
|
321
|
+
```html
|
|
322
|
+
<div class="flex flex-col sm:flex-row sm:justify-end gap-3">
|
|
323
|
+
<button type="button" class="w-full sm:w-auto px-4 py-2.5 border border-neutral-300 rounded-lg">Cancel</button>
|
|
324
|
+
<button type="submit" class="w-full sm:w-auto px-4 py-2.5 bg-neutral-900 text-white rounded-lg">Save changes</button>
|
|
325
|
+
</div>
|
|
326
|
+
```
|
|
327
|
+
* **The Waitsec Way:** Match the layout to the user's hand and habit. The confirming action lives where the thumb and cursor naturally land.
|
|
328
|
+
|
|
329
|
+
### 2. Destructive Action Without Guardrails
|
|
330
|
+
|
|
331
|
+
* **The Bad Habit:** Placing "Delete" next to "Save" with the same weight and the same color.
|
|
332
|
+
* **The Problem:** A slip of the thumb triggers an irreversible action.
|
|
333
|
+
* **Why It Fails:** Destructive mistakes cost real data, and users stop trusting the interface.
|
|
334
|
+
* **Clean Fix:** Separate destructive actions from safe ones, give them a distinct danger style, require an explicit confirmation for irreversible actions, and never make Delete the default focused button.
|
|
335
|
+
* **The Waitsec Way:** Make the safe path easy and the destructive path deliberate.
|
|
336
|
+
|
|
337
|
+
### 3. No Visible State Change
|
|
338
|
+
|
|
339
|
+
* **The Bad Habit:** A button that shows nothing after a click while a request runs in the background.
|
|
340
|
+
* **The Problem:** The user clicks again because the first click appeared to do nothing.
|
|
341
|
+
* **Why It Fails:** Double submissions create duplicate records, and silence reads as failure.
|
|
342
|
+
* **Clean Fix:** Disable the button on click, show a spinner or a "Saving..." label, then render a clear success or error state.
|
|
343
|
+
* **The Waitsec Way:** Every action needs feedback. The user should never wonder whether the click worked.
|
|
344
|
+
|
|
345
|
+
### 4. Primary Actions Out of Thumb Reach
|
|
346
|
+
|
|
347
|
+
* **The Bad Habit:** Tucking important controls into the top corners of the mobile screen.
|
|
348
|
+
* **The Problem:** One-handed users cannot reach them comfortably.
|
|
349
|
+
* **Why It Fails:** Important actions become a physical stretch, so users skip them or tap the wrong thing.
|
|
350
|
+
* **Clean Fix:** Keep primary actions within the lower thumb zone, and give every tap target at least 44px by 44px.
|
|
351
|
+
* **The Waitsec Way:** Design for one thumb on a moving hand.
|
|
352
|
+
|
|
353
|
+
### 5. Missing Empty, Loading, and Error States
|
|
354
|
+
|
|
355
|
+
* **The Bad Habit:** Building only the happy state with content already in place.
|
|
356
|
+
* **The Problem:** Empty lists, slow requests, and failures show a blank screen or a broken layout.
|
|
357
|
+
* **Why It Fails:** Users cannot tell whether the page is loading, empty, or broken, so they leave.
|
|
358
|
+
* **Clean Fix:** Design all four states: loading (skeleton or spinner), empty (short message plus one action), error (clear message plus a retry), and success.
|
|
359
|
+
* **The Waitsec Way:** A screen is not done until its failure states look intentional.
|
|
360
|
+
|
|
361
|
+
### 6. Flat Button Hierarchy
|
|
362
|
+
|
|
363
|
+
* **The Bad Habit:** Giving every button the same filled, high-contrast style.
|
|
364
|
+
* **The Problem:** Nothing communicates which action matters most.
|
|
365
|
+
* **Why It Fails:** Users hesitate, or they pick the wrong button.
|
|
366
|
+
* **Clean Fix:** One primary (filled) button per section, secondary actions as outline or plain text, and destructive actions in a danger style.
|
|
367
|
+
* **The Waitsec Way:** Hierarchy guides decisions. If every button shouts, none of them is heard.
|
|
368
|
+
|
|
369
|
+
---
|
|
370
|
+
|
|
371
|
+
## Part 6: Responsive Navigation Bar
|
|
372
|
+
|
|
373
|
+
### 1. Desktop Navbar Squeezed into Mobile
|
|
374
|
+
|
|
375
|
+
* **The Bad Habit:** Keeping the full horizontal link row on small screens until it overflows.
|
|
376
|
+
* **The Problem:** Links wrap, overlap the logo, or push the entire page into horizontal scroll.
|
|
377
|
+
* **Why It Fails:** The first thing visitors see is a broken top bar, so they assume the whole site is broken.
|
|
378
|
+
* **Clean Fix:** Collapse the links into a menu button below the `md` breakpoint. Keep the logo on the left and one primary action on the right. Show the full link row only when the width allows it.
|
|
379
|
+
* **The Waitsec Way:** Navigation is a layout, not a fixed row. Restructure it for small screens instead of letting it overflow.
|
|
380
|
+
|
|
381
|
+
### 2. Hamburger With No Real State
|
|
382
|
+
|
|
383
|
+
* **The Bad Habit:** A menu button that opens nothing, or opens a drawer with no way to close it.
|
|
384
|
+
* **The Problem:** Mobile users get trapped or see no change at all.
|
|
385
|
+
* **Why It Fails:** The primary navigation becomes unusable on phones, which is where most first visits happen.
|
|
386
|
+
* **Clean Fix:** Toggle a real drawer or panel. Close it on link click, on Escape, and on outside click, and lock body scroll while it is open.
|
|
387
|
+
* **The Waitsec Way:** A control must do exactly what it looks like it does.
|
|
388
|
+
|
|
389
|
+
### 3. Sticky Navbar Hiding Content
|
|
390
|
+
|
|
391
|
+
* **The Bad Habit:** A fixed navbar with no background, sitting directly over headings and buttons.
|
|
392
|
+
* **The Problem:** Page content scrolls underneath a transparent bar and becomes unreadable.
|
|
393
|
+
* **Why It Fails:** Users cannot read the section they just scrolled to, and anchor links land under the bar.
|
|
394
|
+
* **Clean Fix:** Give a sticky bar a solid or high-opacity background, a subtle bottom border, and add enough top padding (or `scroll-margin-top`) so the first heading is never covered.
|
|
395
|
+
* **The Waitsec Way:** Persistent UI must never cover the content it is meant to help navigate.
|
|
396
|
+
|
|
397
|
+
### 4. Too Many Top-Level Links
|
|
398
|
+
|
|
399
|
+
* **The Bad Habit:** Cramming eight or more links plus a logo and two buttons into the bar.
|
|
400
|
+
* **The Problem:** The bar feels crowded, and items shrink awkwardly on tablets.
|
|
401
|
+
* **Why It Fails:** Users cannot scan the options quickly, so they ignore the navigation.
|
|
402
|
+
* **Clean Fix:** Keep 4 to 5 primary links, move the rest into a menu or the footer, and keep exactly one clear call to action.
|
|
403
|
+
* **The Waitsec Way:** Fewer, clearer choices move people faster.
|
|
404
|
+
|
|
405
|
+
### 5. No Active or Focus State
|
|
406
|
+
|
|
407
|
+
* **The Bad Habit:** Links that look identical whether or not the visitor is on that page, with focus rings removed.
|
|
408
|
+
* **The Problem:** Users lose their place, and keyboard users cannot see where they are.
|
|
409
|
+
* **Why It Fails:** Orientation and accessibility both break at once.
|
|
410
|
+
* **Clean Fix:** Mark the current page with color, weight, or an underline, and keep a visible `focus-visible` ring on every link and button.
|
|
411
|
+
* **The Waitsec Way:** Show people where they are and where the keyboard is.
|
|
412
|
+
|
|
413
|
+
---
|
|
414
|
+
|
|
415
|
+
## Part 7: SEO & GEO
|
|
416
|
+
|
|
417
|
+
### 1. Search SEO Basics
|
|
418
|
+
|
|
419
|
+
- One `<h1>` per page that states the topic in plain words. Use `<h2>` and `<h3>` in a logical order with no skipped levels.
|
|
420
|
+
- Write a unique `<title>` (roughly 50 to 60 characters) and a `<meta name="description">` (roughly 140 to 160 characters) that describe the page honestly.
|
|
421
|
+
- Add a `<link rel="canonical">` pointing to the preferred URL.
|
|
422
|
+
- Add Open Graph and Twitter card tags (`og:title`, `og:description`, `og:image`, `og:url`, `og:type`, `twitter:card`) with absolute image URLs.
|
|
423
|
+
- Use semantic landmarks: `<header>`, `<nav>`, `<main>`, `<article>`, `<section>`, `<footer>`.
|
|
424
|
+
- Give every meaningful image a descriptive `alt`. Decorative images get `alt=""`.
|
|
425
|
+
- Keep the main content in server-rendered HTML so crawlers read it without running client scripts.
|
|
426
|
+
- Use descriptive anchor text for internal links, never "click here".
|
|
427
|
+
- Keep Largest Contentful Paint fast: compress images, use modern formats, set explicit width and height, lazy-load below-the-fold media, and avoid layout shift.
|
|
428
|
+
- Add `hreflang` only when the page really has language variants.
|
|
429
|
+
|
|
430
|
+
### 2. GEO (Generative Engine Optimization)
|
|
431
|
+
|
|
432
|
+
GEO is about being quoted correctly by AI answer engines, not just ranked by search.
|
|
433
|
+
|
|
434
|
+
- Answer the main question in the first 1 to 2 sentences of the page and of each section, before adding detail. Answer engines extract these direct statements.
|
|
435
|
+
- Use question-shaped `<h2>` or `<h3>` headings that match how people actually ask (for example "How do I reset a password?"), followed by a short direct answer.
|
|
436
|
+
- Structure facts as lists, tables, or short definition blocks that a model can quote cleanly.
|
|
437
|
+
- Name entities explicitly (product name, company, author) instead of relying on "we" and "it", so machines can attribute the content.
|
|
438
|
+
- Keep dates concrete and current, and show a visible publish or update date on time-sensitive content.
|
|
439
|
+
- Add author, publisher, `datePublished`, and `dateModified` in structured data so engines can verify freshness and authorship.
|
|
440
|
+
- Avoid keyword stuffing and hidden text. GEO rewards clear, well-structured, genuinely useful content.
|
|
441
|
+
|
|
442
|
+
### 3. SEO and GEO Pitfalls
|
|
443
|
+
|
|
444
|
+
#### 1. Multiple H1 and Skipped Headings
|
|
445
|
+
|
|
446
|
+
* **The Bad Habit:** Using `<h1>` for several sections, or jumping from `<h1>` straight to `<h4>`.
|
|
447
|
+
* **The Problem:** The document outline is ambiguous, so parsers guess the page structure.
|
|
448
|
+
* **Why It Fails:** Search engines and answer engines extract weaker summaries, and screen readers lose the hierarchy.
|
|
449
|
+
* **Clean Fix:** One `<h1>` per page, then `<h2>` and `<h3>` in order.
|
|
450
|
+
* **The Waitsec Way:** Structure is information. Keep the outline honest.
|
|
451
|
+
|
|
452
|
+
#### 2. Client-Only Content
|
|
453
|
+
|
|
454
|
+
* **The Bad Habit:** Shipping a page whose text appears only after JavaScript runs.
|
|
455
|
+
* **The Problem:** Many crawlers and answer engines see an almost empty document.
|
|
456
|
+
* **Why It Fails:** The page cannot rank or be quoted for content it never serves.
|
|
457
|
+
* **Clean Fix:** Render the main content and metadata on the server or at build time, and use JavaScript only to enhance it.
|
|
458
|
+
* **The Waitsec Way:** If a machine cannot read it without running your app, treat it as invisible.
|
|
459
|
+
|
|
460
|
+
#### 3. Missing or Duplicate Metadata
|
|
461
|
+
|
|
462
|
+
* **The Bad Habit:** Reusing the same title and description on every page, or leaving them empty.
|
|
463
|
+
* **The Problem:** Every page competes with itself, and shared links look generic.
|
|
464
|
+
* **Why It Fails:** Click-through drops, and social previews show the wrong information.
|
|
465
|
+
* **Clean Fix:** Write one unique title and description per page, and set canonical plus Open Graph tags for each.
|
|
466
|
+
* **The Waitsec Way:** Every page is its own entry point. Describe it accurately.
|
|
467
|
+
|
|
468
|
+
#### 4. Keyword Stuffing
|
|
469
|
+
|
|
470
|
+
* **The Bad Habit:** Repeating the same phrase in every heading and paragraph to please search bots.
|
|
471
|
+
* **The Problem:** The copy reads badly and adds no new information.
|
|
472
|
+
* **Why It Fails:** Modern search and answer engines reward clarity and penalize repetition, so the page ranks worse and converts worse.
|
|
473
|
+
* **Clean Fix:** Write for the reader first. Use the topic phrase where it fits naturally, and cover related questions instead of repeating one keyword.
|
|
474
|
+
* **The Waitsec Way:** Write for humans. Machines already read like humans do.
|
|
475
|
+
|
|
476
|
+
---
|
|
477
|
+
|
|
478
|
+
## Part 8: Structured Data (Schema.org)
|
|
479
|
+
|
|
480
|
+
Structured data helps search engines and answer engines understand what the page is. Add it to every real page you build.
|
|
481
|
+
|
|
482
|
+
### 1. Rules
|
|
483
|
+
|
|
484
|
+
- Use JSON-LD inside a `<script type="application/ld+json">` in the `<head>`. Do not use microdata or RDFa.
|
|
485
|
+
- Choose the most specific type that matches the page (for example `BlogPosting` instead of a generic `Thing`).
|
|
486
|
+
- Use absolute URLs for `image`, `url`, `logo`, and `@id`.
|
|
487
|
+
- Write dates in ISO 8601 with timezone, for example `2026-09-12T09:56:00+07:00`.
|
|
488
|
+
- You may combine several types with `@graph`, or use several script blocks. Do not duplicate the same type with conflicting data.
|
|
489
|
+
- Only mark up content that is actually visible on the page. Never invent ratings, prices, reviews, or dates.
|
|
490
|
+
- Validate every block with the Google Rich Results Test and the Schema.org validator before declaring the page done.
|
|
491
|
+
|
|
492
|
+
### 2. Schema by Page Type
|
|
493
|
+
|
|
494
|
+
| Page | Primary type(s) |
|
|
495
|
+
| :--- | :--- |
|
|
496
|
+
| Landing or product page | `Organization`, `WebSite`, `SoftwareApplication` or `Product`, plus `FAQPage` when an FAQ is present |
|
|
497
|
+
| Blog index or archive | `Blog` or `CollectionPage`, `ItemList`, `BreadcrumbList` |
|
|
498
|
+
| Single article or post | `Article` or `BlogPosting`, `BreadcrumbList`, `Person` as author, `Organization` as publisher |
|
|
499
|
+
| About or portfolio | `ProfilePage`, `Person`, `Organization` |
|
|
500
|
+
| Contact page | `ContactPage`, `Organization`, `ContactPoint` |
|
|
501
|
+
| FAQ section | `FAQPage` |
|
|
502
|
+
| Any page with breadcrumbs | `BreadcrumbList` |
|
|
503
|
+
|
|
504
|
+
Each page blueprint in `references/` includes the exact JSON-LD block for that page type. Read it before writing the schema.
|
|
505
|
+
|
|
506
|
+
### 3. Reference Example: Article Page
|
|
507
|
+
|
|
508
|
+
```html
|
|
509
|
+
<script type="application/ld+json">
|
|
510
|
+
{
|
|
511
|
+
"@context": "https://schema.org",
|
|
512
|
+
"@type": "Article",
|
|
513
|
+
"headline": "Why Errors Appear as Codes and How to Read Them",
|
|
514
|
+
"description": "A short, honest summary of what the article explains.",
|
|
515
|
+
"author": {
|
|
516
|
+
"@type": "Person",
|
|
517
|
+
"name": "Ilyas Mukhlisin"
|
|
518
|
+
},
|
|
519
|
+
"publisher": {
|
|
520
|
+
"@type": "Organization",
|
|
521
|
+
"name": "Fikselink",
|
|
522
|
+
"logo": {
|
|
523
|
+
"@type": "ImageObject",
|
|
524
|
+
"url": "https://example.com/images/logo.png"
|
|
525
|
+
}
|
|
526
|
+
},
|
|
527
|
+
"datePublished": "2026-09-04T09:56:00+07:00",
|
|
528
|
+
"dateModified": "2026-09-04T09:56:00+07:00",
|
|
529
|
+
"mainEntityOfPage": {
|
|
530
|
+
"@type": "WebPage",
|
|
531
|
+
"@id": "https://example.com/blog/post/why-errors-appear-as-codes"
|
|
532
|
+
},
|
|
533
|
+
"image": "https://example.com/storage/blog-thumbnails/cover.webp",
|
|
534
|
+
"articleSection": "Technology",
|
|
535
|
+
"keywords": "error code, HTTP status code, how to read errors"
|
|
536
|
+
}
|
|
537
|
+
</script>
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
### 4. Structured Data Pitfalls
|
|
541
|
+
|
|
542
|
+
#### 1. Schema Type That Does Not Match the Page
|
|
543
|
+
|
|
544
|
+
* **The Bad Habit:** Marking a landing page as `Article`, or a contact page as `BlogPosting`.
|
|
545
|
+
* **The Problem:** The data contradicts what the page actually is.
|
|
546
|
+
* **Why It Fails:** Search and answer engines distrust or ignore mismatched markup, so the rich result never appears.
|
|
547
|
+
* **Clean Fix:** Match the type to the page using the table above, and use the most specific type available.
|
|
548
|
+
* **The Waitsec Way:** Structured data is a factual claim. Make it true.
|
|
549
|
+
|
|
550
|
+
#### 2. Missing Required Fields
|
|
551
|
+
|
|
552
|
+
* **The Bad Habit:** Shipping an `Article` block with no `author`, no `datePublished`, or no `image`.
|
|
553
|
+
* **The Problem:** Validators report errors and eligible rich results are dropped.
|
|
554
|
+
* **Why It Fails:** Incomplete markup is treated as unreliable, so the page loses visibility it could have earned.
|
|
555
|
+
* **Clean Fix:** Fill the required and recommended fields for the chosen type, then re-run a validator.
|
|
556
|
+
* **The Waitsec Way:** Half-true metadata is worse than none. Complete the claim or do not make it.
|
|
557
|
+
|
|
558
|
+
#### 3. Marking Up Hidden Content
|
|
559
|
+
|
|
560
|
+
* **The Bad Habit:** Adding `FAQPage` markup for questions that are not visible on the page, or inventing review ratings.
|
|
561
|
+
* **The Problem:** The markup describes content the user and the crawler cannot find.
|
|
562
|
+
* **Why It Fails:** It violates search engine guidelines and can trigger a manual penalty.
|
|
563
|
+
* **Clean Fix:** Only mark up what is visible on the rendered page.
|
|
564
|
+
* **The Waitsec Way:** Never let metadata promise something the page does not show.
|
|
565
|
+
|
|
566
|
+
#### 4. Relative URLs and Wrong Dates
|
|
567
|
+
|
|
568
|
+
* **The Bad Habit:** Using `"/images/cover.png"` in `image`, or a date with no timezone.
|
|
569
|
+
* **The Problem:** Engines cannot resolve the asset or the timestamp reliably.
|
|
570
|
+
* **Why It Fails:** The rich result renders broken or is ignored.
|
|
571
|
+
* **Clean Fix:** Use absolute URLs and full ISO 8601 timestamps with the correct offset, for example `2026-09-12T09:56:00+07:00`.
|
|
572
|
+
* **The Waitsec Way:** Give machines exact facts, not assumptions.
|
|
573
|
+
|
|
574
|
+
---
|
|
575
|
+
|
|
576
|
+
## Part 9: Page Archetypes & Blueprint Routing
|
|
178
577
|
|
|
179
|
-
When the user asks for a specific type of page,
|
|
578
|
+
When the user asks for a specific type of page, read its dedicated reference guide. Each reference includes the page anatomy, the 5-point pitfalls, the SEO and GEO notes, and the exact JSON-LD block for that page type.
|
|
180
579
|
|
|
181
580
|
### 1. Marketing & Conversion Pages
|
|
182
581
|
* **Includes:** SaaS homepages, landing pages, product launch screens.
|
|
183
|
-
* **Key Blueprint:** Clear hero statement, problem vs solution, key feature cards, social proof, and a single high-contrast primary CTA.
|
|
582
|
+
* **Key Blueprint:** Clear hero statement, problem vs solution, key feature cards, social proof, FAQ where useful, and a single high-contrast primary CTA.
|
|
583
|
+
* **Schema:** `Organization`, `WebSite`, `SoftwareApplication` or `Product`, plus `FAQPage` when an FAQ is present.
|
|
184
584
|
* *Detailed Guide:* [`skills/waitsec-pagemaker/references/landing-page.md`](./references/landing-page.md)
|
|
185
585
|
|
|
186
586
|
### 2. Editorial & Content Pages
|
|
187
587
|
* **Includes:** Blog catalogs, single article readers, changelogs, docs.
|
|
188
588
|
* **Key Blueprint:** Comfortable reading line length (60 to 75 characters per line), clean typography rhythm, clear subheadings, and distraction-free reading.
|
|
589
|
+
* **Schema:** `Blog` or `CollectionPage` with `ItemList` for the index, and `Article` or `BlogPosting` with `BreadcrumbList` for a single post.
|
|
189
590
|
* *Detailed Guides:*
|
|
190
591
|
- Blog Index: [`skills/waitsec-pagemaker/references/blog-index.md`](./references/blog-index.md)
|
|
191
592
|
- Single Article: [`skills/waitsec-pagemaker/references/article-single.md`](./references/article-single.md)
|
|
192
593
|
|
|
193
594
|
### 3. Standalone Single Pages
|
|
194
|
-
* **Includes:** Contact forms, About Me
|
|
195
|
-
* **Key Blueprint:** Single-purpose layouts, minimal input forms (name, email, message) with
|
|
595
|
+
* **Includes:** Contact forms, About Me and Portfolio, simple profile pages.
|
|
596
|
+
* **Key Blueprint:** Single-purpose layouts, minimal input forms (name, email, message) with clear validation states, and direct project or contact links.
|
|
597
|
+
* **Schema:** `ProfilePage` with `Person` for an about page, and `ContactPage` with `Organization` and `ContactPoint` for a contact page.
|
|
196
598
|
* *Detailed Guides:*
|
|
197
599
|
- Contact Page: [`skills/waitsec-pagemaker/references/contact-page.md`](./references/contact-page.md)
|
|
198
600
|
- About / Portfolio: [`skills/waitsec-pagemaker/references/about-me.md`](./references/about-me.md)
|
|
@@ -203,8 +605,18 @@ When the user asks for a specific type of page, check its dedicated reference gu
|
|
|
203
605
|
|
|
204
606
|
Before returning generated page code to the user, verify:
|
|
205
607
|
|
|
608
|
+
- [ ] Did I run Project Recon and report the framework, template engine, styling system, load method, version, and icon library?
|
|
609
|
+
- [ ] Did I follow the existing styling system, or ask before changing it?
|
|
610
|
+
- [ ] Are icons from the detected library or Lucide CDN, with no emoji and no hand-written inline SVG?
|
|
611
|
+
- [ ] Does the page contain zero em dash and zero en dash characters?
|
|
206
612
|
- [ ] Does the mobile layout reflow into a clean vertical stack without horizontal scrolling?
|
|
207
613
|
- [ ] Are clickable buttons and links at least 44px by 44px on mobile viewports?
|
|
614
|
+
- [ ] Is the primary action placed on the right on desktop and at the bottom of the stack on mobile, with Cancel before Save?
|
|
615
|
+
- [ ] Are loading, empty, error, and success states designed, not just the happy path?
|
|
208
616
|
- [ ] Are generic AI gradients, floating shadows, and all-pill buttons removed in favor of clean solid styling?
|
|
209
617
|
- [ ] Does all text meet comfortable readability standards with high contrast against the background?
|
|
618
|
+
- [ ] Is the navbar responsive, with a working menu button on mobile, a solid sticky background, and a visible active and focus state?
|
|
210
619
|
- [ ] Is there exactly one primary Call to Action (CTA) per marketing section?
|
|
620
|
+
- [ ] Does the page have one `<h1>`, a unique title and meta description, a canonical URL, and Open Graph tags?
|
|
621
|
+
- [ ] Is the main content server-rendered and structured so answer engines can quote it?
|
|
622
|
+
- [ ] Is the JSON-LD block present, type-appropriate, using absolute URLs and ISO 8601 dates, and validated with no errors?
|
|
@@ -113,6 +113,44 @@ Use this guide when creating a personal developer portfolio, founder bio, or eng
|
|
|
113
113
|
|
|
114
114
|
---
|
|
115
115
|
|
|
116
|
+
## SEO, GEO & Structured Data (About & Portfolio)
|
|
117
|
+
|
|
118
|
+
- Title: full name plus role, for example "Ilyas Mukhlisin, Backend Engineer", about 50 to 60 characters.
|
|
119
|
+
- Meta description: who you are, what you build, and how to reach you, about 140 to 160 characters.
|
|
120
|
+
- One `<h1>` with your name.
|
|
121
|
+
- Server-render the bio, project list, and contact email.
|
|
122
|
+
- Add `sameAs` links to GitHub, LinkedIn, and X so engines can confirm the identity.
|
|
123
|
+
- Describe each project with a concrete outcome, not a vague claim, so answer engines have something to quote.
|
|
124
|
+
|
|
125
|
+
### JSON-LD for an About or Portfolio Page
|
|
126
|
+
|
|
127
|
+
```html
|
|
128
|
+
<script type="application/ld+json">
|
|
129
|
+
{
|
|
130
|
+
"@context": "https://schema.org",
|
|
131
|
+
"@type": "ProfilePage",
|
|
132
|
+
"url": "https://example.com/about",
|
|
133
|
+
"mainEntity": {
|
|
134
|
+
"@type": "Person",
|
|
135
|
+
"name": "Your Name",
|
|
136
|
+
"jobTitle": "Backend Engineer",
|
|
137
|
+
"url": "https://example.com",
|
|
138
|
+
"image": "https://example.com/images/avatar.jpg",
|
|
139
|
+
"worksFor": { "@type": "Organization", "name": "Fastro" },
|
|
140
|
+
"knowsAbout": ["Laravel", "PostgreSQL", "API design"],
|
|
141
|
+
"sameAs": [
|
|
142
|
+
"https://github.com/username",
|
|
143
|
+
"https://www.linkedin.com/in/username"
|
|
144
|
+
]
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
</script>
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
When the about page is part of a company site, add an `Organization` node and connect it with `worksFor` or `memberOf`.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
116
154
|
## Pre-Flight Checklist for About Me & Portfolio Pages
|
|
117
155
|
|
|
118
156
|
- [ ] Are all fake animated skill percentage bars removed in favor of clean categorical tags?
|
|
@@ -120,3 +158,4 @@ Use this guide when creating a personal developer portfolio, founder bio, or eng
|
|
|
120
158
|
- [ ] Does every featured project have a working live link or public repository link?
|
|
121
159
|
- [ ] Is there a direct, clickable `mailto:` link clearly visible on the page?
|
|
122
160
|
- [ ] Do project cards collapse into a clean single vertical stack on mobile screens?
|
|
161
|
+
- [ ] Is there a valid ProfilePage with Person data, including sameAs links to real profiles?
|
|
@@ -95,6 +95,68 @@ Use this guide when creating a single article view, blog post template, or markd
|
|
|
95
95
|
|
|
96
96
|
---
|
|
97
97
|
|
|
98
|
+
## SEO, GEO & Structured Data (Article Page)
|
|
99
|
+
|
|
100
|
+
- Title: the article headline, optionally with the site name, about 50 to 60 characters.
|
|
101
|
+
- Meta description: an honest summary of the article, about 140 to 160 characters.
|
|
102
|
+
- One `<h1>` that matches the headline.
|
|
103
|
+
- State the article's main answer in the first paragraph, before background detail.
|
|
104
|
+
- Use question-shaped `<h2>` and `<h3>` headings, each followed by a direct answer.
|
|
105
|
+
- Show `datePublished` and `dateModified` visibly near the top, and keep both in the schema.
|
|
106
|
+
- Give the cover image descriptive alt text and an absolute URL.
|
|
107
|
+
- Keep the article body server-rendered.
|
|
108
|
+
|
|
109
|
+
### JSON-LD for an Article Page
|
|
110
|
+
|
|
111
|
+
The `Article` type is safe, while `BlogPosting` is more specific for blog posts. Use the one that matches the page. Add `BreadcrumbList` so search engines can show the path.
|
|
112
|
+
|
|
113
|
+
```html
|
|
114
|
+
<script type="application/ld+json">
|
|
115
|
+
{
|
|
116
|
+
"@context": "https://schema.org",
|
|
117
|
+
"@graph": [
|
|
118
|
+
{
|
|
119
|
+
"@type": "BlogPosting",
|
|
120
|
+
"headline": "Why Errors Appear as Codes and How to Read Them",
|
|
121
|
+
"description": "A short, honest summary of what the article explains.",
|
|
122
|
+
"image": "https://example.com/storage/blog-thumbnails/cover.webp",
|
|
123
|
+
"datePublished": "2026-09-04T09:56:00+07:00",
|
|
124
|
+
"dateModified": "2026-09-04T09:56:00+07:00",
|
|
125
|
+
"author": {
|
|
126
|
+
"@type": "Person",
|
|
127
|
+
"name": "Ilyas Mukhlisin",
|
|
128
|
+
"url": "https://example.com/about"
|
|
129
|
+
},
|
|
130
|
+
"publisher": {
|
|
131
|
+
"@type": "Organization",
|
|
132
|
+
"name": "Fikselink",
|
|
133
|
+
"logo": {
|
|
134
|
+
"@type": "ImageObject",
|
|
135
|
+
"url": "https://example.com/images/logo.png"
|
|
136
|
+
}
|
|
137
|
+
},
|
|
138
|
+
"mainEntityOfPage": {
|
|
139
|
+
"@type": "WebPage",
|
|
140
|
+
"@id": "https://example.com/blog/post/why-errors-appear-as-codes"
|
|
141
|
+
},
|
|
142
|
+
"articleSection": "Technology",
|
|
143
|
+
"keywords": "error code, HTTP status code, how to read errors"
|
|
144
|
+
},
|
|
145
|
+
{
|
|
146
|
+
"@type": "BreadcrumbList",
|
|
147
|
+
"itemListElement": [
|
|
148
|
+
{ "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com" },
|
|
149
|
+
{ "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog" },
|
|
150
|
+
{ "@type": "ListItem", "position": 3, "name": "Why Errors Appear as Codes", "item": "https://example.com/blog/post/why-errors-appear-as-codes" }
|
|
151
|
+
]
|
|
152
|
+
}
|
|
153
|
+
]
|
|
154
|
+
}
|
|
155
|
+
</script>
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
98
160
|
## Pre-Flight Checklist for Single Article Pages
|
|
99
161
|
|
|
100
162
|
- [ ] Is the article reading width capped at `max-w-3xl` or `65-75ch` to prevent eye strain?
|
|
@@ -102,3 +164,5 @@ Use this guide when creating a single article view, blog post template, or markd
|
|
|
102
164
|
- [ ] Is body paragraph line-height set to relaxed (`leading-relaxed` / 1.75)?
|
|
103
165
|
- [ ] Are subheadings given generous top margin (`mt-10` to `mt-12`) to separate topics clearly?
|
|
104
166
|
- [ ] Is there a clear back-navigation link at the top of the article?
|
|
167
|
+
- [ ] Does the first paragraph answer the main question directly?
|
|
168
|
+
- [ ] Is there a valid BlogPosting or Article block with author, publisher, and ISO 8601 dates?
|