Theme Knowledge — Improvement & Growth Plan

Package: capell-app/theme-knowledge · Kind: theme · Tier: premium · Product group: Capell Themes · Bundle: themes · Status: Complete

1. Snapshot

KnowledgeThemeServiceProvider registers the knowledge theme key with a single Blade layout (capell-theme-knowledge::page, src/KnowledgeThemeServiceProvider.php:100) and one preset, extending default (the foundation theme — FoundationThemeServiceProvider::THEME_KEY = 'default', so this is correct, not a mismatch). definition()->includedSections lists 16 keys; navigation and footer are explicitly delegated back to foundation via isFoundationSection(), leaving 14 theme-owned section views plus page.blade.php. The demo command capell:theme-knowledge-demo exists (src/Console/Commands/DemoCommand.php) and delegates to InstallKnowledgeThemeDemoAction, which just calls ThemeDemoPageInstaller::run($data, 'knowledge', 'Knowledge') — there are no bespoke demo layouts; demo content is the generic foundation page installer. The theme overrides hero/features/proof/content sections and the page shell; it inherits navigation, footer, and all chrome from foundation-theme.

Marketplace and Composer copy are buyer-facing, but capell.json now promotes only the extension card because the 9 committed route-backed PNG captures declared by docs/screenshots.json were generated from the generic Capell runner theme-gallery fixture instead of the actual Theme Knowledge shell.

Completed Improvement Slices

• 2026-06-03: Added buyer-facing marketplace and Composer copy, replaced the stub Diagnostics health check with real theme registration/view/vendor-asset probes, and limited marketplace screenshots to committed preview assets.
• 2026-06-06: Captured all 9 docs/screenshots.json route-backed targets through the Capell runner, then demoted the gallery after verifying the route renders the generic theme-gallery fixture rather than the package theme shell.
• 2026-06-06: Added package-owned CSS fallbacks for the real Theme Knowledge hero shell after the Capell runner build showed that package Blade utility classes were not enough to style seeded frontend captures. Anonymous seeded-route captures now render the light and dark Knowledge shell, the shared screenshot wrapper suppresses the Insights consent banner during screenshot runs, and capell.json promotes the strongest route-backed homepage captures.
• 2026-06-04: Moved author bench and topic hub defaults into translations, made both sections accept hydrated item data, removed optional package installation checks from public newsletter/search Blade, and added tests for those public rendering contracts.
• 2026-06-05: Added a first-class doc-article section renderer with hydrated breadcrumbs, category sidebar, article metadata, constrained article body, and sticky table-of-contents layout, plus registry coverage and docs/manifest reconciliation.
• 2026-06-06: Added code-block/prose styling for technical articles, constrained long-form measures with calmer heading scale, tokenized theme colour utilities, dark-mode tokens, a reduced-motion guard for decorative grid overlays, and KB article feedback/version/freshness affordances.

Headline: the package is positioned as a knowledge-base / documentation / help-site theme, and the core documentation layout now exists. Seeded-route light and dark captures now render the actual Theme Knowledge shell/CSS, and marketplace promotion is intentionally conservative around the strongest homepage images until inner-route demo content is stronger.

2. Improvements (existing functionality)

Prioritized. Real templates only.

1. Topic hubs are translated and data-driven. — topic-hubs now reads $section->items/$items when supplied and falls back to translated default hub cards, so real taxonomy labels and summaries can be passed from render data. — resources/views/sections/topic-hubs.blade.php, resources/lang/en/generic.php, tests/Unit/KnowledgeThemeDefinitionTest.php — M

2. Author bench is translated and data-driven. — authors now reads $section->items/$items when supplied and falls back to translated author cards, removing hard-coded public English from the Blade. — resources/views/sections/authors.blade.php, resources/lang/en/generic.php, tests/Unit/KnowledgeThemeDefinitionTest.php — M

3. Done/Shipped: add dark mode screenshot. Theme Knowledge defines dark-mode token overrides and the screenshot contract now declares dark paths for the main frontend/homepage captures. The Capell runner captured the route-backed dark homepage through the real .knowledge-shell, and capell.json promotes it alongside the light homepage. — resources/css/theme-knowledge.css, docs/screenshots.json, capell.json, docs/screenshots/knowledge-homepage-layout-dark.png — L

4. Done/Shipped: tokenize hardcoded hex colors. Theme views now use .knowledge-shell CSS custom properties such as --site-theme-primary, --site-theme-accent, --site-theme-surface, --site-theme-heading, and ink/code variants instead of inline arbitrary hex utilities. The literal hex values are centralized in resources/css/theme-knowledge.css token definitions so Theme Studio presets and future dark-mode overrides have one palette boundary. — resources/views/**/*.blade.php, resources/css/theme-knowledge.css — L

5. Done/Shipped: honor reduced motion on the animated grid. .knowledge-hero::before, .knowledge-search-console::before, and .knowledge-cta::before now sit behind a prefers-reduced-motion: reduce guard that disables decorative grid backgrounds and shortens animation/transition durations inside the theme shell. — resources/css/theme-knowledge.css — S

6. Done/Shipped: skeleton/placeholder bars have semantic fallback. content-listing now gives image-less cards a labelled editorial-resource placeholder with translated visible copy, and search-listing explains the source-map panel before the decorative bars. The bars remain decorative with aria-hidden, but the empty/no-media state now reads as intentional content. — resources/views/sections/search-listing.blade.php, content-listing.blade.php, resources/lang/en/generic.php — S

7. Done/Shipped: heading scale / readability pass for long-form. Long-form doc/article and content-listing surfaces now get a 68ch reading measure for prose/header text, balanced article headings, and a scoped heading weight override that calms the previous all-font-black treatment without rewriting section templates. — resources/css/theme-knowledge.css — M

3. Missing Features (gaps)

capabilities[] = ["theme-knowledge", "theme-knowledge-frontend"]. For the knowledge/docs/help vertical, the current feature status is:

• Done/Shipped: Doc/article layout (table stakes, differentiator-critical). doc-article is now a first-class included section with a left category sidebar, breadcrumb trail, article metadata, constrained article body, and right sticky table of contents backed by hydrated renderer data and translated fallbacks. — src/KnowledgeThemeServiceProvider.php, resources/views/sections/doc-article.blade.php, resources/lang/en/generic.php, tests/Unit/KnowledgeThemeDefinitionTest.php
• Persistent sidebar / category navigation. The shipped doc-article section renders a hydrated first-level category sidebar. Multi-level collapsible sidebar trees remain deeper follow-up work.
• Table of contents (in-page anchor nav). The shipped doc-article section renders hydrated sticky TOC links. Automatic heading extraction remains future work.
• Breadcrumbs. The shipped doc-article section renders hydrated breadcrumb trails with translated fallbacks.
• Done/Shipped: Functional search surface. search-listing.blade.php now renders a translated GET search form with renderer-supplied availability/action data and query input. Deeper Search package result-page integration remains follow-up work.
• Done/Shipped: code-block / syntax styling. .knowledge-doc-prose now styles inline code, scrollable pre blocks, lists, and H2/H3 rhythm for both section-rendered articles and Knowledge Base article views. Full syntax highlighting remains future package/app integration depth.
• Done/Shipped: article feedback (“Was this helpful?”). The Theme Knowledge KB article view renders the package feedback form, submitted-state message, and helpfulness aggregate summary using the Knowledge Base public payload and translated KB strings. A reusable partial can remain future cleanup, but the buyer-facing affordance is present.
• Done/Shipped: versioning / “last updated” freshness affordance. The theme doc-article section accepts a hydrated version, and the KB article view displays the current public article version plus last-modified date from the Knowledge Base article payload. A full version switcher remains future product depth.
• Doc-article hero/header partial (title + category + reading time + updated date). The generic hero is marketing-shaped.

Vs siblings: theme-healthcare ships dedicated healthcare blog views, while Theme Knowledge now concentrates its differentiation in documentation surfaces: doc-article, category sidebar, sticky TOC, search form, code-friendly prose, freshness metadata, and feedback affordances. Cross-sell: Blog, Search, Newsletter, and SEO Suite support remain optional integration depth beyond the renderer, with the theme exposing safe static/flag-driven branches today.

4. Issues / Risks

• Optional-package checks removed from public Blade. Newsletter and search listing views now rely on renderer-provided newsletterAvailable/searchAvailable flags and default to false when rendered in isolation. PublicOutputSafetyTest guards against CapellCore:: and isPackageInstalled( in public views. — resources/views/sections/newsletter.blade.php, search-listing.blade.php, tests/Unit/PublicOutputSafetyTest.php
• Author hard-coded copy fixed. Author default cards now live in translations and the view accepts hydrated item data. — resources/views/sections/authors.blade.php, resources/lang/en/generic.php
• Health check shipped. ThemeKnowledgeHealthCheck now probes Theme Studio registration, required views, and vendor asset registration; tests cover passing diagnostics and an unregistered theme failure. — src/Health/ThemeKnowledgeHealthCheck.php, tests/Unit/ThemeKnowledgeHealthCheckTest.php
• Stub contribution class. src/Manifest/ThemeManagementPageContribution.php is contract-only (compatibleCapellApiVersion() only); confirm the management page actually mounts for themeKey: knowledge rather than relying on an empty contract impl. — src/Manifest/ThemeManagementPageContribution.php
• Screenshot contract recaptured. docs/screenshots.json declares 7 route-backed render entries and every path exists under docs/screenshots/. The current PNGs were captured through seeded package routes with the real .knowledge-shell and package CSS; the shared screenshot wrapper suppresses the Insights consent banner during capture. capell.json promotes the real route-backed homepage capture while leaving weaker inner-route captures as committed evidence until demo content is stronger. — docs/screenshots.json, capell.json, docs/screenshots/, resources/css/theme-knowledge.css
• Marketplace copy shipped. Marketplace/Composer copy is buyer-facing and now matches the shipped documentation, search, code-prose, dark-mode, and optional package-support story. — capell.json
• {!! $content !!} trust boundary accepted and guarded. page.blade.php:12 echoes pre-rendered section HTML unescaped, matching the standard foundation pattern where sections render server-side via trusted renderers. PublicOutputSafetyTest guards against authoring markers, database calls, public Blade CapellCore:: package checks, and untranslated visible static copy. — resources/views/page.blade.php, tests/Unit/PublicOutputSafetyTest.php
• Performance budget guarded. capell.json performance.frontendRenderBudgetMs = 20, adminQueryBudget = 0, and cacheSafety.cacheable = false are covered by manifest/render-budget assertions; hero media paths stay in the screenshot/marketplace contract rather than public Blade fallback logic. — capell.json, tests/Unit/
• Test coverage closed for current roadmap. tests/ covers theme definition, manifest requirements, package-aware rendering, health diagnostics, translated/data-driven author and topic hub defaults, the doc/article layout renderer, public-output leak strings including CapellCore:: checks, static visible-copy translation guards, and manifest render-budget assertions. Route-backed visual evidence is captured through docs/screenshots.json; deeper CSS visual assertions remain future QA depth. — tests/Unit/, tests/Feature/Commands/DemoCommandTest.php, docs/screenshots.json

5. Marketplace & Selling

Critique. Marketplace and Composer copy are now buyer-facing, code blocks have a dedicated prose treatment, and the static visual story is conservative but honest: capell.json promotes the strongest real route-backed light/dark homepage captures while keeping weaker inner-route captures as runner evidence.

Improved 1-sentence summary:

A premium knowledge-base and documentation theme for Capell — sidebar-navigated articles, in-page table of contents, prominent search, and readable long-form layouts out of the box.

Improved 3–4 sentence description:

Theme Knowledge turns a Capell site into a polished documentation and help centre. It pairs a category sidebar, sticky table of contents, code-friendly prose, and breadcrumb trails with a prominent search experience and readable long-form typography, so visitors find answers fast. Resource libraries, author bios, topic hubs, and newsletter capture round out a full knowledge-marketing surface, with optional Blog, Search, and Newsletter integrations lighting up automatically when those packages are installed. Built on the Capell foundation theme with a configurable colour palette and accessible focus states.

Screenshot/media status. The 7 light renders and 2 dark renders are committed to docs/screenshots/ from real seeded package routes. Seeded anonymous homepage light/dark captures render the real styled Knowledge shell through the Capell runner and are promoted in capell.json; the shared screenshot wrapper suppresses the Insights consent panel.

Differentiation / target buyer. Today the theme is hard to distinguish from a generic editorial/marketing theme. Target buyer: documentation/help-centre owners, dev-tool/SaaS teams, and internal-knowledge-base operators who want a docs site without a separate static-site generator. The wedge is “docs site inside your CMS” — sidebar + TOC + search + versioning — which no sibling theme currently fills.

8–12 keywords/tags: knowledge base, documentation, help center, docs theme, technical docs, sidebar navigation, table of contents, search, code blocks, resource library, developer docs, editorial.

6. Prioritized Roadmap

Item	Bucket	Effort	Impact	Section ref
Done/Shipped: Add doc/article layout (sidebar + TOC + breadcrumbs) backing knowledge-docs-layout.svg	Done	L	High	§3
Make search-listing a real, prominent search form (cross-sell capell-app/search)	Done	M	High	§3, §2.6
Done/Shipped 2026-06-06: Replace generic theme-gallery fixture PNGs with real Theme Knowledge renderer captures	Done	M	High	§4, §5
Done/Shipped: Add code-block / pre/code prose styling	Done	M	High	§3
Done/Shipped 2026-06-06: capture a real dark screenshot through a Theme Knowledge CSS fixture	Done	M	High	§2.3, §5
Done/Shipped: Tokenize hardcoded hex to preset --site-theme-* variables	Done	L	Med	§2.4
Done/Shipped: Constrained prose measure + heading-scale readability pass	Done	M	Med	§2.7
Done/Shipped: prefers-reduced-motion guard on animated grid ::before	Done	S	Low	§2.5
Remove CapellCore::isPackageInstalled from newsletter/search-listing Blade; rely on renderer flags	Done	S	Med	§4
Fix untranslated/hardcoded copy in authors (and data-drive it)	Done	M	Med	§2.2, §4
Data-drive topic-hubs instead of fixed 4 labels	Done	M	Med	§2.1
Rewrite marketplace summary; tighten description	Done	S	High	§5
Implement real ThemeKnowledgeHealthCheck logic (views/renderer/assets)	Done	S	Med	§4
Done/Shipped: Article feedback (“Was this helpful?”) affordance	Done	M	Med	§3
Done/Shipped: Versioning / “last updated” freshness affordance	Done	L	Med	§3
Done/Shipped 2026-06-06: extend PublicOutputSafetyTest with visible-copy guard; assert render budget in manifest coverage	Done	M	Med	§4

Completion Review

Completed 2026-06-06. Every prioritized roadmap row is closed. Theme Knowledge now ships doc/article layout, functional search form, real route-backed light/dark screenshot evidence, code/prose styling, tokenized colours, readable long-form measures, reduced-motion handling, package-safe public Blade, data-driven authors/topic hubs, health diagnostics, feedback/version affordances, semantic placeholders, and public-output/render-budget guard coverage. Verification for the final slice used the Capell screenshot runner, visual inspection of the dark homepage capture, PHP lint, JSON validation, screenshot manifest validation, and whitespace checks; Pest/composer tests were intentionally skipped per instruction.