@judarn/ui 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruben Luthman
+
+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,48 @@
-# Temporary Holding Version
+# @judarn/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.
+React components and CSS tokens for the Judarn design system, with colors in OKLCh and a fixed 8 px spacing grid.
+
+```bash
+npm install --save-exact @judarn/ui
+```
+
+```jsx
+import "@judarn/ui/styles";
+import { Button, Card } from "@judarn/ui";
+
+export function Status() {
+  return (
+    <Card eyebrow="System status" title="Operational">
+      <Button variant="primary">View metrics</Button>
+    </Card>
+  );
+}
+```
+
+`react` 18 or later is the only peer dependency. The package ships compiled ESM and CommonJS. Other entry points: `@judarn/ui/colors` (CSS custom properties only), `@judarn/ui/theme` and `@judarn/ui/tailwind` (Tailwind v4), and `@judarn/ui/sdui` (server-driven UI).
+
+## Accent colors
+
+A project that sets its own `--jd-accent` also sets `--jd-accent-ink` to `#000000` or `#ffffff`, whichever stays readable on that fill. Accent buttons and badges read the resolved `--accent-ink`. The `--jd-accent*` hooks have no default, so a value set on `:root` carries into nested scopes.
+
+## Guarantees and the checks behind them
+
+| Guarantee | Check |
+| :--- | :--- |
+| `ink100` meets 7:1 on every surface and appearance; `ink60` and `signalError` meet 4.5:1, and 7:1 in high-contrast appearances | `scripts/verify-contrast.js` (run by `npm test`) |
+| Components render the markup their contracts describe | `scripts/verify-unit.js` |
+| A page with `data-theme="dark"` gets the dark accent ink | `scripts/verify-visual.js` |
+| Server-driven payloads accept only allowlisted props and reject `style`, `className`, and `dangerouslySetInnerHTML` | `scripts/verify-sdui.js` |
+
+White ink on mid-tone fills can fall below 4.5:1 by design, and paragraph line spacing does not meet WCAG SC 1.4.8. The repository README explains both.
+
+## Development
+
+```bash
+npm ci
+npm test
+```
+
+## License
+
+MIT © 2026 Ruben Luthman. The package includes the LICENSE file.

package/dist/Badge/Badge.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+
+export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+  children?: React.ReactNode;
+  /** @default "outline" */
+  variant?: "outline" | "solid" | "accent" | "accent-outline";
+  /** Optional custom accent color hex or rgb string. Automatically resolves accessible contrasting text ink. */
+  accentColor?: string;
+}
+
+export interface TagProps extends React.HTMLAttributes<HTMLSpanElement> {
+  children?: React.ReactNode;
+}
+
+/**
+ * Resolves the foreground ink ("#000000" or "#ffffff") for a fill from its relative luminance and the 0.50 perceptual crossover (ADR-0006).
+ * Accepts #hex, rgb() and oklch(); throws a TypeError for any other format.
+ */
+export function getContrastingInk(hexOrRgb: string): string;
+
+/** Status chip set as written, with optional luminance-aware contrasting ink. */
+export function Badge(props: BadgeProps): React.JSX.Element;
+/** Sentence-case keyword chip. */
+export function Tag(props: TagProps): React.JSX.Element;
+export default Badge;
+

package/dist/Button/Button.d.ts

@@ -0,0 +1,19 @@
+import * as React from "react";
+
+export interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type"> {
+  children?: React.ReactNode;
+  /** Visual style. @default "primary" */
+  variant?: "primary" | "outline" | "secondary" | "ghost" | "accent";
+  /** @default "md" */
+  size?: "sm" | "md" | "lg";
+  /** Stretch to full container width. @default false */
+  block?: boolean;
+  /** @default false */
+  disabled?: boolean;
+  type?: "button" | "submit" | "reset";
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
+}
+
+/** Judarn button – flat fill, border, and hover inversion. A consumer `className` extends the base classes. */
+export function Button(props: ButtonProps): React.JSX.Element;
+export default Button;

package/dist/Card/Card.d.ts

@@ -0,0 +1,22 @@
+import * as React from "react";
+
+export interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Small accent label, set as a `t-label` (uppercase unless `eyebrowCasing` is "asWritten"). */
+  eyebrow?: string;
+  /** "asWritten" for an eyebrow holding a unit, a digit, or a mixed-case term (ADR-0009). @default "uppercase" */
+  eyebrowCasing?: "uppercase" | "asWritten";
+  title?: React.ReactNode;
+  children?: React.ReactNode;
+  /** Media block (image/figure) rendered at top. */
+  media?: React.ReactNode;
+  /** Action row (buttons) rendered at bottom. */
+  actions?: React.ReactNode;
+  /** Remove elevation + padding. @default false */
+  flat?: boolean;
+  /** Apply compact padding (space2 / 16px) for sidebars and dense panes. @default false */
+  compact?: boolean;
+}
+
+/** Content card block with substrate background contrast (surfaceElevated) and the host card radius. */
+export function Card(props: CardProps): React.JSX.Element;
+export default Card;

package/dist/DataMatrix/DataMatrix.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+
+export interface MatrixColumn {
+  key: string;
+  label: string;
+  /** Right-align with tabular figures. @default false */
+  numeric?: boolean;
+  /** Fixed width in pixels (number) or CSS length (string). */
+  width?: number | string;
+  /** "asWritten" for a header holding a unit symbol or mixed-case term, such as kg or e1RM (ADR-0009). @default "uppercase" */
+  casing?: "uppercase" | "asWritten";
+}
+
+export interface DataMatrixProps extends React.TableHTMLAttributes<HTMLTableElement> {
+  /** Column keys (strings) or {key,label,numeric,width} objects. */
+  columns?: Array<string | MatrixColumn>;
+  /** Row objects keyed by column key. */
+  rows?: Array<Record<string, React.ReactNode>>;
+  /** Spoken table label for assistive tech. @default "Data Matrix" */
+  label?: string;
+}
+
+/** Data Matrix with 1px hairline rules between cells and no perimeter border, tabular figures, and accessible landmarks. */
+export function DataMatrix(props: DataMatrixProps): React.JSX.Element;
+export default DataMatrix;
+

package/dist/DataTable/DataTable.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+export interface DataColumn {
+  key: string;
+  label: string;
+  /** Right-align with tabular figures. @default false */
+  numeric?: boolean;
+  /** "asWritten" for a header holding a unit symbol or mixed-case term, such as kg or e1RM (ADR-0009). @default "uppercase" */
+  casing?: "uppercase" | "asWritten";
+}
+
+export interface DataTableProps extends React.TableHTMLAttributes<HTMLTableElement> {
+  /** Column keys (strings) or {key,label,numeric} objects. */
+  columns?: Array<string | DataColumn>;
+  /** Row objects keyed by column key. */
+  rows?: Array<Record<string, React.ReactNode>>;
+}
+
+/** Bordered data table – uppercase headers unless a column sets casing "asWritten", hairline row rules. */
+export function DataTable(props: DataTableProps): React.JSX.Element;
+export default DataTable;

package/dist/Footer/Footer.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+export interface FooterColumn {
+  head: string;
+  links?: Array<string | { label: string; href?: string }>;
+}
+
+export interface FooterProps extends React.HTMLAttributes<HTMLElement> {
+  /** Brand wordmark. @default "JUDARN" */
+  brand?: string;
+  /** Short line under the brand. */
+  tagline?: string;
+  /** Link columns. */
+  columns?: FooterColumn[];
+  /** "asWritten" for column heads holding mixed-case terms (ADR-0009). Heads render as `h2`. @default "uppercase" */
+  headCasing?: "uppercase" | "asWritten";
+}
+
+/** Three-column footer with 2px top rule. */
+export function Footer(props: FooterProps): React.JSX.Element;
+export default Footer;

package/dist/LogoLockup/LogoLockup.d.ts

@@ -0,0 +1,20 @@
+import * as React from "react";
+
+export interface LogoLockupProps {
+  /** Wordmark text (heavy sans). @default "JUDARN" */
+  name?: string;
+  /** Optional descriptor under/after the name. */
+  tagline?: string;
+  /** Your geometric mark (SVG element). Omit for a construction placeholder. */
+  mark?: React.ReactNode;
+  /** Lockup arrangement. @default "horizontal" */
+  variant?: "horizontal" | "vertical" | "icon" | "reversed";
+  /** Pixel size of the placeholder mark. */
+  markSize?: number;
+  /** "asWritten" keeps the tagline as written (ADR-0009). @default "uppercase" */
+  taglineCasing?: "uppercase" | "asWritten";
+}
+
+/** Logo frame – geometric mark + wordmark, four variants. */
+export function LogoLockup(props: LogoLockupProps): React.JSX.Element;
+export default LogoLockup;

package/dist/Navbar/Navbar.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+export interface NavLink {
+  label: string;
+  href?: string;
+}
+
+export interface NavbarProps extends React.HTMLAttributes<HTMLElement> {
+  /** Brand wordmark text. @default "JUDARN" */
+  brand?: string;
+  /** Link labels or {label, href} objects. */
+  links?: Array<string | NavLink>;
+  /** Label of the active link (gets accent underline). */
+  current?: string;
+  /** Right-aligned actions (e.g. a Button). */
+  actions?: React.ReactNode;
+}
+
+/** Top navigation bar – 2px baseline rule, links set as written. */
+export function Navbar(props: NavbarProps): React.JSX.Element;
+export default Navbar;

package/dist/TextField/TextField.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+
+type FieldControlProps = Omit<
+  React.InputHTMLAttributes<HTMLInputElement> &
+    React.TextareaHTMLAttributes<HTMLTextAreaElement> &
+    React.SelectHTMLAttributes<HTMLSelectElement>,
+  "id"
+>;
+
+export interface TextFieldProps extends FieldControlProps {
+  /** Label above the control, uppercase unless labelCasing is "asWritten". */
+  label?: string;
+  /** "asWritten" for a label longer than two words or holding a digit, unit, or mixed-case term (ADR-0009). @default "uppercase" */
+  labelCasing?: "uppercase" | "asWritten";
+  /** Helper text below the control, linked with `aria-describedby`. */
+  hint?: string;
+  /** Error message below the control, linked with `aria-describedby`. Also marks the control invalid. */
+  error?: string;
+  /** Render an input, textarea, or select. @default "input" */
+  as?: "input" | "textarea" | "select";
+  /** Overrides the generated `React.useId()` id. */
+  id?: string;
+  /** Marks the control invalid (`aria-invalid`, signal-error border). @default false */
+  invalid?: boolean;
+  /** @default false */
+  disabled?: boolean;
+}
+
+/** Labelled field – input / textarea / select with Judarn styling. */
+export function TextField(props: TextFieldProps): React.JSX.Element;
+export default TextField;