@kiva/kv-tokens 4.0.3 → 4.2.0

package/README.md

@@ -65,6 +65,7 @@ Our Tailwind config has some differences to the standard install. Notably
 | `@kiva/kv-tokens/js`           | `dist/js/tokens.js`         | Generated JS tokens (flat + nested)       |
 | `@kiva/kv-tokens/css`          | `dist/css/tokens.css`       | Themed CSS custom properties              |
 | `@kiva/kv-tokens/scss`         | `dist/scss/tokens.scss`     | SCSS `$variable` map                      |
+| `@kiva/kv-tokens/make-kit/*`   | `dist/make-kit/*`           | Figma Make kit (guidelines + style context) |
 
 ## Importing Source Tokens
 
@@ -99,6 +100,36 @@ Or read them off disk from `node_modules/@kiva/kv-tokens/tokens/…` — useful
 
 For the transformed, resolved-values-with-code-facing-names shape used by component code, prefer the default export of `@kiva/kv-tokens` or the flat-and-nested `@kiva/kv-tokens/js` module.
 
+## Figma Make kit
+
+`npm run build` emits `dist/make-kit/`, a [Figma Make kit](https://developers.figma.com/docs/code/write-design-system-guidelines/) built from the design-system skills in [`docs/skills/`](docs/skills):
+
+```
+dist/make-kit/
+├── styles.css                 # compiled Tailwind stylesheet (base + utilities + type + theme vars)
+└── guidelines/
+    ├── Guidelines.md          # routing document Make reads first (replaces Make's auto-created stub)
+    ├── setup.md               # how to consume the kit (styles.css, tw- prefix, theming)
+    └── foundations/*.md       # one file per design foundation
+```
+
+A skill is included in the kit when its frontmatter sets `make_kit.include: true` (with a `category` and `order`); skills without that block are excluded. Adding a new tagged skill makes it appear in the kit — and in the `Guidelines.md` routing — on the next build, with no script changes. The transform logic lives in [`build/make-kit-transform.js`](build/make-kit-transform.js); the orchestrator is [`build/build-make-kit.js`](build/build-make-kit.js).
+
+`styles.css` is the Kiva Tailwind preset compiled to a full stylesheet — base layer (fonts, headings), `tw-`-prefixed token utilities, the `tw-text-*` type system (with responsive variants), and every theme's color variables — so Make can match the design system's measurements and type whether or not it runs Tailwind itself. The safelist of utilities to emit is generated from the token scales ([`build/make-kit-safelist.js`](build/make-kit-safelist.js)), so it stays in sync as tokens change.
+
+### Importing into Figma Make
+
+Figma Make has no API to pull these in by path — you upload/drag the files into the kit. One-time setup:
+
+1. **Get the files:** `npm i @kiva/kv-tokens`, then copy from `node_modules/@kiva/kv-tokens/dist/make-kit/` (the `guidelines/` files and `styles.css`).
+2. In Figma Make: **Settings → Create a kit**.
+3. Open the **Code** view → the **`guidelines/`** folder. **Upload or drag in** `setup.md` and the `foundations/*.md` files, and replace the auto-created `Guidelines.md` with ours (or paste its contents in).
+4. Add **`styles.css`** to the project as the kit's style context (drag it into the file explorer).
+5. *(Optional)* The kit import modal also accepts npm packages and library styles, but Make kits currently support **React** codebases only — so `@kiva/kv-tokens` (a Tailwind/token package, not React) isn't added here; the compiled `styles.css` is the delivery.
+6. **Test** (prompt Make to build something and confirm it matches), then **Publish kit** to your team/org. Teammates pick it via **"Select a Make kit"** in a Make file.
+
+See [Get started with Make kits](https://help.figma.com/hc/en-us/articles/39241689698839-Get-started-with-Make-kits) and [Add guidelines to Figma Make](https://help.figma.com/hc/en-us/articles/33665861260823-Add-guidelines-to-Figma-Make).
+
 ## Local Development
 
 The `dist/` directory is gitignored but regenerated automatically by the `prepare` lifecycle script whenever you run `npm install` — both at the monorepo root and inside this package. After a fresh clone, `npm install` leaves `dist/` ready to use, so downstream workspace packages like [`@kiva/kv-components`](../kv-components/) can consume tokens without a separate build step.

package/configs/kivaTypography.js

@@ -6,7 +6,6 @@ const {
 	fontSizes,
 	fontWeights,
 	letterSpacings,
-	lineHeights,
 	lineHeightsAbsolute,
 	radii,
 	semanticFontSizes,
@@ -288,99 +287,6 @@ export const textBaseColor = 'rgb(var(--text-primary))';
  REUSABLE TYPE STYLES
 */
 export const textStyles = (() => {
-	const textJumbo = {
-		fontFamily: fonts.serif,
-		fontWeight: fontWeights.medium,
-		fontSize: rem(fontSizes.jumbo.sm),
-		letterSpacing: letterSpacings['-1'],
-		lineHeight: lineHeights.tight,
-		'@screen md': {
-			fontSize: rem(fontSizes.jumbo.md),
-		},
-		'@screen lg': {
-			fontSize: rem(fontSizes.jumbo.lg),
-		},
-	};
-
-	const textH1 = {
-		fontFamily: fonts.serif,
-		fontSize: rem(fontSizes.h1.sm),
-		fontWeight: fontWeights.medium,
-		letterSpacing: em(letterSpacings['-0.5'], fontSizes.h1.md),
-		lineHeight: lineHeights.tight,
-		'@screen md': {
-			fontSize: rem(fontSizes.h1.md),
-		},
-		'@screen lg': {
-			fontSize: rem(fontSizes.h1.lg),
-		},
-	};
-
-	const textH2 = {
-		fontFamily: fonts.serif,
-		fontSize: rem(fontSizes.h2.sm),
-		fontWeight: fontWeights.medium,
-		letterSpacing: em(letterSpacings.normal, fontSizes.h2.sm),
-		lineHeight: lineHeights.tight,
-		'@screen md': {
-			fontSize: rem(fontSizes.h2.md),
-			letterSpacing: em(letterSpacings['-0.3'], fontSizes.h2.md),
-		},
-		'@screen lg': {
-			fontSize: rem(fontSizes.h2.lg),
-			letterSpacing: em(letterSpacings['-0.3'], fontSizes.h2.lg),
-			lineHeight: lineHeights['nearly-none'],
-		},
-	};
-
-	const textH3 = {
-		fontSize: rem(fontSizes.h3.sm),
-		fontWeight: fontWeights.normal,
-		letterSpacing: em(letterSpacings['-1'], fontSizes.h3.sm),
-		lineHeight: lineHeights.tight,
-		'@screen md': {
-			fontSize: rem(fontSizes.h3.md),
-		},
-		'@screen lg': {
-			fontSize: rem(fontSizes.h3.lg),
-		},
-	};
-
-	const textH4 = {
-		fontSize: rem(fontSizes.h4.sm),
-		fontWeight: fontWeights.normal,
-		lineHeight: lineHeights.normal,
-		textTransform: 'uppercase',
-		'@screen md': {
-			fontSize: rem(fontSizes.h4.md),
-		},
-		'@screen lg': {
-			fontSize: rem(fontSizes.h4.lg),
-		},
-	};
-
-	const textH5 = {
-		fontFamily: fonts.sans,
-		fontSize: rem(fontSizes.h4.sm),
-		fontWeight: fontWeights.normal,
-		letterSpacing: em(letterSpacings.normal, fontSizes.subhead.sm),
-		lineHeight: lineHeights['nearly-none'],
-	};
-
-	const textSubhead = {
-		fontFamily: fonts.sans,
-		fontSize: rem(fontSizes.subhead.sm),
-		fontWeight: fontWeights.light,
-		letterSpacing: em(letterSpacings.normal, fontSizes.subhead.sm),
-		lineHeight: lineHeights.tight,
-		'@screen md': {
-			fontSize: rem(fontSizes.subhead.md),
-		},
-		'@screen lg': {
-			fontSize: rem(fontSizes.subhead.lg),
-		},
-	};
-
 	const textBase = {
 		fontWeight: fontWeights.light,
 		fontSize: rem(fontSizes.base.sm),
@@ -409,21 +315,6 @@ export const textStyles = (() => {
 		fontWeight: fontWeights.light,
 	};
 
-	const textBlockquote = {
-		fontFamily: fonts.serif,
-		fontSize: rem(fontSizes.h2.sm),
-		fontStyle: 'italic',
-		fontWeight: fontWeights.medium,
-		letterSpacing: em(letterSpacings['-0.5'], fontSizes.h2.sm),
-		lineHeight: lineHeights.tight,
-		'@screen md': {
-			fontSize: rem(fontSizes.h2.md),
-		},
-		'@screen lg': {
-			fontSize: rem(fontSizes.h2.lg),
-		},
-	};
-
 	const textDisplay = {
 		fontFamily: fonts.serif,
 		fontWeight: fontWeights.medium,
@@ -442,6 +333,8 @@ export const textStyles = (() => {
 		},
 	};
 
+	const textJumbo = { ...textDisplay };
+
 	const textHeadline = {
 		fontFamily: fonts.serif,
 		fontWeight: fontWeights.medium,
@@ -451,6 +344,7 @@ export const textStyles = (() => {
 		'@screen md': {
 			fontSize: rem(semanticFontSizes.h1.md),
 			letterSpacing: em(letterSpacings['-200'], semanticFontSizes.h1.md),
+			lineHeight: em(lineHeightsAbsolute.h1.md, semanticFontSizes.h1.md),
 		},
 		'@screen lg': {
 			fontSize: rem(semanticFontSizes.h1.lg),
@@ -459,6 +353,8 @@ export const textStyles = (() => {
 		},
 	};
 
+	const textH1 = { ...textHeadline };
+
 	const textHeadlineTwo = {
 		fontFamily: fonts.serif,
 		fontWeight: fontWeights.medium,
@@ -468,6 +364,7 @@ export const textStyles = (() => {
 		'@screen md': {
 			fontSize: rem(semanticFontSizes.h2.md),
 			letterSpacing: em(letterSpacings['-200'], semanticFontSizes.h2.md),
+			lineHeight: em(lineHeightsAbsolute.h2.md, semanticFontSizes.h2.md),
 		},
 		'@screen lg': {
 			fontSize: rem(semanticFontSizes.h2.lg),
@@ -476,6 +373,13 @@ export const textStyles = (() => {
 		},
 	};
 
+	const textH2 = { ...textHeadlineTwo };
+
+	const textBlockquote = {
+		...textHeadlineTwo,
+		fontStyle: 'italic',
+	};
+
 	const textSubheadline = {
 		fontFamily: fonts.sans,
 		fontWeight: fontWeights.light,
@@ -484,13 +388,19 @@ export const textStyles = (() => {
 		lineHeight: em(lineHeightsAbsolute.h3.sm, semanticFontSizes.h3.sm),
 		'@screen md': {
 			fontSize: rem(semanticFontSizes.h3.md),
+			letterSpacing: em(letterSpacings.normal, semanticFontSizes.h3.md),
+			lineHeight: em(lineHeightsAbsolute.h3.md, semanticFontSizes.h3.md),
 		},
 		'@screen lg': {
 			fontSize: rem(semanticFontSizes.h3.lg),
+			letterSpacing: em(letterSpacings.normal, semanticFontSizes.h3.lg),
 			lineHeight: em(lineHeightsAbsolute.h3.lg, semanticFontSizes.h3.lg),
 		},
 	};
 
+	const textH3 = { ...textSubheadline };
+	const textSubhead = { ...textSubheadline };
+
 	const textTitle = {
 		fontFamily: fonts.sans,
 		fontWeight: fontWeights.normal,
@@ -499,13 +409,20 @@ export const textStyles = (() => {
 		lineHeight: em(lineHeightsAbsolute.h3.sm, semanticFontSizes.h3.sm),
 		'@screen md': {
 			fontSize: rem(semanticFontSizes.h3.md),
+			letterSpacing: em(letterSpacings.normal, semanticFontSizes.h3.md),
+			lineHeight: em(lineHeightsAbsolute.h3.md, semanticFontSizes.h3.md),
 		},
 		'@screen lg': {
 			fontSize: rem(semanticFontSizes.h3.lg),
+			letterSpacing: em(letterSpacings.normal, semanticFontSizes.h3.lg),
 			lineHeight: em(lineHeightsAbsolute.h3.lg, semanticFontSizes.h3.lg),
 		},
 	};
 
+	const textH4 = { ...textTitle };
+
+	const textH5 = { ...textBase };
+
 	const textButtonLink = {
 		fontFamily: fonts.sans,
 		fontWeight: fontWeights.medium,
@@ -540,27 +457,27 @@ export const textStyles = (() => {
 	};
 
 	return {
+		textDisplay,
 		textJumbo,
+		textHeadline,
 		textH1,
+		textHeadlineTwo,
 		textH2,
+		textBlockquote,
+		textSubheadline,
+		textSubhead,
 		textH3,
+		textTitle,
 		textH4,
 		textH5,
-		textSubhead,
 		textBase,
 		textSmall,
+		textCaption,
 		textLink,
-		textPlaceholder,
-		textBlockquote,
-		textDisplay,
-		textHeadline,
-		textHeadlineTwo,
-		textSubheadline,
-		textTitle,
 		textButtonLink,
 		textUpper,
 		textLabel,
-		textCaption,
+		textPlaceholder,
 	};
 })();
 
@@ -617,9 +534,16 @@ export const proseOverrides = () => ({
 			h2: false,
 			h3: false,
 			h4: false,
+			caption: {
+				...textStyles.textCaption,
+			},
 			figcaption: {
-				fontSize: false,
-				lineHeight: false,
+				// fontSize: false,
+				// lineHeight: false,
+				...textStyles.textCaption,
+			},
+			label: {
+				...textStyles.textLabel,
 			},
 			code: {
 				color: false,
@@ -636,39 +560,47 @@ export const proseOverrides = () => ({
 				marginBottom: rem(space[2]),
 			},
 			blockquote: {
+				...textStyles?.textBlockquote,
 				marginTop: rem(space[2]),
 				marginBottom: rem(space[2]),
 				padding: `0 0 0 ${rem(space['6'])}`,
 			},
 			h1: {
-				fontSize: false,
-				letterSpacing: false,
+				...textStyles?.textDisplay,
+				// fontSize: false,
+				// letterSpacing: false,
 				marginTop: '0',
 				marginBottom: rem(space[2]),
 				color: textBaseColor,
 			},
 			h2: {
-				fontSize: false,
-				letterSpacing: false,
+				// fontSize: false,
+				// letterSpacing: false,
+				...textStyles?.textHeadline,
 				marginTop: rem(space[2]),
 				marginBottom: rem(space[2]),
 				color: textBaseColor,
 			},
 			h3: {
-				fontSize: false,
-				letterSpacing: false,
+				// fontSize: false,
+				// letterSpacing: false,
+				...textStyles?.textHeadlineTwo,
 				marginTop: rem(space[2]),
 				marginBottom: rem(space[2]),
 				color: textBaseColor,
 			},
 			h4: {
-				letterSpacing: false,
+				// fontSize: false,
+				// letterSpacing: false,
+				...textStyles?.textSubheadline,
 				marginTop: false,
 				marginBottom: rem(space[2]),
 				color: textBaseColor,
 			},
 			h5: {
-				letterSpacing: false,
+				// fontSize: false,
+				// letterSpacing: false,
+				...textStyles?.textTitle,
 				marginTop: false,
 				marginBottom: rem(space[2]),
 				color: textBaseColor,

package/configs/tailwind.config.js

@@ -215,7 +215,9 @@ export default {
 					fontSize: '0.875em',
 				},
 				blockquote: textStyles.textBlockquote,
-				'figure figcaption': textStyles.textBase,
+				'figure figcaption': textStyles.textCaption,
+				caption: textStyles.textCaption,
+				label: textStyles.textLabel,
 				'button:focus': {
 					outline: 'revert', // undo tailwind button focus styling
 				},

package/dist/dtcg/tokens.json

@@ -881,7 +881,7 @@
 		"jumbo": {
 			"sm": {
 				"$type": "number",
-				"$value": 47
+				"$value": 52
 			},
 			"md": {
 				"$type": "number",

package/dist/js/tokens.js

@@ -169,7 +169,7 @@ export const lineHeight150 = 1.5;
 export const lineHeightNearlyNone = 1.05;
 export const lineHeightTight = 1.25;
 export const lineHeightNormal = 1.5;
-export const lineHeightAbsoluteJumboSm = 47;
+export const lineHeightAbsoluteJumboSm = 52;
 export const lineHeightAbsoluteJumboMd = 52;
 export const lineHeightAbsoluteJumboLg = 57;
 export const lineHeightAbsoluteH1Sm = 31;
@@ -1014,7 +1014,7 @@ const tokens = {
 	},
 	"lineHeightsAbsolute": {
 		"jumbo": {
-			"sm": 47,
+			"sm": 52,
 			"md": 52,
 			"lg": 57
 		},

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

@@ -0,0 +1,13 @@
+# Kiva Design System — Guidelines
+
+Guidelines for building with Kiva's design system in Figma Make. Each file below covers one foundation; read the one relevant to the decision you are making. Style context (CSS custom properties for every token) is in `../styles.css`. Read `setup.md` first for how to consume the system.
+
+## Foundations
+
+- [tailwind](foundations/tailwind.md) — How to use Tailwind CSS v3 when it is backed by Kiva's design tokens — what the @kiva/kv-tokens preset changes about stock Tailwind (the tw- prefix, themable colors compiled to CSS custom properties, disabled core plugins, token-driven scales, an opinionated base layer), how to wire the preset into a project, and how the preset is compiled from DTCG tokens. Mechanical and integration-focused; for which token to pick, defer to the per-topic skills (color, spacing, radius, typography, layout).
+- [color](foundations/color.md) — Semantic color system from the Kiva design system — primitive palettes (eco-green, marigold, desert-rose, stone, gray, neutral), the five themes (Default, Green Light, Green Dark, Marigold, Stone Light), the role/slot/state token grammar, accessibility levels per pairing, and rules for picking a token by purpose rather than hex value. Sourced from Figma; values describe design intent and may diverge from current code implementation.
+- [color-themes](foundations/color-themes.md) — Per-theme semantic color token tables from the Kiva design system — every token in Default, Green Light, Green Dark, Marigold, and Stone Light, with hex value, primitive source, and Figma-authored description. Plus the shadow color tokens. The reference companion to the conceptual `color` skill.
+- [typography](foundations/typography.md) — Semantic typography guidelines from the Kiva design system — type scale, heading hierarchy, font families, pairing rules, and HTML/Tailwind mappings. Sourced from Figma; values describe design intent and may diverge from current code implementation.
+- [spacing](foundations/spacing.md) — Semantic spacing system from the Kiva design system — token categories (Structure, Component Gap, Component Inset, Micro), the 4px-grain ramp, responsive per-tier values, and rules for picking a token by spatial relationship rather than pixel value. Sourced from Figma; values describe design intent and may diverge from current code implementation.
+- [layout](foundations/layout.md) — Layout grid system from the Kiva design system — breakpoint tiers (XS/SM/MD/LG/XL), columns, gutters, margins, nested grids, and rules for aligning content within the grid. Sourced from Figma; values describe design intent and may diverge from current code implementation.
+- [radius](foundations/radius.md) — Border-radius token system from the Kiva design system — the 8-step scale from none (0px) to full (9999px), per-component use cases, the inner-radius formula for nested elements, and rules for keeping corners consistent. Sourced from Figma; values describe design intent and may diverge from current code implementation.