Web Components logo Web Components Architecture

Phase plan — web-framework-components.com

The schedule to grow this site phase-by-phase, generated from the Django Site model. No OpenRouter / no API — you (Claude Code) do the work, grounded in the real markdown under content/.

How to upgrade a phase

Work through every step in order. Do not skip the uplift, the term cleanup, the SVG render check, or the finish/deploy steps — those were the gaps in earlier runs.

  1. Read & orient. Read this whole file, then skim content/ to learn what exists and the writing tone.

  2. Uplift EVERY existing page (not just new ones). Bring all current pages — from earlier phases — up to the Page blueprint below: its page anatomy, frontmatter, JSON-LD schema, the custom SVG visuals, and the mandatory wiki-style interlinking. Old pages must reach the current standard, not be left as they were.

  3. Build the next phase. Add this phase’s page mix (see schedule), slotting pages into the existing hierarchy, each built to the same blueprint standard.

  4. Keep it niche-specific. Section topics must be drawn from this niche, not generic placeholders.

  5. Remove internal IA/SEO terms from visible copy. The words pillar, cluster, long-tail (and “hub and spoke”, “supporting page”, etc.) are internal labels — they must not appear in reader-facing prose. Scan and fix:

    python3 /home/martin/WebstormProjects/_qa/term_lint.py web-framework-components.com

    (Legit domain uses of “cluster” — e.g. a Kafka/DB cluster — are fine; rewrite only the information-architecture sense.)

  6. Author custom SVG visuals per the “Custom visuals” section, then build the site and verify the SVGs render correctly ON THE PAGE — the page’s CSS/typography must not leak in and break them. Fix and rebuild until clean:

    cd /home/martin/WebstormProjects/web-framework-components.com && npm run build
python3 /home/martin/WebstormProjects/_qa/svg_check.py web-framework-components.com

    It statically validates each SVG (XML, id refs), then renders the BUILT pages in headless chromium with the real stylesheet applied — flagging page typography overflowing labels, distorted/zero-size, and empty SVGs. Must pass with no FAILs.

  7. Record completion (updates page/word count, advances current→next phase, and rewrites this plan ready for the next phase). From the Django project (/home/martin/PycharmProjects/Django-Pillar-Cluster-Long-Tail):

    .venv/bin/python manage.py finish_phase web-framework-components.com --completed maturity \
    --blueprint "/home/martin/WebstormProjects/web-framework-components.com/_plan/blueprint.json"

  8. Commit & deploy. Build, deploy to Cloudflare, and push to GitHub:

    cd /home/martin/WebstormProjects/web-framework-components.com
npm run deploy          # build + wrangler deploy (auth from the site .env)
git add -A && git commit -m "Upgrade to maturity phase" && git push

Phase schedule

# Phase Status Adds Target total Focus
1 1. Foundation ✅ done 2-3 pillars + 10-14 clusters + 8-12 long-tails ~22 Establish core authority: the main pillars and their primary clusters, with enough long-tails to validate demand. Get a consistent page skeleton in place.
2 2. Expansion ✅ done 1-2 pillars + 7-10 clusters + 18-25 long-tails ~50 Broaden coverage: fill out each pillar’s clusters and add the high-intent long-tails around them. Strengthen interlinking between siblings.
3 3. Maturity ➡️ NEXT 4-6 clusters + 28-40 long-tails ~82 Deepen the long tail: comprehensive how-tos, comparisons and edge-case pages under existing clusters. Ensure FAQ blocks and schema on every page.
4 4. Authority … future 2-3 clusters + 20-30 long-tails ~105 Complete topical authority: remaining gaps, advanced/expert pages, and a tight internal link graph so every page is 1-2 clicks from its pillar.

Priorities for the next phase (maturity)

Page blueprint

(tailored to this site)

pillar pages (~4500 words)

cluster pages (~3500 words)

long_tail pages (~2000 words)

All code examples must be complete and runnable (no ellipsis placeholders). Each ‘Debugging Pitfall’ callout should be a distinct styled block. The audience (UI engineers, design system builders, frontend architects) expects spec citations alongside practical production code — never omit the normative grounding. CSS code blocks should use real shadow DOM selectors (:host, ::slotted, ::part, :host-context). Avoid generic intro/outro filler; every section must deliver actionable information specific to web components and framework-agnostic UI. Tables comparing browser support should use real version numbers and link to MDN compatibility data internally where a dedicated page exists.

Custom visuals (SVG)

When upgrading or building any page, add a custom, hand-authored inline SVG wherever a visual would genuinely raise quality (architecture/data-flow diagrams, sequence or state diagrams, comparison matrices, timelines, annotated illustrations). Do NOT add decorative or generic stock-style images. Each SVG must: be original and specific to the page’s content; match the site’s existing design system (colours, fonts, stroke weight); be responsive (viewBox, no fixed pixel width) and accessible (/<desc>, role=“img”, aria-label); and use currentColor / CSS variables so it adapts to light/dark themes. Prefer one strong diagram that explains the hardest concept on the page over many small ones. Pillar pages should almost always carry a top-level overview diagram.</p> </main> <footer class="site-footer"> <div class="shell footer-inner"> <p>Framework-agnostic Web Components guidance for production teams.</p> <nav aria-label="Footer navigation"> <a href="/">Home</a> <a href="/core-architecture-lifecycle-management/">Core Architecture</a> <a href="/styling-theming-css-encapsulation/">Styling & Theming</a> <a href="/distribution-testing-tooling/">Distribution & Testing</a> </nav> </div> </footer> <script src="/assets/js/site.js" defer></script> </body> </html>