@talelk/newui-tailwind 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @talelk/newui-tailwind
 
-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.
+Import `@talelk/newui-tailwind/style.css` once in your application stylesheet. This
+Tailwind v4 layer emits semantic @theme utilities and token variables. The
+`@talelk/newui-tailwind/source` export exposes source paths for build integration.
+There is no root JavaScript component export.
+
+Keep package source visible to Tailwind scanning, use semantic colour utilities,
+and run `pnpm css:check` against a fresh production build after recipe changes.
+Reduced-motion styles and focus rings are part of the emitted contract.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@talelk/newui-tailwind",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Tailwind CSS v4 layer: the newui design tokens as @theme, @utility and plugins.",
+  "exports": {
+    "./style.css": {
+      "style": "./src/style.css",
+      "import": "./src/style.css"
+    },
+    "./source": {
+      "types": "./src/source.d.ts",
+      "default": "./src/source.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@talelk/newui-tokens": "0.1.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/forms": "^0.5.11",
+    "@tailwindcss/typography": "^0.5.20",
+    "lucide-static": "^1.57.0",
+    "tailwindcss": "^4.3.3"
+  },
+  "peerDependencies": {
+    "tailwindcss": "^4.0.0"
+  },
+  "sideEffects": false,
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/talelk/newui.git",
+    "directory": "packages/tailwind"
+  },
+  "scripts": {
+    "build": "tsx scripts/build-css.ts",
+    "build:css": "tsx scripts/build-css.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
 }

package/src/contrast.test.ts

@@ -0,0 +1,160 @@
+import { semanticColors } from '@talelk/newui-tokens'
+import { wcagLuminance } from 'culori'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * The contrast contract.
+ *
+ * Every foreground/background pairing the components ship is asserted against
+ * WCAG AA in both themes. This is objective UX: a pairing that fails is a
+ * legibility bug, not a taste question.
+ *
+ * The pairs mirror the recipes (Button, Badge, Alert, labels, links). Disabled
+ * text is deliberately absent — WCAG exempts inactive controls from contrast.
+ */
+type Mode = 'light' | 'dark'
+
+const AA = 4.5
+
+function resolve(mode: Mode, token: string): string {
+  const [category = '', ...rest] = token.split('-')
+  const layer = semanticColors[mode] as unknown as Record<
+    string,
+    Record<string, string>
+  >
+  const value = layer[category]?.[rest.join('-')]
+  if (!value) throw new Error(`unknown token: ${token}`)
+  return value
+}
+
+function contrast(fg: string, bg: string): number {
+  const a = wcagLuminance(fg)
+  const b = wcagLuminance(bg)
+  const [hi, lo] = a > b ? [a, b] : [b, a]
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+const THEMES = ['gray', 'blue', 'green', 'amber', 'red', 'violet'] as const
+
+interface Pair {
+  fg: string
+  bg: string
+  what: string
+}
+
+const PAIRS: Pair[] = [
+  // body copy and labels
+  { fg: 'ink-gray-8', bg: 'surface-base', what: 'body text' },
+  { fg: 'ink-gray-6', bg: 'surface-base', what: 'label on base' },
+  { fg: 'ink-gray-6', bg: 'surface-gray-2', what: 'muted on gray-2' },
+  {
+    fg: 'ink-gray-6',
+    bg: 'surface-elevation-2',
+    what: 'muted on a popover/menu surface',
+  },
+
+  {
+    fg: 'ink-gray-6',
+    bg: 'surface-elevation-1',
+    what: 'chart subtitle and card caption',
+  },
+
+  // a board column is the one tinted region muted text lands on
+  { fg: 'ink-gray-8', bg: 'surface-gray-1', what: 'column heading' },
+  { fg: 'ink-gray-6', bg: 'surface-gray-1', what: 'muted on a board column' },
+
+  { fg: 'ink-blue-link', bg: 'surface-base', what: 'blue link on base' },
+  { fg: 'ink-blue-link', bg: 'surface-elevation-1', what: 'blue link on card' },
+  { fg: 'ink-blue-link', bg: 'surface-gray-1', what: 'blue link on canvas' },
+
+  {
+    fg: 'ink-blue-8',
+    bg: 'surface-blue-1',
+    what: 'selected navigation and its count',
+  },
+
+  // subtle / outline / ghost text — ink-{theme}-8 on the pale surface
+  ...THEMES.map((theme) => ({
+    fg: `ink-${theme}-8`,
+    bg: `surface-${theme}-2`,
+    what: `${theme} subtle`,
+  })),
+  ...THEMES.map((theme) => ({
+    fg: `ink-${theme}-8`,
+    bg: 'surface-base',
+    what: `${theme} outline/ghost`,
+  })),
+
+  // solid fills — ink-base on the saturated surface (amber needs the deepest)
+  ...THEMES.map((theme) => ({
+    fg: 'ink-base',
+    bg:
+      theme === 'gray'
+        ? 'surface-gray-10'
+        : theme === 'amber'
+          ? 'surface-amber-9'
+          : `surface-${theme}-8`,
+    what: `${theme} solid`,
+  })),
+]
+
+describe('contrast contract (WCAG AA)', () => {
+  for (const mode of ['light', 'dark'] as Mode[]) {
+    for (const pair of PAIRS) {
+      it(`${mode}: ${pair.what} ≥ ${AA}`, () => {
+        const ratio = contrast(resolve(mode, pair.fg), resolve(mode, pair.bg))
+        expect(
+          Number(ratio.toFixed(2)),
+          `${pair.fg} on ${pair.bg} = ${ratio.toFixed(2)}:1`,
+        ).toBeGreaterThanOrEqual(AA)
+      })
+    }
+  }
+
+  /**
+   * Why the muted step is `ink-gray-6` and not `ink-gray-5`.
+   *
+   * The contract above only covers the pairings the recipes ship, so a *new*
+   * recipe can introduce a pairing nobody listed — which is exactly how
+   * `text-ink-gray-5` reached the pagination range, the empty-state description
+   * and the timeline in one pass, caught by Lighthouse rather than here.
+   *
+   * So the boundary is pinned instead: the step above the muted one fails AA on
+   * the base surface, and the muted one passes. Change a token and this tells
+   * you which side of the line it moved to.
+   */
+  for (const mode of ['light', 'dark'] as Mode[]) {
+    it(`${mode}: ink-gray-5 on base is below AA — that is why muted text is ink-gray-6`, () => {
+      const failing = contrast(
+        resolve(mode, 'ink-gray-5'),
+        resolve(mode, 'surface-base'),
+      )
+      const passing = contrast(
+        resolve(mode, 'ink-gray-6'),
+        resolve(mode, 'surface-base'),
+      )
+      expect(failing).toBeLessThan(AA)
+      expect(passing).toBeGreaterThanOrEqual(AA)
+    })
+  }
+
+  for (const mode of ['light', 'dark'] as Mode[]) {
+    it(`${mode}: a decorative glyph may use ink-gray-5 (3:1 non-text)`, () => {
+      // Chevrons and leading icons are non-text: WCAG 1.4.11 asks for 3:1, not
+      // 4.5:1. That is the one place the step is allowed.
+      const ratio = contrast(
+        resolve(mode, 'ink-gray-5'),
+        resolve(mode, 'surface-base'),
+      )
+      expect(ratio).toBeGreaterThanOrEqual(3)
+    })
+  }
+})
+
+for (const mode of ['light', 'dark'] as Mode[]) {
+  it(`${mode}: invalid field boundary meets non-text contrast`, () => {
+    expect(
+      contrast(resolve(mode, 'outline-red-6'), resolve(mode, 'surface-base')),
+    ).toBeGreaterThanOrEqual(3)
+  })
+}

package/src/fonts/Inter/LICENSE.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/fonts/Inter/inter.css

@@ -0,0 +1,61 @@
+/* Variable fonts usage:
+:root { font-family: "Inter", sans-serif; }
+@supports (font-variation-settings: normal) {
+  :root { font-family: "InterVar", sans-serif; font-optical-sizing: auto; }
+} */
+@font-face {
+  font-family: "InterVar";
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: normal;
+  src:
+    url("Inter.var.woff2?v=3.19") format("woff2-variations"),
+    url("Inter.var.woff2?v=3.19") format("woff2");
+  src: url("Inter.var.woff2?v=3.19") format("woff2") tech("variations");
+  unicode-range:
+    U+0000-05FF, /* Latin, Greek, Cyrillic, Hebrew */ U+0700-1FFF,
+    /* Extended Latin, Greek, Cyrillic, Armenian, Georgian */ U+2C00-2FFF,
+    /* Additional scripts */ U+4E00-9FFF,
+    /* CJK (Chinese, Japanese, Korean) */ U+AC00-D7AF; /* Hangul (Korean) */
+}
+@font-face {
+  font-family: "InterVar";
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: italic;
+  src:
+    url("Inter-Italic.var.woff2?v=3.19") format("woff2-variations"),
+    url("Inter-Italic.var.woff2?v=3.19") format("woff2");
+  src: url("Inter-Italic.var.woff2?v=3.19") format("woff2") tech("variations");
+  unicode-range:
+    U+0000-05FF, U+0700-1FFF, U+2C00-2FFF, U+4E00-9FFF, U+AC00-D7AF;
+}
+/* Aliased 'InterVar' font as 'Inter' */
+/* To prevent breaking usage of `font-family: 'Inter'` */
+@font-face {
+  font-family: "Inter";
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: normal;
+  src:
+    url("Inter.var.woff2?v=3.19") format("woff2-variations"),
+    url("Inter.var.woff2?v=3.19") format("woff2");
+  src: url("Inter.var.woff2?v=3.19") format("woff2") tech("variations");
+  unicode-range:
+    U+0000-05FF, /* Latin, Greek, Cyrillic, Hebrew */ U+0700-1FFF,
+    /* Extended Latin, Greek, Cyrillic, Armenian, Georgian */ U+2C00-2FFF,
+    /* Additional scripts */ U+4E00-9FFF,
+    /* CJK (Chinese, Japanese, Korean) */ U+AC00-D7AF; /* Hangul (Korean) */
+}
+@font-face {
+  font-family: "Inter";
+  font-weight: 100 900;
+  font-display: swap;
+  font-style: italic;
+  src:
+    url("Inter-Italic.var.woff2?v=3.19") format("woff2-variations"),
+    url("Inter-Italic.var.woff2?v=3.19") format("woff2");
+  src: url("Inter-Italic.var.woff2?v=3.19") format("woff2") tech("variations");
+  unicode-range:
+    U+0000-05FF, U+0700-1FFF, U+2C00-2FFF, U+4E00-9FFF, U+AC00-D7AF;
+}