@kyzarky/ui 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ky Merritt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,172 @@
 # @kyzarky/ui
 
-This version is a placeholder with nothing in it. It was published so the package exists
-and npm trusted publishing could be set up. Use 0.1.0 or later.
+Design tokens and React components for Ky Merritt's apps: a Tailwind CSS 4 theme with
+light and dark values, and the components built on it
+([ADR 0002](docs/decisions/0002-first-scope.md)). First consumer: Fluent Prior. Next:
+Merritt's Mini Mind.
 
-Source: https://github.com/KyzarKy/design-system
+## Use
+
+```bash
+npm install --save-exact @kyzarky/ui
+```
+
+Then import the theme after Tailwind in the app's CSS:
+
+```css
+@import "tailwindcss";
+@import "@kyzarky/ui/theme.css";
+```
+
+It needs Tailwind CSS 4, and React 19 for the components. The import also has the app's
+Tailwind scan the package's components, so their classes are generated with the app's own.
+**Pin an exact version and upgrade on purpose,** so work in
+progress here never changes an app under it. The [changelog](CHANGELOG.md) says what each
+version changes and how to upgrade.
+
+## Tokens
+
+The names are shadcn/ui's, plus three status colors. Each is a CSS variable (`--card`) and
+a Tailwind color (`bg-card`, `text-card`, `border-card`, and so on).
+
+| Token | Used for |
+|---|---|
+| `background` | The page |
+| `foreground` | Text |
+| `card` | Raised surfaces |
+| `card-foreground` | Text on a card |
+| `muted` | Subtle fills: meter tracks, inset boxes, the unselected segment |
+| `muted-foreground` | Secondary text |
+| `border` | Card edges and dividers. Decorative: too faint for a control's edge |
+| `input` | Edges of form controls (3:1 or more) |
+| `primary` | Brand: filled buttons, meters, links |
+| `primary-foreground` | Text on `primary` |
+| `ring` | Focus rings |
+| `success`, `warning`, `destructive` | Results and notices, as text or as a `/15` badge |
+
+The pairs this table implies meet WCAG AA in both modes: text on each surface, status
+colors on their badges, and `input` and `ring` edges. The tests check each one.
+
+## Light and dark
+
+Each token holds both values, and CSS's `light-dark()` picks one from the `color-scheme`
+of the element using it. The theme sets `color-scheme: light dark` on `:root`, so the page
+follows the system. To let people choose, set `color-scheme` yourself:
+
+```css
+:root { color-scheme: light; }
+.dark { color-scheme: dark; }
+```
+
+Don't use Tailwind's `dark:` variant: the tokens already change.
+
+- **Browsers:** both themes need `light-dark()`: Safari 17.5, Chrome 123, Firefox 120, or
+  later. A browser without it gets the light theme, whatever the system is set to
+  ([ADR 0003](docs/decisions/0003-light-fallback-and-browser-check.md)).
+- **Reading a token in JavaScript** gives the text `light-dark(#f6f4ef, #15181a)`, not a
+  color. Read a computed property instead, such as
+  `getComputedStyle(document.body).backgroundColor`.
+
+## Theming
+
+Redefine a token after the import. The theme's tokens sit in a cascade layer, so an app's
+own rule wins wherever it is. For example, a green brand color:
+
+```css
+:root {
+  --primary: light-dark(#2f6b3f, #5fd08a);
+}
+```
+
+`ring` follows `primary` unless you set it too. Keep the contrast of every pair in the
+table above.
+
+## Components
+
+```tsx
+import { List, ListRow, Meter } from "@kyzarky/ui";
+
+<List heading={<h3>Grammar</h3>} description="Optional help text.">
+  <ListRow label="Question word order" detail="99% · 9 answers">
+    <Meter value={0.99} />
+  </ListRow>
+</List>
+```
+
+- **`List`** is a group of rows with a divider between them. Pass the `heading` as an
+  element, at whatever level the page needs; `List` sets its look. A `List` that follows
+  something sits 32px below it.
+- **`ListRow`** is one row: a `label`, a `detail` on the right, and optional children
+  below for a graphic.
+- **`Meter`** is a bar for a `value` from 0 to 1. It's hidden from screen readers, so
+  state the value in the row's `detail`.
+
+## Rules
+
+- **Less space inside a group than between groups,** at least 1:2.
+- **Rows are separated by dividers; groups by space and a heading.**
+- **Type roles:** page title `text-2xl` semibold; card title `text-lg` semibold; group
+  heading `text-base` semibold; body `text-base`; row labels and help text `text-sm`;
+  details `text-sm` in `muted-foreground`, with `tabular-nums` for numbers; counters and
+  chips `text-xs`.
+- **Every control is at least 44px tall.**
+- **A value shown as a graphic is also shown as text.**
+
+## Why
+
+- One visual language across Ky's portfolio apps.
+- Fluent Prior's "What you know" list is hard to read: it's hard to tell where one row ends
+  and the next starts. The fix is rules the app never had, and they belong here, not in
+  one app.
+- A token-themed design system is the kind of frontend work Ky's job search targets.
+
+## Decisions
+
+- **[ADR 0001](docs/decisions/0001-name-registry-and-contents.md), accepted:** the package
+  is `@kyzarky/ui`, published to public npm from this repo, with tokens and React
+  components.
+- **[ADR 0002](docs/decisions/0002-first-scope.md), accepted:** the first scope, based on
+  a [style audit](docs/audit/README.md) of both apps.
+- **[ADR 0003](docs/decisions/0003-light-fallback-and-browser-check.md), accepted:** a
+  light fallback for browsers without `light-dark()`, and a browser check in CI.
+
+## Development
+
+| Command | What it does |
+|---|---|
+| `npm run verify` | Typecheck, lint, test, and build |
+| `npm run build` | Compiles `src` to `dist` with `tsc`. `npm pack` and `npm publish` run it first |
+| `npm test` | The contrast, fallback, and component tests, and a Tailwind build of the theme |
+| `npm run test:browsers` | Opens `browser-check.html` in Chromium, Firefox, and WebKit, in light and dark. Needs `npx playwright install` once. Add engine names to run only those: `npm run test:browsers -- webkit` |
+| `npm run format` | Biome: format and apply safe lint fixes |
+
+## Releasing
+
+1. In a pull request: bump `version` in `package.json` and add a changelog entry.
+2. Try it in an app before merging: `npm pack`, then in the app
+   `npm install --no-save <path to the .tgz>` and its `npm run verify`.
+3. After merging, tag the merge commit and push the tag:
+   `git tag v0.2.0 && git push origin v0.2.0`. The publish workflow checks that the tag
+   matches `package.json`, runs `verify`, and publishes with provenance. It skips a
+   version that's already on npm, so running it again is safe.
+
+**How publishing is set up** ([ADR 0001](docs/decisions/0001-name-registry-and-contents.md)).
+npm adds a trusted publisher only to a package that already exists, and a new one expires
+unless it makes a successful publish within 2 days. So:
+
+1. `0.0.0` is a placeholder with no theme in it, published by hand so the package exists.
+   It's deprecated.
+2. The trusted publisher is added with
+   `npm trust github @kyzarky/ui --file publish.yml --repo KyzarKy/design-system --allow-publish`.
+3. Pushing `v0.1.0` within those 2 days has CI publish the first real version, which
+   confirms the setup. A replacement trusted publisher would have the same 2 days.
+4. Then publishing access is set to require two-factor auth and disallow tokens, in the
+   package's settings on npmjs.com.
+
+## How we work
+
+Ky decides; Claude proposes and implements. Docs first: decisions go in ADRs before code.
+Small commits, each saying what changed and why, how to verify it, and three questions an
+interviewer might ask, with short answers. Never commit secrets. Never force-push. Commits
+use Ky's GitHub noreply email (set in this repo's git config). In anything written in Ky's
+voice: no em dashes, and use Oxford commas.

package/dist/List.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+interface ListProps {
+    /**
+     * The heading element, at whatever level the page needs: `<h3>Grammar</h3>`. The level
+     * is the page's to choose; the look is set here. Tailwind's preflight makes headings
+     * inherit size and weight, so the wrapper's classes apply to it.
+     */
+    heading?: ReactNode;
+    /** A line of help text between the heading and the rows. */
+    description?: ReactNode;
+    /** `ListRow`s. */
+    children: ReactNode;
+}
+export declare function List({ heading, description, children }: ListProps): import("react").JSX.Element;
+export {};

package/dist/List.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function List({ heading, description, children }) {
+    return (_jsxs("div", { className: "mt-8 first:mt-0", children: [heading && _jsx("div", { className: "font-semibold text-base", children: heading }), description && _jsx("p", { className: "mt-1 text-muted-foreground text-sm", children: description }), _jsx("ul", { className: "mt-2 divide-y divide-border", children: children })] }));
+}

package/dist/ListRow.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+interface ListRowProps {
+    label: ReactNode;
+    /** Secondary text on the right. If the row has a graphic, this states its value. */
+    detail?: ReactNode;
+    /** A graphic for the row, such as a `Meter`. */
+    children?: ReactNode;
+}
+export declare function ListRow({ label, detail, children }: ListRowProps): import("react").JSX.Element;
+export {};

package/dist/ListRow.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function ListRow({ label, detail, children }) {
+    return (_jsxs("li", { className: "py-3", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3 text-sm", children: [_jsx("span", { children: label }), detail && _jsx("span", { className: "shrink-0 text-muted-foreground tabular-nums", children: detail })] }), children && _jsx("div", { className: "mt-2", children: children })] }));
+}

package/dist/Meter.d.ts

@@ -0,0 +1,6 @@
+interface MeterProps {
+    /** From 0 to 1. Values outside that are clamped, and NaN draws an empty bar. */
+    value: number;
+}
+export declare function Meter({ value }: MeterProps): import("react").JSX.Element;
+export {};

package/dist/Meter.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function Meter({ value }) {
+    // `|| 0` turns NaN into 0. An invalid width would be ignored, leaving the bar full.
+    const percent = Math.min(1, Math.max(0, value || 0)) * 100;
+    return (_jsx("div", { "aria-hidden": "true", className: "h-2 overflow-hidden rounded-full bg-muted", children: _jsx("div", { className: "h-full rounded-full bg-primary", style: { width: `${percent}%` } }) }));
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { List } from "./List.js";
+export { ListRow } from "./ListRow.js";
+export { Meter } from "./Meter.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// The package's components. The tokens they use come from theme.css.
+export { List } from "./List.js";
+export { ListRow } from "./ListRow.js";
+export { Meter } from "./Meter.js";

package/package.json

@@ -1,14 +1,53 @@
 {
   "name": "@kyzarky/ui",
-  "version": "0.0.0",
-  "description": "Placeholder. The first release of @kyzarky/ui is 0.1.0.",
+  "version": "0.2.0",
+  "description": "Design tokens and React components for Ky Merritt's apps, built on Tailwind CSS 4",
   "license": "MIT",
   "author": "Ky Merritt",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/KyzarKy/design-system.git"
   },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./theme.css": "./theme.css"
+  },
+  "files": [
+    "theme.css",
+    "dist"
+  ],
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run",
+    "test:browsers": "node browser-check.ts",
+    "verify": "npm run typecheck && npm run lint && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "tailwindcss": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@tailwindcss/node": "^4.3.3",
+    "@types/node": "^26.6.4",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "playwright": "^1.64.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "~6.0.3",
+    "vitest": "^5.0.3"
   }
 }

package/theme.css

@@ -0,0 +1,86 @@
+/* The design tokens and the Tailwind utilities that use them (ADRs 0002 and 0003). An app
+   imports this after Tailwind:
+
+     @import "tailwindcss";
+     @import "@kyzarky/ui/theme.css";
+
+   Each token holds a light and a dark value. light-dark() picks one from the color-scheme
+   of the element using it, so the page follows the system unless the app sets
+   color-scheme itself. Components use the utilities (bg-card, text-muted-foreground) and
+   never Tailwind's dark: variant. */
+
+/* The components are published as compiled files full of Tailwind class names. This has
+   the app's Tailwind scan them, so it generates those classes along with the app's own. */
+@source "./dist";
+
+/* In the base layer, so an app's own unlayered rules win wherever it puts them. That's
+   how an app themes the package: by redefining a token. */
+@layer base {
+  /* The light theme, for browsers without light-dark() (Safari before 17.5). Without
+     these, every token is invalid there and each fill it colors disappears (ADR 0003).
+     theme.test.ts checks that each value equals the light value in the block below. */
+  :root {
+    color-scheme: light;
+
+    --background: #f6f4ef;
+    --foreground: #1f2326;
+    --card: #ffffff;
+    --card-foreground: var(--foreground);
+    --muted: #efece4;
+    --muted-foreground: #5b6166;
+    --border: #dedad0;
+    --input: #858279;
+    --primary: #1d6b73;
+    --primary-foreground: #ffffff;
+    --ring: var(--primary);
+    --success: #2a7548;
+    --warning: #915d00;
+    --destructive: #b1352b;
+  }
+
+  @supports (color: light-dark(#000, #fff)) {
+    :root {
+      color-scheme: light dark;
+
+      --background: light-dark(#f6f4ef, #15181a);
+      --foreground: light-dark(#1f2326, #eceae4);
+      --card: light-dark(#ffffff, #1e2225);
+      /* Subtle fills: meter tracks, inset boxes, the unselected segment. */
+      --muted: light-dark(#efece4, #272c30);
+      --muted-foreground: light-dark(#5b6166, #a3a9ad);
+      /* Decorative edges: cards and dividers. Too faint for a control's edge. */
+      --border: light-dark(#dedad0, #353b40);
+      /* Edges of form controls: at least 3:1 on card and background (WCAG 1.4.11). */
+      --input: light-dark(#858279, #737779);
+      --primary: light-dark(#1d6b73, #5fb3ba);
+      --primary-foreground: light-dark(#ffffff, #0e1a1c);
+      --success: light-dark(#2a7548, #6cc38f);
+      --warning: light-dark(#915d00, #e0a846);
+      --destructive: light-dark(#b1352b, #ef8a7f);
+    }
+  }
+
+  body {
+    background-color: var(--background);
+    color: var(--foreground);
+  }
+}
+
+/* inline: each utility reads the token where it's used, not a copy resolved at :root, so
+   an element that redefines a token gets its own value. */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-ring: var(--ring);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-destructive: var(--destructive);
+}