@axle-lang/ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axle Language
+
+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

@@ -0,0 +1,70 @@
+# @axle-lang/ui
+
+The Axle **design system** — a content-agnostic Svelte 5 + Tailwind v4
+component library, shared by the Axle landing and docs sites.
+
+It holds presentation only: components, the design tokens
+(`src/lib/app.css`), the syntax tokenizer, the small utils
+(`cn` / `cva` variants / icons), the cross-domain routing helpers, and
+the i18n **chrome** catalog (UI labels). It contains **no page content** —
+prose, the stdlib reference and benchmarks are generated in the
+[`axle`](https://github.com/axle-lang/axle) repo and injected by the apps
+at build time.
+
+```
+src/lib/
+├── index.ts      public barrel
+├── app.css       Tailwind v4 tokens (the single source of truth)
+├── components/   atoms · molecules · code · nav · landing · layout · reference
+├── i18n/         synchronous svelte-i18n setup + chrome catalog + K keys
+├── site/         site.ts (buildSite / route / setSite / getSite) · version.ts
+└── utils/        cn · variants (cva) · tokenizer · icons · types
+```
+
+## Consuming it
+
+The package is **source-typed** and built with `@sveltejs/package` to
+`dist/` (with `.d.ts`). Peer dependencies — `svelte`, `@sveltejs/kit`
+(for the route-aware `Seo` / `Sidebar`), and `svelte-i18n` (one shared
+locale store) — are provided by the consuming app.
+
+Published to npm as a public package:
+
+```jsonc
+// in each app's package.json
+"dependencies": {
+  "@axle-lang/ui": "^0.1.0"
+}
+```
+
+```js
+import { Header, Footer, Seo, initI18n, setSite, buildSite, K } from '@axle-lang/ui';
+import '@axle-lang/ui/app.css';
+```
+
+i18n labels are referenced through the `K` keys object (never raw string
+literals): `$t(K.nav.guide)`.
+
+## Develop
+
+```bash
+pnpm install
+pnpm dev        # the in-repo gallery (src/routes) — visual smoke test
+pnpm check      # svelte-check (TypeScript)
+pnpm lint       # prettier --check + eslint
+pnpm package    # build dist/ + publint
+pnpm format
+```
+
+## Publishing
+
+Published to **npmjs** under the `@axle-lang` scope (public).
+
+- **Automated** (preferred): publishing a GitHub Release triggers
+  `.github/workflows/publish.yml`, which runs `pnpm publish` with the
+  `NPM_TOKEN` repo secret. `prepare` builds `dist/` before packing and
+  `publishConfig.access` makes the scoped package public.
+- **Manual**: `npm login` then `pnpm publish`.
+
+Bump the version first with `npm version patch|minor|major`, then push
+`--follow-tags` and cut the Release. Requires the `@axle-lang` npm org.

package/dist/app.css

@@ -0,0 +1,337 @@
+/* =============================================================
+   Axle — Design System (Tailwind v4)
+   Single source of truth for tokens, fonts and primitives.
+   Import once in your app entry:  @import "./app.css";
+   Works in mdbook (drop into theme/) and SvelteKit (src/app.css).
+   ============================================================= */
+
+@import 'tailwindcss';
+
+/* Dark mode is class-based: add `dark` on <html> (or any ancestor). */
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* -------------------------------------------------------------
+   1. Fonts
+   Self-host for production; the CDN links below are a quick start.
+   ------------------------------------------------------------- */
+
+/* -------------------------------------------------------------
+   2. Raw token values (light is the default theme)
+   Edit these to retheme the whole system.
+   ------------------------------------------------------------- */
+:root {
+  /* Surfaces */
+  --canvas: #ffffff;
+  --surface: #faf9f7;
+  --surface2: #f1efea;
+  /* Text */
+  --fg: #15171c;
+  --muted: #5b626d;
+  --faint: #8b919c;
+  /* Lines & accent */
+  --line: #e9e6e0;
+  --accent: #ff5a1f;
+  --accent-soft: #fff1ea;
+  --ink-soft: #c2774a; /* handwritten annotation tone */
+  /* Code surface */
+  --code-strong: #0d1117;
+
+  /* Syntax (light) */
+  --sx-kw: #9333ea;
+  --sx-ty: #0e7490;
+  --sx-fn: #1d4ed8;
+  --sx-str: #15803d;
+  --sx-num: #b45309;
+  --sx-com: #9aa1ac;
+  --sx-p: #6b7280;
+}
+
+.dark {
+  --canvas: #0b0d11;
+  --surface: #0f1217;
+  --surface2: #161a21;
+  --fg: #e6e9ee;
+  --muted: #9aa2ae;
+  --faint: #69727f;
+  --line: #222831;
+  --accent: #ff6a33;
+  --accent-soft: #2a160d;
+  --ink-soft: #e0a071;
+  --code-strong: #080a0e;
+
+  --sx-kw: #c792ea;
+  --sx-ty: #5ccfe6;
+  --sx-fn: #82aaff;
+  --sx-str: #c3e88d;
+  --sx-num: #f78c6c;
+  --sx-com: #5c6675;
+  --sx-p: #8b94a3;
+}
+
+/* Code blocks always render on the dark surface, regardless of theme.
+   Add `.dark-code` to a code container to get the dark syntax palette. */
+.dark-code {
+  --sx-kw: #c792ea;
+  --sx-ty: #5ccfe6;
+  --sx-fn: #82aaff;
+  --sx-str: #c3e88d;
+  --sx-num: #f78c6c;
+  --sx-com: #6b7587;
+  --sx-p: #8b94a3;
+}
+
+/* -------------------------------------------------------------
+   3. Expose tokens to Tailwind utilities
+   Enables bg-canvas, text-fg, border-line, text-accent,
+   font-sans, font-mono, etc. — everywhere.
+   ------------------------------------------------------------- */
+@theme inline {
+  --color-canvas: var(--canvas);
+  --color-surface: var(--surface);
+  --color-surface2: var(--surface2);
+  --color-fg: var(--fg);
+  --color-muted: var(--muted);
+  --color-faint: var(--faint);
+  --color-line: var(--line);
+  --color-accent: var(--accent);
+  --color-accent-soft: var(--accent-soft);
+  --color-ink-soft: var(--ink-soft);
+  --color-codebg: var(--code-strong);
+
+  --font-sans: 'Geist', ui-sans-serif, system-ui, sans-serif;
+  --font-mono: 'Geist Mono', ui-monospace, SFMono-Regular, monospace;
+  --font-hand: 'Caveat', cursive;
+
+  /* Type scale used across docs + landing */
+  --text-display: clamp(36px, 5.2vw, 58px); /* hero h1 */
+  --text-h1: 34px; /* page title */
+  --text-h2: 22px; /* section */
+  --text-h3: 18px;
+  --text-body: 16px;
+  --text-sm: 13.5px;
+
+  /* Radii */
+  --radius-card: 12px; /* rounded-xl cards */
+  --radius-md: 8px;
+
+  /* Shadows */
+  --shadow-card: 0 1px 3px rgb(0 0 0 / 0.06);
+  --shadow-pop: 0 10px 30px rgb(0 0 0 / 0.12);
+}
+
+/* -------------------------------------------------------------
+   4. Base resets
+   ------------------------------------------------------------- */
+@layer base {
+  html,
+  body {
+    margin: 0;
+    padding: 0;
+  }
+  body {
+    font-family: var(--font-sans);
+    background: var(--canvas);
+    color: var(--fg);
+    -webkit-font-smoothing: antialiased;
+    text-rendering: optimizeLegibility;
+  }
+  ::selection {
+    background: var(--accent);
+    color: #fff;
+  }
+}
+
+/* -------------------------------------------------------------
+   5. Component primitives
+   Reusable classes the Svelte components (and mdbook) lean on.
+   ------------------------------------------------------------- */
+@layer components {
+  /* Thin scrollbar used on code/overflow areas */
+  .axle-scroll::-webkit-scrollbar {
+    width: 9px;
+    height: 9px;
+  }
+  .axle-scroll::-webkit-scrollbar-thumb {
+    background: var(--line);
+    border-radius: 9px;
+  }
+  .axle-scroll::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  /* Syntax highlight token colors (pair with a tokenizer that
+     emits .t-kw / .t-ty / .t-fn / .t-str / .t-num / .t-com / .t-p) */
+  .t-kw {
+    color: var(--sx-kw);
+    font-weight: 500;
+  }
+  .t-ty {
+    color: var(--sx-ty);
+  }
+  .t-fn {
+    color: var(--sx-fn);
+  }
+  .t-str {
+    color: var(--sx-str);
+  }
+  .t-num {
+    color: var(--sx-num);
+  }
+  .t-com {
+    color: var(--sx-com);
+    font-style: italic;
+  }
+  .t-p {
+    color: var(--sx-p);
+  }
+  .dark-code pre code {
+    color: #c3cad6;
+  }
+
+  /* Handwritten annotation + thin hand-drawn underline */
+  .ink {
+    font-family: var(--font-hand);
+    color: var(--accent);
+    line-height: 1;
+  }
+  .note {
+    font-family: var(--font-hand);
+    color: var(--ink-soft);
+    line-height: 1.4;
+  }
+  .uline {
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 120 10' preserveAspectRatio='none'%3E%3Cpath d='M2 6 C 22 2, 42 9, 62 5 S 102 2, 118 6' fill='none' stroke='%23c2774a' stroke-width='2.2' stroke-linecap='round'/%3E%3C/svg%3E");
+    background-repeat: no-repeat;
+    background-position: 0 100%;
+    background-size: 100% 0.34em;
+    padding-bottom: 0.16em;
+  }
+  .dark .uline {
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 120 10' preserveAspectRatio='none'%3E%3Cpath d='M2 6 C 22 2, 42 9, 62 5 S 102 2, 118 6' fill='none' stroke='%23e0a071' stroke-width='2.2' stroke-linecap='round'/%3E%3C/svg%3E");
+  }
+
+  /* Marker swipe highlight (used on the hero word) */
+  .mark {
+    background: linear-gradient(120deg, var(--accent-soft) 0%, var(--accent-soft) 100%);
+    background-repeat: no-repeat;
+    background-position: 0 88%;
+    background-size: 100% 38%;
+    border-radius: 1px;
+  }
+  .dark .mark {
+    background-image: linear-gradient(
+      120deg,
+      color-mix(in oklch, var(--accent) 32%, transparent) 0%,
+      color-mix(in oklch, var(--accent) 32%, transparent) 100%
+    );
+  }
+
+  /* --- Buttons --- */
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    height: 2.75rem;
+    padding-inline: 1.25rem;
+    border-radius: var(--radius-md);
+    font-size: 14px;
+    font-weight: 500;
+    cursor: pointer;
+    transition:
+      opacity 0.15s,
+      background-color 0.15s,
+      border-color 0.15s;
+  }
+  .btn-primary {
+    background: var(--accent);
+    color: #fff;
+  }
+  .btn-primary:hover {
+    opacity: 0.9;
+  }
+  .btn-secondary {
+    background: var(--canvas);
+    color: var(--fg);
+    border: 1px solid var(--line);
+  }
+  .btn-secondary:hover {
+    background: var(--surface);
+  }
+
+  /* --- Card --- */
+  .card {
+    background: var(--canvas);
+    border: 1px solid var(--line);
+    border-radius: var(--radius-card);
+  }
+  .card-muted {
+    background: var(--surface);
+    border: 1px solid var(--line);
+    border-radius: var(--radius-card);
+  }
+
+  /* --- Inline code chip --- */
+  .code-chip {
+    font-family: var(--font-mono);
+    font-size: 12px;
+    border: 1px solid var(--line);
+    background: var(--surface);
+    color: var(--muted);
+    border-radius: var(--radius-md);
+    padding: 0.25rem 0.5rem;
+  }
+
+  /* --- Callout (info/note banner) --- */
+  .callout {
+    display: flex;
+    gap: 0.75rem;
+    border-left: 2px solid var(--accent);
+    background: var(--accent-soft);
+    border-radius: var(--radius-card);
+    padding: 1rem 1.25rem;
+  }
+
+  /* --- Eyebrow / kicker label --- */
+  .eyebrow {
+    font-size: 12px;
+    font-weight: 600;
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+    color: var(--accent);
+  }
+}
+
+/* -------------------------------------------------------------
+   6. Keyframes
+   ------------------------------------------------------------- */
+@keyframes axle-blink {
+  0%,
+  49% {
+    opacity: 1;
+  }
+  50%,
+  100% {
+    opacity: 0;
+  }
+}
+@keyframes axle-deck-in {
+  0% {
+    opacity: 0.4;
+    transform: translateY(6px);
+  }
+  100% {
+    opacity: 1;
+    transform: none;
+  }
+}
+@keyframes axle-prog {
+  0% {
+    width: 0;
+  }
+  100% {
+    width: 100%;
+  }
+}
+.cursor-blink {
+  animation: axle-blink 1.05s steps(1) infinite;
+}

package/dist/components/Seo.svelte

@@ -0,0 +1,38 @@
+<script lang="ts">
+  // Per-page SEO head: title, description, canonical, Open Graph, Twitter.
+  // Canonical/OG URL is built from the site origin (injected via setSite)
+  // + the current path.
+  import { page } from '$app/state';
+  import { getSite } from '../site/site.js';
+
+  let {
+    title = '',
+    description = '',
+    image = ''
+  }: { title?: string; description?: string; image?: string } = $props();
+
+  const { origin = '' } = getSite();
+  const url = $derived(origin + page.url.pathname);
+  const fullTitle = $derived(
+    !title ? 'Axle' : title.startsWith('Axle') ? title : `${title} · Axle`
+  );
+  const card = $derived(image ? 'summary_large_image' : 'summary');
+</script>
+
+<svelte:head>
+  <title>{fullTitle}</title>
+  {#if description}<meta name="description" content={description} />{/if}
+  <link rel="canonical" href={url} />
+
+  <meta property="og:type" content="website" />
+  <meta property="og:site_name" content="Axle" />
+  <meta property="og:title" content={fullTitle} />
+  {#if description}<meta property="og:description" content={description} />{/if}
+  <meta property="og:url" content={url} />
+  {#if image}<meta property="og:image" content={image} />{/if}
+
+  <meta name="twitter:card" content={card} />
+  <meta name="twitter:title" content={fullTitle} />
+  {#if description}<meta name="twitter:description" content={description} />{/if}
+  {#if image}<meta name="twitter:image" content={image} />{/if}
+</svelte:head>

package/dist/components/Seo.svelte.d.ts

@@ -0,0 +1,8 @@
+type $$ComponentProps = {
+    title?: string;
+    description?: string;
+    image?: string;
+};
+declare const Seo: import("svelte").Component<$$ComponentProps, {}, "">;
+type Seo = ReturnType<typeof Seo>;
+export default Seo;

package/dist/components/atoms/Badge.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  /** Pill badge, e.g. version tag. */
+  let { class: klass = '', children }: { class?: string; children?: Snippet } = $props();
+</script>
+
+<span
+  class="inline-flex items-center rounded-full border border-line px-2 py-0.5 text-[11px] font-medium text-muted whitespace-nowrap {klass}"
+>
+  {@render children?.()}
+</span>

package/dist/components/atoms/Badge.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    class?: string;
+    children?: Snippet;
+};
+declare const Badge: import("svelte").Component<$$ComponentProps, {}, "">;
+type Badge = ReturnType<typeof Badge>;
+export default Badge;

package/dist/components/atoms/Button.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { button } from '../../utils/variants.js';
+  import { cn } from '../../utils/cn.js';
+  /**
+   * Button / link. Renders <a> when `href` is set, otherwise <button>.
+   */
+  let {
+    variant = 'primary',
+    href,
+    onclick,
+    size = 'md',
+    class: klass = '',
+    children,
+    ...rest
+  }: {
+    variant?: 'primary' | 'secondary';
+    href?: string;
+    onclick?: (e: MouseEvent) => void;
+    size?: 'sm' | 'md';
+    class?: string;
+    children?: Snippet;
+  } = $props();
+
+  const cls = $derived(cn(button({ variant, size }), klass));
+</script>
+
+{#if href}
+  <a {href} class={cls} {...rest}>{@render children?.()}</a>
+{:else}
+  <button type="button" {onclick} class={cls} {...rest}>{@render children?.()}</button>
+{/if}

package/dist/components/atoms/Button.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    variant?: 'primary' | 'secondary';
+    href?: string;
+    onclick?: (e: MouseEvent) => void;
+    size?: 'sm' | 'md';
+    class?: string;
+    children?: Snippet;
+};
+declare const Button: import("svelte").Component<$$ComponentProps, {}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;

package/dist/components/atoms/Callout.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import Icon from './Icon.svelte';
+  /** Info / note banner with accent left border. */
+  let { class: klass = '', children }: { class?: string; children?: Snippet } = $props();
+</script>
+
+<div class="flex gap-3 rounded-xl border-l-2 border-accent bg-accent-soft px-5 py-4 {klass}">
+  <span class="text-accent mt-0.5 shrink-0"><Icon name="info" size={18} /></span>
+  <p class="text-[14px] leading-relaxed text-fg">{@render children?.()}</p>
+</div>

package/dist/components/atoms/Callout.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    class?: string;
+    children?: Snippet;
+};
+declare const Callout: import("svelte").Component<$$ComponentProps, {}, "">;
+type Callout = ReturnType<typeof Callout>;
+export default Callout;

package/dist/components/atoms/CodeChip.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  /** Inline monospace code chip. */
+  let { class: klass = '', children }: { class?: string; children?: Snippet } = $props();
+</script>
+
+<code
+  class="font-mono text-[12px] rounded-md border border-line bg-surface px-2 py-1 text-muted {klass}"
+>
+  {@render children?.()}
+</code>

package/dist/components/atoms/CodeChip.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    class?: string;
+    children?: Snippet;
+};
+declare const CodeChip: import("svelte").Component<$$ComponentProps, {}, "">;
+type CodeChip = ReturnType<typeof CodeChip>;
+export default CodeChip;

package/dist/components/atoms/Eyebrow.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  /** Uppercase accent kicker label. */
+  let { class: klass = '', children }: { class?: string; children?: Snippet } = $props();
+</script>
+
+<div class="text-[12px] font-semibold tracking-[0.14em] text-accent uppercase {klass}">
+  {@render children?.()}
+</div>

package/dist/components/atoms/Eyebrow.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    class?: string;
+    children?: Snippet;
+};
+declare const Eyebrow: import("svelte").Component<$$ComponentProps, {}, "">;
+type Eyebrow = ReturnType<typeof Eyebrow>;
+export default Eyebrow;

package/dist/components/atoms/HandNote.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  /**
+   * Handwritten margin note. Wrap the keyword to underline in {#snippet} or
+   * pass plain text; set `underline` to the substring you want hand-underlined.
+   * Simplest usage: <HandNote>Because comfortable code should never cost you <span class="uline">performance</span>.</HandNote>
+   */
+  let {
+    size = 21,
+    class: klass = '',
+    children
+  }: { size?: number; class?: string; children?: Snippet } = $props();
+</script>
+
+<span class="note leading-[1.4] {klass}" style="font-size:{size}px">{@render children?.()}</span>

package/dist/components/atoms/HandNote.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    size?: number;
+    class?: string;
+    children?: Snippet;
+};
+declare const HandNote: import("svelte").Component<$$ComponentProps, {}, "">;
+type HandNote = ReturnType<typeof HandNote>;
+export default HandNote;

package/dist/components/atoms/Icon.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+  import { icons } from '../../utils/icons.js';
+  import type { IconName } from '../../utils/icons.js';
+
+  /**
+   * Atomic icon. Pass either a known `name` (see lib/icons.js) or raw `paths`.
+   */
+  let {
+    name,
+    paths,
+    size = 16,
+    stroke = 1.7,
+    class: klass = ''
+  }: {
+    name?: IconName;
+    paths?: string[];
+    size?: number;
+    stroke?: number;
+    class?: string;
+  } = $props();
+
+  const d = $derived(paths ?? (name ? icons[name] : undefined) ?? []);
+</script>
+
+<svg
+  width={size}
+  height={size}
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width={stroke}
+  stroke-linecap="round"
+  stroke-linejoin="round"
+  class={klass}
+  aria-hidden="true"
+>
+  {#each d as p}
+    <path d={p} />
+  {/each}
+</svg>

package/dist/components/atoms/Icon.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { IconName } from '../../utils/icons.js';
+type $$ComponentProps = {
+    name?: IconName;
+    paths?: string[];
+    size?: number;
+    stroke?: number;
+    class?: string;
+};
+declare const Icon: import("svelte").Component<$$ComponentProps, {}, "">;
+type Icon = ReturnType<typeof Icon>;
+export default Icon;