Scholia Design System
Relevant source files
The following files were used as context for generating this wiki page:
Scholia is the design system for the Marginalia studio, a local web application used to read machine-written code reviews. It follows the creative concept of "The Reading Desk," prioritizing a high-contrast, technical, and dense interface that stays out of the way of the review content. The system emphasizes flat surfaces, graphite neutrals, and specific signal colors to indicate status and action.
The system is implemented using React, Vite, and Tailwind CSS. It is documented using Storybook, which provides a live reference for foundations and presentational components.
Sources: DESIGN.md:94-100, README.md:162-167, studio/src/stories/Foundations.stories.tsx:4-6
Visual Foundations
The Scholia design system relies on a set of core tokens for colors, typography, and spacing to maintain consistency across the studio.
Color Palette
The palette consists primarily of graphite neutrals and one "Signal Blue" reserved for selection and focus. Status is always double-coded, meaning it uses both color and an icon or text to convey meaning.
| Token Name | OKLCH Value | Application |
|---|---|---|
| Signal Blue | 62.3% 0.214 259.815 | Selection, unread dots, keyboard focus. |
| Action Blue | 54.6% 0.245 262.881 | Primary action buttons (e.g., Post comment). |
| Changes Red | 57.7% 0.245 27.325 | "Request changes" verdicts, critical findings. |
| Approved Green | 59.6% 0.145 163.225 | "Approve" verdicts, success states. |
| Important Amber | 55.5% 0.163 48.998 | "Important" findings, pending review alerts. |
| Graphite Canvas | 14.1% 0.005 285.823 | Page background (dark mode). |
Sources: DESIGN.md:126-160, studio/src/stories/Foundations.stories.tsx:13-30
Typography Hierarchy
Scholia uses the system sans-serif stack for all interface and prose text. Monospace fonts are strictly reserved for code, file paths, and identifiers.
- Display: 1.875rem (600 weight), used only for the Home page title.
- Headline: 1.5rem (600 weight), used for review titles.
- Title: 1rem (500 weight), used for section headings.
- Body: 0.875rem (400 weight), the default for buttons, lists, and card text.
- Prose: 1rem (400 weight), used for the main review text with an 80ch measure cap.
- Label: 0.75rem (400 weight), used for metadata, counts, and timestamps.
Sources: DESIGN.md:183-203, studio/src/stories/Foundations.stories.tsx:55-68
Layout and Composition
The studio layout uses a sticky chrome structure to keep navigation and status visible while scrolling through long reviews.
The layout uses a 4px base spacing rhythm. Standard increments include 8px for compact controls, 12px for related items, 16px for card padding, and 24px for page gutters.
Sources: DESIGN.md:209-221, studio/src/stories/Foundations.stories.tsx:78-88
Component Architecture
Components in Scholia are designed for density and technical clarity.
Cards and Containers
Cards use a 12px corner radius and a 1px hairline border. Hierarchy is achieved through tonal shifts rather than shadows. Shadows are reactive and only appear during hover states or for modal dialogs.
Sources: DESIGN.md:225-236, DESIGN.md:265-274
Status Verdicts
Verdicts are the most prominent visual elements. They are derived from the review's findings.json or parsed directly from Markdown.
| Verdict | Meaning | Design Treatment |
|---|---|---|
| APPROVE | No critical/important issues. | Approved Green + Check Icon. |
| REQUEST_CHANGES | Critical issues found. | Changes Red + X/Alert Icon. |
| OTHER | Neutral feedback. | Neutral / Semantic Violet. |
Sources: README.md:65-72, studio/src/lib/api.ts:6-15
Content Processing
The system includes specific logic to transform raw Markdown reports into structured UI components.
Section Parsing
The splitSections function divides Markdown content based on ## or ### headings while ignoring code fences. Sections are ranked to ensure a consistent reading order:
- Summary / At a Glance
- Shape of the Change
- Critical Findings
- Important Findings
- Suggestions
- Out of Scope
Sources: studio/src/lib/reviewSections.ts:8-40
Linkification and References
Scholia automatically detects and links GitLab merge request references (e.g., !123) and file paths within the review text.
Design Principles and Constraints
- Flat-By-Default: No surface has a resting shadow.
- The Signal Rule: Blue is never used for decoration; it only signifies selection, focus, or the primary action.
- No Playfulness: The system explicitly rejects consumer-app trends like very round corners, bright decorative colors, or cheerful copy.
- English Only: The interface language is strictly English.
- Long-Word Handling: Because reviews contain long identifiers and paths, prose components set
overflow-wrap: anywhereto prevent layout breaks.
Sources: DESIGN.md:112-120, DESIGN.md:300-315, PRODUCT.md:79-81
The Scholia Design System provides a rigid, professional framework that ensures machine-generated reviews remain legible and actionable for developers. By strictly defining color usage and typography, it minimizes visual noise and focuses the user's attention on code quality and risk assessment.