UI Components Overview

Relevant source files

The following files were used as context for generating this wiki page:

• src/components/ArchivePanel.svelte
• src/components/LightDarkSwitch.svelte
• src/components/Search.svelte
• src/config.ts
• src/constants/constants.ts
• src/plugins/expressive-code/code-toolbar.ts
• src/styles/markdown.css
• src/styles/transition.css

The Charlotte blog theme utilizes a combination of Svelte for interactive components, Astro for the static site structure, and Tailwind CSS for styling. The user interface is composed of several key Svelte components that provide dynamic functionality such as theme switching, content searching, and post archiving. These components are designed to be modular and are heavily influenced by a central configuration system.

Styling is managed through a mix of Tailwind CSS utility classes, custom stylesheets for specific contexts like Markdown rendering, and dedicated CSS for animations and page transitions. Global settings defined in src/config.ts and layout constants from src/constants/constants.ts allow for high-level customization of the site's appearance and behavior, from theme colors to banner dimensions.

Core Interactive Components

The primary interactive elements of the UI are built as Svelte components, providing a reactive user experience.

ArchivePanel.svelte

This component is responsible for rendering the post archive page. It groups posts by year and allows for filtering based on URL query parameters.

Functionality:

• Receives a list of all sorted posts (sortedPosts) as a prop.
• On component mount, it reads tag, category, and uncategorized from the URL's query string to filter the posts.
• The filtered posts are then grouped by their publication year.
• The component iterates through the year groups, displaying each year as a heading followed by a list of posts from that year.
• Each post in the list displays its publication date, title, and associated tags (on wider screens).

Sources: src/components/ArchivePanel.svelte

The following diagram illustrates the data flow within the ArchivePanel component upon loading.

LightDarkSwitch.svelte

This component provides the user with controls to change the website's color scheme. It supports light, dark, and an automatic mode that respects the user's operating system preference.

Functionality:

• Manages the current theme state (mode), which can be light, dark, or auto.
• On mount, it retrieves the user's saved theme from local storage via getStoredTheme() and listens for system-level color scheme changes.
• A primary button toggles the theme in a cycle: light -> dark -> auto.
• On desktop, hovering over the button reveals a panel for direct selection of any of the three modes.
• The selected theme is applied to the document and persisted in local storage using applyThemeToDocument() and setTheme().

Sources: src/components/LightDarkSwitch.svelte, src/constants/constants.ts:3-5

The state transitions for the theme switcher are shown below.

Search.svelte

The Search component integrates with Pagefind to provide fast, client-side search functionality. It features a responsive design with different presentations for desktop and mobile.

Functionality:

• In production environments, it uses the window.pagefind.search() function to query an index built at compile time.
• In development, it returns mock search results, as the Pagefind index is not available.
• A search bar is displayed in the main navigation on desktop and within a floating panel on mobile.
• As the user types, the search function is invoked, and the results are displayed in a panel.
• The search result items link directly to the relevant page and show an excerpt with the keyword highlighted.

Sources: src/components/Search.svelte

This sequence diagram shows the interaction between the user, the Svelte component, and the Pagefind library during a search query.

Content-Specific UI Elements

Code Block Toolbar

To enhance the readability and utility of code blocks, the site uses a custom Expressive Code plugin to add a toolbar.

Features:

• Language Badge: Automatically displays the language of the code block (e.g., typescript, shell).
• Title: An optional title can be displayed in the center of the toolbar by adding title="Your Title" to the markdown code fence.
• Copy Button: A button on the right allows users to copy the code to their clipboard. It provides visual feedback by briefly changing to a "success" icon.

This plugin is implemented in src/plugins/expressive-code/code-toolbar.ts and works by hooking into Expressive Code's postprocessRenderedBlock lifecycle to inject the toolbar elements into the rendered HTML structure.

Toolbar Element	Description	Source Function
Language Badge	Displays the code language. Defaults to "text".	createLanguageBadge()
Title	Displays a title extracted from markdown meta.	createToolbar()
Copy Button	Copies code. Shows a success icon on click.	createCopyButton()

Sources: src/plugins/expressive-code/code-toolbar.ts

Styling and Animation

The visual presentation and motion design are handled by dedicated CSS files that work in conjunction with Tailwind CSS.

Component Transitions

Page transitions and component load-in effects are defined in src/styles/transition.css.

• Page Transitions: The site uses Swup.js for smooth page transitions. When navigating, the html.is-animating .transition-swup-fade class is applied to fade out the old content and fade in the new.
• Onload Animations: A fade-in-up keyframe animation is used to animate components as they load. Different components have staggered animation-delay values to create a sequential, orchestrated entrance effect.

Component Selector	Animation Delay
#navbar	0ms
#sidebar	100ms
#content-wrapper	var(--content-delay)
.footer	250ms

Sources: src/styles/transition.css

Markdown Content Styling

The file src/styles/markdown.css provides custom styling for content rendered from Markdown files, ensuring a consistent and polished look for articles.

• Headings: On hover, an anchor link icon (#) appears, allowing for direct linking to sections.
• Inline Code: Styled with a distinct background color and the 'JetBrains Mono Variable' font for better code readability.
• Blockquotes: Styled with a vertical bar on the left instead of traditional quotation marks.
• Code Blocks: The layout is adjusted to accommodate the custom toolbar, and the text selection color is customized.

Sources: src/styles/markdown.css

UI Configuration

Many aspects of the UI are controlled through centralized configuration files, making it easy to customize the site's appearance without modifying component logic.

Global Layout Constants

The src/constants/constants.ts file defines fixed dimensional values for key layout elements.

Constant	Value	Description
BANNER_HEIGHT	35 (vh)	The base height of the banner on most pages.
BANNER_HEIGHT_EXTEND	35 (vh)	Additional height added to the banner on the homepage.
NAVBAR_HEIGHT	4.5 (rem)	The height of the main navigation bar.
PAGE_WIDTH	clamp(64rem, 70vw, 78rem)	The responsive width of the main content area.

Sources: src/constants/constants.ts

Site-wide UI Settings

The src/config.ts file is the central hub for configuring the site's UI. The siteConfig object contains properties that control everything from the theme to the banner.

siteConfig Property	Description
themeColor	Sets the base hue for the site's color palette and whether the user can change it (fixed: boolean).
defaultTheme	Defines the initial theme on first visit (light, dark, or auto).
banner	Configures the main banner's visibility, image source, text titles, and colors.
toc	Controls the table of contents on post pages, including its visibility (enable) and heading depth (depth).

Sources: src/config.ts:9-55