Theming: New Theming Pattern for Easier Customization

[hnb-ku]

This issue proposes a new pattern to make theming the application easier and more maintainable.

Core Idea:

The idea is to shift towards a more component-centric architecture, separating data fetching and logic from presentation, and allowing themes to override both CSS and component templates (with guardrails).

Implementation Details:

1. Minimal Logic in Routes: Remove styling and logic from +page.svelte files. Keep most non-client-side logic in +page.server.ts and pass data down to components.
2. Component-Based Routes: Add a components folder inside each route, containing smaller components focused on presentation.
3. Common Component Library: Move frequently used components to $lib/components for global reusability.
4. Initial Tailwind Styling: Use Tailwind CSS in the initial refactor to reduce review/explanation overhead.
5. $props for Props: Use the $props rune for accessing props in Svelte 5 components.

Theming Vision:

• Primary Focus: CSS-Based Theming: Site admins should be able to override colors, spacing, etc., using a single theme.css file.
• Secondary: Template Overrides: Offer a controlled option to override specific component templates.
• Future Exploration: We'll investigate alternative CSS theming strategies (CSS variables/open props, theming libraries) for more complex scenarios.

Guardrails for Theming:

1. CSS Changes are Safe: Site admins are responsible for CSS-only theme changes.
2. Template Override Responsibility: Theme developers are responsible for maintaining template overrides.

This enables:

• Faster Core Development: We can iterate quickly without worrying about breaking themes.
• Theme Developer Control: Themes have flexibility but also clear responsibilities.

Theming Hierarchy:

1. Global CSS Overrides: theme.css for site-wide styling changes.
2. Component Template Overrides: Replace default templates for specific components.
3. Route-Level Overrides: Override the entire Page.svelte component for a route.
4. No Server-Side Theming: Theming changes should not affect +page.server.ts files.

Implementation Stages:

1. Component-Based Refactoring: Convert routes to the new pattern (one route per PR), keeping existing logic and using Tailwind.
2. Extract Common Components: Move frequently used components to the $lib folder.
3. Establish Default Theme: Create the default theme (likely Tailwind-based).
4. Investigate CSS Theming: Explore advanced CSS theming options (open props, libraries).

[hnb-ku]

This is a list to track the current work on stage 1

• [ ] (app)/[username]/[slug]/+page.svelte
• [ ] (app)/[username]/mastodon/+page.svelte
• [ ] (app)/[username]/+page.svelte
• [ ] (app)/account/[user_id]/custom-domain/+page.svelte
• [ ] (app)/account/codeberg/profile/+page.svelte
• [ ] (app)/account/codeberg/+page.svelte
• [ ] (app)/account/forgot-password/+page.svelte
• [ ] (app)/account/github/profile/readme/+page.svelte
• [ ] (app)/account/github/profile/+page.svelte
• [ ] (app)/account/github/+page.svelte
• [ ] (app)/account/link-mastodon/+page.svelte
• [ ] (app)/account/linktree/profile/+page.svelte
• [ ] (app)/account/linktree/+page.svelte
• [ ] (app)/account/pages/edit/[slug]/+page.svelte
• [ ] (app)/account/pages/new/+page.svelte
• [ ] (app)/account/pages/+page.svelte
• [ ] (app)/account/register/confirmation/+page.svelte
• [ ] (app)/account/update/+page.svelte
• [ ] (app)/account/zulip/profile/+page.svelte
• [ ] (app)/account/zulip/+page.svelte
• [ ] (app)/auth/v1/account/+page.svelte
• [ ] (app)/auth/v1/oidc/authorize/worker/+page.svelte
• [ ] (app)/auth/v1/oidc/authorize/+page.svelte
• [ ] (app)/auth/v1/oidc/logout/+page.svelte
• [ ] (app)/auth/v1/providers/callback/+page.svelte
• [ ] (app)/auth/v1/users/[user]/reset/[token]/+page.svelte
• [ ] (app)/auth/v1/users/register/+page.svelte
• [ ] (app)/connect/discord/[linkId]/+page.svelte
• [ ] (app)/feedback/confirmation/+page.svelte
• [ ] (app)/feedback/+page.svelte
• [ ] (app)/people/+page.svelte
• [ ] (app)/+layout.svelte
• [ ] (internal)/__internal__/admin/update-username-domains/+page.svelte
• [ ] (internal)/__internal__/admin/+page.svelte
• [ ] (subsites)/subsite/[usernameOrDomain]/+page.svelte

[hnb-ku]

• (app)/[username]/[slug]/+page.svelte

https://github.com/muni-town/weird/pull/188