[Summary view] [Print] [Text view]

   1  # DESIGN.md
   2  
   3  How to design with Ipsum: what each preset is for, how the theme uses it, and what the style variations, templates, parts and block styles give you. `AGENTS.md` covers working in the repository.
   4  
   5  ## Ipsum
   6  
   7  Ipsum is the default theme for WordPress 7.2: a block theme built around blogging, which its readme calls a blank canvas. Each palette is a background and a text ink in a few strengths, plus an accent the theme uses once.
   8  
   9  ## Color
  10  
  11  Six palette colors. Every color variation redefines all six, and the duotone too. The values are in `theme.json` and the files in `styles/colors/`.
  12  
  13  | Slug | Name | Role | Where the theme uses it |
  14  | --- | --- | --- | --- |
  15  | `base` | Base | Background | Page background, button text, form field fill, text and links on Strong Contrast grounds, the end of both gradients |
  16  | `contrast` | Contrast | Text | Body text, headings, links, button fill and border, form field text and border |
  17  | `accent-3` | Strong Contrast | Strongest ink | Hover for links, buttons, form fields and tag pills; the ground of inverted sections, cards and the navigation overlay |
  18  | `accent-1` | Accent | Accent | One place only: the arrival bar, a 3px line that sweeps the top of the screen when a single post loads (only when the visitor hasn't asked for reduced motion) |
  19  | `accent-5` | Surface | Faint fill | Quotes, pullquotes, comment bubbles, tag pills, table headers and stripes, the calendar header, the audio player, cards in patterns, the start of both gradients, and a few rules (Header Sticky, Text Alternating) |
  20  | `accent-6` | Border | Faint line | Separators, list markers, quote marks, table and calendar lines, the code block border, dotted rules between rows |
  21  
  22  `accent-2` and `accent-4` are not defined. The slugs match Twenty Twenty-Five's, so patterns written for it find matching colors, but a block that asks for `accent-2` or `accent-4` gets no color.
  23  
  24  How the palettes are built:
  25  
  26  -   **Light palettes:** Contrast, Border and Surface are the dark ink at 75%, 20% and 3% opacity (hex alpha `bf`, `33`, `08`). Strong Contrast is the ink itself. The default builds Border and Surface on `#0a0a0a` instead of its `#000000` ink.
  27  -   **Dark palettes:** Contrast is opaque. Border and Surface are Contrast at 25% and 10% (`40`, `1a`). Strong Contrast is lighter than Contrast.
  28  -   Border and Surface are translucent, so they tint whatever is under them.
  29  
  30  ### Usage rules
  31  
  32  -   **Use the slugs, never literal colors.** `var(--wp--preset--color--contrast)` in CSS, `var:preset|color|contrast` in block attributes, or `textColor` and `backgroundColor`. A literal hex freezes one variation's look into all the others.
  33  -   **Text is Contrast.** Body, headings and links all use it. Hover goes to Strong Contrast. Contrast is translucent in the light palettes, so it only reads as intended on Base or Surface; on any other ground, use Strong Contrast.
  34  -   **Links** have a dotted 1px underline. On hover they turn Strong Contrast and lose the underline. Navigation, post title, post navigation and pagination links do the reverse: no underline until hover.
  35  -   **Buttons** fill with Contrast, with Base text, and fill with Strong Contrast on hover. Focus and press use Contrast at 85% (`color-mix()`). The Outline style keeps a Contrast border and fills with Surface on hover.
  36  -   **Form fields** in Search and the comment form are Base with Contrast text and border. The border turns Strong Contrast on hover. Jetpack form fields get the same border.
  37  -   **Accent is not a link or button color.** The theme uses it only in the arrival bar.
  38  -   **Inverted sections and cards** use a Strong Contrast ground with Base text and links: the About Row band, the Navigation Overlay, and the cards in Text Statement, Footer Centered, Footer Subscribe, Header Collapsed, Page Bio, Page Blog Home and the gallery text tiles. They are dark in light variations and light in dark ones.
  39  -   **Tinted cards** use a Surface ground, Contrast text and 10px corners: Kind Words, CTA Membership, Hero Colophon, Format Audio, Format Link and the author chip in single posts. Surface works on any ground, so keep Contrast text on it.
  40  -   **Lines** use Border, at 1px, apart from the Surface rules in Header Sticky (1px) and Text Alternating (5px). Dotted rules use Border or the current text color.
  41  -   **Light or dark:** read `settings.custom.controlScheme`. It is `light` in `theme.json`, and each color variation sets its own. The variation titles don't tell you.
  42  -   **Colors that don't follow the palette:** the Evening code block style keeps the Evening palette's literals on purpose, so it reads as a dark slab under every variation. The Soft shadow is black at 8%. Each variation's duotone colors are hex copies of its palette colors.
  43  
  44  ### Gradients and duotone
  45  
  46  -   **Gradients:** two presets, both Surface to Base, top to bottom. `gradient-1`, "Vertical soft wash to base", fades over the whole height. `gradient-2`, "Vertical hard wash to base", is Surface for the top 90%, then Base. No template or pattern uses them.
  47  -   **Duotone:** one preset, `duotone-1`. The default is "Black and white". Each color variation redefines it with two of its own palette colors as hex, dark first, so editing a palette doesn't update its duotone. Header Collapsed, Header Sticky and Hero Colophon apply it to the site logo. Blue Hour and Golden Hour also apply it to every Featured Image.
  48  -   Core's default palette, gradients and duotones are off, so only Ipsum's presets show.
  49  
  50  ## Typography
  51  
  52  | Slug | Family | Role |
  53  | --- | --- | --- |
  54  | `inter` | Inter | The text font: body and, by default, headings |
  55  | `manrope` | Manrope | The meta voice (below), buttons, navigation, site title and tagline; the text font in Golden Hour |
  56  | `jetbrains-mono` | JetBrains Mono | Code and preformatted text; the text font in High Noon |
  57  | `stix-two-text` | STIX Two Text | The text font in Blue Hour, plus its site title and tagline |
  58  | `besley` | Besley | The text font in Sunrise |
  59  | `archivo` | Archivo | The text font in Morning and After Hours |
  60  | `archivo-condensed` | Archivo Condensed | Headings in After Hours |
  61  
  62  All seven are variable fonts. Manrope has no italic face.
  63  
  64  ### The meta voice
  65  
  66  Labels, dates, terms, bylines, comment meta, pagination, read more links, cites, form labels and table headers share one treatment: **Manrope, Small, weight 600**. A few use 700 (site title, accordion and details summaries, table headers) or 400 (comment date, comment edit and reply links, comments title). The tagline is 500. The Navigation block defaults to Manrope at Medium, 500; every header but Header Vertical sets it to Small.
  67  
  68  It isn't a preset you can pick. New meta text needs Manrope, Small and weight 600 set on the block, and changing the voice means changing every block that carries it. Typography variations leave it alone, since those blocks set Manrope directly. Blue Hour is the one variation that moves part of it: the site title and tagline go to STIX Two Text.
  69  
  70  ### Size scale
  71  
  72  | Slug | Name | Used for |
  73  | --- | --- | --- |
  74  | `small` | Small | The meta voice, h5, h6 |
  75  | `medium` | Medium | Body text, h4, navigation, verse |
  76  | `large` | Large | h3 |
  77  | `x-large` | X-Large | h2 |
  78  | `2-x-large` | 2X-Large | h1, single post titles, quote marks |
  79  
  80  Small to Large are fixed; X-Large and 2X-Large are fluid, smaller on narrow screens. The sizes are in `theme.json`. Above 2X-Large, the theme uses the Display block style (`is-style-text-display`) or fit text (Hero Epigraph, About Row, the 404 heading, the Footer Centered wordmark). Core's default sizes are off.
  81  
  82  ### Conventions
  83  
  84  -   **Line height:** body 1.5, paragraphs 1.6. Headings use `calc(1em + 0.5rem)`, so they get tighter as they grow. Display is 1.2; quote marks are 1.
  85  -   **Weight:** text 400, headings 500.
  86  -   **Letter spacing:** h1 and h2 are tightened by -0.02rem, h3 by -0.01rem. The site title and tagline open to 0.01rem. The meta voice sets 0.
  87  -   **Uppercase** is rare: the site title in Header Sticky, Header Vertical and Footer Social, and the Navigation Overlay menu.
  88  -   **Writing mode** is on. Header Vertical runs its site title vertically.
  89  
  90  ## Spacing and layout
  91  
  92  | Slug | Name | Typical use |
  93  | --- | --- | --- |
  94  | `20` | 2X-Small | Gaps inside rows (date · categories, title and tagline), tag pill padding, heading bottom margin |
  95  | `30` | X-Small | Gaps between small items and buttons; padding in most cards and in compact boxes (code, comment bubbles, button top and bottom) |
  96  | `40` | Small | The root block gap and side padding, button side padding |
  97  | `50` | Regular | Section padding (header top, footer), heading top margin |
  98  | `60` | Large | Between sections (separators, comments, tags, author chip), the gap between posts in query loops, header bottom padding |
  99  | `70` | X-Large | Large section padding, the gap beside the sidebar |
 100  | `80` | 2X-Large | Hero and statement patterns: Hero Epigraph, CTA Search, Contact Say Hi, About Row |
 101  
 102  `20` and `30` are fixed; from `40` up, sizes scale with the viewport. The sizes are in `theme.json`. Core's default spacing sizes are off.
 103  
 104  ### Layout
 105  
 106  -   **Widths:** content 640px, wide 1280px.
 107  -   **Root padding:** spacing `40` on each side, with root-padding-aware alignments, so full-width blocks reach the screen edges.
 108  -   **Templates** wrap their content in a `main` group with a constrained layout; `archive` and `search` use the default layout. In the one-column templates, post content is full-aligned with a constrained layout, so its blocks sit at 640px and can go wide or full.
 109  -   **Sidebar templates** use a wide Columns block: 66.66% content, 33.33% sidebar, spacing `70` between.
 110  
 111  ### Shadow
 112  
 113  One preset, `soft` ("Soft"), a small black shadow at 8%. Only the Header Sticky bar uses it.
 114  
 115  ### Corners and lines
 116  
 117  | Radius | Where |
 118  | --- | --- |
 119  | 10px | Buttons, featured images, avatars, comment bubbles, tag pills, the audio player, most cards in patterns |
 120  | 5px | Images, quotes and pullquotes, code, form fields, the site logo |
 121  | 4px | Site title, search button |
 122  | 2px | Post author name |
 123  | 0 and 9999px | The Sharp and Rounded site logo styles |
 124  
 125  Lines are 1px, except Text Alternating's 5px heading rules. Dotted lines mark link underlines, button focus outlines, the Search Outline button, the top of accordions and details, the rules between rows in Archive Simple, Archive Minimal, Events List and All Archives Sidebar, and the rule beside the link in Format Link. Other buttons, separators, tables and code use solid lines.
 126  
 127  ## Style variations
 128  
 129  ### Color variations
 130  
 131  Six of the seven also change fonts, and two apply duotone to featured images. Every one redefines the six colors and `duotone-1`, so the duotone on the header site logos follows the variation.
 132  
 133  | # | Title | Scheme | Also changes |
 134  | --- | --- | --- | --- |
 135  | | Default (`theme.json`) | light | Nothing |
 136  | 01 | Blue Hour | light | Text font, site title and tagline in STIX Two Text. Duotone "Ink on paper" on featured images. |
 137  | 02 | Sunrise | light | Text font in Besley. |
 138  | 03 | Morning | light | Text font in Archivo. |
 139  | 04 | High Noon | light | Text font in JetBrains Mono. |
 140  | 05 | Golden Hour | dark | Text font and headings in Manrope. Duotone "Peach on maroon" on featured images. |
 141  | 06 | Evening | dark | Colors only. |
 142  | 07 | After Hours | dark | Text font in Archivo, headings in Archivo Condensed. |
 143  
 144  Scheme is `settings.custom.controlScheme`. Each variation's colors are in its file in `styles/colors/`.
 145  
 146  ### Typography variations
 147  
 148  Each sets only the root font family, which headings inherit. Manrope blocks and code keep their own families.
 149  
 150  | Title | Slug | Text font |
 151  | --- | --- | --- |
 152  | Archivo | `archivo` | Archivo |
 153  | Archivo Condensed | `archivo-condensed` | Archivo Condensed |
 154  | Besley | `besley` | Besley |
 155  | JetBrains Mono | `jetbrains-mono` | JetBrains Mono |
 156  | STIX Two Text | `stix-two-text` | STIX Two Text |
 157  
 158  ### Block style variations
 159  
 160  The class is `is-style-` plus the slug.
 161  
 162  | Style | Class | Blocks | What it does |
 163  | --- | --- | --- | --- |
 164  | Crop Contents | `is-style-crop-contents` | Group | `overflow: clip` |
 165  | Display | `is-style-text-display` | Heading, Paragraph, Post Title, Site Title, Query Title | A size above 2X-Large that scales with the viewport, line height 1.2 |
 166  | Quote Mark | `is-style-text-quote-mark` | Heading, Paragraph | A ❝ above the text, in Border, at 2X-Large |
 167  | Quote Mark on Color | `is-style-text-quote-mark-on-color` | Heading, Paragraph | The same mark in the current text color; Text Statement uses it on a Strong Contrast card |
 168  | Evening | `is-style-evening` | Code | A black ground with near-white text and border, the same under every variation |
 169  | Sharp | `is-style-sharp` | Site Logo | Square corners |
 170  | Pinned to Bottom | `is-style-sticky-bottom` | Template Part | Pins the part to the bottom of the screen; see [Utility block styles](#utility-block-styles) |
 171  | Row Hover | `is-style-hover-together` | Post Template | Post rows hover as one |
 172  | Dot Separator | `is-style-dot-before` | Comment Edit Link, Comment Reply Link | A decorative `·` before the link |
 173  | Outline | `is-style-outline` | Search | A dotted Contrast outline on a Base button until hover, focus or press; the Search Bar part uses it |
 174  
 175  Ipsum also restyles core's own block styles: Button Outline (a separate style from Search's Outline, though they share the name), Quote Plain (no ground, padding or corners), Separator Wide (capped at the wide width), Site Logo Rounded (9999px) and Social Icons Logos Only (icons in the current text color).
 176  
 177  ## Templates and parts
 178  
 179  ### Templates
 180  
 181  | Template | Pattern | Shows |
 182  | --- | --- | --- |
 183  | `index` | `ipsum/hidden-index` | The post feed, each post in full |
 184  | `archive` | `ipsum/hidden-archive` | The archive title over the Archive Compact list |
 185  | `search` | `ipsum/hidden-search` | The search title and field, then results with excerpts |
 186  | `single` | `ipsum/hidden-single` | The post, tags, author chip, comments and Keep Reading |
 187  | `page` | `ipsum/hidden-page` | Featured image, title and content |
 188  | `404` | `ipsum/hidden-404` | A fit-text heading, a line of text and search |
 189  | `page-no-title` | `ipsum/hidden-page-no-title` | Content only |
 190  | `page-sidebar` | `ipsum/hidden-page-sidebar` | The page beside the Sidebar part |
 191  | `single-sidebar` | `ipsum/hidden-single-sidebar` | The post beside the Sidebar part |
 192  | `index-sidebar` | `ipsum/hidden-index-sidebar` | The feed beside the Sidebar part |
 193  | `archive-sidebar` | `ipsum/hidden-archive-sidebar` | The archive beside the Sidebar part |
 194  
 195  -   Every template starts with the Header part.
 196  -   One-column templates use the Footer part; sidebar templates use Footer Wide.
 197  -   All but `404` and `search` add the Search Bar part with the Pinned to Bottom block style, which pins it to the bottom of the screen.
 198  -   Both single templates insert two hidden helper patterns: `ipsum/hidden-comments` and `ipsum/hidden-keep-reading` (the three latest posts).
 199  
 200  ### Custom templates
 201  
 202  -   **In `theme.json` `customTemplates`:** Single Posts Sidebar (`single-sidebar`, posts), Pages Sidebar (`page-sidebar`, pages) and Pages No Title (`page-no-title`, pages). Editors pick them per post or page.
 203  -   **Template types:** Index Sidebar (`index-sidebar`) and All Archives Sidebar (`archive-sidebar`) have a title and description in the Site Editor. Their slugs aren't in the template hierarchy, so WordPress doesn't choose them on its own.
 204  
 205  ### Template parts
 206  
 207  | Part | Area | Pattern | Used in |
 208  | --- | --- | --- | --- |
 209  | `header` | `header` | `ipsum/header-default` | Every template |
 210  | `header-collapsed` | `header` | `ipsum/header-collapsed` | None; an alternative with the menu always behind a button |
 211  | `header-sticky` | `header` | `ipsum/header-sticky` | None; an alternative sticky bar with the Soft shadow |
 212  | `footer` | `footer` | `ipsum/footer` | One-column templates |
 213  | `footer-wide` | `footer` | `ipsum/footer-wide` | Sidebar templates |
 214  | `navigation-overlay` | `navigation-overlay` | `ipsum/navigation-overlay` | The menu button in Header Default, Header Collapsed, Header Sticky, Hero Colophon and Hero Epigraph |
 215  | `search-bar` | `uncategorized` | `ipsum/hidden-search-bar` | All templates but `404` and `search` |
 216  | `sidebar` | `uncategorized` | `ipsum/hidden-sidebar` | The four sidebar templates: categories and the five latest posts |
 217  
 218  The header, footer and overlay parts delegate to insertable patterns. Other patterns carry `Block Types: core/template-part/<area>`, so the editor offers them as replacements:
 219  
 220  -   **Header:** Header Default, Header Collapsed, Header Sticky, Header Vertical, Hero Colophon, Hero Epigraph.
 221  -   **Footer:** Footer, Footer Wide, Footer Centered, Footer Social, Footer Subscribe.
 222  -   **Navigation overlay:** Navigation Overlay, Overlay Contents, Overlay Profile.
 223  
 224  ## Utility block styles
 225  
 226  Three block styles carry behaviour, not just looks, and need a particular setup to work. Like every block style, they're listed in the block's Styles panel and in REST at `/wp/v2/block-types/<block>` under `styles`. A block holds one style at a time, and choosing a style stores `is-style-<slug>` in its `className`.
 227  
 228  | Style | Block | What it does | Used in |
 229  | --- | --- | --- | --- |
 230  | Pinned to Bottom (`sticky-bottom`) | Template Part | Pins the part to the bottom of the viewport, shrunk to its content at the inline end (bottom right in LTR, bottom left in RTL), above the content (`z-index: 10`). | The Search Bar part at the end of every template but Search and 404. |
 231  | Row Hover (`hover-together`) | Post Template | Post rows hover as one: hovering any visible part of a row turns all its text and links Strong Contrast and gives its featured image a small tilt and settle (skipped with reduced motion). The empty space beside the content doesn't trigger it. | Archive Simple, Archive Standard, Archive Compact, Archive Lead, Search Results, All Archives Sidebar. |
 232  | Dot Separator (`dot-before`) | Comment Edit Link, Comment Reply Link | Puts a decorative `·` before the link, with 0.5em of space on each side and weight 600. Screen readers skip it, and the dot comes and goes with its link. | The date, Edit and Reply row of each comment in `ipsum/hidden-comments`. |
 233  
 234  What each one needs to work:
 235  
 236  -   **Pinned to Bottom:** put the template part at the root of the template, after the footer. A sticky element only travels within its parent; at the root that's the site wrapper, which the theme stretches to at least the viewport height. Inside a Group it only sticks while that Group is on screen.
 237  -   **Row Hover:** wrap each post's blocks in a single Group directly inside the Post Template, as every Ipsum pattern that uses it does. Without that Group the style does nothing.
 238  -   **Dot Separator:** put the link in a flex row with a block gap of 0. The dot's padding does the spacing, so a gap would double it.
 239  
 240  ### Helper classes
 241  
 242  Two classes in `style.css` hide a group when a block inside it renders nothing, so the hand-written text around it doesn't stand alone. Keep the class on the group when you copy it into a new pattern.
 243  
 244  -   **`comments-meta`** goes on the group around the comments link row in post lists. Core renders nothing for the Comments Link block when comments are closed, so the row, with its `·` and call to action, hides with it.
 245  -   **`author-card`** goes on the author chip in single posts. Core renders nothing for the Author Name block when the post type doesn't support authors, so the card, with its "Written by" byline and avatar, hides with it.
 246  
 247  ### The `·` meta separator
 248  
 249  The separator between meta items is built three ways, on purpose:
 250  
 251  -   **Where both neighbours always render** (post date · categories), it's a Paragraph named Meta Separator: small, weight 600, with the dot hidden from screen readers. The row's block gap (`spacing|20`) spaces it. To add one, copy it from an archive pattern.
 252  -   **Where the whole row can go** (comments link · call to action), it's the same Paragraph, and the `comments-meta` class hides the row when comments are closed.
 253  -   **Where a neighbour may not render**, it's the Dot Separator style. The Edit link only renders for people who can edit the comment, and the Reply link only when threading allows it, so a Paragraph would be left behind as a stray dot. Use the Paragraph wherever it's safe: unlike the style's dot, it can be translated.