@hzblj/kara-expo-plugin 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# @hzblj/kara-expo-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The optional Expo config plugin of kara-ui. It redefines UIKit semantic colours app-wide, natively, from a JSON file or inline values — `plugins: [['@hzblj/kara-ui', {iosSemanticColors: {file: './ios-colors.json'}}]]`.
+
+**Install [`@hzblj/kara-ui`](https://www.npmjs.com/package/@hzblj/kara-ui) instead.** This package is one of its building
+blocks, published so the umbrella can depend on it; it is versioned together with it and has no standalone docs.
+
+MIT

package/app.plugin.js

@@ -0,0 +1,2 @@
+// The Expo config plugin: `plugins: ['@hzblj/kara-expo-plugin']`. Built from `src/` by `yarn build`.
+module.exports = require('./build').default

package/build/cli.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `npx kara-icons ./assets/icons` — the half of custom icons that runs before prebuild: validation, so a bad SVG fails
+ * here rather than mid-prebuild, and the names, so the app type-checks against the icons it actually ships.
+ */
+export declare const main: (args: string[]) => number;

package/build/cli.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const icons_1 = require("./icons");
+const USAGE = `Usage: kara-icons <source> [--out <file>]
+
+  Checks every SVG in <source> the way prebuild will, and writes the TypeScript declaration that makes
+  their names valid for <Icon name="…" />. The config plugin does the same whenever the app config is
+  read; this is for CI and for projects that type-check without starting Expo.
+
+  --out   where to write the declaration (default: kara-icons.d.ts in the current directory)`;
+/**
+ * `npx kara-icons ./assets/icons` — the half of custom icons that runs before prebuild: validation, so a bad SVG fails
+ * here rather than mid-prebuild, and the names, so the app type-checks against the icons it actually ships.
+ */
+const main = (args) => {
+    const outIndex = args.indexOf('--out');
+    const out = outIndex === -1 ? 'kara-icons.d.ts' : args[outIndex + 1];
+    const source = args.find((arg, index) => !arg.startsWith('--') && index !== outIndex + 1);
+    if (!source || !out || args.includes('--help')) {
+        console.log(USAGE);
+        return source ? 0 : 1;
+    }
+    try {
+        const { android, ios, names } = (0, icons_1.readIconFolder)(node_path_1.default.resolve(source));
+        (0, node_fs_1.writeFileSync)(node_path_1.default.resolve(out), (0, icons_1.iconTypes)(names, source));
+        console.log(`kara-icons: ${names.length} icons (${ios.length} iOS, ${android.length} Android) → ${out}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        return 1;
+    }
+};
+exports.main = main;

package/build/icons.d.ts

@@ -0,0 +1,58 @@
+/** One `<path>` of a glyph. `evenOdd` keeps holes punched by an inner contour, the way Figma exports them. */
+export type IconPath = {
+    d: string;
+    evenOdd: boolean;
+};
+/** A single-colour glyph, read from an SVG: its viewBox and the paths drawn in it. */
+export type SvgIcon = {
+    height: number;
+    minX: number;
+    minY: number;
+    name: string;
+    paths: IconPath[];
+    width: number;
+};
+export type IconPlatform = 'android' | 'ios';
+/** `arrow-left` → `arrow_left`: Android resource names allow neither `-` nor capitals. */
+export declare const snakeCase: (name: string) => string;
+/** An app icon's native name, the same on both platforms: `kara_icon_<name>` — the asset, and the drawable. */
+export declare const iconResourceName: (name: string) => string;
+/**
+ * Reads one glyph. Only `<path>` elements (optionally `fill-rule="evenodd"`) inside one `<svg>` with a numeric
+ * `viewBox` are accepted, and anything else fails loudly — a glyph that silently lost a clip or a mask is worse than
+ * none (a mask leftover flattens into a solid square). The colour in the file is ignored: every icon is a template the
+ * platform tints.
+ */
+export declare const parseSvgIcon: (file: string) => SvgIcon;
+/** What one folder holds: each platform's glyphs, and every name that exists on at least one of them. */
+export type IconFolder = {
+    android: SvgIcon[];
+    ios: SvgIcon[];
+    names: string[];
+};
+/**
+ * Every icon in a folder, per platform: `<name>.svg` for both, `<name>.ios.svg` / `<name>.android.svg` for one — a
+ * variant wins over the shared file on its platform, and a name with only a variant exists on that platform alone.
+ * Refused when two names would land on one native resource name (`arrow-left` and `arrow_left`).
+ */
+export declare const readIconFolder: (directory: string) => IconFolder;
+/**
+ * An asset-catalog image set: the glyph as an SVG template that keeps its vector data, so SwiftUI's `resizable()` and
+ * `UIImageView` scale it crisply to any size, and UIKit tints it with the view's tint colour. `size` is the point size
+ * a system control draws it at when nothing resizes it.
+ */
+export declare const iosImageset: (icon: SvgIcon, assetName: string, size: number, author: string) => {
+    contents: string;
+    svg: string;
+};
+/**
+ * The glyph as an Android vector drawable — compiled by aapt like any resource, drawn by `ImageView` and Compose's
+ * `painterResource` alike. White fill, because every consumer tints it. A viewBox that does not start at the origin
+ * (Material Symbols use `0 -960 960 960`) is moved there by a group, since a vector's viewport always starts at 0,0.
+ */
+export declare const androidVectorDrawable: (icon: SvgIcon, size?: number) => string;
+/**
+ * The declaration that teaches TypeScript the app's icon names: a global `KaraIcons` the components read, so
+ * `<Icon name="bolt" />` type-checks without any import — and an icon deleted from the folder fails at its call sites.
+ */
+export declare const iconTypes: (names: string[], source: string) => string;

package/build/icons.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.iconTypes = exports.androidVectorDrawable = exports.iosImageset = exports.readIconFolder = exports.parseSvgIcon = exports.iconResourceName = exports.snakeCase = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+/** Kebab or snake case, lower case, starting with a letter: the file name is the icon name. */
+const ICON_NAME = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
+/** `share.android.svg` replaces `share.svg` on Android only — the platform's own glyph where the two differ. */
+const PLATFORM_SUFFIX = /\.(android|ios)$/;
+/** Every element the generator understands. Anything else — groups, clips, masks, strokes — must be flattened first. */
+const ALLOWED_TAGS = new Set(['path', 'svg', 'title']);
+const fail = (file, message) => {
+    throw new Error(`[kara-icons] ${node_path_1.default.basename(file)}: ${message}`);
+};
+/** `arrow-left` → `arrow_left`: Android resource names allow neither `-` nor capitals. */
+const snakeCase = (name) => name.replace(/-/g, '_').toLowerCase();
+exports.snakeCase = snakeCase;
+/** An app icon's native name, the same on both platforms: `kara_icon_<name>` — the asset, and the drawable. */
+const iconResourceName = (name) => `kara_icon_${(0, exports.snakeCase)(name)}`;
+exports.iconResourceName = iconResourceName;
+/**
+ * Reads one glyph. Only `<path>` elements (optionally `fill-rule="evenodd"`) inside one `<svg>` with a numeric
+ * `viewBox` are accepted, and anything else fails loudly — a glyph that silently lost a clip or a mask is worse than
+ * none (a mask leftover flattens into a solid square). The colour in the file is ignored: every icon is a template the
+ * platform tints.
+ */
+const parseSvgIcon = (file) => {
+    const name = node_path_1.default.basename(file, '.svg').replace(PLATFORM_SUFFIX, '');
+    const svg = (0, node_fs_1.readFileSync)(file, 'utf8');
+    if (!ICON_NAME.test(name)) {
+        fail(file, 'name it in lower kebab or snake case, starting with a letter — the file name is the icon name');
+    }
+    const viewBox = svg.match(/viewBox="\s*(-?[\d.]+)[\s,]+(-?[\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)\s*"/);
+    if (!viewBox) {
+        fail(file, 'expected a numeric viewBox="<minX> <minY> <width> <height>"');
+    }
+    for (const [, tag] of svg.matchAll(/<([a-zA-Z][\w-]*)/g)) {
+        if (!ALLOWED_TAGS.has(tag)) {
+            fail(file, `only <path> elements are supported, found <${tag}> — flatten groups, clips, masks and strokes first`);
+        }
+    }
+    const paths = [];
+    for (const [, attributes] of svg.matchAll(/<path\b([^>]*)>/g)) {
+        const d = attributes.match(/\sd="([^"]+)"/)?.[1];
+        if (!d) {
+            fail(file, '<path> without d');
+        }
+        paths.push({ d: d, evenOdd: /fill-rule="evenodd"/.test(attributes) });
+    }
+    if (paths.length === 0) {
+        fail(file, 'no <path> elements');
+    }
+    const [, minX, minY, width, height] = viewBox;
+    return { height: Number(height), minX: Number(minX), minY: Number(minY), name, paths, width: Number(width) };
+};
+exports.parseSvgIcon = parseSvgIcon;
+const glyphsFor = (directory, names, platform) => names.flatMap(name => {
+    const variant = node_path_1.default.join(directory, `${name}.${platform}.svg`);
+    const shared = node_path_1.default.join(directory, `${name}.svg`);
+    if ((0, node_fs_1.existsSync)(variant)) {
+        return [(0, exports.parseSvgIcon)(variant)];
+    }
+    return (0, node_fs_1.existsSync)(shared) ? [(0, exports.parseSvgIcon)(shared)] : [];
+});
+/**
+ * Every icon in a folder, per platform: `<name>.svg` for both, `<name>.ios.svg` / `<name>.android.svg` for one — a
+ * variant wins over the shared file on its platform, and a name with only a variant exists on that platform alone.
+ * Refused when two names would land on one native resource name (`arrow-left` and `arrow_left`).
+ */
+const readIconFolder = (directory) => {
+    if (!(0, node_fs_1.existsSync)(directory)) {
+        throw new Error(`[kara-icons] No icon folder at ${directory}.`);
+    }
+    const names = [
+        ...new Set((0, node_fs_1.readdirSync)(directory)
+            .filter(file => file.endsWith('.svg'))
+            .map(file => node_path_1.default.basename(file, '.svg').replace(PLATFORM_SUFFIX, ''))),
+    ].sort();
+    const byResource = new Map();
+    for (const name of names) {
+        const resource = (0, exports.snakeCase)(name);
+        const existing = byResource.get(resource);
+        if (existing) {
+            throw new Error(`[kara-icons] "${existing}" and "${name}" would both become the resource "${resource}".`);
+        }
+        byResource.set(resource, name);
+    }
+    return { android: glyphsFor(directory, names, 'android'), ios: glyphsFor(directory, names, 'ios'), names };
+};
+exports.readIconFolder = readIconFolder;
+const fillRule = (iconPath) => (iconPath.evenOdd ? ' fill-rule="evenodd"' : '');
+/**
+ * An asset-catalog image set: the glyph as an SVG template that keeps its vector data, so SwiftUI's `resizable()` and
+ * `UIImageView` scale it crisply to any size, and UIKit tints it with the view's tint colour. `size` is the point size
+ * a system control draws it at when nothing resizes it.
+ */
+const iosImageset = (icon, assetName, size, author) => {
+    const paths = icon.paths.map(iconPath => `  <path d="${iconPath.d}"${fillRule(iconPath)} fill="black"/>`);
+    const viewBox = `${icon.minX} ${icon.minY} ${icon.width} ${icon.height}`;
+    return {
+        contents: `${JSON.stringify({
+            images: [{ filename: `${assetName}.svg`, idiom: 'universal' }],
+            info: { author, version: 1 },
+            properties: { 'preserves-vector-representation': true, 'template-rendering-intent': 'template' },
+        }, null, 2)}\n`,
+        svg: `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="${viewBox}">\n${paths.join('\n')}\n</svg>\n`,
+    };
+};
+exports.iosImageset = iosImageset;
+/**
+ * The glyph as an Android vector drawable — compiled by aapt like any resource, drawn by `ImageView` and Compose's
+ * `painterResource` alike. White fill, because every consumer tints it. A viewBox that does not start at the origin
+ * (Material Symbols use `0 -960 960 960`) is moved there by a group, since a vector's viewport always starts at 0,0.
+ */
+const androidVectorDrawable = (icon, size = 24) => {
+    const paths = icon.paths.map(iconPath => `    <path\n        android:fillColor="@android:color/white"${iconPath.evenOdd ? '\n        android:fillType="evenOdd"' : ''}\n        android:pathData="${iconPath.d}"/>`);
+    const offset = icon.minX !== 0 || icon.minY !== 0;
+    const body = offset
+        ? `  <group android:translateX="${-icon.minX}" android:translateY="${-icon.minY}">\n${paths.join('\n')}\n  </group>`
+        : paths.join('\n').replace(/^ {2}/gm, '');
+    return `<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="${size}dp"
+    android:height="${size}dp"
+    android:viewportWidth="${icon.width}"
+    android:viewportHeight="${icon.height}">
+${body}
+</vector>
+`;
+};
+exports.androidVectorDrawable = androidVectorDrawable;
+/**
+ * The declaration that teaches TypeScript the app's icon names: a global `KaraIcons` the components read, so
+ * `<Icon name="bolt" />` type-checks without any import — and an icon deleted from the folder fails at its call sites.
+ */
+const iconTypes = (names, source) => {
+    const key = (name) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : `'${name}'`);
+    const entries = names.map(name => `    ${key(name)}: true`);
+    return `// Generated by @hzblj/kara-ui from ${source} — do not edit. It is rewritten whenever the app config is read
+// (\`expo start\`, \`expo prebuild\`), or by \`npx kara-icons ${source}\`.
+declare global {
+  interface KaraIcons {
+${entries.join('\n')}
+  }
+}
+
+export {}
+`;
+};
+exports.iconTypes = iconTypes;

package/build/index.d.ts

@@ -0,0 +1,14 @@
+import { type ConfigPlugin } from 'expo/config-plugins';
+import { type IosSemanticColorsProps } from './ios-semantic-colors';
+import { type IconsProps } from './with-icons';
+export * from './icons';
+export type { IosColorAppearances, IosSemanticColorsProps } from './ios-semantic-colors';
+export type { IconsProps } from './with-icons';
+export type KaraUIPluginProps = {
+    /** The app's icons: a folder of SVGs turned into native assets on both platforms, and their names into types. */
+    icons?: IconsProps;
+    /** Redefines UIKit semantic colours app-wide, natively. See `withIosSemanticColors`. */
+    iosSemanticColors?: IosSemanticColorsProps;
+};
+declare const _default: ConfigPlugin<KaraUIPluginProps | undefined>;
+export default _default;

package/build/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_plugins_1 = require("expo/config-plugins");
+const ios_semantic_colors_1 = require("./ios-semantic-colors");
+const with_icons_1 = require("./with-icons");
+__exportStar(require("./icons"), exports);
+/**
+ * `plugins: [['@hzblj/kara-ui', {icons: {source: './assets/icons'}}]]` in the app config. Everything native the
+ * library cannot ship itself: the app's own icons as native assets, and — optionally — what a UIKit semantic colour
+ * itself resolves to, for every token (and every piece of UIKit) that names it.
+ */
+const withKaraUI = (config, { icons, iosSemanticColors } = {}) => {
+    const withColors = iosSemanticColors ? (0, ios_semantic_colors_1.withIosSemanticColors)(config, iosSemanticColors) : config;
+    return icons ? (0, with_icons_1.withIcons)(withColors, icons) : withColors;
+};
+// Read at prebuild from the shipped package.json, beside `build/` — outside `rootDir`, so not an import.
+const pkg = require('../package.json');
+exports.default = (0, config_plugins_1.createRunOncePlugin)(withKaraUI, pkg.name, pkg.version);

package/build/ios-semantic-colors.d.ts

@@ -0,0 +1,49 @@
+import { type ConfigPlugin } from 'expo/config-plugins';
+/**
+ * Our own values for one UIKit semantic colour. `light` and `dark` are required — a colour set without both
+ * would leave one appearance to fall through to Apple's value, which is the confusing half-override.
+ */
+export type IosColorAppearances = {
+    dark: string;
+    /** Used instead of `dark` when the user has asked for increased contrast. */
+    highContrastDark?: string;
+    /** Used instead of `light` when the user has asked for increased contrast. */
+    highContrastLight?: string;
+    light: string;
+};
+export type IosSemanticColorsProps = {
+    /**
+     * The overrides, keyed by UIKit semantic name. Wins over anything in `file` for the same key, so a designer
+     * can hand over a JSON and the config can still pin one colour.
+     */
+    colors?: Record<string, IosColorAppearances>;
+    /** Path to a JSON file of the same shape, relative to the project root. */
+    file?: string;
+};
+/**
+ * Builds one colour set's `Contents.json`. Exported so the mapping can be exercised without a prebuild.
+ *
+ * A colour set carries one entry per appearance combination it answers. The plain entry is the fallback UIKit uses
+ * when nothing more specific matches, so light lives there rather than under `luminosity: light`.
+ */
+export declare const iosColorSet: (name: string, appearances: IosColorAppearances) => string;
+export declare const assertOverridable: (names: string[]) => void;
+/**
+ * Redefines what a UIKit semantic colour resolves to, app-wide, by writing a colour set of that exact name into
+ * the generated asset catalog. Both bridges look a semantic name up with `UIColor(named:)` *before* falling back
+ * to the platform's own colour, so an asset of that name wins — which is what makes this an override rather than
+ * one more token.
+ *
+ * Two things it does not do, and both matter:
+ *
+ * - It reaches only code that resolves colours *by name*, which means our own tokens. UIKit asking itself for
+ *   `UIColor.label` is a class property, not a lookup, so system chrome is unlikely to follow. Verify on device
+ *   before relying on it.
+ * - It has no Android counterpart. Material roles are computed from the wallpaper, `materialSeed` or the M3
+ *   baseline, none of which an app can reach into — so anything overridden here needs `adaptive(...)` in the
+ *   palette to match on the other platform.
+ *
+ * Prefer `adaptive({light, dark})` in the palette for a single colour. This earns its keep when one semantic
+ * backs many tokens and you want all of them moved by one edit.
+ */
+export declare const withIosSemanticColors: ConfigPlugin<IosSemanticColorsProps>;

package/build/ios-semantic-colors.js

@@ -0,0 +1,193 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withIosSemanticColors = exports.assertOverridable = exports.iosColorSet = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const config_plugins_1 = require("expo/config-plugins");
+/**
+ * The names this plugin will write a colour set for. A value rather than a type because JSON is not type-checked — a
+ * typo would otherwise produce an asset nobody asks for, and the override would silently not apply.
+ *
+ * Deliberately a copy of the theme's `IosSemanticColor` rather than an import of it: the plugin is compiled for Node on
+ * its own, and the theme sits behind platform-split files that only Metro resolves. A name added there and not here
+ * fails loudly at prebuild, listing what is known, rather than silently doing nothing.
+ */
+const OVERRIDABLE = [
+    'blueColor',
+    'clearColor',
+    'darkTextColor',
+    'labelColor',
+    'lightTextColor',
+    'linkColor',
+    'opaqueSeparatorColor',
+    'placeholderTextColor',
+    'quaternaryLabelColor',
+    'quaternarySystemFillColor',
+    'secondaryLabelColor',
+    'secondarySystemBackgroundColor',
+    'secondarySystemFillColor',
+    'secondarySystemGroupedBackgroundColor',
+    'separatorColor',
+    'systemBackgroundColor',
+    'systemBlueColor',
+    'systemBrownColor',
+    'systemCyanColor',
+    'systemFillColor',
+    'systemGray2Color',
+    'systemGray3Color',
+    'systemGray4Color',
+    'systemGray5Color',
+    'systemGray6Color',
+    'systemGrayColor',
+    'systemGreenColor',
+    'systemGroupedBackgroundColor',
+    'systemIndigoColor',
+    'systemMintColor',
+    'systemOrangeColor',
+    'systemPinkColor',
+    'systemPurpleColor',
+    'systemRedColor',
+    'systemTealColor',
+    'systemYellowColor',
+    'tertiaryLabelColor',
+    'tertiarySystemBackgroundColor',
+    'tertiarySystemFillColor',
+    'tertiarySystemGroupedBackgroundColor',
+];
+/** Stamped into every set we write, so a later run can tell ours from one a designer added by hand. */
+const AUTHOR = '@hzblj/kara-ui';
+const COLORSET_SUFFIX = '.colorset';
+const HEX_SHORT = 4;
+const HEX_RGB = 7;
+const HEX_RGBA = 9;
+const ALPHA_MAX = 255;
+const byte = (hex) => `0x${hex.toUpperCase()}`;
+/**
+ * Accepts `#rgb`, `#rrggbb` and `#rrggbbaa` — the forms the palette itself is written in, alpha last, CSS order.
+ * The asset catalog wants the channels as `0xNN` and the alpha as a decimal fraction, hence the split.
+ */
+const components = (name, appearance, hex) => {
+    const value = hex.trim();
+    if (!/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(value)) {
+        throw new Error(`[ios-semantic-colors] "${name}.${appearance}" is "${hex}" — expected #rgb, #rrggbb or #rrggbbaa.`);
+    }
+    const digits = value.length === HEX_SHORT ? [...value.slice(1)].map(digit => `${digit}${digit}`).join('') : value.slice(1, HEX_RGB);
+    const alpha = value.length === HEX_RGBA ? Number.parseInt(value.slice(HEX_RGB), 16) / ALPHA_MAX : 1;
+    return {
+        alpha: alpha.toFixed(3),
+        blue: byte(digits.slice(4, 6)),
+        green: byte(digits.slice(2, 4)),
+        red: byte(digits.slice(0, 2)),
+    };
+};
+const entry = (appearances, components) => ({
+    ...(appearances.length > 0 ? { appearances } : {}),
+    color: { 'color-space': 'srgb', components },
+    idiom: 'universal',
+});
+/**
+ * Builds one colour set's `Contents.json`. Exported so the mapping can be exercised without a prebuild.
+ *
+ * A colour set carries one entry per appearance combination it answers. The plain entry is the fallback UIKit uses
+ * when nothing more specific matches, so light lives there rather than under `luminosity: light`.
+ */
+const iosColorSet = (name, appearances) => {
+    const colors = [
+        entry([], components(name, 'light', appearances.light)),
+        entry([{ appearance: 'luminosity', value: 'dark' }], components(name, 'dark', appearances.dark)),
+    ];
+    if (appearances.highContrastLight) {
+        colors.push(entry([{ appearance: 'contrast', value: 'high' }], components(name, 'highContrastLight', appearances.highContrastLight)));
+    }
+    if (appearances.highContrastDark) {
+        colors.push(entry([
+            { appearance: 'contrast', value: 'high' },
+            { appearance: 'luminosity', value: 'dark' },
+        ], components(name, 'highContrastDark', appearances.highContrastDark)));
+    }
+    return `${JSON.stringify({ colors, info: { author: AUTHOR, version: 1 } }, null, 2)}\n`;
+};
+exports.iosColorSet = iosColorSet;
+const readJsonColors = async (projectRoot, file) => {
+    const filePath = node_path_1.default.resolve(projectRoot, file);
+    try {
+        return JSON.parse(await (0, promises_1.readFile)(filePath, 'utf8'));
+    }
+    catch (cause) {
+        throw new Error(`[ios-semantic-colors] Could not read "${filePath}".`, { cause });
+    }
+};
+const assertOverridable = (names) => {
+    const unknown = names.filter(name => !OVERRIDABLE.some(allowed => allowed === name));
+    if (unknown.length > 0) {
+        throw new Error(`[ios-semantic-colors] Not UIKit semantic colours: ${unknown.join(', ')}. ` +
+            `A name must carry its Objective-C \`Color\` suffix — \`labelColor\`, not \`label\`. ` +
+            `Known: ${OVERRIDABLE.join(', ')}.`);
+    }
+};
+exports.assertOverridable = assertOverridable;
+/**
+ * Removes sets this plugin wrote on an earlier run that are no longer configured. Only ours are touched — the
+ * author stamp is what keeps a hand-authored set safe — and a stale one matters because a colour left in the
+ * catalog keeps overriding long after it was deleted from the config.
+ */
+const removeOrphans = async (catalog, keep) => {
+    const dirents = await (0, promises_1.readdir)(catalog, { withFileTypes: true }).catch(() => []);
+    for (const dirent of dirents) {
+        if (!dirent.isDirectory() || !dirent.name.endsWith(COLORSET_SUFFIX)) {
+            continue;
+        }
+        const name = dirent.name.slice(0, -COLORSET_SUFFIX.length);
+        if (keep.has(name)) {
+            continue;
+        }
+        const setPath = node_path_1.default.join(catalog, dirent.name);
+        const existing = await (0, promises_1.readFile)(node_path_1.default.join(setPath, 'Contents.json'), 'utf8').catch(() => '');
+        if (existing.includes(`"author": "${AUTHOR}"`)) {
+            await (0, promises_1.rm)(setPath, { force: true, recursive: true });
+        }
+    }
+};
+/**
+ * Redefines what a UIKit semantic colour resolves to, app-wide, by writing a colour set of that exact name into
+ * the generated asset catalog. Both bridges look a semantic name up with `UIColor(named:)` *before* falling back
+ * to the platform's own colour, so an asset of that name wins — which is what makes this an override rather than
+ * one more token.
+ *
+ * Two things it does not do, and both matter:
+ *
+ * - It reaches only code that resolves colours *by name*, which means our own tokens. UIKit asking itself for
+ *   `UIColor.label` is a class property, not a lookup, so system chrome is unlikely to follow. Verify on device
+ *   before relying on it.
+ * - It has no Android counterpart. Material roles are computed from the wallpaper, `materialSeed` or the M3
+ *   baseline, none of which an app can reach into — so anything overridden here needs `adaptive(...)` in the
+ *   palette to match on the other platform.
+ *
+ * Prefer `adaptive({light, dark})` in the palette for a single colour. This earns its keep when one semantic
+ * backs many tokens and you want all of them moved by one edit.
+ */
+const withIosSemanticColors = (config, { colors = {}, file } = {}) => (0, config_plugins_1.withDangerousMod)(config, [
+    'ios',
+    async (config) => {
+        const fromFile = file ? await readJsonColors(config.modRequest.projectRoot, file) : {};
+        const merged = { ...fromFile, ...colors };
+        const names = Object.keys(merged);
+        (0, exports.assertOverridable)(names);
+        // Everything is generated — and therefore validated — before anything is written, so a bad hex late in the
+        // map cannot leave the catalog holding half an override.
+        const sets = names.map(name => [name, (0, exports.iosColorSet)(name, merged[name])]);
+        const catalog = node_path_1.default.join(config_plugins_1.IOSConfig.Paths.getSourceRoot(config.modRequest.projectRoot), 'Images.xcassets');
+        for (const [name, contents] of sets) {
+            const setPath = node_path_1.default.join(catalog, `${name}${COLORSET_SUFFIX}`);
+            await (0, promises_1.mkdir)(setPath, { recursive: true });
+            await (0, promises_1.writeFile)(node_path_1.default.join(setPath, 'Contents.json'), contents, 'utf8');
+        }
+        // Sets from an earlier run that are no longer configured, so a deleted override stops overriding.
+        await removeOrphans(catalog, new Set(names));
+        return config;
+    },
+]);
+exports.withIosSemanticColors = withIosSemanticColors;

package/build/with-icons.d.ts

@@ -0,0 +1,26 @@
+import { type ConfigPlugin } from 'expo/config-plugins';
+export type IconsProps = {
+    /**
+     * A folder of SVGs, one glyph per file, relative to the project root. The file name is the icon name
+     * (`bolt.svg` → `<Icon name="bolt" />`); `share.android.svg` replaces `share.svg` on Android. Only single-colour
+     * `<path>`s are accepted — the platform tints every icon.
+     */
+    source: string;
+    /**
+     * Where the declaration of the icon names goes, relative to the project root — `false` to skip it. Rewritten
+     * whenever the app config is read, so `expo start` alone keeps it current. `kara-icons.d.ts` by default.
+     */
+    types?: string | false;
+    /**
+     * The point size iOS system controls (bar items, menus, swipe actions) draw an icon at when nothing resizes it.
+     * Everything kara-ui renders sizes the icon itself. 24 by default.
+     */
+    iosSize?: number;
+};
+/**
+ * The app's icons as native assets on both platforms, generated from SVGs at prebuild: a template image set per icon in
+ * the iOS asset catalog (vector data kept), a vector drawable per icon in Android's `res/drawable`. They have to live
+ * in the app's own catalog and resources — `Image("…")` and `UIImage(named:)` look in the main bundle, and an asset
+ * catalog shipped by a pod collides with the app's `Assets.car`. A new or changed SVG needs a prebuild.
+ */
+export declare const withIcons: ConfigPlugin<IconsProps>;

package/build/with-icons.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withIcons = void 0;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const config_plugins_1 = require("expo/config-plugins");
+const icons_1 = require("./icons");
+/** Stamped into every image set this writes, so a later run can tell ours from one added by hand. */
+const AUTHOR = '@hzblj/kara-ui';
+const IMAGESET_SUFFIX = '.imageset';
+const RESOURCE_PREFIX = (0, icons_1.iconResourceName)('');
+const DEFAULT_IOS_SIZE = 24;
+const DEFAULT_TYPES = 'kara-icons.d.ts';
+/** Removes what an earlier run wrote for icons no longer in the folder — a deleted SVG must stop existing natively. */
+const removeStaleImagesets = async (catalog, keep) => {
+    const dirents = await (0, promises_1.readdir)(catalog, { withFileTypes: true }).catch(() => []);
+    for (const dirent of dirents) {
+        const name = dirent.name.slice(0, -IMAGESET_SUFFIX.length);
+        if (!dirent.isDirectory() || !dirent.name.endsWith(IMAGESET_SUFFIX) || keep.has(name)) {
+            continue;
+        }
+        const setPath = node_path_1.default.join(catalog, dirent.name);
+        const contents = await (0, promises_1.readFile)(node_path_1.default.join(setPath, 'Contents.json'), 'utf8').catch(() => '');
+        if (name.startsWith(RESOURCE_PREFIX) && contents.includes(`"author": "${AUTHOR}"`)) {
+            await (0, promises_1.rm)(setPath, { force: true, recursive: true });
+        }
+    }
+};
+const withIosIcons = (config, { iosSize = DEFAULT_IOS_SIZE, source }) => (0, config_plugins_1.withDangerousMod)(config, [
+    'ios',
+    async (config) => {
+        const { projectRoot } = config.modRequest;
+        const { ios } = (0, icons_1.readIconFolder)(node_path_1.default.resolve(projectRoot, source));
+        const catalog = node_path_1.default.join(config_plugins_1.IOSConfig.Paths.getSourceRoot(projectRoot), 'Images.xcassets');
+        const written = new Set();
+        for (const icon of ios) {
+            const assetName = (0, icons_1.iconResourceName)(icon.name);
+            const setPath = node_path_1.default.join(catalog, `${assetName}${IMAGESET_SUFFIX}`);
+            const { contents, svg } = (0, icons_1.iosImageset)(icon, assetName, iosSize, AUTHOR);
+            written.add(assetName);
+            await (0, promises_1.mkdir)(setPath, { recursive: true });
+            await (0, promises_1.writeFile)(node_path_1.default.join(setPath, 'Contents.json'), contents, 'utf8');
+            await (0, promises_1.writeFile)(node_path_1.default.join(setPath, `${assetName}.svg`), svg, 'utf8');
+        }
+        await removeStaleImagesets(catalog, written);
+        return config;
+    },
+]);
+const withAndroidIcons = (config, { source }) => (0, config_plugins_1.withDangerousMod)(config, [
+    'android',
+    async (config) => {
+        const { platformProjectRoot, projectRoot } = config.modRequest;
+        const { android } = (0, icons_1.readIconFolder)(node_path_1.default.resolve(projectRoot, source));
+        const drawables = node_path_1.default.join(platformProjectRoot, 'app', 'src', 'main', 'res', 'drawable');
+        const written = new Set(android.map(icon => `${(0, icons_1.iconResourceName)(icon.name)}.xml`));
+        await (0, promises_1.mkdir)(drawables, { recursive: true });
+        for (const icon of android) {
+            await (0, promises_1.writeFile)(node_path_1.default.join(drawables, `${(0, icons_1.iconResourceName)(icon.name)}.xml`), (0, icons_1.androidVectorDrawable)(icon), 'utf8');
+        }
+        // The `kara_icon_` prefix is this plugin's alone, so any such drawable not written now was written before.
+        for (const file of await (0, promises_1.readdir)(drawables)) {
+            if (file.startsWith(RESOURCE_PREFIX) && file.endsWith('.xml') && !written.has(file)) {
+                await (0, promises_1.rm)(node_path_1.default.join(drawables, file), { force: true });
+            }
+        }
+        return config;
+    },
+]);
+/**
+ * Keeps the declaration of icon names in step with the folder. Done while the config is evaluated rather than in a mod
+ * on purpose: mods run only at prebuild, while `expo start` reads the config too — so adding an SVG and starting Metro
+ * is all it takes for its name to type-check. Written only when the content changed.
+ */
+const writeTypes = (projectRoot, { source, types = DEFAULT_TYPES }) => {
+    if (types === false) {
+        return;
+    }
+    const { names } = (0, icons_1.readIconFolder)(node_path_1.default.resolve(projectRoot, source));
+    const file = node_path_1.default.resolve(projectRoot, types);
+    const contents = (0, icons_1.iconTypes)(names, source);
+    if (!(0, node_fs_1.existsSync)(file) || (0, node_fs_1.readFileSync)(file, 'utf8') !== contents) {
+        (0, node_fs_1.writeFileSync)(file, contents);
+    }
+};
+/**
+ * The app's icons as native assets on both platforms, generated from SVGs at prebuild: a template image set per icon in
+ * the iOS asset catalog (vector data kept), a vector drawable per icon in Android's `res/drawable`. They have to live
+ * in the app's own catalog and resources — `Image("…")` and `UIImage(named:)` look in the main bundle, and an asset
+ * catalog shipped by a pod collides with the app's `Assets.car`. A new or changed SVG needs a prebuild.
+ */
+const withIcons = (config, props) => {
+    writeTypes(config._internal?.projectRoot ?? process.cwd(), props);
+    return withAndroidIcons(withIosIcons(config, props), props);
+};
+exports.withIcons = withIcons;

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@hzblj/kara-expo-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The Expo config plugin and tooling of @hzblj/kara-ui: the app's SVG icons as native assets on iOS and Android, and UIKit semantic colour overrides.",
+  "author": "Jan Blazej",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hzblj/kara-ui.git",
+    "directory": "packages/expo-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/hzblj/kara-ui/issues"
+  },
+  "homepage": "https://github.com/hzblj/kara-ui/tree/main/packages/expo-plugin#readme",
+  "keywords": [
+    "expo",
+    "config-plugin",
+    "kara-ui"
+  ],
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./cli": {
+      "types": "./build/cli.d.ts",
+      "default": "./build/cli.js"
+    },
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build",
+    "app.plugin.js"
+  ],
+  "scripts": {
+    "build": "tsc -p ./tsconfig.json",
+    "clean": "rm -rf build",
+    "prepack": "yarn run -T turbo run build --filter=$npm_package_name...",
+    "lint": "yarn run -T concurrently \"yarn biome:check\" \"yarn tsc:check\"",
+    "lint:fix": "yarn run -T biome check --write .",
+    "biome:check": "yarn run -T biome check .",
+    "tsc:check": "tsc -p ./tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "expo": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "expo": "~57.0.22",
+    "typescript": "~7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}