@rokkit/core 1.0.5 → 1.1.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./constants.js";
+export * from "./named-tokens.ts";
 export * from "./utils.js";
 export * from "./nested.js";
 export * from "./string.js";

package/dist/named-tokens.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The 24 canonical named tokens that constitute the "core" emit vocabulary.
+ * Order is significant for tests and for predictable CSS-var output ordering.
+ */
+export declare const NAMED_TOKENS: readonly ["paper", "paper-soft", "paper-mute", "paper-edge", "ink", "ink-mute", "ink-soft", "ink-faint", "primary", "on-primary", "accent", "accent-soft", "success", "success-soft", "warning", "warning-soft", "danger", "danger-soft", "error", "error-soft", "info", "info-soft", "focus-ring", "shadow-tint"];
+export type NamedToken = (typeof NAMED_TOKENS)[number];
+export type SkinRole = 'surface' | 'ink' | 'primary' | 'accent' | 'success' | 'warning' | 'danger' | 'error' | 'info';
+export type ZSlot = 'z0' | 'z1' | 'z2' | 'z3' | 'z4' | 'z5' | 'z6' | 'z7' | 'z8' | 'z9' | 'z10';
+export declare const Z_SLOTS: ZSlot[];
+/**
+ * Maps each named token to the palette shade index that backs it.
+ * 'derived' indicates the token is computed from another palette (e.g., on-primary
+ * picks the paper shade of the surface palette by default for white-on-primary).
+ *
+ *   paper:        50  (lightest surface tone, canvas)
+ *   paper-soft:   100 (card background)
+ *   paper-mute:   200 (subdued panel)
+ *   paper-edge:   400 (hairline border tone)
+ *   ink:          900 (primary text)
+ *   ink-mute:     700 (secondary text)
+ *   ink-soft:     500 (placeholder)
+ *   ink-faint:    300 (disabled)
+ *   primary:      500 (CTA fill)
+ *   on-primary:   derived — surface.50 default (white-on-primary)
+ *   accent / status: 500 (solid)
+ *   *-soft:       100 (tinted-bg companion)
+ *   focus-ring:   500 of accent
+ *   shadow-tint:  900 of ink
+ */
+export declare const NAMED_TOKEN_SHADE_MAP: Record<NamedToken, number | 'derived'>;
+/**
+ * Maps each named token to the skin role whose palette it draws from.
+ */
+export declare const NAMED_TOKEN_ROLE_MAP: Record<NamedToken, SkinRole>;
+/**
+ * Surface z-slot → named slot. Used to emit back-compat aliases like
+ * `--color-surface-z1: var(--paper-soft);` in core mode.
+ *
+ * z2/z3 collapse to paper-mute, z5/z6 to ink-soft, z7/z8 to ink-mute,
+ * z9/z10 to ink. This collapse is the contract: 4 surface tones in core mode.
+ */
+export declare const Z_COLLAPSE_MAP_SURFACE: Record<ZSlot, NamedToken>;
+/**
+ * Ink role uses the inverted z-scale (z0 = darkest = primary text).
+ * In core mode, the same 4+4 named ladder is reused; this table just inverts.
+ */
+export declare const Z_COLLAPSE_MAP_INK: Record<ZSlot, NamedToken>;
+/**
+ * Returns true when the role has a `-soft` companion in the named vocabulary.
+ * Used to decide whether the role's tinted-background slot collapses to
+ * `var(--{role}-soft)` or to `var(--{role})`.
+ */
+export declare function hasSoftCompanion(role: string): boolean;
+export declare function shadeForNamedToken(name: string): number | 'derived' | undefined;
+export declare function roleForNamedToken(name: string): SkinRole | undefined;

package/dist/theme.d.ts

@@ -80,6 +80,60 @@ export declare class Theme {
     mapVariant(color: any, variant: any): {};
     getColorRules(mapping?: null): {};
     getPalette(mapping?: null): {};
+    /**
+     * Returns the named-token layer as a map of `--{name}: <resolved value>` entries.
+     *
+     * Palette values are inlined — there is no `var(--color-{role}-{shade})` indirection.
+     *
+     * `on-primary` is derived: it picks the paper shade (50) of the surface palette so the
+     * default contrast pair is "primary fill + white-ish text." Skins that need a different
+     * pair should override via custom tokens.
+     *
+     * `*-soft` variants resolve to shade 100 of their role's palette.
+     * `shadow-tint` resolves to shade 900 of the ink palette.
+     *
+     * @param {'light' | 'dark'} _mode — accepted for symmetry with future
+     *   dark-aware derivations. Today the Theme is constructed with a mode-resolved
+     *   mapping, so this parameter is informational.
+     * @param perRoleModes — optional map of role → 'core' | 'extended'. When a token's
+     *   role is 'extended', the value is a `var(--color-{role}-{shade})` alias instead
+     *   of the inlined palette value. Defaults to 'core' for all unspecified roles
+     *   (and for the whole map when undefined).
+     */
+    getNamedTokens(_mode?: string, perRoleModes?: Record<string, 'core' | 'extended'>): Record<string, string>;
+    /**
+     * Returns z-alias CSS-var assignments for back-compat in core mode.
+     * `--color-{role}-z{n}` → `var(--{namedSlot})`.
+     *
+     * - surface: uses Z_COLLAPSE_MAP_SURFACE (z2/z3 → paper-mute, z9/z10 → ink, etc.)
+     * - ink: uses Z_COLLAPSE_MAP_INK (inverted scale)
+     * - primary/accent/status: tint-vs-solid 2-state collapse.
+     *   z0–z2 → role-soft (if it exists) else role; z3+ → role.
+     *
+     * This is the back-compat layer: existing `@apply bg-surface-z3` etc. resolves
+     * through these aliases until consumers migrate to the named vocabulary.
+     */
+    /** Accepts SkinRole and any custom skin roles beyond the SkinRole literal union. */
+    getZAliasesForCore(role: string): Record<string, string>;
+    /**
+     * Returns named tokens as CSS-var aliases pointing at the palette layer.
+     * Used in extended mode where the preset emits the full --color-{role}-{shade}
+     * palette; named tokens become thin syntactic aliases over the palette.
+     *
+     * `on-primary` aliases to `var(--color-surface-50)` (derived: paper of surface,
+     * matching the core-mode resolution).
+     */
+    getZAliasesForExtended(): Record<string, string>;
+    /**
+     * Emit the full --color-{role}-{shade} palette CSS vars for a single role.
+     * Mirrors what getPalette does for all roles, but scoped to one.
+     */
+    getPaletteForRole(role: string): Record<string, string>;
+    /**
+     * Emit z-aliases for one role in extended mode — they point at the palette vars,
+     * using TONE_MAP for surface/non-inverted roles and the inverted map for ink.
+     */
+    getZAliasesForRoleExtended(role: string): Record<string, string>;
     getShortcuts(name: any): (string[] | (RegExp | (([, variant, end]: [any, any, any]) => string))[] | (RegExp | (([, end]: [any, any]) => string))[])[];
     /**
      * Generates CSS custom property declarations for the semantic z0–z10 tone scale.

package/dist/utils.d.ts

@@ -101,9 +101,16 @@ export function hex2oklch(hex: string): string;
  */
 export function oklch2hex(L: number, C: number, H: number): string;
 /**
- * Detects whether an icon value is a CSS class (i-*) or literal text (kanji, emoji, etc.)
+ * Detects whether an icon value is a CSS class or a literal character
+ * (kanji, emoji, single letter, etc.).
+ *
+ * Anything more than one grapheme is treated as a class — including bare
+ * semantic names like `file-svelte` which UnoCSS expands to the configured
+ * icon collection via `iconShortcuts(DEFAULT_ICONS, …)`. Single characters
+ * (kanji, emoji, single letters) render as literal text.
+ *
  * @param {string | null | undefined} icon
- * @returns {boolean} true if icon is a CSS class string
+ * @returns {boolean} true if icon should render as a CSS class
  */
 export function isIconClass(icon: string | null | undefined): boolean;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/core",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Contains core utility functions and classes that can be used in various components.",
   "repository": {
     "type": "git",
@@ -46,6 +46,6 @@
     "ramda": "^0.32.0"
   },
   "devDependencies": {
-    "@rokkit/icons": "1.0.5"
+    "@rokkit/icons": "1.1.0"
   }
 }

package/src/constants.js

@@ -79,6 +79,7 @@ export const DEFAULT_ICONS = [
 	'action-close',
 	'action-copy',
 	'action-copysuccess',
+	'action-download',
 	'action-check',
 	'action-pin',
 	'action-save',
@@ -87,6 +88,20 @@ export const DEFAULT_ICONS = [
 	'node-closed',
 	'folder-opened',
 	'folder-closed',
+	'doc-default',
+	'doc-svelte',
+	'doc-js',
+	'doc-ts',
+	'doc-css',
+	'doc-html',
+	'doc-json',
+	'doc-md',
+	'doc-text',
+	'doc-pdf',
+	'doc-archive',
+	'media-image',
+	'media-video',
+	'media-audio',
 	'selector-opened',
 	'selector-closed',
 	'menu-opened',
@@ -133,7 +148,9 @@ export const DEFAULT_ICONS = [
 	'align-vertical-bottom',
 	'align-vertical-middle',
 	'view-code',
-	'view-chart'
+	'view-chart',
+	'view-preview',
+	'view-off'
 ]
 
 export const DEFAULT_OPTIONS = {

package/src/index.js

@@ -2,6 +2,7 @@
 export * from './types.js'
 // skipcq: JS-E1004 - Needed for exposing all constants
 export * from './constants.js'
+export * from './named-tokens.ts'
 // skipcq: JS-E1004 - Needed for exposing all functions
 export * from './utils.js'
 // skipcq: JS-E1004 - Needed for exposing all functions

package/src/named-tokens.ts

@@ -0,0 +1,161 @@
+/**
+ * The 24 canonical named tokens that constitute the "core" emit vocabulary.
+ * Order is significant for tests and for predictable CSS-var output ordering.
+ */
+export const NAMED_TOKENS = [
+  'paper', 'paper-soft', 'paper-mute', 'paper-edge',
+  'ink', 'ink-mute', 'ink-soft', 'ink-faint',
+  'primary', 'on-primary',
+  'accent', 'accent-soft',
+  'success', 'success-soft',
+  'warning', 'warning-soft',
+  'danger', 'danger-soft',
+  'error', 'error-soft',
+  'info', 'info-soft',
+  'focus-ring', 'shadow-tint'
+] as const
+
+export type NamedToken = (typeof NAMED_TOKENS)[number]
+
+export type SkinRole =
+  | 'surface' | 'ink' | 'primary' | 'accent'
+  | 'success' | 'warning' | 'danger' | 'error' | 'info'
+
+export type ZSlot = 'z0' | 'z1' | 'z2' | 'z3' | 'z4' | 'z5' | 'z6' | 'z7' | 'z8' | 'z9' | 'z10'
+
+export const Z_SLOTS: ZSlot[] = ['z0', 'z1', 'z2', 'z3', 'z4', 'z5', 'z6', 'z7', 'z8', 'z9', 'z10']
+
+/**
+ * Maps each named token to the palette shade index that backs it.
+ * 'derived' indicates the token is computed from another palette (e.g., on-primary
+ * picks the paper shade of the surface palette by default for white-on-primary).
+ *
+ *   paper:        50  (lightest surface tone, canvas)
+ *   paper-soft:   100 (card background)
+ *   paper-mute:   200 (subdued panel)
+ *   paper-edge:   400 (hairline border tone)
+ *   ink:          900 (primary text)
+ *   ink-mute:     700 (secondary text)
+ *   ink-soft:     500 (placeholder)
+ *   ink-faint:    300 (disabled)
+ *   primary:      500 (CTA fill)
+ *   on-primary:   derived — surface.50 default (white-on-primary)
+ *   accent / status: 500 (solid)
+ *   *-soft:       100 (tinted-bg companion)
+ *   focus-ring:   500 of accent
+ *   shadow-tint:  900 of ink
+ */
+export const NAMED_TOKEN_SHADE_MAP: Record<NamedToken, number | 'derived'> = {
+  paper: 50,
+  'paper-soft': 100,
+  'paper-mute': 200,
+  'paper-edge': 400,
+  ink: 900,
+  'ink-mute': 700,
+  'ink-soft': 500,
+  'ink-faint': 300,
+  primary: 500,
+  'on-primary': 'derived',
+  accent: 500,
+  'accent-soft': 100,
+  success: 500,
+  'success-soft': 100,
+  warning: 500,
+  'warning-soft': 100,
+  danger: 500,
+  'danger-soft': 100,
+  error: 500,
+  'error-soft': 100,
+  info: 500,
+  'info-soft': 100,
+  'focus-ring': 500,
+  'shadow-tint': 900
+}
+
+/**
+ * Maps each named token to the skin role whose palette it draws from.
+ */
+export const NAMED_TOKEN_ROLE_MAP: Record<NamedToken, SkinRole> = {
+  paper: 'surface',
+  'paper-soft': 'surface',
+  'paper-mute': 'surface',
+  'paper-edge': 'surface',
+  ink: 'ink',
+  'ink-mute': 'ink',
+  'ink-soft': 'ink',
+  'ink-faint': 'ink',
+  primary: 'primary',
+  'on-primary': 'primary',
+  accent: 'accent',
+  'accent-soft': 'accent',
+  success: 'success',
+  'success-soft': 'success',
+  warning: 'warning',
+  'warning-soft': 'warning',
+  danger: 'danger',
+  'danger-soft': 'danger',
+  error: 'error',
+  'error-soft': 'error',
+  info: 'info',
+  'info-soft': 'info',
+  'focus-ring': 'accent',
+  'shadow-tint': 'ink'
+}
+
+/**
+ * Surface z-slot → named slot. Used to emit back-compat aliases like
+ * `--color-surface-z1: var(--paper-soft);` in core mode.
+ *
+ * z2/z3 collapse to paper-mute, z5/z6 to ink-soft, z7/z8 to ink-mute,
+ * z9/z10 to ink. This collapse is the contract: 4 surface tones in core mode.
+ */
+export const Z_COLLAPSE_MAP_SURFACE: Record<ZSlot, NamedToken> = {
+  z0: 'paper',
+  z1: 'paper-soft',
+  z2: 'paper-mute',
+  z3: 'paper-mute',
+  z4: 'paper-edge',
+  z5: 'ink-soft',
+  z6: 'ink-soft',
+  z7: 'ink-mute',
+  z8: 'ink-mute',
+  z9: 'ink',
+  z10: 'ink'
+}
+
+/**
+ * Ink role uses the inverted z-scale (z0 = darkest = primary text).
+ * In core mode, the same 4+4 named ladder is reused; this table just inverts.
+ */
+export const Z_COLLAPSE_MAP_INK: Record<ZSlot, NamedToken> = {
+  z0: 'ink',
+  z1: 'ink-mute',
+  z2: 'ink-mute',
+  z3: 'ink-soft',
+  z4: 'ink-soft',
+  z5: 'paper-edge',
+  z6: 'paper-edge',
+  z7: 'paper-mute',
+  z8: 'paper-mute',
+  z9: 'paper-soft',
+  z10: 'paper'
+}
+
+const SOFT_TOKENS: Set<string> = new Set(NAMED_TOKENS.filter((t) => t.endsWith('-soft')))
+
+/**
+ * Returns true when the role has a `-soft` companion in the named vocabulary.
+ * Used to decide whether the role's tinted-background slot collapses to
+ * `var(--{role}-soft)` or to `var(--{role})`.
+ */
+export function hasSoftCompanion(role: string): boolean {
+  return SOFT_TOKENS.has(`${role}-soft`)
+}
+
+export function shadeForNamedToken(name: string): number | 'derived' | undefined {
+  return NAMED_TOKEN_SHADE_MAP[name as NamedToken]
+}
+
+export function roleForNamedToken(name: string): SkinRole | undefined {
+  return NAMED_TOKEN_ROLE_MAP[name as NamedToken]
+}

package/src/theme.ts

@@ -3,6 +3,15 @@
 import { DEFAULT_THEME_MAPPING, defaultColors, TONE_MAP, INVERTED_ROLES } from './constants'
 import { shades } from './colors/index'
 import { ColorSpace } from './color-space'
+import {
+  NAMED_TOKENS,
+  NAMED_TOKEN_SHADE_MAP,
+  NAMED_TOKEN_ROLE_MAP,
+  Z_COLLAPSE_MAP_SURFACE,
+  Z_COLLAPSE_MAP_INK,
+  Z_SLOTS,
+  hasSoftCompanion
+} from './named-tokens'
 
 /**
  * Generate shades for a color using css variable and a ColorSpace adapter.
@@ -109,9 +118,11 @@ function toneShortcuts({ prefix, name, toneName, lightValue, darkValue }) {
  * @returns {Array} Array of shortcut definitions
  */
 export function semanticShortcuts(name) {
+	const inverted = INVERTED_ROLES.has(name)
 	const shortcuts = []
-	for (const [toneName, lightValue] of Object.entries(TONE_MAP)) {
-		const darkValue = 1000 - lightValue
+	for (const [toneName, toneValue] of Object.entries(TONE_MAP)) {
+		const lightValue = inverted ? 1000 - toneValue : toneValue
+		const darkValue  = inverted ? toneValue : 1000 - toneValue
 		for (const prefix of SEMANTIC_PREFIXES) {
 			shortcuts.push(...toneShortcuts({ prefix, name, toneName, lightValue, darkValue }))
 		}
@@ -241,6 +252,191 @@ export class Theme {
 		return rules
 	}
 
+	/**
+	 * Returns the named-token layer as a map of `--{name}: <resolved value>` entries.
+	 *
+	 * Palette values are inlined — there is no `var(--color-{role}-{shade})` indirection.
+	 *
+	 * `on-primary` is derived: it picks the paper shade (50) of the surface palette so the
+	 * default contrast pair is "primary fill + white-ish text." Skins that need a different
+	 * pair should override via custom tokens.
+	 *
+	 * `*-soft` variants resolve to shade 100 of their role's palette.
+	 * `shadow-tint` resolves to shade 900 of the ink palette.
+	 *
+	 * @param {'light' | 'dark'} _mode — accepted for symmetry with future
+	 *   dark-aware derivations. Today the Theme is constructed with a mode-resolved
+	 *   mapping, so this parameter is informational.
+	 * @param perRoleModes — optional map of role → 'core' | 'extended'. When a token's
+	 *   role is 'extended', the value is a `var(--color-{role}-{shade})` alias instead
+	 *   of the inlined palette value. Defaults to 'core' for all unspecified roles
+	 *   (and for the whole map when undefined).
+	 */
+	getNamedTokens(_mode = 'light', perRoleModes?: Record<string, 'core' | 'extended'>) {
+		const colors = { ...defaultColors, ...this.#colors }
+		const result: Record<string, string> = {}
+		for (const name of NAMED_TOKENS) {
+			const value = this.#resolveNamedToken(name, colors, perRoleModes)
+			if (value !== undefined) result[`--${name}`] = value
+		}
+		return result
+	}
+
+	/**
+	 * Resolves a single named token to its CSS value, respecting per-role mode.
+	 * Returns undefined when the role's palette is missing.
+	 */
+	#resolveNamedToken(name: string, colors: Record<string, Record<string, string>>, perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
+		const role = NAMED_TOKEN_ROLE_MAP[name]
+		const shadeOrDerived = NAMED_TOKEN_SHADE_MAP[name]
+		const paletteName = this.#mapping[role]
+		if (!paletteName || !colors[paletteName]) return undefined
+		if (shadeOrDerived === 'derived') return this.#resolveDerivedToken(name, colors, perRoleModes)
+		return this.#resolveShadeToken(role, shadeOrDerived as number, colors[paletteName], perRoleModes)
+	}
+
+	/**
+	 * Resolves a shade-based named token value in either core (inline) or extended (alias) mode.
+	 */
+	#resolveShadeToken(role: string, shade: number, palette: Record<string, string>, perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
+		const roleMode = perRoleModes?.[role] ?? 'core'
+		if (roleMode === 'extended') return `var(--color-${role}-${shade})`
+		const raw = palette[String(shade)]
+		return raw !== undefined ? this.#adapter.wrap(raw) : undefined
+	}
+
+	/**
+	 * Resolves a 'derived' named token. Today only `on-primary` is derived — it picks
+	 * shade 50 from the surface palette for the default white-on-primary contrast pair.
+	 */
+	#resolveDerivedToken(name: string, colors: Record<string, Record<string, string>>, perRoleModes?: Record<string, 'core' | 'extended'>): string | undefined {
+		if (name === 'on-primary') {
+			const surfacePaletteName = this.#mapping['surface']
+			const surfacePalette = colors[surfacePaletteName]
+			if (!surfacePalette?.['50']) return undefined
+			const surfaceMode = perRoleModes?.['surface'] ?? 'core'
+			if (surfaceMode === 'extended') {
+				return `var(--color-surface-50)`
+			}
+			return this.#adapter.wrap(surfacePalette['50'])
+		}
+		return undefined
+	}
+
+	/**
+	 * Generate z-aliases for surface or ink role using the provided map.
+	 */
+	#getZAliasesFromMap(role: 'surface' | 'ink', map: Record<ZSlot, NamedToken>): Record<string, string> {
+		const result: Record<string, string> = {}
+		// Bare `--color-{role}` alias — points at the role's primary named
+		// slot. Lets preset-wind3 color utilities (bg-surface, from-surface,
+		// to-surface, etc.) resolve in core mode without forcing the full
+		// palette emit. Surface → paper, Ink → ink.
+		result[`--color-${role}`] = role === 'surface' ? 'var(--paper)' : 'var(--ink)'
+		for (const z of Z_SLOTS) {
+			result[`--color-${role}-${z}`] = `var(--${map[z]})`
+		}
+		return result
+	}
+
+	/**
+	 * Generate z-aliases for other roles using tint-vs-solid 2-state collapse.
+	 */
+	#getZAliasesOther(role: string): Record<string, string> {
+		const result: Record<string, string> = {}
+		const hasSoft = hasSoftCompanion(role)
+		const softTarget = hasSoft ? `${role}-soft` : role
+		// Bare `--color-{role}` alias points at the named token so
+		// preset-wind3 color utilities (from-{role}, to-{role}, divide-{role},
+		// etc.) resolve in core mode — they read `--color-{role}` and we'd
+		// otherwise leave it undefined since core mode skips the palette emit.
+		result[`--color-${role}`] = `var(--${role})`
+		for (const z of Z_SLOTS) {
+			const zNum = parseInt(z.slice(1), 10)
+			const target = zNum <= 2 ? softTarget : role
+			result[`--color-${role}-${z}`] = `var(--${target})`
+		}
+		return result
+	}
+
+	/**
+	 * Returns z-alias CSS-var assignments for back-compat in core mode.
+	 * `--color-{role}-z{n}` → `var(--{namedSlot})`.
+	 *
+	 * - surface: uses Z_COLLAPSE_MAP_SURFACE (z2/z3 → paper-mute, z9/z10 → ink, etc.)
+	 * - ink: uses Z_COLLAPSE_MAP_INK (inverted scale)
+	 * - primary/accent/status: tint-vs-solid 2-state collapse.
+	 *   z0–z2 → role-soft (if it exists) else role; z3+ → role.
+	 *
+	 * This is the back-compat layer: existing `@apply bg-surface-z3` etc. resolves
+	 * through these aliases until consumers migrate to the named vocabulary.
+	 */
+	/** Accepts SkinRole and any custom skin roles beyond the SkinRole literal union. */
+	getZAliasesForCore(role: string): Record<string, string> {
+		if (role === 'surface') {
+			return this.#getZAliasesFromMap('surface', Z_COLLAPSE_MAP_SURFACE)
+		}
+		if (role === 'ink') {
+			return this.#getZAliasesFromMap('ink', Z_COLLAPSE_MAP_INK)
+		}
+		return this.#getZAliasesOther(role)
+	}
+
+	/**
+	 * Returns named tokens as CSS-var aliases pointing at the palette layer.
+	 * Used in extended mode where the preset emits the full --color-{role}-{shade}
+	 * palette; named tokens become thin syntactic aliases over the palette.
+	 *
+	 * `on-primary` aliases to `var(--color-surface-50)` (derived: paper of surface,
+	 * matching the core-mode resolution).
+	 */
+	getZAliasesForExtended(): Record<string, string> {
+		const result: Record<string, string> = {}
+		for (const name of NAMED_TOKENS) {
+			const role = NAMED_TOKEN_ROLE_MAP[name]
+			const shadeOrDerived = NAMED_TOKEN_SHADE_MAP[name]
+			if (shadeOrDerived === 'derived') {
+				// on-primary → surface.50
+				result[`--${name}`] = `var(--color-surface-50)`
+				continue
+			}
+			result[`--${name}`] = `var(--color-${role}-${shadeOrDerived})`
+		}
+		return result
+	}
+
+	/**
+	 * Emit the full --color-{role}-{shade} palette CSS vars for a single role.
+	 * Mirrors what getPalette does for all roles, but scoped to one.
+	 */
+	getPaletteForRole(role: string): Record<string, string> {
+		const colors = { ...defaultColors, ...this.#colors }
+		const paletteName = this.#mapping[role]
+		if (!paletteName || !colors[paletteName]) return {}
+		const palette = colors[paletteName]
+		const result: Record<string, string> = {}
+		for (const shade of shades) {
+			if (palette[shade] !== undefined) {
+				result[`--color-${role}-${shade}`] = this.#adapter.wrap(palette[shade])
+			}
+		}
+		return result
+	}
+
+	/**
+	 * Emit z-aliases for one role in extended mode — they point at the palette vars,
+	 * using TONE_MAP for surface/non-inverted roles and the inverted map for ink.
+	 */
+	getZAliasesForRoleExtended(role: string): Record<string, string> {
+		const result: Record<string, string> = {}
+		const isInverted = INVERTED_ROLES.has(role)
+		for (const [zone, light] of Object.entries(TONE_MAP)) {
+			const shade = isInverted ? 1000 - light : light
+			result[`--color-${role}-${zone}`] = `var(--color-${role}-${shade})`
+		}
+		return result
+	}
+
 	getShortcuts(name) {
 		return [...semanticShortcuts(name), ...contrastShortcuts(name)]
 	}

package/src/utils.js

@@ -318,13 +318,22 @@ export function oklch2hex(L, C, H) {
 }
 
 /**
- * Detects whether an icon value is a CSS class (i-*) or literal text (kanji, emoji, etc.)
+ * Detects whether an icon value is a CSS class or a literal character
+ * (kanji, emoji, single letter, etc.).
+ *
+ * Anything more than one grapheme is treated as a class — including bare
+ * semantic names like `file-svelte` which UnoCSS expands to the configured
+ * icon collection via `iconShortcuts(DEFAULT_ICONS, …)`. Single characters
+ * (kanji, emoji, single letters) render as literal text.
+ *
  * @param {string | null | undefined} icon
- * @returns {boolean} true if icon is a CSS class string
+ * @returns {boolean} true if icon should render as a CSS class
  */
 export function isIconClass(icon) {
 	if (!icon || typeof icon !== 'string') return false
-	return icon.startsWith('i-')
+	// Spread to count graphemes, not UTF-16 code units, so multi-codepoint
+	// emoji (e.g. 👨‍👩‍👧‍👦) and single CJK characters don't get misread.
+	return [...icon].length > 1
 }
 
 /**