Add runtime skin contract and docs

packages/ui/src/lib/skin.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+
+import { defaultSkin, setSkin, skinDetails, skinNames } from "./skin";
+
+describe("skin contract", () => {
+  it("exposes a default skin that exists in the public name set", () => {
+    expect(skinNames).toContain(defaultSkin);
+    expect(skinDetails[defaultSkin].label).toBeTruthy();
+  });
+
+  it("sets the document root skin when no target element is provided", () => {
+    setSkin("glass");
+
+    expect(document.documentElement.dataset.skin).toBe("glass");
+  });
+
+  it("sets the provided target element instead of the document root", () => {
+    const target = document.createElement("div");
+
+    setSkin("pixel", target);
+
+    expect(target.dataset.skin).toBe("pixel");
+  });
+});

packages/ui/src/lib/skin.ts

@@ -0,0 +1,41 @@
+export const skinNames = ["minimal", "glass", "pixel"] as const;
+export type SkinName = (typeof skinNames)[number];
+
+export const defaultSkin: SkinName = "minimal";
+
+export const skinDetails = {
+  minimal: {
+    label: "Minimal",
+    note: "Restrained surfaces and low-ornament defaults"
+  },
+  glass: {
+    label: "Glass",
+    note: "Translucent layers, brighter edges, and blurred panels"
+  },
+  pixel: {
+    label: "Pixel",
+    note: "Hard edges, crisp borders, and stepped shadows"
+  }
+} as const satisfies Record<SkinName, { label: string; note: string }>;
+
+function getTargetElement(root?: HTMLElement) {
+  if (root) {
+    return root;
+  }
+
+  if (typeof document === "undefined") {
+    return undefined;
+  }
+
+  return document.documentElement;
+}
+
+export function setSkin(skin: SkinName, root?: HTMLElement) {
+  const target = getTargetElement(root);
+
+  if (!target) {
+    return;
+  }
+
+  target.dataset.skin = skin;
+}