tokens: member docs become JSDoc; the Theme split moves onto Theme
commit 2b3489bba1f30fc89d67bb0a93ca4b9060291eb5 · parent 46d9ddfb0a
· browse this tree
Ximianth, 2026-10-18 10:46:08 UTC
The header's Theme paragraph moves onto the Theme type; its installTokens sentence merges into installTokens' own doc. tokenGroups, which had no doc, gets one line. TokenKind, the interface fields, TokenName, themeCssText, themeStyles, and installTokens get their comments as /** */ blocks. The per-token `about` strings are data and untouched. The header keeps the purpose and the SSOT statement. Wording is unchanged apart from lowercasing emphasis, backticks, name-first prefixes, and the installTokens merge; lines break at clauses.
diff --git a/packages/yukey/src/tokens.ts b/packages/yukey/src/tokens.ts index afb5543..adfba7e 100644 --- a/packages/yukey/src/tokens.ts +++ b/packages/yukey/src/tokens.ts @@ -1,41 +1,39 @@ -// The design-token vocabulary: every color, gap, size, and type choice the kit's -// components are styled with, as CSS custom properties. This file is the SSOT for -// token NAMES and their roles; docs/precepts-aesthetics.md describes the intent, and -// the `tokens` gallery entry renders the vocabulary live. -// -// Values live in a Theme (themes/default.ts is the one the kit ships). The split -// is the point: components write `var(--yk-...)` against names that hold still, -// and an application restyles the whole kit by installing a different theme. -// A Theme is typed against the vocabulary, so a theme missing a token is a compile -// error rather than a silently unstyled element. -// -// installTokens(theme) puts the theme's values on :root; custom properties inherit -// through shadow boundaries from there, so that one call is the whole setup. +// The design-token vocabulary: +// every color, gap, size, and type choice the kit's components are styled with, as CSS custom properties. +// This file is the SSOT for token names and their roles; +// docs/precepts-aesthetics.md describes the intent, and the `tokens` gallery entry renders the vocabulary live. +// Values live in a Theme; installTokens is the whole setup. import type { CSSResult } from "lit"; import { unsafeCSS } from "lit"; import { defaultTheme } from "./themes/default.js"; -// What a token's value IS (the W3C design-tokens draft calls this $type). -// The gallery picks preview renderings from it; nothing else branches on it. +/** + * TokenKind is what a token's value is (the W3C design-tokens draft calls this $type). + * The gallery picks preview renderings from it; nothing else branches on it. + */ export type TokenKind = "color" | "size" | "font" | "composite" | "duration"; export interface TokenDef { name: `--yk-${string}`; kind: TokenKind; - // The role, in a sentence: what kind of thing should use this token. + + /** about is the role, in a sentence: what kind of thing should use this token. */ about: string; } export interface TokenGroup { - // Stable handle for consumers that single out a group (the gallery's type specimen); - // title is display text and free to change. + /** + * id is a stable handle for consumers that single out a group (the gallery's type specimen); + * title is display text and free to change. + */ id: string; title: string; about: string; tokens: readonly TokenDef[]; } +/** tokenGroups is the vocabulary, grouped, in display order. */ export const tokenGroups = [ { id: "surfaces", @@ -363,15 +361,26 @@ export const tokenGroups = [ }, ] as const satisfies readonly TokenGroup[]; -// Every token name in the vocabulary, as a type. Derived from tokenGroups, so adding -// a token there is the one edit; every Theme then has to supply it. +/** + * TokenName is every token name in the vocabulary, as a type. + * Derived from {@link tokenGroups}, so adding a token there is the one edit; every Theme then has to supply it. + */ export type TokenName = (typeof tokenGroups)[number]["tokens"][number]["name"]; -// A complete set of values for the vocabulary: one CSS value per token name. +/** + * Theme is a complete set of values for the vocabulary: one CSS value per token name + * (themes/default.ts is the one the kit ships). + * The split is the point: components write `var(--yk-...)` against names that hold still, + * and an application restyles the whole kit by installing a different theme. + * A Theme is typed against the vocabulary, + * so a theme missing a token is a compile error rather than a silently unstyled element. + */ export type Theme = Readonly<Record<TokenName, string>>; -// Renders a theme into one `:root { ... }` block, in vocabulary order, group titles as comments. -// Exported for the unit test; everything else should use installTokens. +/** + * themeCssText renders a theme into one `:root { ... }` block, in vocabulary order, group titles as comments. + * Exported for the unit test; everything else should use {@link installTokens}. + */ export function themeCssText(theme: Theme, groups: readonly TokenGroup[] = tokenGroups): string { const lines: string[] = [":root {"]; for (const group of groups) { @@ -384,16 +393,20 @@ export function themeCssText(theme: Theme, groups: readonly TokenGroup[] = token return lines.join("\n"); } -// A theme as a lit CSSResult, for callers that compose stylesheets by hand. -// unsafeCSS is safe here: the text is generated from the vocabulary and the theme's -// literal values, never from runtime data. +/** + * themeStyles is a theme as a lit CSSResult, for callers that compose stylesheets by hand. + * unsafeCSS is safe here: the text is generated from the vocabulary and the theme's literal values, never from runtime data. + */ export function themeStyles(theme: Theme): CSSResult { return unsafeCSS(themeCssText(theme)); } -// Installs a theme document-wide (a <style> in head). Custom properties inherit -// into every shadow root from there. With no argument, the kit's default theme. -// Idempotent: a second call is harmless and leaves the first theme in place. +/** + * installTokens installs a theme document-wide (a `<style>` in head); + * custom properties inherit through shadow boundaries into every shadow root from there, so that one call is the whole setup. + * With no argument, the kit's default theme. + * Idempotent: a second call is harmless and leaves the first theme in place. + */ export function installTokens(theme: Theme = defaultTheme, doc: Document = document): void { if (doc.head.querySelector("style[data-yk-tokens]") !== null) return; const style = doc.createElement("style");