# Theme Development Guide Guide for theme designers, UI/UX designers, and front-end engineers who want to build Traven themes from scratch, customize an existing skin, or ship a Traven-aware theme for a CMS or static site. Traven's skinning model is intentionally decoupled: themes are **plain CSS files** with no JavaScript and no build step. The editor engine and the shortcode widgets are class-driven, so every visual decision — fonts, colors, borders, spacing, alignment, and dark-mode behavior — lives in your theme. The trade-off is that the WYSIWYM (live) editor and the HTML preview share the same content but use **two different DOM scopes**, and a complete theme must style both. This document is a comprehensive guide to styling Traven, detailing the side-by-side skin comparisons, the canonical selector reference, a "what every theme must include" QA checklist, and recipes for styling elements in both the editor and preview DOM scopes (including the raw Markdown pane, Vim's fat cursor, scrollbars, and LaTeX math widgets). ## Quick Start: How to Build or Extend a Skin ### Building a Skin from Scratch 1. **Duplicate a Base Theme**: Copy `packages/core/assets/skins/skin-light.css` and rename it (e.g., `skin-forest.css`). 2. **Define Fonts and Variables**: Import your preferred typography (e.g., from Google Fonts, or locally loaded for better reader privacy and no telemetry) and update the main CSS color variables. 3. **Adjust Editor Typography**: Map heading styles and inline code elements. Make sure to apply `!important` to headings padding. 4. **Set Up Shortcode Styles**: Target the CodeMirror widget containers (`.cm-wysiwym-*`) and the HTML Preview equivalents (`.traven-preview *`) using the cheat sheet selectors. 5. **Test Dark Mode**: Ensure variables and overrides resolve correctly when `.cm-wysiwym-dark` is toggled. 6. **Load the Skin**: Link your stylesheet in the `` of your host application: ```html ``` ### Extending an Existing Skin If you just want to tweak colors or minor settings on an existing skin without modifying its source file: 1. Create a custom override stylesheet (e.g., `theme-overrides.css`). 2. Import or load the main skin first: ```html ``` 3. Apply specific overrides using CSS variables or classes: ```css /* Tweak Editorial theme default link colors */ .cm-wysiwym-link-anchor, .traven-preview a { color: #059669 !important; /* Emphatic emerald green */ } ``` --- ## 1. Mental model: two scopes, one CSS file A Traven skin is a single `.css` file that targets **two cooperating DOM trees** rendered by the same editor: ```mermaid graph TD A[packages/core/assets/skins/skin-yourname.css] -->|styles| B[Editor Scope: .cm-editor] A -->|styles| C[Preview Scope: .traven-preview] B -->|WYSIWYM| W[Writer's live view] C -->|Compiled HTML| P[Reader's preview] A -.->|optional| D[Raw Markdown Pane: .raw-editor-mount] A -.->|always| E[Dark-mode: .cm-wysiwym-dark] ``` 1. **Editor scope (`.cm-editor`)** — the live WYSIWYM canvas. Traven translates Markdown tokens into visual elements using CodeMirror 6 decorations. Live editor classes are prefixed with `.cm-wysiwym-*` (for example `.cm-wysiwym-bold`, `.cm-wysiwym-blockquote`, `.cm-wysiwym-inline-code`). 2. **Preview scope (`.traven-preview`)** — the compiled HTML output displayed in the preview pane. It is styled using normal native HTML selectors nested inside the wrapper class (for example `.traven-preview h1`, `.traven-preview blockquote`, `.traven-preview img`). 3. **Raw editor scope (`.raw-editor-mount`)** — optional split-pane that shows raw Markdown source. Most themes restyle the raw pane to use a monospace font. 4. **Dark mode** — controlled by the `.cm-wysiwym-dark` class on the editor host node (and the preview container, when present). See [§7](#7-dark-mode) for details. > IMPORTANT: A complete theme styles **both** the editor and the preview. If a heading looks right in the live editor but cropped in the preview, or vice-versa, the writer will assume the theme is broken. --- ## 2. The eight shipping skins, side by side All eight skins live in `packages/core/assets/skins/` and are auto-discovered by the customization dropdown (`includes/_customization-dropdowns.php`); any new file you add to that directory shows up in the demo page's skin picker with no further wiring. | Skin | Design intent | Body font | Mono font | Gutter | Headings | Caret | Accent | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | `skin-starter.css` ⭐ | Modern Georgia — base (**bundled default**) | `Georgia` (serif) | System monospace | Visible, soft slate | System sans, bold | Slate 900 | Slate 600 | | `skin-light.css` | Neutral Slate — baseline | `Atkinson Hyperlegible Next` (Google Fonts) | `Fira Code` (Google Fonts) | Visible, soft slate | Bold sans, tight | Slate 900 | Slate 600 | | `skin-colorful.css` | Warm Rust — expressive | `Atkinson Hyperlegible Next` (Google Fonts) | `Fira Code` (Google Fonts) | Visible, indigo active | Bold sans, bright rust caret | `#cc4a0a` rust | `#3b82f6` indigo | | `skin-dark.css` | Premium Dark Slate | `Atkinson Hyperlegible Next` (Google Fonts) | `Fira Code` (Google Fonts) | Visible, dim slate | Bold sans, near-white | Sky `#38bdf8` | Sky `#38bdf8` | | `skin-editorial.css` | Minimalist Focus — no chrome | `Goudy Bookletter 1911` (serif) | `Victor Mono` | Visible, soft slate | `Macondo` (h1–h3), Goudy (h4–h6) | Ink black | None — pure paper | | `skin-modern.css` | Modern Clean — premium | `Epunda Slab` (serif) | `JetBrains Mono` | Visible, borderless | `Saira Condensed` (sans) | Zinc 900 | `#115e59` teal | | `skin-academic.css` | Classic LaTeX Booktabs | `Source Serif 4` (serif) | `Courier Prime` | Visible, soft slate | Serif, booktabs tables | Oxblood `#7a2226` | Oxblood `#7a2226` | | `skin-custom.css` | Dynamic parameterized fonts | Configurable via `--traven-font-body` | Configurable via `--traven-font-mono` | Inherits starter | Configurable via `--traven-font-display` | Slate 900 | Slate 600 | Other dimensions worth knowing: * **External requests.** `skin-light.css`, `skin-dark.css`, `skin-colorful.css`, `skin-editorial.css`, `skin-modern.css`, and `skin-academic.css` `@import` from Google Fonts by default. `skin-starter.css` and `skin-custom.css` load zero web fonts on initial request. Custom font loading for `skin-custom.css` is handled dynamically at runtime by the host page. See [§10](#10-telemetry--offline-self-hosting) for self-hosting setups. * **First-load fonts.** `skin-light.css`, `skin-dark.css`, and `skin-academic.css` import Atkinson Hyperlegible, Fira Code, Source Serif 4, and/or Courier Prime from Google Fonts. `skin-starter.css` uses system fonts only. * **Blockquote treatment.** The `skin-light`, `skin-colorful`, `skin-dark`, `skin-modern`, and `skin-starter` themes use a thick left bar. The `skin-editorial` theme uses a decorative `::before` curly-quote mark. The `skin-academic` theme uses a transparent background with a simple left bar. * **Info / warning cards.** The `skin-light`, `skin-colorful`, `skin-dark`, `skin-modern`, and `skin-starter` themes render these as soft rounded/bordered cards. The `skin-editorial` theme uses the "hand-drawn" organic border-radius. The `skin-academic` theme uses clean rectangular left-bordered callout boxes matching the academic position paper callout style. * **Pullquote dividers.** Only the `skin-editorial` theme renders the decorative wave SVG above and below `.traven-component-pullquote`; the other themes use simple top/bottom rules. When in doubt, copy the theme that is closest to your goal and patch its variables. --- ## 3. The selector reference The list below covers every selector a complete theme should consider. Anything in **bold** is required; anything in *italics* is optional but recommended; the rest is "if the feature is visible in your demo, style it." ### 3.1 Editor scope — `.cm-editor` #### Chrome | Selector | Required? | Notes | | :--- | :--- | :--- | | `.cm-editor` | **Yes** | Base wrapper. Set `font-family`, `background-color`, `color`. | | `.cm-editor:focus`, `.cm-editor.cm-focused` | Recommended | Strip the default focus ring. | | `.cm-scroller` | Recommended | Inner scroll viewport. Inherit font, set `line-height` and vertical padding. | | `.cm-content` | Recommended | Sets horizontal padding (typical: `0 24px`). | | `.cm-line` | Optional | General line. **Never** apply `padding: 0` here unless you also re-pad every heading variant. | | `.cm-gutters`, `.cm-gutterElement` | Optional | Line-number column. Hide with `display: none !important` for a paper feel. | | `.cm-activeLine` | Optional | Soft tint of the active line. | | `.cm-activeLineGutter` | Optional | Active line indicator in the gutter. | | `.cm-selectionBackground`, `.cm-native-selection` | **Yes** | Selection highlight. The focused variant uses `.cm-editor.cm-focused > .cm-scroller > .cm-selectionLayer .cm-selectionBackground`. | | `.cm-cursor` | **Yes** | Caret color. | | `.cm-fat-cursor` | **Yes** | Vim Normal-mode block cursor. Always set `opacity: 0.6 !important` so the character underneath is readable. | | Scrollbars: `.cm-editor ::-webkit-scrollbar*` | Optional | Skinnable per theme. | #### Inline marks (all required) | Selector | Purpose | | :--- | :--- | | `.cm-wysiwym-bold` | Bold text | | `.cm-wysiwym-italic` | Italic text | | `.cm-wysiwym-strikethrough` | ~~strikethrough~~ | | `.cm-wysiwym-highlight` | `==highlight==` mark | | `.cm-wysiwym-inline-code` | `` `inline code` `` pill | | `.cm-wysiwym-link-anchor` | Live link anchor (Ctrl/Cmd-click) | | `.cm-wysiwym-bullet` | Custom list bullet glyph | | `cmt-heading`, `tok-heading`, `span` inside `.cm-wysiwym-h1`–`h6` | Strip any default underline from the highlighter. | #### Block-level live elements | Selector | Purpose | | :--- | :--- | | `.cm-wysiwym-h1` … `.cm-wysiwym-h6` | Live heading lines (one class per level). **Use `padding` (not `margin`) and add `!important`.** | | `.cm-wysiwym-blockquote` | Live blockquote lines. Use the `:has()` sibling selectors (see [§4.2](#42-blockquotes-and-the-has-trick)) to style first, middle, and last lines. | | `.cm-wysiwym-frontmatter` | YAML frontmatter block. | | `.cm-wysiwym-frontmatter-active` | Active frontmatter line (the one the cursor is on). | | `.cm-wysiwym-hr-widget` | Horizontal rule replacement. | | `.cm-wysiwym-codeblock-line` | One line inside a fenced code block. Use `-first` / `-last` modifiers for rounded corners. | | `.cm-wysiwym-collapsed-fence` | A fence line whose text is hidden but the empty container still occupies space. **Set `height: 0 !important`.** | | `.cm-wysiwym-image-widget-container` | Legacy plain `![alt](src)` Markdown image widget. | | `.cm-wysiwym-image-shortcode-container` | Advanced `[image ...]` shortcode widget. Same alignment helpers (`.align-left`, etc.) as the preview. | | `.cm-wysiwym-image-caption` | Caption text under the legacy image widget. | | `.cm-wysiwym-image-shortcode-container .shortcode-meta` | The meta row under the advanced shortcode widget. | | `.cm-wysiwym-image-shortcode-container .meta-badge` | "Tag name" pill (`[IMAGE]`, etc.). Use `.tag-name` for the first badge. | | `.cm-wysiwym-image-uploading` | Optimistic upload pill (green dashed border). | | `.cm-wysiwym-video-shortcode-container` | `[video]` widget. | | `.cm-wysiwym-video-shortcode-container .video-placeholder`, `.video-placeholder-icon-wrap`, `.video-placeholder-details`, `.video-placeholder-platform`, `.video-placeholder-url` | Pieces of the video placeholder card. | | `.cm-wysiwym-audio-shortcode-container` | `[audio]` widget, same shape as the video container. | | `.cm-wysiwym-component-shortcode` | Generic `[component]` block, plus variants `.component-blockquote`, `.component-pullquote`, `.component-info`, `.component-warning`. | | `.cm-wysiwym-component-shortcode .component-body` | Inner body container. | | `.cm-wysiwym-component-shortcode .component-body p` | Paragraphs inside the body. | | `.cm-wysiwym-component-shortcode cite` | The "— Author, Source" line on blockquote components. | | `.cm-wysiwym-figure-shortcode` | `[figure]` widget. Contains `.component-body` and `.figure-caption`. | | `.cm-wysiwym-table-row` | GFM table source line in raw editing mode. | | `.cm-wysiwym-table-widget` | Rendered WYSIWYM table (when the cursor is outside). Style `.cm-wysiwym-table-widget table`, `th`, `td` normally. | | `.cm-wysiwym-inline-math-widget` | Live LaTeX inline equation. | | `.cm-wysiwym-block-math-widget` | Live LaTeX display equation. | | `.katex-inline-fallback`, `.katex-display-fallback` | Fallback rendering when KaTeX is not loaded. | #### Hover-edit icons All block widgets have an absolute-positioned icon that appears on hover: * `.cm-wysiwym-image-shortcode-container .image-edit-icon` * `.cm-wysiwym-video-shortcode-container .video-edit-icon` * `.cm-wysiwym-audio-shortcode-container .audio-edit-icon` * `.cm-wysiwym-component-shortcode .image-edit-icon` * `.cm-wysiwym-figure-shortcode .figure-edit-icon` Style them like 24 × 24 px round buttons with a subtle border, hidden by `opacity: 0` and shown on `:hover` of the parent. #### Syntax highlighting (optional) The CodeMirror Markdown highlighter tags tokens with classes in two parallel namespaces: `tok-*` and `cmt-*`. Style both for safety. The complete list is short: * `tok-markup` / `cmt-markup` — `*`, `_`, `~~`, `` ` `` markers * `tok-meta` / `cmt-meta` * `tok-punctuation` / `cmt-punctuation` * `tok-list` / `cmt-list` — list bullet characters * `tok-comment` / `cmt-comment` — `` * `tok-keyword` / `cmt-keyword` * `tok-string` / `cmt-string` * `tok-number` / `cmt-number`, `tok-boolean` / `cmt-boolean` * `tok-variableName` / `cmt-variableName` * `tok-propertyName` / `cmt-propertyName` * `tok-operator` / `cmt-operator` * `tok-url` / `cmt-url`, `tok-link` / `cmt-link` The shipping skins style only the markdown-relevant subset (`markup`, `meta`, `punctuation`, `list`, `comment`, `keyword`, `string`, `number`). For a content-focused theme that is plenty. ### 3.2 Raw editor scope — `.raw-editor-mount` If the host page mounts a raw Markdown pane (most demos do), the entire CodeMirror tree lives inside a `.raw-editor-mount` wrapper. The default themes override the font and line height: ```css .raw-editor-mount .cm-editor, .raw-editor-mount .cm-content, .raw-editor-mount .cm-scroller, .raw-editor-mount .cm-line { font-family: 'Victor Mono', Courier, monospace !important; font-size: 14px !important; line-height: 2 !important; background-color: transparent !important; color: #1a1a1a !important; } ``` Themes that keep the same mono font as the inline code (e.g. `Fira Code`) can drop this block, but the raw pane should always use **monospace** at a slightly larger size with generous line-height for readability. ### 3.3 Preview scope — `.traven-preview` Targets compiled HTML. Almost all of these are standard selectors nested inside `.traven-preview`. | Selector | Maps to | | :--- | :--- | | `.traven-preview` | Preview wrapper. Set the base font, color, and background. | | `.traven-preview h1` … `h6` | Compiled headings. Set sizes, weights, margins, and family. | | `.traven-preview > h1:first-child`, `> h2:first-child`, `> h3:first-child` | First-child headings — match the editor's `padding-top` to avoid a visual jump. | | `.traven-preview p` | Paragraphs. `line-height` and `margin-bottom` only. | | `.traven-preview ul`, `ol`, `li` | Lists. `padding-left`, `li::marker` (color). | | `.traven-preview blockquote:not(.traven-component-pullquote)` | Native blockquotes. (The `:not()` keeps the `[pullquote]` shortcode from picking these styles up.) | | `.traven-preview pre`, `.traven-preview code` | Code blocks and inline code. | | `.traven-preview a` | Links. | | `.traven-preview mark` | `==highlight==` output. | | `.traven-preview hr` | Horizontal rule. | | `.traven-preview table`, `th`, `td` | GFM tables. Set `height: 38px` on `th`/`td` to keep blank cells from collapsing. | | `.traven-preview img.traven-image-shortcode` | The advanced image shortcode, no caption. | | `.traven-preview figure.traven-image-figure` | The advanced image shortcode, with caption. | | `.traven-preview figure.traven-image-figure figcaption.traven-image-caption` | Caption text. | | `.traven-preview .traven-video-container`, `figure.traven-video-figure` | `[video]` output. | | `.traven-preview figure.traven-video-figure .traven-video-container`, `figcaption.traven-video-caption` | Inner video container + caption. | | `.traven-preview .traven-audio-container`, `figure.traven-audio-figure` | `[audio]` output. | | `.traven-preview .traven-audio-figure figcaption.traven-audio-caption` | Audio caption. | | `.traven-preview .traven-component` | Generic `[component]` card wrapper. | | `.traven-preview .traven-component-blockquote` | The `[quote]` / `[blockquote]` / `[component="blockquote"]` block. | | `.traven-preview .traven-component-blockquote::before` | Decorative opening quote (the editorial/write themes draw it with a `::before`; default/colorful/dark omit it). | | `.traven-preview .traven-component-blockquote footer`, `cite` | The optional citation. | | `.traven-preview .traven-component-pullquote` | The `[pullquote]` block. Optional decorative `::before` / `::after`. | | `.traven-preview .traven-component-info` | The `[info]` notice block. | | `.traven-preview .traven-component-warning` | The `[warning]` notice block. | | `.traven-preview .traven-figure` | The `[figure]` block wrapper. | | `.traven-preview .traven-figure-caption` | The caption inside `.traven-figure`. | | `.traven-preview .traven-figure.align-fullbleed` | Breakout. Apply the same `100vw / calc(-50vw + 50%)` trick used elsewhere. | | `.traven-preview figure.traven-image-figure figcaption.traven-image-caption` | Caption of the `[image]` figure. | #### Alignment helpers (shared between editor and preview) Every shortcode accepts `align="left|right|center|fullbleed"` and `size="small|medium|large|full"`. Both the editor widget and the preview HTML emit these as classes, so a single rule typically covers both scopes: ```css .cm-wysiwym-image-shortcode-container.align-left, .traven-preview figure.traven-image-figure.align-left { ... } /* Or in a combined block: */ .cm-wysiwym-image-shortcode-container, .cm-wysiwym-video-shortcode-container, .cm-wysiwym-audio-shortcode-container, .cm-wysiwym-figure-shortcode { /* shared card chrome */ } .size-small { width: 150px; } .size-medium { width: 300px; } .size-large { width: 600px; } .size-full { width: 100%; } ``` > WARNING: Inside the **editor**, alignment uses auto-margins (e.g. `margin: 0 auto 0 0 !important`). Inside the **preview**, you may use `float: left/right`. Mixing them up breaks CodeMirror's coordinate mapping. See [§4.4](#44-no-floats-or-vertical-margins-in-the-editor) for the full rule. ### 3.4 Modal dialog scope Traven's modal overlay (link, image, video, audio, component, figure, table editor, help, etc.) is rendered in a separate overlay class `.traven-modal-overlay`. The default toolbar stylesheet (`packages/core/assets/toolbars/toolbar-default.css`) handles most of the modal chrome. A theme normally only needs to override these: * `.traven-modal-overlay` — outer backdrop. * `.traven-modal-overlay.cm-wysiwym-dark` — dark-mode modal. * `.traven-modal-btn.btn-primary` / `.btn-secondary` — action buttons. * `.traven-modal-input`, `.traven-modal-textarea`, `.traven-modal-select` — form fields. * `.traven-modal-dropzone` — drag-and-drop file zone. If you ship a dark skin, the toolbar stylesheet's existing `.traven-modal-overlay.cm-wysiwym-dark` rules will look right if the theme's body background and text colors match the editor. If they don't, override the toolbar variables in your theme. --- ## 4. CodeMirror 6 layout-engine rules A handful of CSS assumptions that work everywhere else on the web **break** the WYSIWYM editor. They are not bugs; they are consequences of how CodeMirror 6 measures characters and maps coordinates. Every shipping skin obeys them, and a custom theme that violates them will see cursor clicks land on the wrong lines. ### 4.1 Never use vertical margins on line elements CodeMirror stacks `.cm-line` elements sequentially and re-measures the stack on every layout pass. A `margin-top` on a heading pushes the next line down by an amount CodeMirror does not see, so `posAtCoords` returns a stale position and clicks land above or below where the user actually clicked. Always use `padding` and add `!important` so a generic `.cm-line { padding: 0 }` reset cannot win: ```css .cm-editor .cm-wysiwym-h1 { font-size: 2em; font-weight: 800; line-height: 1.2; padding-top: 24px !important; padding-bottom: 12px !important; margin: 0 !important; } ``` The same rule applies to every other block element that lives on its own line: blockquotes, code-block lines, table rows, list items, and (in [§4.4](#44-no-floats-or-vertical-margins-in-the-editor)) block widgets. ### 4.2 Blockquotes and the `:has()` trick A blockquote in CodeMirror is rendered as **multiple** `.cm-line` siblings that all share the `.cm-wysiwym-blockquote` class. The first line needs top padding, the last line needs bottom padding, and the middle lines need neither, otherwise you get a double-thick bar at the top. The shipping skins use: ```css .cm-editor .cm-wysiwym-blockquote { padding-top: 2px !important; padding-bottom: 2px !important; padding-left: 16px !important; border-left: 3px solid #cbd5e1; margin: 0 !important; } /* First line of the block */ .cm-editor .cm-wysiwym-blockquote { padding-top: 10px !important; } /* Subsequent lines in the same block */ .cm-editor .cm-wysiwym-blockquote + .cm-wysiwym-blockquote { padding-top: 2px !important; } /* Last line of the block */ .cm-editor .cm-wysiwym-blockquote:not(:has(+ .cm-wysiwym-blockquote)) { padding-bottom: 10px !important; } ``` The same trick is used in the preview: `.traven-preview blockquote:not(.traven-component-pullquote) { ... }` and the equivalent `:not(:has(+ ...))` rule for the last line. ### 4.3 Blank-line collapse after headings A blank Markdown line directly after a heading renders as a full-height empty `.cm-line` in the editor, but the preview parser collapses it away. The shipping themes close the gap with: ```css .cm-editor .cm-wysiwym-h1 + .cm-line:has(br:only-child), .cm-editor .cm-wysiwym-h2 + .cm-line:has(br:only-child), .cm-editor .cm-wysiwym-h3 + .cm-line:has(br:only-child) { height: 0.6em !important; min-height: 0.6em !important; } ``` Apply the same pattern around blockquotes (`+ .cm-line:has(br:only-child)` before *and* after) and after code-block fences (see [§4.5](#45-fenced-code-blocks)). ### 4.4 No floats or vertical margins in the editor Block widgets (`.cm-wysiwym-image-shortcode-container`, `.cm-wysiwym-video-shortcode-container`, `.cm-wysiwym-audio-shortcode-container`, `.cm-wysiwym-figure-shortcode`, and the component shortcode variants) are rendered as CodeMirror block decorations. CodeMirror's coordinate mapping assumes they sit in the normal document flow. * **No `float: left` or `float: right`** — floated elements wrap text around themselves, which CodeMirror doesn't expect. The result: mouse clicks below a floated widget land on the wrong line. * **No `margin-top` or `margin-bottom`** — same family of issues as [§4.1](#41-never-use-vertical-margins-on-line-elements). * **Use auto-margins for horizontal alignment:** ```css .cm-wysiwym-image-shortcode-container.align-left { margin: 0 auto 0 0 !important; } .cm-wysiwym-image-shortcode-container.align-right { margin: 0 0 0 auto !important; } .cm-wysiwym-image-shortcode-container.align-center { margin: 0 auto !important; } .cm-wysiwym-image-shortcode-container.align-fullbleed { width: 100% !important; margin: 0 !important; border: none !important; border-radius: 0 !important; } ``` * **In the preview, floats are fine.** `.traven-preview img.traven-image-shortcode.align-left { float: left; ... }` works without breaking anything, because the preview is plain HTML and never goes through CodeMirror's coordinate mapper. ### 4.5 Fenced code blocks When a fenced code block is collapsed (cursor outside), the opening and closing fence lines become empty `.cm-line` containers that still occupy vertical space. The shipping themes mark them with a `.cm-wysiwym-collapsed-fence` class and squash them: ```css .cm-editor .cm-wysiwym-collapsed-fence { height: 0 !important; min-height: 0 !important; padding: 0 !important; margin: 0 !important; border: none !important; overflow: hidden !important; visibility: hidden !important; } ``` For the first / last / middle content lines, use the `-first` / `-last` modifiers to apply rounded corners and `border` rules that stitch the block into a single visual unit. ### 4.6 Character width caching CodeMirror measures and caches character widths on first paint. If your theme loads custom fonts asynchronously (Google Fonts, a self-hosted `font-display: swap` face, etc.), the cache can be populated with the fallback's widths and then never re-measured when the real font loads, causing cursor misalignment. Mitigations: * Defer editor construction until fonts are ready: ```javascript document.fonts.ready.then(() => { new TravenEditor({ element: document.getElementById("editor") }); }); ``` * Avoid `font-display: swap` for the editor's body font. * For self-hosted fonts, preload the `.woff2` files in the `` so the measurement cache is correct from the first paint. For runtime font swapping (changing typefaces after the editor is mounted), see the **[Custom Typography Guide](custom-typography.md)** which covers the CSS custom property pattern (`--traven-font-display`, `--traven-font-body`, `--traven-font-mono`) and the `requestMeasure()` re-measurement step. --- ## 5. WYSIWYM/Preview parity The preview and the editor should look as similar as possible. The shipping skins accomplish this with the following patterns. ### 5.1 First-child heading margin CodeMirror's first line is flush with the editor's top; the heading's `padding-top` provides the breathing room. In the preview, the same heading's `margin-top` is collapsed with the preview container's padding, so the first heading appears at the wrong offset unless you compensate: ```css .cm-editor .cm-wysiwym-h1 { padding-top: 27px !important; } .traven-preview > h1:first-child { margin-top: 27px !important; } .traven-preview > h2:first-child { margin-top: 12px !important; } .traven-preview > h3:first-child { margin-top: 4.5px !important; } ``` The numbers in `editorial`/`write` themes are larger because their `padding-top` values are larger; whatever you pick, the editor and the preview must agree. ### 5.2 Blockquote spacing parity Reduce the preview's blockquote vertical neighbors with a `:has()` selector to mirror the editor's collapsed blank line: ```css .traven-preview p:has(+ blockquote:not(.traven-component-pullquote)), .traven-preview ul:has(+ blockquote:not(.traven-component-pullquote)), .traven-preview pre:has(+ blockquote:not(.traven-component-pullquote)) { margin-bottom: 0.6em !important; } .traven-preview blockquote:not(.traven-component-pullquote) + p, .traven-preview blockquote:not(.traven-component-pullquote) + pre { margin-top: 0.6em !important; } ``` The same pattern is used around the `[component="blockquote"]` and `[info]`/`[warning]` blocks. (Search your theme for `:has(+ .traven-` to see them.) ### 5.3 Tables The live table widget (`.cm-wysiwym-table-widget table`) and the preview table (`.traven-preview table`) should share the same border colors, padding, and minimum cell height. All shipping themes set `height: 38px` on `th` and `td` so that an empty cell never collapses to zero. ### 5.4 Code blocks Match the editor's `.cm-wysiwym-codeblock-line` colors and the preview's `.traven-preview pre`. The `-first` / `-last` borders on the editor side correspond to a `border-top` / `border-bottom` on the preview `
`.

### 5.5 Font Family Inheritance on Nested Elements (The CSS Cascade Override)

In Traven, the default starter skin (`skin-starter.css` which is bundled inside `dist/traven.css`) defines high-priority overrides for standard body elements like paragraphs:
```css
.traven-preview p {
  font-family: var(--traven-font-body) !important;
}
```
If your custom theme has elements that wrap nested paragraphs — such as standard blockquotes, blockquote components (`[component="blockquote"]`), and notice blocks (`[info]`, `[warning]`) — those nested paragraph tags will ignore the parent container's custom font declarations. Instead, they will inherit the starter skin's default body typeface (e.g. `Georgia`), breaking visual consistency.

#### The Fix
To enforce your theme's custom typography on all nested structures, apply the `font-family` declaration using a selector targeting both the parent container and all its descendants (using `*`) along with `!important`:
```css
/* Editor scope */
.cm-wysiwym-component-shortcode.component-info,
.cm-wysiwym-component-shortcode.component-info * {
  font-family: 'Atkinson Hyperlegible Next', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif !important;
}

/* Preview scope */
.traven-preview .traven-component-info,
.traven-preview .traven-component-info * {
  font-family: 'Atkinson Hyperlegible Next', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif !important;
}
```
This ensures the cascade correctly forces nested block contents to render using the theme's designated body font.

---

## 6. Shortcode markup reference (cheat sheet)

The fallback renderer emits **zero inline styles**; every visual decision is delegated to your theme. This section is a copy of the canonical markup in `docs/dev/shortcodestyles.css`, condensed for theme authors. Use the comment blocks in that file as your authoritative reference.

### 6.1 `[image ...]`

```html

...




  ...
  
Caption



```

* **Editor wrapper:** `.cm-wysiwym-image-shortcode-container`
* **Preview wrapper:** `.traven-preview img.traven-image-shortcode`, `.traven-preview figure.traven-image-figure`
* **Caption:** `figcaption.traven-image-caption`
* **Alignment:** `align-left` / `align-right` / `align-center` / `align-fullbleed`
* **Sizes:** `size-small` (~150 px), `size-medium` (~300 px), `size-large` (~600 px), `size-full` (100%)

For `align-fullbleed`, use the standard 100vw breakout:

```css
.traven-preview img.traven-image-shortcode.align-fullbleed,
.traven-preview figure.traven-image-figure.align-fullbleed {
  width: 100vw !important;
  max-width: 100vw !important;
  margin-left: calc(-50vw + 50%) !important;
  margin-right: calc(-50vw + 50%) !important;
  border-radius: 0 !important;
  display: block !important;
  float: none !important;
  clear: both !important;
}
```

### 6.2 `[video ...]`

```html



  
  
  






  

      
  

  
Caption



```

* **Editor wrapper:** `.cm-wysiwym-video-shortcode-container` (plus `.video-placeholder`, `.video-placeholder-icon-wrap`, `.video-placeholder-details`, `.video-placeholder-platform`, `.video-placeholder-url`).
* **Preview wrapper:** `.traven-preview .traven-video-container` (16:9 `aspect-ratio`), `.traven-preview figure.traven-video-figure`.
* **Caption:** `figcaption.traven-video-caption`.

### 6.3 `[audio ...]`

```html


  






  

    
  

  
Caption



```

Same alignment helpers as image/video.

### 6.4 `[figure ...]...[/figure]`

Wraps arbitrary block content (tables, code blocks, images, etc.) in a captioned figure.

```html


  
  
Caption



```

* **Editor wrapper:** `.cm-wysiwym-figure-shortcode` (with `.component-body` and `.figure-caption`).
* **Preview wrapper:** `.traven-preview .traven-figure`.

### 6.5 `[component]...[/component]` and its aliases

The `[component]` shortcode has a structural base class plus one variant class derived from the `name` attribute. Aliases normalize to the same variants:

| Author writes | Compiles to |
| :--- | :--- |
| `[component name="blockquote"]...[/component]` | `.traven-component-blockquote` |
| `[quote]...[/quote]`, `[blockquote]...[/blockquote]` | `.traven-component-blockquote` |
| `[component="blockquote"]...[/component]` | `.traven-component-blockquote` |
| `[pullquote]...[/pullquote]` | `.traven-component-pullquote` |
| `[info]...[/info]`, `[component="info"]...[/component]` | `.traven-component-info` |
| `[warning]...[/warning]`, `[component="warning"]...[/component]` | `.traven-component-warning` |
| `[component="my-card"]...[/component]` | `.traven-component.traven-component-my-card` |
| `[highlight]...[/highlight]` | `...` |

HTML output by variant:

```html



  
Quote...

  
— Author, Source






Editorial emphasis.





  
Heads-up text…







  
Anything you like.



```

The editorial and write themes draw the `[info]` and `[warning]` blocks with the "hand-drawn" border radius:

```css
.traven-preview .traven-component-info,
.traven-preview .traven-component-warning {
  border: 2px solid #1a1a1a !important;
  border-radius: 255px 15px 225px 15px/15px 225px 15px 255px !important;
}
```

The other themes use clean rounded rectangles. Either is a valid aesthetic — pick one and stay consistent.

### 6.6 LaTeX math (when enabled)

The math parser uses `$...$` for inline and `$$...$$` for display. When KaTeX is loaded the output is `.katex` / `.katex-display`. When it isn't, the fallback classes are:

* `.katex-inline-fallback` — inline equation rendered as monospaced text on a soft background.
* `.katex-display-fallback` — display equation, centered, monospaced, with rounded background.

In the editor, the live widgets are:

* `.cm-wysiwym-inline-math-widget`
* `.cm-wysiwym-block-math-widget`

The shipping editorial and write themes define these; the default/colorful/dark themes inherit the rules from the built-in `dist/traven.css`.

---

## 7. Dark mode

Dark mode is **decoupled** between the editor and the surrounding page. The editor's toggle adds a `.cm-wysiwym-dark` class to its own host DOM nodes (and, in split-pane setups, to the preview container too). Themes handle the resulting rules in two ways.

### 7.1 The minimal approach (used by the default skin)
Define light values at the top of the stylesheet and re-declare the same selectors with the dark prefix for the dark variants. The shipping pattern is to keep both halves of every selector adjacent, e.g.:

```css
/* Light */
.cm-editor .cm-wysiwym-blockquote { border-left-color: #cbd5e1; color: #475569; }
.cm-editor .cm-wysiwym-blockquote,
.cm-editor .cm-wysiwym-blockquote * { color: #475569; }

/* Dark — same selectors under .cm-editor.cm-wysiwym-dark */
.cm-editor.cm-wysiwym-dark .cm-wysiwym-blockquote { border-left-color: #475569; }
.cm-editor.cm-wysiwym-dark .cm-wysiwym-blockquote,
.cm-editor.cm-wysiwym-dark .cm-wysiwym-blockquote * { color: #cbd5e1 !important; }
```

This is verbose but explicit, and every rule is right next to its light counterpart — easy to diff.

### 7.2 The CSS-variables approach (recommended for new themes)
Define a small palette of variables at `:root` and re-declare them under the dark class. Every other rule references the variables. The cheat-sheet at `docs/dev/shortcodestyles.css` demonstrates this pattern with a `--traven-color-*` family:

```css
:root {
  --traven-color-text-main: #0f172a;
  --traven-color-text-muted: #64748b;
  --traven-color-text-blockquote: #475569;
  --traven-color-border: #e2e8f0;
  --traven-blockquote-border: #cbd5e1;
  --traven-color-info-border: #1a1a1a;
  --traven-color-info-bg: #fafafa;
  --traven-color-warning-border: #1a1a1a;
  --traven-color-warning-bg: rgba(250, 204, 21, 0.25);
}

.cm-wysiwym-dark,
.traven-preview.cm-wysiwym-dark {
  --traven-color-text-main: #f8fafc;
  --traven-color-text-muted: #94a3b8;
  --traven-color-text-blockquote: #cbd5e1;
  --traven-color-border: #334155;
  --traven-blockquote-border: #475569;
  /* …dark info / warning overrides… */
}

.traven-preview .traven-component-blockquote {
  border-left: 3px solid var(--traven-blockquote-border) !important;
  color: var(--traven-color-text-blockquote);
}
```

You can drive the same variables with `@media (prefers-color-scheme: dark)` to get an automatic dark mode that does not depend on the editor's toggle, but be aware that the editor's class-based toggle wins when both are active.

### 7.3 The two dark scopes are independent
* **Editor dark:** scoped under `.cm-editor.cm-wysiwym-dark …`.
* **Preview dark:** scoped under `.traven-preview.cm-wysiwym-dark …`.

A complete theme declares both. If you only style one, the editor and the preview will drift out of sync when the user toggles dark mode.

### 7.4 Dark-mode pitfalls
* The Vim "fat cursor" (`.cm-fat-cursor`) is shared across modes; always set `opacity: 0.6 !important` on it (the base stylesheet does this for you, but reinforce it in your theme if you override background colors).
* Selection colors: the focused and unfocused variants use different selector paths. Mirror both:

  ```css
  .cm-editor.cm-wysiwym-dark .cm-selectionBackground,
  .cm-editor.cm-wysiwym-dark .cm-native-selection { background-color: rgba(56, 189, 248, 0.35) !important; }
  .cm-editor.cm-wysiwym-dark.cm-focused > .cm-scroller > .cm-selectionLayer .cm-selectionBackground {
    background-color: rgba(56, 189, 248, 0.6) !important;
  }
  ```

* The "active" frontmatter line uses a different border color than the inactive variant — see `.cm-wysiwym-frontmatter-active`.
* The image / video / audio / figure / component hover edit icons get their own dark backgrounds. The shipping themes re-tint them per skin.

---

## 8. Building a new theme

### 8.1 File placement
Drop a new file into `packages/core/assets/skins/` with the `skin-` prefix:

```
packages/core/assets/skins/skin-aurora.css
```

The dropdown script (`includes/_customization-dropdowns.php`) auto-discovers any `*.css` file in that directory, sorts `skin-light` first and everything else alphabetically, and registers a `