Web Components logo Web Components Architecture

Upgrade brief — shared spec for all content agents

You are writing pages for web-framework-components.com, a spec-authoritative engineering reference on Web Components & framework-agnostic UI architecture. Audience: UI engineers, design-system builders, frontend architects, framework maintainers. Tone: precise, production-grade, normative-spec-grounded, zero marketing fluff. Every claim must be technically correct (real APIs, real selectors, real version numbers). Code must be complete and runnable — NO ... ellipsis placeholders.

File & format conventions (CRITICAL — match exactly)

Forbidden vocabulary (a linter WILL fail the build)

NEVER use these words/phrases in visible prose (they are internal SEO/IA jargon): pillar, cluster, long-tail / long tail / longtail, hub and spoke, content silo / topic silo, supporting page, pillar content, internal linking structure/strategy. Also avoid the bare phrases “this pillar”, “the cluster”, etc. Say instead: section, topic area, overview, guide, deep-dive, family of pages, parent section. (A literal Kafka/DB/server “cluster” would be fine, but our content rarely needs it — avoid the word.)

Page anatomy by type

Pillar (~4000–4500 words) — top-level index.md directly under a section

  1. Architectural overview paragraph (why this domain matters for framework-agnostic systems)
  2. Spec authority block: normative W3C/WHATWG/CSS-WG references governing the domain 3–6. Four domain concepts — EACH with: an inline link to a child topic page, a runnable code example, and a Debugging Pitfall callout (a **Debugging Pitfall:** bold-led paragraph)
  3. Cross-domain integration (how these primitives compose with the other sections)
  4. Production validation & contract testing
  5. Distribution & publishing implications
  6. Conclusion (architectural synthesis)
  7. ## Related block linking all child topic pages + the other sections

Cluster / topic page (~3000–3500 words) — index.md one level under a section

Open the first paragraph with an inline up-link to the parent section. Then:

  1. Concept definition & spec grounding (cite the governing spec, link parent section)
  2. Browser engine integration points (parse/render/style engine timing, phases, thread model)
  3. Core API surface (a syntax table OR annotated code block of all options/attributes/params)
  4. Production implementation pattern (complete, self-contained, commented code)
  5. Common failure modes & debugging steps (2–4 numbered pitfalls, root cause + concrete fix)
  6. Framework interop (React, Vue, Angular, SSR differences)
  7. Performance & memory implications (benchmarks, observer teardown, bundle size, leak vectors)
  8. Browser compatibility & polyfill strategy (real version numbers, support matrix, degradation)
  9. ## Related block: 3–5 links to sibling topic pages + parent up-link

Long-tail / deep-dive page (~1800–2200 words) — deepest index.md

  1. Problem statement with a minimal reproducible example (the gotcha/tradeoff, in code)
  2. Root-cause analysis (normative spec clause or engine behavior that explains why)
  3. Production-safe fix or pattern (complete corrected code, commented)
  4. Verification step (console output, DevTools inspection, or test assertion to confirm the fix)
  5. When to use / when to avoid (a decision table or bullet list)
  6. ## Related block: parent topic up-link, grandparent section, 2–3 sibling deep-dive links

Interlinking rules (mandatory)

Hyperlink the FIRST prose mention of any concept that has its own page on the site, woven into the sentence (not “click here”). Example: the [Custom Element Registry & Definition](/core-architecture-lifecycle-management/custom-element-registry-definition/) ensures deterministic instantiation. Use ONLY URLs from the site map below — never invent a URL. Every page ends with a ## Related bullet list (3–5 items) of the exact form:

## Related

- [Title](/url/) — short reason.
- [Title](/url/) — short reason.

Custom SVG visual (every page gets exactly ONE)

Author one original inline SVG that explains the hardest concept on the page (architecture/data-flow, sequence, state machine, comparison matrix, or timeline). Place it right after the first paragraph (pillars/clusters) or near the relevant section (deep-dives). Rules that MUST hold (a headless renderer checks these):

Palette: bg #0a1022, surface #0f1833, card #121d3d, deep #1a2a55, text #e8eeff, text-soft #b7c4ef, brand #5a7bff, brand-2 #1cc8ff/#8fd9ff, accent #7c4dff/#c79cff, ok #8ff0c2/#29c587, warn #ffbf7a/#ffa83e, border #2b3d73.

Proven SVG skeleton (copy this structure; pass pfx- ids are examples — change the prefix):

<svg viewBox="0 0 880 300" role="img" aria-labelledby="pfx-t pfx-d" xmlns="http://www.w3.org/2000/svg" style="width:100%;height:auto;max-width:880px;margin:1.6rem auto;display:block;font-family:Inter,ui-sans-serif,system-ui,sans-serif;color:#e8eeff;">
  <title id="pfx-t">Short title</title>
  <desc id="pfx-d">One-sentence description of the diagram.</desc>
  <defs>
    <linearGradient id="pfx-grad" x1="0" y1="0" x2="0" y2="1">
      <stop offset="0" stop-color="#1a2a55"/><stop offset="1" stop-color="#121d3d"/>
    </linearGradient>
    <marker id="pfx-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto">
      <path d="M0 0 L10 5 L0 10 z" fill="#5a7bff"/>
    </marker>
  </defs>
  <rect x="20" y="40" width="180" height="80" rx="12" fill="url(#pfx-grad)" stroke="#2b3d73" stroke-width="1.5"/>
  <text x="110" y="76" text-anchor="middle" font-size="16" font-weight="700" fill="#e8eeff">Label</text>
  <text x="110" y="98" text-anchor="middle" font-size="12" fill="#b7c4ef">sub label</text>
  <line x1="202" y1="80" x2="236" y2="80" stroke="#5a7bff" stroke-width="2.5" marker-end="url(#pfx-arrow)"/>
</svg>

Code rules

FULL SITE MAP (use these exact URLs for links)

Sections (top level):

Core Architecture & Lifecycle Management:

Styling, Theming & CSS Encapsulation:

Distribution, Testing & Tooling: