@kiva/kv-tokens 4.0.2 → 4.1.0

package/dist/make-kit/guidelines/foundations/tailwind.md

@@ -0,0 +1,226 @@
+# Kiva Tailwind
+
+**When to use:** When authoring or reviewing Tailwind utility classes in any repo that uses the Kiva preset (kv-components, kiva/ui, and other consumers), when setting up the preset in a new project, when a Tailwind class behaves differently than stock Tailwind would suggest (e.g. tw-text-lg or tw-font-bold "not working"), or when modifying the design-token → Tailwind pipeline inside this monorepo. Read this for how the system works and how to use it; read color/spacing/radius/typography/layout for which value to choose.
+
+## Source of truth
+
+The canonical definition of Kiva's Tailwind setup is the **preset itself** — [`@kiva/kv-tokens/configs/tailwind.config.js`](../../configs/tailwind.config.js) — and the design tokens it compiles from. Unlike the design-intent skills (color, spacing, etc.), which describe Figma intent that code may temporarily lag, this skill describes **shipped mechanics**: how the preset reshapes Tailwind and how to author against it.
+
+This skill deliberately **does not enumerate class values**. Exact scales drift as tokens change, and listing them here would duplicate the per-topic skills and the config. For specific values, read the config or the relevant skill:
+
+- **[color](color.md)** / **[color-themes](color-themes.md)** — which color token, what the themes are.
+- **[spacing](spacing.md)** — which spacing token for a given relationship.
+- **[radius](radius.md)** — which corner radius per component.
+- **[typography](typography.md)** — which text style, the type scale.
+- **[layout](layout.md)** — the breakpoint/grid system and content placement.
+
+Verify any specific class or value against the current config before depending on it.
+
+## What the preset is (mental model)
+
+Kiva does not ship a stylesheet you import — it ships a **Tailwind preset**: a partial `tailwind.config.js` that a consuming project merges into its own config via the `presets` array. Tailwind then generates utility classes from the merged result.
+
+The preset is itself generated from design tokens. The full path a value travels:
+
+```
+tokens/*.json (DTCG)  →  Style Dictionary build  →  dist/js/tokens.js
+        │                                                   │
+        │                                                   ▼
+        │                              configs/tailwind.config.js  (the preset)
+        │                                                   │
+        └──────────────► dist/css/tokens.css                ▼
+            (themed CSS custom properties)     your project's tailwind.config.js
+                                                  (presets: [tailwindConfig])
+                                                            │
+                                                            ▼
+                                                  generated tw-* utilities
+```
+
+Two consequences worth internalizing up front:
+
+1. **You author Tailwind utilities as normal** — the preset changes *which* utilities exist and what they resolve to, not *how* Tailwind works.
+2. **Themable colors are not baked into the CSS at build time.** They compile to `var(--token)` references and are resolved at runtime from CSS custom properties (see [Color](#color-is-semantic-themable-and-runtime-resolved) below). This is the single biggest departure from stock Tailwind.
+
+## Consuming the preset
+
+This is the common case: a project that installs `@kiva/kv-tokens` and wants Kiva styling.
+
+### 1. Install
+
+```sh
+npm i --save-dev @kiva/kv-tokens
+```
+
+### 2. Register the preset
+
+```js
+// tailwind.config.js
+import { tailwindConfig } from '@kiva/kv-tokens';
+
+export default {
+	presets: [tailwindConfig],
+	content: [
+		// YOUR project's template globs — the preset does not set these for you
+		'./src/**/*.{vue,js,ts}',
+	],
+};
+```
+
+Two equivalent import paths exist:
+
+- `import { tailwindConfig } from '@kiva/kv-tokens'` — named export from the package index.
+- `import tailwindConfig from '@kiva/kv-tokens/tailwind'` — the config file directly, via the `./tailwind` export.
+
+Use either. **You own `content`** — Tailwind purges any class it can't find in your templates, so an incomplete `content` glob is the most common reason a Kiva class "doesn't show up."
+
+### 3. Make themable colors resolve (required for color to render)
+
+Themable color utilities (`tw-bg-primary`, `tw-text-primary`, …) emit `rgb(var(--bg-primary))`-style values. Those custom properties must exist on the page. The preset already injects the **default theme** onto `:root` via its base layer, so a project that registers the preset gets working colors out of the box.
+
+To switch themes, swap the custom-property values for a subtree. In `@kiva/kv-components` this is done by `KvThemeProvider`; at the token layer, `@kiva/kv-tokens/css` ([`dist/css/tokens.css`](../../dist/css/tokens.css)) ships a `:root` block plus `[data-theme="…"]` blocks you can apply directly. See [color](color.md) for the theme catalog.
+
+### 4. Safelist dynamically generated classes (only if you need it)
+
+Tailwind only emits classes it can statically find in `content`. If you generate class names at runtime (e.g. a styleguide that renders every color name), build a `safelist`. `@kiva/kv-components` does this by resolving the preset and enumerating theme keys:
+
+```js
+import resolveConfig from 'tailwindcss/resolveConfig';
+import { tailwindConfig as sharedConfig } from '@kiva/kv-tokens';
+
+const { theme } = resolveConfig(sharedConfig);
+// …walk theme.backgroundColor, theme.spacing, etc. to build a safelist array
+```
+
+Most projects do **not** need this — reach for it only when class names aren't present as literal strings in your source.
+
+## Authoring with the Kiva preset
+
+This section is the heart of the skill: how stock Tailwind v3 knowledge changes once the preset is in place. Each item is a rule, the reason, and what to do instead.
+
+### Every utility carries the `tw-` prefix
+
+The preset sets `prefix: 'tw-'`. Every generated class is prefixed: `tw-flex`, `tw-mb-2`, `tw-bg-primary`.
+
+- The prefix sits **after** any variant: `hover:tw-bg-primary`, `md:tw-flex`, `dark:tw-text-primary` — not `tw-hover:...`.
+- It sits **after** a negative sign: `-tw-mt-2`.
+- Arbitrary values keep the prefix: `tw-mt-[3px]`.
+
+If a class isn't taking effect, the missing `tw-` is the first thing to check. When porting markup from a stock-Tailwind project, every utility needs the prefix added.
+
+### Color is semantic, themable, and runtime-resolved
+
+The preset replaces Tailwind's default color palette. There are two families:
+
+- **Themable (semantic) colors** — role-based names like `primary`, `secondary`, `action`, etc., available on text, background, border, ring, divide, placeholder, and gradient-stop utilities: `tw-text-primary`, `tw-bg-secondary`, `tw-border-primary`. These compile to `rgb(var(--…))` and change with the active theme. **This is what you should reach for by default.**
+- **Static colors** — fixed palettes that do *not* change with theme: `brand`, `eco-green`, `marigold`, `desert-rose`, `stone`, `gray`, `social`, plus `black` / `white` / `transparent` / `current`. Use these only when a color must stay constant regardless of theme.
+
+Opacity modifiers work on both: `tw-bg-primary/50` resolves to `rgba(var(--bg-primary), 0.5)`. Do **not** assume stock Tailwind color names exist — `tw-bg-gray-500` works (gray is a static palette) but `tw-bg-slate-500`, `tw-text-red-600`, etc. do not. For *which* token, see **[color](color.md)**.
+
+### Spacing is an 8px scale with 4px half-steps
+
+The spacing scale is token-driven: each whole step is **8px** (`tw-p-1` = 8px, `tw-m-2` = 16px), with `.5` half-steps at **4px** granularity (`tw-p-0.5` = 4px, `tw-gap-1.5` = 12px), running up to `16` (128px). This differs from stock Tailwind's 4px-per-step scale, so the *same number means a different size* — `tw-p-4` is 32px here, not 16px. Apply a scale token, never a raw pixel value; see **[spacing](spacing.md)**.
+
+### Text sizing utilities don't exist — use semantic text styles
+
+The preset **disables the `fontSize`, `lineHeight`, and `letterSpacing` core plugins.** That means these stock utilities are **not generated**:
+
+- No `tw-text-xs` / `tw-text-lg` / `tw-text-2xl` (font-size scale)
+- No `tw-leading-*` (line-height)
+- No `tw-tracking-*` (letter-spacing)
+
+Size, line-height, and letter-spacing are bundled into **semantic text-style utilities** instead — `tw-text-h1`, `tw-text-body`, `tw-text-caption`, and the 2026 styles (`tw-text-display`, `tw-text-headline`, `tw-text-title`, …). Note `tw-text-{color}` still works (color is a separate concern); only the *sizing* `tw-text-*` utilities are gone. So `tw-text-primary` (color) is valid; `tw-text-lg` (size) is not. Reach for a semantic style; see **[typography](typography.md)**.
+
+### Font weight tops out at `medium` (500)
+
+Available weights are `light` (300), `normal` (400), and `medium` (500) — plus `book` as a legacy alias for 300. There is **no `tw-font-bold`** (700) or `tw-font-semibold`. Additionally, the base layer sets `strong` / `b` to normal weight (400), so bolding text requires an explicit weight utility and the design system's heaviest weight is `medium`.
+
+### Border-radius is token-driven and `tw-rounded` ≠ pill
+
+`tw-rounded` (the unsuffixed utility) resolves to **16px**, not a small radius, and `tw-rounded-full` is the pill/circle. This is a frequent porting bug from stock Tailwind. See **[radius](radius.md)** for the full scale and the concentric-corner rules.
+
+### Breakpoints are `md` / `lg` / `xl` (mobile-first, no `sm`)
+
+The preset defines only three min-width screens — `md`, `lg`, `xl` — plus a `print` screen. There is **no `sm:` and no `2xl:`**. Unprefixed utilities are the mobile/base tier; the design system's smaller tiers (XS, SM in the layout skill) both fall under "no prefix" in Tailwind. Use `print:` to target print styles. For the grid and tier semantics, see **[layout](layout.md)**.
+
+### Z-index, shadow, and opacity are small named scales
+
+- **z-index** uses semantic names (`tw-z-modal`, `tw-z-dropdown`, `tw-z-sticky`, `tw-z-toast`, …) rather than `tw-z-10` / `tw-z-50`. Pick by role.
+- **box-shadow** ships only `tw-shadow` (default) and `tw-shadow-lg`. There is no `tw-shadow-md` / `tw-shadow-xl` scale.
+- **opacity** utilities are limited (`tw-opacity-0`, `tw-opacity-10`, `tw-opacity-low`, `tw-opacity-full`) — the full `0–100` scale is not generated. (Color opacity *modifiers* like `tw-bg-primary/50` are unaffected and work normally.)
+
+### The base layer styles bare HTML
+
+The preset's plugin injects global element styles via `addBase`: web fonts, `body` typography and color, `h1`–`h5`, `small`, `code`, `blockquote`, links (`a`), `hr`, and input placeholders, plus a button focus reset. Two implications:
+
+- Bare semantic HTML is already styled — don't re-apply utilities to recreate what the base layer provides.
+- `h6` is **not** styled by the base layer, and `strong`/`b` are set to normal (400) weight. Don't assume browser defaults for those.
+
+The `@tailwindcss/typography` plugin is included with Kiva overrides, so `tw-prose` is available for long-form rich text.
+
+### Escape hatches
+
+When no token fits, Tailwind's arbitrary-value syntax still works with the prefix (`tw-mt-[7px]`, `tw-bg-[#123456]`). Treat this as a last resort and a signal: a recurring need for an off-scale value is a design-system conversation, not a one-off. Prefer a token every time one exists.
+
+## How the preset is compiled
+
+Read this section when working **inside this monorepo** to change a value or understand where one comes from.
+
+### Token authoring
+
+Tokens are authored as [W3C DTCG](https://design-tokens.github.io/community-group/format/) JSON under [`tokens/`](../../tokens/):
+
+- [`tokens/core/`](../../tokens/core/) — primitives (color, size/space/radius/border-width, typography, z-index, opacity).
+- [`tokens/semantic/themes/`](../../tokens/semantic/themes/) — per-theme semantic tokens that reference primitives.
+
+### Build pipeline
+
+`npm run build` (also run automatically by the `prepare` lifecycle hook on install) does three things:
+
+1. **Style Dictionary** ([`build/style-dictionary.config.js`](../../build/style-dictionary.config.js)) emits `dist/js/tokens.js` (flat named exports **and** a nested default export), `dist/css/tokens.css` (themed CSS custom properties as `R, G, B` triples so opacity composes), and `dist/scss/tokens.scss`.
+2. **`build/build-dtcg.js`** deep-merges all source files into the single manifest `dist/dtcg/tokens.json`.
+3. **`build/build.js`** copies fonts and emits the heading-underline SVG sprite.
+
+`dist/` is gitignored but regenerated by `prepare`, so a fresh `npm install` leaves it ready for workspace consumers like `@kiva/kv-components`.
+
+### How the config assembles the theme
+
+[`configs/tailwind.config.js`](../../configs/tailwind.config.js) imports the generated `dist/js/tokens.js` plus two helper modules and builds the Tailwind `theme`:
+
+- **[`configs/kivaColors.js`](../../configs/kivaColors.js)** — `buildColorChoices(category)` maps each semantic token name to a `withOpacity('--token')` function so utilities emit `rgb(var(--token))` / `rgba(var(--token), <opacity>)`. It also exports per-theme objects (`defaultTheme`, `greenLightTheme`, …) that are sets of CSS custom properties.
+- **[`configs/kivaTypography.js`](../../configs/kivaTypography.js)** — text styles, web-font `@font-face` rules, and prose overrides.
+
+The config then:
+
+- Sets `prefix`, `screens`, `spacing`, `borderRadius`, `fontFamily`, `fontWeight`, `borderWidth`, `opacity`, `zIndex`, `boxShadow`, and static `colors` directly from token values.
+- Disables `container`, `fontSize`, `letterSpacing`, and `lineHeight` core plugins.
+- In `theme.extend`, wires themable color categories (`textColor`, `backgroundColor`, `borderColor`, …) to `buildColorChoices` output.
+- Registers a custom plugin that: `addBase` for element styles and web fonts, injects `:root` = `defaultTheme` custom properties, and `addUtilities` for the semantic text styles (which inherit the `tw-` prefix → `tw-text-h1`, etc.).
+
+### Changing a value safely
+
+- **To change a token value** (a color, a spacing step, a radius), edit the relevant file under `tokens/`, then run `npm run build` to regenerate `dist/`. Do **not** hand-edit `dist/` — it is generated.
+- **To change Tailwind structure** (add a utility category, adjust a base style, enable a core plugin), edit `configs/tailwind.config.js` directly.
+- After either change, rebuild and verify against a consumer (e.g. run Storybook in `@kiva/kv-components`).
+- Package exports (which subpath resolves to what) are documented in the [README](../../README.md#package-exports).
+
+## Common mistakes
+
+- Forgetting the **`tw-` prefix** on a utility (or writing `tw-hover:` instead of `hover:tw-`).
+- Using **stock Tailwind color names** (`tw-bg-slate-500`, `tw-text-red-600`) that the preset doesn't define.
+- Reaching for **`tw-text-lg` / `tw-leading-*` / `tw-tracking-*`** — disabled; use semantic text styles.
+- Expecting **`tw-font-bold`** — the heaviest weight is `medium` (500).
+- Treating **`tw-rounded`** as a small radius — it's 16px; use `tw-rounded-full` for pills.
+- Assuming a **`sm:`** breakpoint or the full **opacity / shadow / z-index** numeric scales exist.
+- Using **raw pixel values** instead of scale tokens; or assuming a spacing number matches stock Tailwind (`tw-p-4` is 32px here).
+- An incomplete **`content`** glob (or missing `safelist` for runtime-generated classes), so Tailwind purges classes you expected.
+- Hand-editing **`dist/`** instead of editing `tokens/` and rebuilding.
+
+## Current code state (verify before depending)
+
+This skill describes shipped mechanics, but specifics still change as tokens and the config evolve. Before relying on an exact class or value:
+
+- **The preset is authoritative:** [`configs/tailwind.config.js`](../../configs/tailwind.config.js) defines exactly which utilities exist and what they resolve to. The token values feeding it live in [`tokens/`](../../tokens/) and the generated [`dist/js/tokens.js`](../../dist/js/tokens.js).
+- **Disabled core plugins** (`container`, `fontSize`, `letterSpacing`, `lineHeight`) are the source of the "missing utility" surprises above — confirm the list in the config if a utility you expect is absent.
+- **Semantic color and text-style names** are the categories most likely to gain or rename entries over time; treat [color](color.md) and [typography](typography.md) as companions and cross-check the config.
+
+When you find a divergence between this skill and the shipped preset, flag it — each instance is a data point for the design-system team.

package/dist/make-kit/guidelines/foundations/typography.md

@@ -0,0 +1,257 @@
+# Kiva Typography
+
+**When to use:** When designing or implementing UI that involves text styling — choosing a heading level, applying a type token, picking a font family, building a section that pairs multiple type styles, or reasoning about typographic hierarchy. Reference design intent first; verify token names against current code before relying on them.
+
+## Source of truth
+
+This skill captures the **semantic typography system** as defined in Figma (the Kiva Ecosystem 2026 file). Figma is the canonical source for design intent: which token exists, what it means, when to use it, and how styles pair together.
+
+Numeric values, token names, and Tailwind utility class names in this document reflect the Figma specifications. The shipped code in `@kiva/kv-tokens` may temporarily lag behind these specs while the token sync work is in progress. **Verify any class name or token reference against the current code before depending on it.**
+
+## How to apply type styles
+
+Always apply type styles by using the right **semantic HTML element** or by adding a **provided typography utility class**. Do not write custom CSS to set font family, size, weight, line height, or letter spacing for text. If no existing element default or class fits the use case, that is a signal to talk to the design system team — not to author bespoke styles.
+
+The typography utility classes shipped today (defined in `configs/tailwind.config.js`, served with the `tw-` prefix the project's Tailwind config applies to all classes):
+
+- `tw-text-base`
+- `tw-text-display`
+- `tw-text-headline`
+- `tw-text-headline-two`
+- `tw-text-subheadline`
+- `tw-text-title`
+- `tw-text-button-link`
+- `tw-text-upper`
+- `tw-text-caption`
+- `tw-text-label`
+- `tw-text-small`
+- `tw-text-link`
+- `tw-text-blockquote`
+
+## Design principles
+
+1. **Hierarchy first.** Kiva serves borrowers, lenders, and partners on the same page. Stick to the predefined scale to maintain visual balance and communicate an immediate reading order.
+2. **Simple semantics.** Semantic groupings tell teams how a style is *intended* to be used, while leaving room for context-specific decisions.
+
+A typography token is a complete unit — it bundles font family, size, weight, line height, and letter spacing. Apply tokens whole; do not override individual attributes.
+
+## Typefaces
+
+| Role | Family | Used for |
+|---|---|---|
+| Serif (brand) | **Dovetail MVB** | Display, Headline 1, Headline 2 — structural hierarchy that anchors a page |
+| Sans (product) | **Kiva Post Grotesk** | Subheadline, Title, Base, all utility styles — content, UI, long-form reading |
+
+**Fallbacks**
+
+| Primary | Fallback |
+|---|---|
+| Dovetail MVB | Georgia |
+| Kiva Post Grotesk | Arial |
+
+Fallbacks are tuned to closely match the metrics of the primary typefaces to minimize layout shift if brand fonts fail to load.
+
+## Type scale
+
+Each style is responsive across three device tiers: **Large** (desktop), **Medium** (tablet), **Small** (mobile). `Base` and the small-tier utility styles (Button, Label, Caption, Upper) are universal across all devices.
+
+### Display — `Dovetail MVB Medium`
+
+Expressive, large-scale text reserved for the single most important headline on a marketing page (homepage hero, campaign title). Limit to one per page; marketing pages only.
+
+| Tier | Size | Line height | Letter spacing | Example use |
+|---|---|---|---|---|
+| Large (desktop) | 44px | 57px (1.3) | -0.88px (-0.02em) | Homepage hero, campaign hero |
+| Medium (tablet) | 40px | 52px (1.3) | -0.80px (-0.02em) | Same content, tablet |
+| Small (mobile) | 36px | 52px (1.3) | -0.72px (-0.02em) | Same content, mobile |
+
+### Headline 1 — `Dovetail MVB Medium`
+
+Primary section headers that establish top-level hierarchy within a page below the hero.
+
+| Tier | Size | Line height | Letter spacing | Example use |
+|---|---|---|---|---|
+| Large | 26px | 36px (1.4) | -0.52px (-0.02em) | Section headers |
+| Medium | 22px | 31px (1.4) | -0.22px (-0.01em) | Section headers, tablet |
+| Small | 22px | 31px (1.4) | -0.22px (-0.01em) | Section headers, mobile |
+
+> **Why are Medium and Small identical?** At this level of hierarchy, further size reduction from tablet to mobile interferes with rather than improves readability.
+
+### Headline 2 — `Dovetail MVB Medium`
+
+Secondary headers that organize and support content within a section.
+
+| Tier | Size | Line height | Letter spacing | Example use |
+|---|---|---|---|---|
+| Large | 22px | 31px (1.4) | -0.22px (-0.01em) | Category labels, subsection titles |
+| Medium | 20px | 26px (1.3) | -0.20px (-0.01em) | Same content, tablet |
+| Small | 20px | 26px (1.3) | -0.20px (-0.01em) | Same content, mobile |
+
+### Subheadline — `Kiva Post Grotesk Book`
+
+Supporting text that sits below a Headline to expand on it.
+
+| Tier | Size | Line height | Letter spacing | Example use |
+|---|---|---|---|---|
+| Large | 20px | 26px (1.3) | 0 | Subheading below the headline |
+| Medium | 18px | 23px (1.3) | 0 | Same content, tablet |
+| Small | 18px | 23px (1.3) | 0 | Same content, mobile |
+
+### Title — `Kiva Post Grotesk Medium`
+
+Component-level headings used to label cards, modules, or distinct content blocks. Same size/line-height as Subheadline but **Medium weight** instead of Book — this is what distinguishes a component title from a supporting subheadline.
+
+| Tier | Size | Line height | Letter spacing | Example use |
+|---|---|---|---|---|
+| Large | 20px | 26px (1.3) | 0 | Card headers, modal titles, list titles |
+| Medium | 18px | 23px (1.3) | 0 | Same content, tablet |
+| Small | 18px | 23px (1.3) | 0 | Same content, mobile |
+
+### Base — `Kiva Post Grotesk Book`
+
+Default body text for paragraphs and most reading content. **Universal across all devices.**
+
+| Token | Size | Line height | Letter spacing | Example use |
+|---|---|---|---|---|
+| Base | 16px | 22px (1.4) | 0 | Borrower stories, loan descriptions |
+
+### Utility / Small styles — `Kiva Post Grotesk`
+
+Functional UI text. Universal across all devices.
+
+| Token | Size | Weight | Line height | Letter spacing | Example use |
+|---|---|---|---|---|---|
+| Button | 16px | Medium | 21px (1.25) | 0 | CTA labels |
+| Label | 14px | Medium | 18px (1.25) | 0 | Form labels, filter names |
+| Caption | 14px | Book | 18px (1.25) | 0 | Disclaimers, captions |
+| Upper | 14px | Medium | 18px (1.25) | 0 | Tags, status badges (always UPPERCASE) |
+
+## Heading hierarchy & semantic HTML mapping
+
+The design system defines semantic type tokens for heading levels **h1 through h4 only**. Do not use `<h5>` or `<h6>`. For deeper content hierarchy, use a paragraph element with the appropriate type token (see "Going deeper than h4" below).
+
+### Default mapping (most contexts)
+
+| Style token | HTML element | Tailwind class | Mobile | Tablet | Desktop | Notes |
+|---|---|---|---|---|---|---|
+| Headline 1 | `<h1>` | `tw-text-headline` | 22px | 22px | 26px | Global h1 default via base CSS |
+| Headline 2 | `<h2>` | `tw-text-headline-two` | 20px | 20px | 22px | Global h2 default via base CSS |
+| Subheadline | `<h3>` | `tw-text-subheadline` | 18px | 18px | 20px | Global h3 default via base CSS |
+| Title | `<h4>` | `tw-text-title` | 18px | 18px | 20px | Global h4 default via base CSS |
+| Base / Body | `<p>`, `<body>` | `tw-text-base` | 16px | 16px | 16px | Global paragraph and body default |
+| Button | `<button>` | `tw-text-button-link` | 16px | 16px | 16px | Global button default; primary CTA labels |
+| Label | `<label>` | `tw-text-label` | 14px | 14px | 14px | Global label default |
+| Caption | `<figcaption>` | `tw-text-caption` | 14px | 14px | 14px | Use for disclaimers and captions |
+| Upper | — (utility only) | `tw-text-upper` | 14px | 14px | 14px | No element default; always UPPERCASE |
+| Small | `<small>` | `tw-text-small` | 14px | 14px | 14px | Supportive UI text |
+| Blockquote | `<blockquote>` | `tw-text-blockquote` | 20px | 20px | 22px | Italic Dovetail serif |
+| Link | `<a>` | `tw-text-link` | 16px | 16px | 16px | Underline + action color; inherits size from parent |
+
+### Going deeper than h4
+
+For content that needs sub-h4 hierarchy, do not reach for `<h5>`. Use a semantic text element with a type token instead:
+
+- "Small heading" feel → `<p>` + `tw-text-title` or `tw-text-label`
+- Supportive / metadata text → `<p>` or `<span>` + `tw-text-caption` or `tw-text-small`
+- Form field labels → `<label>` + `tw-text-label`
+
+### Contentful-specific shifted header mapping
+
+Marketing pages rendered through Contentful shift each heading element down one level so that `<h1>` can be reserved for the Display style on hero modules. Use this mapping only in the Contentful context; a CSS override is needed for it.
+
+| Style token | HTML element | Tailwind class | Mobile | Tablet | Desktop | Notes |
+|---|---|---|---|---|---|---|
+| Display | `<h1>` | `tw-text-display` | 36px | 40px | 44px | Marketing hero only; CSS override required |
+| Headline 1 | `<h2>` | `tw-text-headline` | 22px | 22px | 26px | |
+| Headline 2 | `<h3>` | `tw-text-headline-two` | 20px | 20px | 22px | |
+| Subheadline | `<h4>` | `tw-text-subheadline` | 18px | 18px | 20px | |
+| Title | `<h5>` | `tw-text-title` | 18px | 18px | 20px | Permitted only inside the Contentful shift |
+
+## Pairing guidelines
+
+The full marketing pairing pattern stacks five elements in this order:
+
+1. **Upper** — short eyebrow / category label above the headline
+2. **Display** — hero headline (one per page, marketing only)
+3. **Subheadline** — supporting paragraph that expands the headline
+4. **Button** — primary CTA
+5. **Caption** — supportive metadata, e.g., a contact prompt
+
+The standard in-page (non-hero) pairing pattern stacks:
+
+1. **Headline 1** — section header (with a paragraph of Subheadline beneath it)
+2. **Subheadline** — supporting paragraph
+3. **Headline 2** — subsection header (with a paragraph of Base beneath it)
+4. **Base** — body content
+5. **Title** — card/module heading (with a paragraph of Base beneath it)
+
+The semantic distinction worth remembering: **Subheadline** and **Title** share the same size at every tier — Subheadline (Book weight) describes/expands the thing above it, Title (Medium weight) names the thing it sits inside (a card, a modal, a module).
+
+## Best practices
+
+### Hierarchy and legibility
+
+- **Do** clearly differentiate heading sizes to create hierarchy. Use Base for long-form body paragraphs.
+- **Don't** make headings and body text look too similar. Don't use Caption or Label for long paragraphs.
+
+### All caps
+
+- **Do** use the Upper style for short, 1–3 word labels (tags, eyebrows, status badges).
+- **Don't** use all caps for full sentences or long paragraphs.
+
+## Usage rules
+
+### Do
+
+- Use the correct size tier (Large / Medium / Small) for the target device.
+- Respect the Dovetail MVB / Kiva Post Grotesk family boundary — serif for Display and Headlines, sans for everything else.
+- Limit Display to one per page, and only on marketing pages.
+- Default to Base for any paragraph content.
+
+### Don't
+
+- Override individual attributes of a token (size, weight, line height, letter spacing). Apply the token whole, or pick a different token.
+- Write custom CSS (or one-off Tailwind utility combinations like `tw-text-[18px] tw-font-medium tw-leading-[23px]`) to set type styles. Use a semantic HTML element or one of the provided typography utility classes.
+- Create new styles outside this system without design system team review.
+
+### Need something not covered here?
+
+Open a request with the design system team. Include the use case, the component, and why existing tokens don't work.
+
+## How to use in Figma
+
+All tokens are published as text styles in the Kiva Ecosystem library.
+
+- Match the size tier to your frame: Desktop frames get Large variants, Tablet frames get Medium, Mobile frames get Small. Utility styles and Base are universal.
+- A detached style breaks the connection to the library — the element stops receiving updates and becomes an undocumented variant.
+- Hover over a text style to see a description of where it's used.
+- Before handing off, inspect every text layer. If a layer shows raw values (e.g. "Dovetail / 26px / Medium") instead of a style name (e.g. "Headline 1 Large"), it's detached — reapply the matching style from the library.
+
+## Using with Tailwind
+
+The typography utilities come from the `@kiva/kv-tokens` Tailwind preset. Haven't registered it yet? See [tailwind → Consuming the preset](tailwind.md#consuming-the-preset). Not using the preset? See [Without the preset](#without-the-preset) below.
+
+Type styles ship as **semantic, whole-style utilities** (e.g. `tw-text-base`, `tw-text-headline`, `tw-text-caption`) — each bundles font-family, size, line-height, and letter-spacing together. Pick one from [How to apply type styles](#how-to-apply-type-styles) or the [HTML + Tailwind mapping](#heading-hierarchy--semantic-html-mapping) tables above; don't assemble a style from individual utilities.
+
+Two stock-Tailwind habits won't work here, by design:
+
+- **No `tw-text-lg` / `tw-text-2xl` / `tw-leading-*` / `tw-tracking-*`.** The preset disables the `fontSize`, `lineHeight`, and `letterSpacing` core plugins, so those utilities aren't generated — use a semantic text style instead. (`tw-text-{color}` like `tw-text-primary` still works; that's color, a separate concern.) See [tailwind → Text sizing utilities don't exist](tailwind.md#text-sizing-utilities-dont-exist--use-semantic-text-styles).
+- **No `tw-font-bold` / `tw-font-semibold`.** The heaviest weight is `medium` (500), and the base layer resets `strong` / `b` to normal (400). See [tailwind → Font weight tops out at `medium`](tailwind.md#font-weight-tops-out-at-medium-500).
+
+These utilities are defined in `@kiva/kv-tokens/configs/tailwind.config.js` (via `kivaTypography.js`) — verify a class name against the current config before depending on it.
+
+### Without the preset
+
+- **Kiva (or Kiva-adjacent) repo, preset not registered yet:** install and register it — [tailwind → Consuming the preset](tailwind.md#consuming-the-preset).
+- **Stock-Tailwind / non-Kiva project:** the semantic `tw-text-*` styles won't exist. Replicate a style by reading its font-family, size, and line-height from the [type scale](#type-scale) and the mapping tables, and load the web fonts with the `@font-face` rules the package ships. Copied values are point-in-time.
+
+> The in-progress `<h1>`–`<h6>` / `tw-text-h1`–`tw-text-h6` semantic remap is tracked separately — see the `header-element-audit` skill before doing heading cleanup.
+
+## Figma source references
+
+- Typography Overview: node `17279:6062`
+- Type Scales & Tokens: node `17443:6589`
+- Typography Guidelines: node `17279:6478`
+- HTML + Tailwind Reference: node `19446:186`
+
+File: `TPmBUB4olYPMF6glEhBGDG` (Ecosystem 2026 — WIP)

package/dist/make-kit/guidelines/setup.md

@@ -0,0 +1,34 @@
+# Setup
+
+**When to use:** Read this first, before generating any UI, to consume Kiva's design system correctly.
+
+Kiva's design system is a Tailwind CSS v3 preset, compiled to a full stylesheet that ships as `../styles.css` (base layer, token-backed utilities, the `tw-text-*` type system, and themable color variables).
+
+## Primary: use the compiled stylesheet
+
+Link `../styles.css` into the app and apply its `tw-`-prefixed classes directly — `tw-p-4`, `tw-text-h1`, `tw-bg-primary`, `tw-rounded-md`, etc. This needs no build step and works regardless of the app's framework or CSS setup.
+
+- Every utility carries a `tw-` prefix (e.g. `tw-bg-primary`, `tw-mb-2`).
+- Use the semantic type utilities (`tw-text-h1`, `tw-text-display`, `tw-text-caption`, …) for text — there is no `tw-text-lg`-style sizing.
+- Colors are themable: the default theme is in `:root`; set `data-theme="…"` on a container to switch (theme variables ship in `../styles.css`).
+- The foundation guidelines explain which class/token to choose for a given decision.
+
+## Optional: install the Kiva Tailwind preset
+
+If the generated app builds Tailwind itself and can add the package, this gives the full preset (utilities generated on demand rather than shipped):
+
+1. Install: `npm i -D tailwindcss@^3 @kiva/kv-tokens @tailwindcss/typography`.
+2. `tailwind.config.js`:
+
+```js
+import { tailwindConfig } from '@kiva/kv-tokens';
+
+export default {
+	presets: [tailwindConfig],
+	content: ['./src/**/*.{js,jsx,ts,tsx,html}'],
+};
+```
+
+3. Import `@tailwind base; @tailwind components; @tailwind utilities;` in your root CSS.
+
+The same `tw-` prefix and semantic type utilities apply. See `foundations/tailwind.md` for the full mechanics.