# [THEME NAME] — [ORGANIZATION] Design Theme

**Version:** 1.0
**Date:** [MONTH YEAR]
**Origin:** [What this was derived from — a brand sheet, an existing document, a logo]
**Purpose:** A reusable theme for all [ORGANIZATION] documents — [list the document types you actually make].

---

> **HOW TO USE THIS TEMPLATE**
>
> Fill in every bracket. Delete every instruction line (the ones in blockquotes like this one) before you save it as your real file.
>
> The rule that governs the whole thing: **write numbers, not adjectives.** If a line in your finished file could be argued about, it isn't done. "Use the accent sparingly" is an argument. "≤2% of page area, never a ground" is a rule.
>
> Any section you genuinely can't answer yet, write "Not yet defined" and move on. An honest gap is useful. A guess is not.

---

## 1. Identity

> Two or three sentences. What it feels like, what it's for, and what makes it recognizable across pieces. Somebody who has never seen your work should be able to read this and know whether a given document belongs.

[THEME NAME] is [two adjectives that mean something]. It uses [the core visual move — e.g. "large uppercase condensed headlines against a warm page"], [the second move], and [the accent behavior].

The signature is **[the one element people would recognize]**.

---

## 2. Version and Precedence

> The cheapest paragraph in the file and the one that saves the most arguments. Write it even if you only have one theme today.

- **This version:** 1.0, [Month Year]
- **Supersedes:** [previous theme name, or "nothing — this is the first"]
- **Status of the old theme:** [e.g. "Still valid for existing documents. New work uses this file. Never mix the two inside one document."]
- **Language authority:** [If you have a separate voice or copy guide, name it and say it wins on wording. If not, write "None — this file governs look only."]
- **Print authority:** `PRINT_SAFE_HTML.md` governs page mechanics. Where this file and that one disagree about heights, margins, or page breaks, that one wins.

---

## 3. Color Tokens

> Four colors. Two more only if you can name the job of each. Every token gets a hex, a role written as a job, and a share of the page measured by **area**, not by how many times you use it.

| Token | Hex | Role | Share of page |
|---|---|---|---|
| `--[x]-[name]` | `#______` | [Light ground / dark ground / the action / the accent] | __% |
| `--[x]-[name]` | `#______` | | __% |
| `--[x]-[name]` | `#______` | | __% |
| `--[x]-[name]` | `#______` | [The accent — usually ≤2%] | ≤_% |

**There is no fifth hue.** Every tint below is derived from the colors above.

| Support token | Value | Role |
|---|---|---|
| `--[x]-text-secondary` | `rgba(_,_,_,0.72)` | Subtitles, secondary body |
| `--[x]-text-muted` | `rgba(_,_,_,0.58)` | Captions, helper text |
| `--[x]-text-faint` | `rgba(_,_,_,0.42)` | Running headers and footers only — furniture, not reading |
| `--[x]-rule` | `rgba(_,_,_,0.16)` | Rules, card borders |

> **Not in this palette:** [list the colors that keep trying to sneak in. Gold. Any green. Pure white. Pure black. Gradients. Per-event custom colors.]

---

## 4. Legal Pairs — Contrast

> Do not eyeball this and do not copy the numbers off a brand sheet without re-checking. Ask Claude to compute every pair against the WCAG relative-luminance formula and tell you which ones fail.
>
> Thresholds: **4.5:1** for normal text. **3:1** for 18pt+ normal or 14pt+ bold. Below 3:1 a color pair is a decoration, not type.

| Pair | Computed ratio | Verdict |
|---|---|---|
| [Dark text on light ground] | __:1 | Legal, all sizes |
| [Accent on dark ground] | __:1 | Legal, all sizes |
| [Accent on light ground] | __:1 | **Display only — 18pt+ or 14pt bold** |
| [The one people get wrong] | __:1 | **Never** |

**The rule people will get wrong:** [state it in one line. e.g. "Dark ground takes the lighter accent. Light ground takes the darker accent. Never swap them."]

---

## 5. Typography

### The faces — two, no third

| Role | Family | Permitted weights | Fallback stack |
|---|---|---|---|
| **Display / headlines** | [Face] | [e.g. 400 only — this face has no bold] | [stack] |
| **Body / everything that's a sentence** | [Face] | [400 / 500 / 700] | [stack] |

Webfont import:
```
https://fonts.googleapis.com/css2?family=...&display=swap
```

> If your renderer is WeasyPrint, download the woff2 files locally and render with `base_url='.'`. Webfonts over HTTP are unreliable in a render pipeline.

### Type scale

> Every role gets a size, a weight, and a line-height. Line-height is where amateur files stop and it's the single biggest visual difference between a document that looks designed and one that doesn't.

| Element | Face | Size | Weight | Line-height | Color |
|---|---|---|---|---|---|
| Cover title | | __pt | | | |
| Section title | | __pt | | | |
| Page headline | | __pt | | | |
| Subhead | | __pt | | | |
| Eyebrow / label | | __pt | | | |
| Lead paragraph | | __pt | | | |
| **Body text** | | **__pt** | | | |
| Caption | | __pt | | | |
| Running header | | __pt | | | |
| Footer | | __pt | | | |

**Hard floor: __pt for anything a reader is meant to read.** Running headers, footers, and page numbers are furniture and are exempt at __pt. **If body copy won't fit at the floor, cut the copy or add a page. Never shrink the type.**

**Display face floor: __pt.** Below that, use [body face] at weight 700 instead.

### Letter spacing

| Element | Tracking |
|---|---|
| Display headlines | [usually 0] |
| Uppercase eyebrows and labels | 0.18–0.22em |
| Body | 0 |

---

## 6. Signature Elements

> The two or three things that make separate pieces read as one system. Be specific enough that somebody could rebuild them from this text alone.

### [Element one — e.g. the underbar]
- Dimensions: __px tall × __px wide
- Position: [exactly where it sits]
- Color: [which token, and how it changes on a dark ground]
- **This is the single most recognizable mark in the system.**

### [Element two]
- [Spec]
- **One per layout.** [Or whatever the quantity rule is.]

### Rule weights — [number], no others
| Weight | Use |
|---|---|
| __px | Section break |
| __px | Emphasis |
| __px | Standard divider |
| __px | Hairline in tables |

Anything else is off-theme.

---

## 7. Components

> Write these as CSS you can paste, not as descriptions. A component you have to interpret is a component that will be built differently every time.

### Callout box
```css
background: var(--[x]-callout-bg);
border-left: __px solid var(--[x]-[accent]);
padding: __pt __pt;
border-radius: __;
```

### Note box
```css
background: var(--[x]-note-bg);
border-left: __px solid var(--[x]-[token]);
padding: __pt __pt;
```
Label: `[LABEL TEXT]` in [face] __pt, weight __, 0.2em tracking, color [token].

### Table
```css
table { width: 100%; table-layout: fixed; border-collapse: collapse; }
thead { display: table-header-group; }
tr    { page-break-inside: avoid; }
th    { /* ... */ }
td    { /* ... */ overflow-wrap: break-word; vertical-align: top; }
```
[State what the table never has — vertical rules? zebra striping? tinted cells?]

### Cover page
- Ground: [token]
- [Wordmark position, and whether it's the real asset or type]
- Document label: [face, size, weight, tracking, color]
- Title: [face, size, line-height]
- [Rule, standfirst, date placement]

### Page footer
- Position, alignment, content left and right
- [Face] __pt, weight __, tracking __, color [token]

### [Any component specific to what you actually make]
> Fill-in-the-blank lines for workbooks. Time badges for facilitator guides. Scripture blocks. Price rows. Whatever you build every week.

---

## 8. Always / Never

> The highest-value paragraph in the file. It takes four minutes and it prevents more damage than everything above it. A "never" is easier to follow than a "prefer" — for a person and for a model.

**Always** — [display face] uppercase at weight ___ for headlines · [the line-height rule] · [body face] for sentences · [ground rule] · [accent-per-ground rule] · [type-on-accent rule] · __pt body floor · **add a page rather than compress**.

**Never** — [display face] bold, letterspaced, or centered · [the accent on the wrong ground] · [border-radius or the opposite] · gradients, drop shadows, bevels · a fifth hue · [the specific colors that don't belong] · body copy under __pt · [the phrases or visual clichés you've banned].

---

## 9. CSS Variable Block

> Copy this into any document built in this theme. One paste, every token.

```css
:root {
  /* Core colors */
  --[x]-[name]:      #______;
  --[x]-[name]:      #______;
  --[x]-[name]:      #______;
  --[x]-[name]:      #______;   /* [ground restriction, if any] */

  /* Text */
  --[x]-text-secondary: rgba(_,_,_,0.72);
  --[x]-text-muted:     rgba(_,_,_,0.58);
  --[x]-text-faint:     rgba(_,_,_,0.42);

  /* Rules and tints */
  --[x]-rule:        rgba(_,_,_,0.16);
  --[x]-rule-light:  rgba(_,_,_,0.09);
  --[x]-callout-bg:  rgba(_,_,_,0.06);
  --[x]-note-bg:     rgba(_,_,_,0.05);

  /* Type */
  --[x]-font-display: '[Face]', [fallbacks];
  --[x]-font-body:    '[Face]', [fallbacks];

  /* Rule weights — [n], no others */
  --[x]-rule-section:  __px;
  --[x]-rule-emphasis: __px;
  --[x]-rule-standard: __px;
  --[x]-rule-hairline: __px;
}
```

> **Enforce the fragile rules at class level,** so a copy edit can't break them. If your display face must be uppercase and must never go bold, put `text-transform: uppercase` and `font-weight: 400` in the class — don't rely on whoever writes the next headline remembering.

```css
.[x]-display {
  font-family: var(--[x]-font-display);
  font-weight: 400;              /* never raise this */
  text-transform: uppercase;
  letter-spacing: 0;
  line-height: ____;
  margin: 0;
}
```

---

## Activation Instruction

> Paste this into your Claude Project's custom instructions, not just into the file. A file in project knowledge is *available*. This is what makes it the *default*.

```
[THEME NAME] is the default visual theme for every document produced in this
project. Apply it in full — colors, type scale, components, and the
Always/Never list — unless I explicitly override it for one document. Do not
simplify, compress, or substitute parts of it. Follow PRINT_SAFE_HTML.md for
anything that will be printed or saved as a PDF. If content won't fit, add a
page. Never shrink the type or cut the spacing to make it fit.
```

---

## Before you call this file finished

1. Does every color have a hex, a job, and a share of the page?
2. Has every contrast ratio been **computed**, not copied?
3. Does every type role have a size *and* a line-height?
4. Is there a hard minimum type size, with the escape hatch explicitly closed?
5. Could somebody rebuild your signature element from the text alone?
6. Is there a "Never" list?
7. Is there a version line saying what this supersedes and what wins in a conflict?
8. Read it looking for adjectives. Every adjective doing the work of a number is a bug.

---

*[THEME NAME] v1.0 · [Month Year] · [ORGANIZATION]*
*Companion: `PRINT_SAFE_HTML.md` (page mechanics)*

---

*Template from th3dan.com/theme-file — free to copy, change, and ignore.*