@kyzarky/ui 0.0.0-stage → 0.1.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,3 +1,148 @@
-# Temporary Holding Version
+# @kyzarky/ui
 
-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.
+Design tokens for Ky Merritt's apps: a Tailwind CSS 4 theme with light and dark values.
+React components arrive in 0.2.0 ([ADR 0002](docs/decisions/0002-first-scope.md)). First
+consumer: Fluent Prior. Next: Merritt's Mini Mind.
+
+## 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. **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.
+
+## 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, and test |
+| `npm test` | The contrast and fallback 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/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@kyzarky/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Design tokens for Ky Merritt's apps, as a Tailwind CSS 4 theme with light and dark values",
+  "license": "MIT",
+  "author": "Ky Merritt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KyzarKy/design-system.git"
+  },
+  "type": "module",
+  "exports": {
+    "./theme.css": "./theme.css"
+  },
+  "files": [
+    "theme.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run",
+    "verify": "npm run typecheck && npm run lint && npm run test",
+    "test:browsers": "node browser-check.ts"
+  },
+  "peerDependencies": {
+    "tailwindcss": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@tailwindcss/node": "^4.3.3",
+    "@types/node": "^26.6.4",
+    "playwright": "^1.64.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "~6.0.3",
+    "vitest": "^5.0.3"
+  }
+}

package/theme.css

@@ -0,0 +1,82 @@
+/* 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. */
+
+/* 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);
+}