@atelic-action/ui 0.13.0 → 0.14.0

package/README.md

@@ -31,10 +31,12 @@ Import the stylesheets in this order, from the root route or the site's base she
 2. `@atelic-action/ui/styles/base.css`
 3. `@atelic-action/ui/styles/chrome.css`
 4. `@atelic-action/ui/styles/components.css`
-5. The site's own CSS
-6. The site's `theme.css`, last
+5. `@atelic-action/ui/styles/primitives.css`
+6. `@atelic-action/ui/styles/gate.css`, on a site that mounts the access gate
+7. The site's own CSS
+8. The site's `theme.css`, last
 
-The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outside a layer wins over them whatever its specificity. The package reads the theme tokens (`--ink`, `--surface`, `--primary`, `--nav-height`, and the rest) and defines none, so `theme.css` stays the one file a site edits to rebrand. The chrome's buttons wear the site's own `.btn` classes.
+The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outside a layer wins over them whatever its specificity. The package reads the theme tokens (`--ink`, `--surface`, `--primary`, `--nav-height`, and the rest) and defines none, so `theme.css` stays the one file a site edits to rebrand. The chrome's buttons wear the `.btn` classes, which `primitives.css` defines and a site may restyle.
 
 ## What Is Inside
 
@@ -42,10 +44,12 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 |---|---|
 | `@atelic-action/ui/chrome` | `SiteHeader`, `SiteMenu`, `Footer`, `CreditBar`, `StickyCTABar`, `BrandLockup`, `SkipLink`, and their prop types |
 | `@atelic-action/ui/components` | `NotFound`, the access gate's `GateLogin` and `Watermark` (with `readCookie`), and the page components (`Checklist`, `DataTable`, `StatRow`, `Callout`, `Collapsible`, `StackedBar`, `ColumnChart`, `ThresholdScale`, `StarRating`, `Disclosure`), with their prop types (see [The Not Found Page](#the-not-found-page) and [Page Components](#page-components)) |
+| `@atelic-action/ui/primitives` | `Button`, `Chip`, `Eyebrow`, `Lead`, `SectionHeading`, and their prop types (see [Primitives](#primitives)) |
 | `@atelic-action/ui/email` | The email components, the theme provider, the plain text helpers, and their prop types (see [Email](#email)) |
 | `@atelic-action/ui/email/render` | `renderEmail` and `renderFailureEmail`, the only entry that imports `react-dom/server` |
 | `@atelic-action/ui/tokens` | `Palette`, `atelicPalette`, `Fonts`, `atelicFonts`, `toThemeCSS`, `themeTokenMap` |
 | `@atelic-action/ui/hooks` | `useScrollSpy` and its `PageStop` type |
+| `@atelic-action/ui/styles/primitives.css` | Styles for everything under `primitives`, the `.btn` classes included |
 | `@atelic-action/ui/styles/gate.css` | Styles for `GateLogin` and `Watermark` |
 | `@atelic-action/ui/gate` | `signToken`, `verifyToken`, `safeNext`, `needsSession`, and the token types |
 | `@atelic-action/ui/gate/request-link` | `POST`, the handler that emails a sign in link, and `createRequestLink` |
@@ -121,6 +125,21 @@ export function NotFoundPage() {
 
 `staticNotFoundRouting` is for prerendered sites only. On a live app the pending state is a real loading moment and the page would flash through every slow load, so an app sets `defaultNotFoundComponent` alone. A browser test is the only proof any of this works; template-marketing's `e2e/not-found.spec.ts` is the one to copy.
 
+## Primitives
+
+`Button`, `Chip`, `Eyebrow`, `Lead`, and `SectionHeading` are the small pieces a page is set in, the same in every template. Each renders from props and wears a class of the same name (`.btn`, `.chip`, `.eyebrow`, `.lead`, `.section-head`), styled by `primitives.css` from the theme tokens.
+
+```tsx
+import { Button, SectionHeading } from "@atelic-action/ui/primitives";
+
+<SectionHeading eyebrow="Pricing" title="One number" lead="Flat and posted." />;
+<Button href="/contact" size="lg" arrow>
+	Book a visit
+</Button>;
+```
+
+`Button` is an anchor when it has an `href` and a real button otherwise. It renders the `href` as given: a site served under a base path wraps it once and applies its own prefix there. Its arrow is hidden from the name a screen reader hears.
+
 ## The Access Gate
 
 The gate puts a whole host behind an email sign in with no database: a reader on the allowlist asks for a link, the link starts a signed session cookie, and the middleware holds every page and file back from anyone without one. It is opt in and fails open, so a host with no `GATE_SESSION_SECRET` is fully public.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.13.0",
+	"version": "0.14.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, and the access gate they install",
 	"type": "module",
 	"license": "UNLICENSED",
@@ -24,12 +24,14 @@
 		"./email": "./src/email/index.ts",
 		"./email/render": "./src/email/render.tsx",
 		"./hooks": "./src/hooks/index.ts",
+		"./primitives": "./src/primitives/index.ts",
 		"./routing": "./src/routing/index.ts",
 		"./tokens": "./src/tokens/index.ts",
 		"./styles/base.css": "./src/styles/base.css",
 		"./styles/chrome.css": "./src/styles/chrome.css",
 		"./styles/components.css": "./src/styles/components.css",
 		"./styles/gate.css": "./src/styles/gate.css",
+		"./styles/primitives.css": "./src/styles/primitives.css",
 		"./styles/star-rating.css": "./src/styles/star-rating.css",
 		"./gate": {
 			"types": "./dist/gate/index.d.ts",

package/src/primitives/Button.tsx

@@ -0,0 +1,87 @@
+import type { CSSProperties, ReactNode } from "react";
+import { newTabProps } from "../lib/newTabProps";
+
+export interface ButtonProps {
+	variant?: "primary" | "dark" | "ghost";
+	size?: "md" | "lg";
+	/** Inverts ghost styling for use on dark surfaces. */
+	onDark?: boolean;
+	/** Appends the animated arrow glyph. */
+	arrow?: boolean;
+	/**
+	 * Link target: an internal path ("/services") or protocol link
+	 * (https, tel, mailto). Marketing pages navigate as an MPA, so plain
+	 * anchors are intentional here.
+	 */
+	href?: string;
+	/** Open href in a new tab with rel="noopener". */
+	newTab?: boolean;
+	/** Renders a real button element (e.g. form submit) when set. */
+	type?: "submit" | "button";
+	onClick?: () => void;
+	ariaLabel?: string;
+	className?: string;
+	style?: CSSProperties;
+	children: ReactNode;
+}
+
+export function Button({
+	variant = "primary",
+	size = "md",
+	onDark = false,
+	arrow = false,
+	href,
+	newTab = false,
+	type,
+	onClick,
+	ariaLabel,
+	className,
+	style,
+	children,
+}: ButtonProps) {
+	const classes = [
+		"btn",
+		`btn-${variant}`,
+		size === "lg" && "btn-lg",
+		onDark && "on-dark",
+		className,
+	]
+		.filter(Boolean)
+		.join(" ");
+
+	const content = (
+		<>
+			{children}
+			{arrow && (
+				<span className="arrow" aria-hidden="true">
+					→
+				</span>
+			)}
+		</>
+	);
+
+	if (href) {
+		return (
+			<a
+				href={href}
+				className={classes}
+				style={style}
+				aria-label={ariaLabel}
+				{...newTabProps(href, newTab)}
+			>
+				{content}
+			</a>
+		);
+	}
+	return (
+		<button
+			type={type ?? "button"}
+			className={classes}
+			style={style}
+			aria-label={ariaLabel}
+			onClick={onClick}
+		>
+			{content}
+		</button>
+	);
+}

package/src/primitives/Chip.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+
+export interface ChipProps {
+	/** Shows the small brand-colored dot before the label. */
+	dot?: boolean;
+	/** Inverts styling for dark surfaces. */
+	onDark?: boolean;
+	/** Renders the chip as an anchor (e.g. jump links on a page hero). */
+	href?: string;
+	children: ReactNode;
+}
+
+/** Small mono tag/badge, used for credentials, tags, and service areas. */
+export function Chip({ dot = false, onDark = false, href, children }: ChipProps) {
+	const classes = ["chip", onDark && "on-dark"].filter(Boolean).join(" ");
+	const content = (
+		<>
+			{dot && <span className="dot" />}
+			{children}
+		</>
+	);
+	if (href) {
+		return (
+			<a className={classes} href={href}>
+				{content}
+			</a>
+		);
+	}
+	return <span className={classes}>{content}</span>;
+}

package/src/primitives/Eyebrow.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+
+export interface EyebrowProps {
+	/** Lifts the color for dark surfaces. */
+	onDark?: boolean;
+	/** Centers the eyebrow (its trailing fade included). */
+	center?: boolean;
+	/**
+	 * Deprecated no-op. The trailing fade (the wordmark's signature) is now
+	 * the default and only rendering; the old leading-dash mode is retired.
+	 * Accepted so existing call sites keep compiling.
+	 */
+	run?: boolean;
+	children: ReactNode;
+}
+
+/**
+ * The small mono, uppercase kicker line above a heading, trailed by a bar
+ * that fades out to the right (the practice wordmark's signature), rendered
+ * from the primary token so it carries each site's brand color.
+ */
+export function Eyebrow({ onDark = false, center = false, children }: EyebrowProps) {
+	const classes = ["eyebrow", onDark && "on-dark", center && "center"].filter(Boolean).join(" ");
+	return <p className={classes}>{children}</p>;
+}

package/src/primitives/Lead.tsx

@@ -0,0 +1,17 @@
+import type { CSSProperties, ReactNode } from "react";
+
+export interface LeadProps {
+	className?: string;
+	style?: CSSProperties;
+	children: ReactNode;
+}
+
+/** Lead paragraph: the larger intro copy under a heading. */
+export function Lead({ className, style, children }: LeadProps) {
+	const classes = ["lead", className].filter(Boolean).join(" ");
+	return (
+		<p className={classes} style={style}>
+			{children}
+		</p>
+	);
+}

package/src/primitives/SectionHeading.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+import { Eyebrow } from "./Eyebrow";
+import { Lead } from "./Lead";
+
+export interface SectionHeadingProps {
+	eyebrow?: string;
+	/** Heading content; may include serif emphasis spans. */
+	title: ReactNode;
+	lead?: ReactNode;
+	center?: boolean;
+	/** Lifts colors for dark surfaces. */
+	onDark?: boolean;
+	/** Deprecated no-op: the eyebrow's trailing fade is now its only rendering. */
+	eyebrowRun?: boolean;
+	/** Heading level; sections default to h2. */
+	as?: "h1" | "h2" | "h3";
+	className?: string;
+}
+
+/** Standard section opener: eyebrow, title, optional lead. */
+export function SectionHeading({
+	eyebrow,
+	title,
+	lead,
+	center = false,
+	onDark = false,
+	as: Heading = "h2",
+	className,
+}: SectionHeadingProps) {
+	const classes = ["section-head", center && "center", className].filter(Boolean).join(" ");
+	return (
+		<div className={classes}>
+			{eyebrow && (
+				<Eyebrow onDark={onDark} center={center}>
+					{eyebrow}
+				</Eyebrow>
+			)}
+			<Heading>{title}</Heading>
+			{lead && <Lead className="section-head-lead">{lead}</Lead>}
+		</div>
+	);
+}

package/src/primitives/index.ts

@@ -0,0 +1,5 @@
+export { Button, type ButtonProps } from "./Button";
+export { Chip, type ChipProps } from "./Chip";
+export { Eyebrow, type EyebrowProps } from "./Eyebrow";
+export { Lead, type LeadProps } from "./Lead";
+export { SectionHeading, type SectionHeadingProps } from "./SectionHeading";

package/src/styles/primitives.css

@@ -0,0 +1,153 @@
+/* The primitives under src/primitives: the button, the chip, the eyebrow,
+   the lead paragraph, and the section heading. Every value is a theme token.
+   They sit in the package's layer like every sheet here, so any rule a site
+   writes outside a layer still wins over them whatever its specificity. */
+@layer atelic-ui {
+	/* CTA buttons: primary (brand), dark (ink), ghost (outline). */
+	:is(.mkt, .atelic-ui) .btn {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		gap: 0.6em;
+		padding: 0.95em 1.6em;
+		font-weight: 700;
+		font-size: 1rem;
+		letter-spacing: -0.01em;
+		border-radius: var(--radius-pill);
+		transition:
+			transform 0.18s ease,
+			background 0.2s ease,
+			box-shadow 0.2s ease,
+			color 0.2s ease;
+		text-align: center;
+		line-height: 1;
+	}
+	:is(.mkt, .atelic-ui) .btn:active {
+		transform: translateY(1px) scale(0.99);
+	}
+	:is(.mkt, .atelic-ui) .btn-primary {
+		background: var(--primary);
+		color: #fff;
+		box-shadow: var(--primary-shadow);
+	}
+	:is(.mkt, .atelic-ui) .btn-primary:hover {
+		background: var(--primary-deep);
+		box-shadow: var(--primary-shadow-hover);
+		transform: translateY(-1px);
+	}
+	:is(.mkt, .atelic-ui) .btn-dark {
+		background: var(--ink);
+		color: var(--surface);
+	}
+	:is(.mkt, .atelic-ui) .btn-dark:hover {
+		background: #000;
+		transform: translateY(-1px);
+	}
+	:is(.mkt, .atelic-ui) .btn-ghost {
+		background: transparent;
+		color: var(--ink);
+		box-shadow: inset 0 0 0 1.5px var(--neutral-300);
+	}
+	:is(.mkt, .atelic-ui) .btn-ghost:hover {
+		box-shadow: inset 0 0 0 1.5px var(--ink);
+	}
+	:is(.mkt, .atelic-ui) .btn-ghost.on-dark {
+		color: #fff;
+		box-shadow: inset 0 0 0 1.5px rgba(255, 255, 255, 0.45);
+	}
+	:is(.mkt, .atelic-ui) .btn-ghost.on-dark:hover {
+		box-shadow: inset 0 0 0 1.5px #fff;
+		background: rgba(255, 255, 255, 0.08);
+	}
+	:is(.mkt, .atelic-ui) .btn-lg {
+		padding: 1.1em 2em;
+		font-size: 1.08rem;
+	}
+	:is(.mkt, .atelic-ui) .btn .arrow {
+		transition: transform 0.2s ease;
+	}
+	:is(.mkt, .atelic-ui) .btn:hover .arrow {
+		transform: translateX(3px);
+	}
+
+	/* Chip: small mono tag for credentials, feature tags, service areas. */
+	:is(.mkt, .atelic-ui) .chip {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.5em;
+		font-family: var(--font-mono);
+		font-size: 0.72rem;
+		letter-spacing: 0.06em;
+		text-transform: uppercase;
+		padding: 0.5em 0.85em;
+		border-radius: var(--radius-pill);
+		background: var(--card);
+		color: var(--ink-soft);
+		box-shadow: inset 0 0 0 1px var(--neutral-200);
+		white-space: nowrap;
+	}
+	:is(.mkt, .atelic-ui) .chip .dot {
+		width: 6px;
+		height: 6px;
+		border-radius: 50%;
+		background: var(--primary);
+	}
+	:is(.mkt, .atelic-ui) .chip svg {
+		flex: none;
+	}
+	:is(.mkt, .atelic-ui) .chip.on-dark {
+		background: rgba(255, 255, 255, 0.08);
+		color: #efe7da;
+		box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.18);
+	}
+
+	/* Eyebrow: mono uppercase kicker trailed by a bar that fades off to the
+	   right — the wordmark's signature, in the brand's primary. This fade is
+	   the only rendering; the old leading-dash mode is retired. */
+	:is(.mkt, .atelic-ui) .eyebrow {
+		font-family: var(--font-mono);
+		font-size: 0.74rem;
+		font-weight: 500;
+		letter-spacing: 0.18em;
+		text-transform: uppercase;
+		color: var(--primary);
+		display: inline-flex;
+		align-items: center;
+		gap: 0.6em;
+	}
+	:is(.mkt, .atelic-ui) .eyebrow.on-dark {
+		color: var(--primary-bright);
+	}
+	:is(.mkt, .atelic-ui) .eyebrow.center {
+		justify-content: center;
+	}
+	:is(.mkt, .atelic-ui) .eyebrow::after {
+		content: "";
+		width: 40px;
+		height: 2px;
+		display: inline-block;
+		/* Themes with a dedicated ruling accent (a brand color reserved for
+		   rules, never text) set --rule-accent; default stays the text color. */
+		background: linear-gradient(90deg, var(--rule-accent, currentColor), transparent);
+	}
+
+	:is(.mkt, .atelic-ui) .lead {
+		font-size: clamp(1.05rem, 2vw, 1.3rem);
+		color: var(--ink-soft);
+		line-height: 1.55;
+	}
+
+	:is(.mkt, .atelic-ui) .section-head {
+		/* Width is constrained on the lead only: titles size to their section so
+		   they never wrap early into dead space (the 60ch cap here was measured
+		   at the body font size, boxing every title into ~510px). */
+		max-width: none;
+	}
+	:is(.mkt, .atelic-ui) .section-head.center {
+		margin-inline: auto;
+	}
+	:is(.mkt, .atelic-ui) .section-head .section-head-lead {
+		margin-top: 16px;
+		max-width: 60ch;
+	}
+}