Markdown & Theming
Relevant source files
The following files were used as context for generating this wiki page:
Markdown & Theming encompasses the systems used to render agent-generated content and maintain a consistent visual identity across the Opificia project. The project utilizes Markdown for implementation plans, pull request descriptions, and agent communications. Theming is controlled through CSS variables that follow a specific brand book, supporting both light and dark modes without external dependencies.
Markdown Rendering and Security
Opificia renders Markdown within the web application to display agent plans and messages. The renderer is loaded lazily to reduce initial bundle size and includes strict security measures to prevent data exfiltration and cross-site scripting (XSS).
Security Constraints
The Markdown system enforces specific security rules during rendering:
- It converts raw HTML into plain text instead of rendering it as active elements.
- It blocks the loading of all images to prevent agents from sending data to external hosts via tracking pixels.
- It intercepts link clicks and requires user confirmation before opening.
- It removes
javascript:links and other script-based URI schemes.
Sources: apps/web/src/markdown.test.tsx:18-40, apps/web/src/run/conversation.tsx:43-51
Formatting Standards
Agents must follow specific Markdown structures for consistency. Pull request descriptions and implementation plans include standard headers:
## Summary: High-level overview of changes.## Changes: List of modified files.## Tests: Verification steps.## Risks: Potential side effects.
Sources: plugins/harness-claude/src/prompts.ts:85-115
Rendering Pipeline
The rendering pipeline ensures that large Markdown chunks do not block the main thread by utilizing React's Suspense and lazy loading.
The flow shows how agent content is processed before being displayed in the conversation interface.
Sources: apps/web/src/run/conversation.tsx:43-51, apps/web/src/markdown.test.tsx:8-16
Brand Identity and Theming
Theming is driven by "Brand Book Tokens" defined in CSS. The project uses a specific color palette consisting primarily of Navy, Gold, and Slate.
Color Tokens
The theme defines core colors as CSS variables to ensure consistency across the website and web application.
| Variable | HEX Value | Purpose |
|---|---|---|
--navy | #10194A | Primary brand color, backgrounds. |
--gold | #F2B705 | Attention, human intervention required. |
--white | #FFFFFF | Text on dark backgrounds, surface color. |
--ink | #10194A | Default text color. |
--line | #D3D8E6 | Borders and dividers. |
Sources: website/styles.css:36-58, AGENTS.md:79-82
Dark Mode Support
The theme uses the prefers-color-scheme media query to automatically switch between light and dark modes. It redefines variable values to maintain readability in dark environments.
This diagram illustrates the conditional logic for applying theme variables based on system settings.
Sources: website/styles.css:76-85, website/index.html:10
Typography
The project uses two primary typefaces served locally to maintain privacy and performance:
- Archivo: Used for display text and headings.
- IBM Plex Mono: Used for code blocks, tags, and technical details.
Sources: website/styles.css:3-33, website/index.html:20
Component Styling
Components like the "Rack" and "Status Tags" use themed CSS variables to reflect the Opificia visual identity.
The Rack Component
The Rack is a decorative element representing the software factory. It uses a repeating linear gradient based on the --tooth and --pitch variables. A specific "slot" is highlighted using the --slot variable to indicate the project's current state or focus.
| Property | Value | Description |
|---|---|---|
--tooth | 12px | Width of a single rack tooth. |
--pitch | 24px | Distance between teeth. |
--slot | 9, 19, or 31 | Position of the highlighted slot based on screen width. |
Sources: website/styles.css:66-74, website/index.html:28-29
Status Indicators
Status indicators use specific color combinations to convey meaning:
- Navy/Slate: Default states.
- Gold: Action required by a person.
- Red/Bad: Failure or blocked actions.
- Green/Ok: Success or passing checks.
Sources: AGENTS.md:79-82, apps/web/src/run/conversation.tsx:165-175
Implementation Details
Prose Styles
Markdown content is wrapped in a .prose-run or .section-head container. These containers define spacing, line heights, and font weights for standard Markdown elements like lists and headers.
.section-head h2 {
font-size: clamp(30px, 4.5vw, 44px);
line-height: 1.1;
font-weight: 700;
letter-spacing: -0.025em;
}
Sources: website/styles.css:186-192, apps/web/src/run/conversation.tsx:44-51
Local Resource Loading
To comply with sovereignty commitments, no fonts or styles are loaded from third-party servers. All assets are served from the local /fonts/ or /assets/ directories.
Sources: website/index.html:20-21, AGENTS.md:15-18
The Markdown and Theming systems provide a secure, consistent, and performant interface for interacting with AI agents while adhering to the project's core principles of self-hosting and data sovereignty.