# Components — shared glossary (v0.1 — DRAFT for Isaac to ratify)

The point of this file: you and I use the **same word for the same thing**,
every time. You flagged that "set" is doing too many jobs — it is, so it's
retired below. Edit anything here; once you ratify it, it's law for the project.

---

## The core nouns (smallest → largest)

| Term | Definition | Example |
|---|---|---|
| **Token** | A single design variable. The atom of a look. Matches Mitchell's Style Guide v2 names exactly. | `--brand-primary`, `--radius-md`, `--font-heading` |
| **Skin** | A complete, coordinated set of token *values* — one full look. Swapping the skin re-skins everything. | the values that make "Warm Editorial" warm |
| **Theme** | The human-facing *name* for a skin. 1:1 with a skin. You pick a theme; the skin is how it's wired. | "Warm Editorial", "Clean Modern" |
| **Skeleton** | The structural markup + layout rules of a thing, with no skin applied. The bones. Same skeleton renders under any skin. | the HTML+layout of a button, independent of colour |
| **Component** | The smallest reusable building block = skeleton + token-driven styling. Not page-specific. | button, card, input, badge, nav-link |
| **Section** | A full-width page region **composed of components**. It adds only *layout* — grid, spacing, background, position — and **never restyles a component**. The Mobile Quick Bar's actions ARE buttons (theme button style); a service card IS a `.c-card`; a section CTA IS a `.c-btn`; a team avatar IS an `.c-img--circle`. Change a component's token and every section using it updates. This is the unit Mitchell's system distributes as a package. | hero, pricing table, testimonials, footer |
| **Variant** | A different skeleton for the *same* section purpose. | `hero-centred` vs `hero-text-image-grid` |
| **Library** | The whole collection: all skins + all components + all sections. The Bootstrap-replacement as one body of work. | "the Components library" |

**Retired word: "set".** When you reach for "set", you mean one of:
- a **theme/skin** ("a whole new set" → "a new theme")
- the **library** ("that set of comprehensive stylesheets" → "the library")
- a **component group** (buttons as a family → "the button components")

---

## The contract nouns (how it plugs into Slipstream)

| Term | Definition |
|---|---|
| **Manifest** | The machine-readable source of truth the harness binds to: every **field** and **token** Slipstream knows about, plus the 24 principles, perf budgets, and allowed Twig syntax. Derived from Mitchell's `slipstream-sections` repo. |
| **Field** | A content slot a section consumes, with a storage binding (e.g. `business.hero_headline` → `business_info.hero_headline`). Defined in Mitchell's `fields.json` / `field_definitions`. |
| **Harness** | The validator + binder. It (a) forces every section's content to map to a real field or flag a needed new one, and (b) checks the emitted package against the full spec. A harness-passed draft is *provably* spec-compliant, so Mitchell's only remaining job is visual/front-end judgement. |
| **Emit target** | Where a finished section is sent. Two of them: **Slipstream** (Mitchell's package format) and **SaaS** (Isaac's private product). Same library + harness, different emitter. |

---

## The verbs

| Term | Definition |
|---|---|
| **Skin / re-skin** | Apply or swap a skin's token values. No skeleton changes. |
| **Ingest** | Feed a URL or screenshot in; break its styling down into tokens + structure we can examine, then keep / merge / make-new. |
| **Specify (a section)** | Define a new section by nominating fields from the manifest (or flagging a new field), choosing components, and arranging them. |
| **Seed** | Claude produces a first-draft section (or skin) for you to workshop. |
| **Emit** | Render a finished section into a real package for an emit target. |

---

## One precision worth keeping straight

**"Deterministic"** describes the *output*, not the *authoring*. You and I
designing a section together is interactive and creative. What must be
deterministic is the emitted section's runtime: a pure render that, given the
same business data + skin, always produces the same HTML — no AI, no randomness
at render time. The **harness** is what guarantees that property before anything
reaches Mitchell. That is the answer to "he doesn't know if it was deterministic
or not" — a harness-passed draft provably is.

---

## Library values vs Style Guide skin

Two kinds of value live in the token layer, and it matters which is which:

- **Style Guide skin** (per-client, inherited): colour, fonts, type scale, base
  size, **rounding**, spacing unit, transition, button shape/weight/size, link
  underline. A *brand* sets these.
- **Library values / character** (per-library, the house style): the traits that
  make one library distinct from another *even under the same skin* — component
  anatomy, layout rhythm, decorative motifs, type treatment, **line thickness**
  (`--line-width`, `--btn-border-width`), and the **text-over-image halo**
  (`--text-over-image-shadow`, Principle #22 — text on a photo always gets a
  legibility shadow). A delicate library uses hairlines
  throughout; a bold one uses thick rules. These are declared in the library, not
  chosen per client.

**Line thickness was the first value we explicitly moved into the library layer**
(2026-06-03). A teardown's captured `border_width_px` is what gets assigned to a
new library's line-thickness tokens when we seed it.

---

## The three data layers (Catalogue · Library · Teardown)

| Layer | What it is | Shows |
|---|---|---|
| **Catalogue** | Every component type that *can* exist (the spec). | The full taxonomy. |
| **Library** | One instance's *decisions* — how it handles images, buttons, spacing, line weight, etc. Can render the whole catalogue in its style. | "How this library does everything." |
| **Teardown** | The *captured facts* mined from a real site. | "This is how X was handled on this site" — only if detected. By extension, "this is how it would look if this teardown became a library." |

**The hard rule for the Teardown (A-side):** it shows **captured facts only** — never
invented/generative content. If something wasn't detected, it says so or shows nothing;
it is never filled in. **Generative work is allowed in exactly two places: the tool's own
code, and the B-side (proposals).** Reference/option menus (e.g. every image-rounding
option) belong to the Catalogue/Library docs, NOT the teardown.